LineTable class contains deserialized versions of line tables for each function's address ranges. More...

#include "llvm/DebugInfo/GSYM/LineTable.h"

Public Member Functions
llvm::Error	encode (FileWriter &O, uint64_t BaseAddr) const
	Encode this LineTable object into FileWriter stream.

bool	empty () const

void	clear ()

std::optional< LineEntry >	first () const
	Return the first line entry if the line table isn't empty.

std::optional< LineEntry >	last () const
	Return the last line entry if the line table isn't empty.

void	push (const LineEntry &LE)

size_t	isValid () const

size_t	size () const

LineEntry &	get (size_t i)

const LineEntry &	get (size_t i) const

LineEntry &	operator[] (size_t i)

const LineEntry &	operator[] (size_t i) const

bool	operator== (const LineTable &RHS) const

bool	operator!= (const LineTable &RHS) const

bool	operator< (const LineTable &RHS) const

Collection::const_iterator	begin () const

Collection::const_iterator	end () const

Static Public Member Functions
static Expected< LineEntry >	lookup (DataExtractor &Data, uint64_t BaseAddr, uint64_t Addr)
	Lookup a single address within a line table's data.

static llvm::Expected< LineTable >	decode (DataExtractor &Data, uint64_t BaseAddr)
	Decode an LineTable object from a binary data stream.

Detailed Description

LineTable class contains deserialized versions of line tables for each function's address ranges.

When saved to disk, the line table is encoded using a modified version of the DWARF line tables that only tracks address to source file and line.

ENCODING

The line table starts with a small prolog that contains the following values:

ENCODING NAME DESCRIPTION ======== =========== ==================================================== SLEB MinDelta The min line delta for special opcodes that advance the address and line number. SLEB MaxDelta The max line delta for single byte opcodes that advance the address and line number. ULEB FirstLine The value of the first source line number to initialize the LineEntry with.

Once these prolog items are read, we initialize a LineEntry struct with the start address of the function from the FunctionInfo's address range, a default file index of 1, and the line number set to "FirstLine" from the prolog above:

LineEntry Row(BaseAddr, 1, FirstLine);

The line table state machine is now initialized and ready to be parsed. The stream that follows this encodes the line entries in a compact form. Some opcodes cause "Row" to be modified and some opcodes may also push "Row" onto the end of the "LineTable.Lines" vector. The end result is a vector of LineEntry structs that is sorted in ascending address order.

NORMAL OPCODES

The opcodes 0 through 3 are normal in opcodes. Their encoding and descriptions are listed below:

ENCODING ENUMERATION VALUE DESCRIPTION ======== ================ ===== ======================================== LTOC_EndSequence 0x00 Parsing is done. ULEB LTOC_SetFile 0x01 Row.File = ULEB ULEB LTOC_AdvancePC 0x02 Row.Addr += ULEB, push "Row". SLEB LTOC_AdvanceLine 0x03 Row.Line += SLEB LTOC_FirstSpecial 0x04 First special opcode (see SPECIAL OPCODES below).

SPECIAL OPCODES

Opcodes LTOC_FirstSpecial through 255 are special opcodes that always increment both the Row.Addr and Row.Line and push "Row" onto the LineEntry.Lines array. They do this by using some of the bits to increment/decrement the source line number, and some of the bits to increment the address. Line numbers can go up or down when making line tables, where addresses always only increase since line tables are sorted by address.

In order to calculate the amount to increment the line and address for these special opcodes, we calculate the number of values reserved for the line increment/decrement using the "MinDelta" and "MaxDelta" from the prolog:

const int64_t LineRange = MaxDelta - MinDelta + 1;

Then we can adjust the opcode to not include any of the normal opcodes:

const uint8_t AdjustedOp = Opcode - LTOC_FirstSpecial;

And we can calculate the line offset, and address offset:

const int64_t LineDelta = MinDelta + (AdjustedOp % LineRange);
const uint64_t AddrDelta = (AdjustedOp / LineRange);

And use these to modify our "Row":

Row.Line += LineDelta;
Row.Addr += AddrDelta;

And push a row onto the line table:

Lines.push_back(Row);

This is verify similar to the way that DWARF encodes its line tables. The only difference is the DWARF line tables have more normal opcodes and the "Row" contains more members, like source column number, bools for end of prologue, beginnging of epilogue, is statement and many others. There are also more complex rules that happen for the extra normal opcodes. By leaving these extra opcodes out, we leave more bits for the special opcodes that allows us to encode line tables in fewer bytes than standard DWARF encodings.

Opcodes that will push "Row" onto the LineEntry.Lines include the LTOC_AdvancePC opcode and all special opcodes. All other opcodes only modify the current "Row", or cause the line table to end.

Definition at line 118 of file LineTable.h.

Member Function Documentation

◆ begin()

Collection::const_iterator llvm::gsym::LineTable::begin ( ) const

inline

Definition at line 223 of file LineTable.h.

◆ clear()

void llvm::gsym::LineTable::clear ( )

inline

Definition at line 168 of file LineTable.h.

◆ decode()

llvm::Expected< LineTable > LineTable::decode	(	DataExtractor &	Data,
		uint64_t	BaseAddr
	)

static

Decode an LineTable object from a binary data stream.

Parameters

Data	The binary stream to read the data from. This object must have the data for the LineTable object starting at offset zero. The data can contain more data than needed.
BaseAddr	The base address to use when decoding the line table. This will be the FunctionInfo's start address and will be used to initialize the line table row prior to parsing any opcodes.

Returns: An LineTable or an error describing the issue that was encountered during decoding.

Definition at line 251 of file LineTable.cpp.

References llvm::Data.

Referenced by llvm::gsym::FunctionInfo::decode().

◆ empty()

bool llvm::gsym::LineTable::empty ( ) const

inline

Definition at line 167 of file LineTable.h.

◆ encode()

llvm::Error LineTable::encode	(	FileWriter &	O,
		uint64_t	BaseAddr
	)		const

Encode this LineTable object into FileWriter stream.

Parameters

O	The binary stream to write the data to at the current file position.
BaseAddr	The base address to use when decoding the line table. This will be the FunctionInfo's start address.

Returns: An error object that indicates success or failure or the encoding process.

Definition at line 122 of file LineTable.cpp.

References llvm::gsym::LineEntry::Addr, AdvanceLine, AdvancePC, assert(), llvm::createStringError(), encodeSpecial(), End, EndSequence, llvm::gsym::LineEntry::File, llvm::First, I, INT64_MAX, INT64_MIN, isValid(), llvm::gsym::LineEntry::Line, SetFile, llvm::Error::success(), llvm::gsym::FileWriter::writeSLEB(), llvm::gsym::FileWriter::writeU8(), and llvm::gsym::FileWriter::writeULEB().

◆ end()

Collection::const_iterator llvm::gsym::LineTable::end ( ) const

inline

Definition at line 224 of file LineTable.h.

◆ first()

std::optional< LineEntry > llvm::gsym::LineTable::first ( ) const

inline

Return the first line entry if the line table isn't empty.

Returns: An optional line entry with the first line entry if the line table isn't empty, or std::nullopt if the line table is emtpy.

Definition at line 173 of file LineTable.h.

◆ get() [1/2]

LineEntry & llvm::gsym::LineTable::get ( size_t i )

inline

Definition at line 196 of file LineTable.h.

References assert().

Referenced by operator[]().

◆ get() [2/2]

const LineEntry & llvm::gsym::LineTable::get ( size_t i ) const

inline

Definition at line 200 of file LineTable.h.

References assert().

◆ isValid()

size_t llvm::gsym::LineTable::isValid ( ) const

inline

Definition at line 190 of file LineTable.h.

Referenced by encode().

◆ last()

std::optional< LineEntry > llvm::gsym::LineTable::last ( ) const

inline

Return the last line entry if the line table isn't empty.

Returns: An optional line entry with the last line entry if the line table isn't empty, or std::nullopt if the line table is emtpy.

Definition at line 182 of file LineTable.h.

◆ lookup()

Expected< LineEntry > LineTable::lookup	(	DataExtractor &	Data,
		uint64_t	BaseAddr,
		uint64_t	Addr
	)

static

Lookup a single address within a line table's data.

Clients have the option to decode an entire line table using LineTable::decode() or just find a single matching entry using this function. The benefit of using this function is that parsed LineEntry objects that do not match will not be stored in an array. This will avoid memory allocation costs and parsing can stop once a match has been found.

Parameters

Data	The binary stream to read the data from. This object must have the data for the LineTable object starting at offset zero. The data can contain more data than needed.
BaseAddr	The base address to use when decoding the line table. This will be the FunctionInfo's start address and will be used to initialize the line table row prior to parsing any opcodes.

Returns: An LineEntry object if a match is found, error otherwise.

Definition at line 266 of file LineTable.cpp.

References Addr, llvm::createStringError(), and llvm::Data.

Referenced by llvm::gsym::FunctionInfo::lookup().

◆ operator!=()

bool llvm::gsym::LineTable::operator!= ( const LineTable & RHS ) const

inline

Definition at line 213 of file LineTable.h.

References RHS.

◆ operator<()

bool llvm::gsym::LineTable::operator< ( const LineTable & RHS ) const

inline

Definition at line 216 of file LineTable.h.

References RHS.

◆ operator==()

bool llvm::gsym::LineTable::operator== ( const LineTable & RHS ) const

inline

Definition at line 210 of file LineTable.h.

References RHS.

◆ operator[]() [1/2]

LineEntry & llvm::gsym::LineTable::operator[] ( size_t i )

inline

Definition at line 204 of file LineTable.h.

References get().

◆ operator[]() [2/2]

const LineEntry & llvm::gsym::LineTable::operator[] ( size_t i ) const

inline

Definition at line 207 of file LineTable.h.

References get().

◆ push()

void llvm::gsym::LineTable::push ( const LineEntry & LE )

inline

Definition at line 187 of file LineTable.h.

◆ size()

size_t llvm::gsym::LineTable::size ( ) const

inline

Definition at line 193 of file LineTable.h.

Referenced by llvm::gsym::CUInfo::CUInfo().

The documentation for this class was generated from the following files:

include/llvm/DebugInfo/GSYM/LineTable.h
lib/DebugInfo/GSYM/LineTable.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ begin()

◆ clear()

◆ decode()

◆ empty()

◆ encode()

◆ end()

◆ first()

◆ get() [1/2]

◆ get() [2/2]

◆ isValid()

◆ last()

◆ lookup()

◆ operator!=()

◆ operator<()

◆ operator==()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ push()

◆ size()