GsymReader is used to read GSYM data from a file or buffer. More...

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

Public Member Functions
	GsymReader (GsymReader &&RHS)

	~GsymReader ()

const Header &	getHeader () const
	Access the GSYM header.

llvm::Expected< FunctionInfo >	getFunctionInfo (uint64_t Addr) const
	Get the full function info for an address.

llvm::Expected< FunctionInfo >	getFunctionInfoAtIndex (uint64_t AddrIdx) const
	Get the full function info given an address index.

llvm::Expected< LookupResult >	lookup (uint64_t Addr, std::optional< DataExtractor > *MergedFuncsData=nullptr) const
	Lookup an address in the a GSYM.

llvm::Expected< std::vector< LookupResult > >	lookupAll (uint64_t Addr) const
	Lookup all merged functions for a given address.

StringRef	getString (uint32_t Offset) const
	Get a string from the string table.

std::optional< FileEntry >	getFile (uint32_t Index) const
	Get the a file entry for the suppplied file index.

void	dump (raw_ostream &OS)
	Dump the entire Gsym data contained in this object.

void	dump (raw_ostream &OS, const FunctionInfo &FI, uint32_t Indent=0)
	Dump a FunctionInfo object.

void	dump (raw_ostream &OS, const MergedFunctionsInfo &MFI)
	Dump a MergedFunctionsInfo object.

void	dump (raw_ostream &OS, const CallSiteInfo &CSI)
	Dump a CallSiteInfo object.

void	dump (raw_ostream &OS, const CallSiteInfoCollection &CSIC, uint32_t Indent=0)
	Dump a CallSiteInfoCollection object.

void	dump (raw_ostream &OS, const LineTable &LT, uint32_t Indent=0)
	Dump a LineTable object.

void	dump (raw_ostream &OS, const InlineInfo &II, uint32_t Indent=0)
	Dump a InlineInfo object.

void	dump (raw_ostream &OS, std::optional< FileEntry > FE)
	Dump a FileEntry object.

uint32_t	getNumAddresses () const
	Get the number of addresses in this Gsym file.

std::optional< uint64_t >	getAddress (size_t Index) const
	Gets an address from the address table.

Static Public Member Functions
static llvm::Expected< GsymReader >	openFile (StringRef Path)
	Construct a GsymReader from a file on disk.

static llvm::Expected< GsymReader >	copyBuffer (StringRef Bytes)
	Construct a GsymReader from a buffer.

Protected Member Functions
template<class T >
ArrayRef< T >	getAddrOffsets () const
	Get an appropriate address info offsets array.

template<class T >
std::optional< uint64_t >	addressForIndex (size_t Index) const
	Get an appropriate address from the address table.

template<class T >
std::optional< uint64_t >	getAddressOffsetIndex (const uint64_t AddrOffset) const
	Lookup an address offset in the AddrOffsets table.

Expected< uint64_t >	getAddressIndex (const uint64_t Addr) const
	Given an address, find the address index.

std::optional< uint64_t >	getAddressInfoOffset (size_t Index) const
	Given an address index, get the offset for the FunctionInfo.

llvm::Expected< llvm::DataExtractor >	getFunctionInfoDataForAddress (uint64_t Addr, uint64_t &FuncStartAddr) const
	Given an address, find the correct function info data and function address.

llvm::Expected< llvm::DataExtractor >	getFunctionInfoDataAtIndex (uint64_t AddrIdx, uint64_t &FuncStartAddr) const
	Get the function data and address given an address index.

Static Protected Member Functions
static llvm::Expected< llvm::gsym::GsymReader >	create (std::unique_ptr< MemoryBuffer > &MemBuffer)
	Create a GSYM from a memory buffer.

Detailed Description

GsymReader is used to read GSYM data from a file or buffer.

This class is optimized for very quick lookups when the endianness matches the host system. The Header, address table, address info offsets, and file table is designed to be mmap'ed as read only into memory and used without any parsing needed. If the endianness doesn't match, we swap these objects and tables into GsymReader::SwappedData and then point our header and ArrayRefs to this swapped internal data.

GsymReader objects must use one of the static functions to create an instance: GsymReader::openFile(...) and GsymReader::copyBuffer(...).

Definition at line 44 of file GsymReader.h.

Constructor & Destructor Documentation

◆ GsymReader()

GsymReader::GsymReader ( GsymReader && RHS )

default

◆ ~GsymReader()

GsymReader::~GsymReader ( )

default

Member Function Documentation

◆ addressForIndex()

template<class T >

std::optional< uint64_t > llvm::gsym::GsymReader::addressForIndex ( size_t Index ) const

inlineprotected

Get an appropriate address from the address table.

The address table in the GSYM file is stored as array of 1, 2, 4 or 8 byte address offsets from the The gsym::Header::BaseAddress. The table is stored internally as a array of bytes that are in the correct endianness. In order to extract an address from the address table we must access the address offset using the correct size and then add it to the BaseAddress in the header.

Parameters

Index An index into the AddrOffsets array.

Returns: An virtual address that matches the original object file for the address as the specified index, or std::nullopt if Index is out of bounds.

Definition at line 309 of file GsymReader.h.

References llvm::gsym::Header::BaseAddress, Index, and llvm::ArrayRef< T >::size().

◆ copyBuffer()

llvm::Expected< GsymReader > GsymReader::copyBuffer ( StringRef Bytes )

static

Construct a GsymReader from a buffer.

Parameters

Bytes A set of bytes that will be copied and owned by the returned object on success.

Returns: An expected GsymReader that contains the object or an error object that indicates reason for failing to read the GSYM.

Definition at line 42 of file GsymReader.cpp.

References create(), and llvm::MemoryBuffer::getMemBufferCopy().

◆ create()

llvm::Expected< llvm::gsym::GsymReader > GsymReader::create ( std::unique_ptr< MemoryBuffer > & MemBuffer )

staticprotected

Create a GSYM from a memory buffer.

Called by both openFile() and copyBuffer(), this function does all of the work of parsing the GSYM file and returning an error.

Parameters

MemBuffer A memory buffer that will transfer ownership into the GsymReader.

Returns: An expected GsymReader that contains the object or an error object that indicates reason for failing to read the GSYM.

Definition at line 48 of file GsymReader.cpp.

References llvm::createStringError().

Referenced by copyBuffer(), and openFile().

◆ dump() [1/8]

void GsymReader::dump ( raw_ostream & OS )

Dump the entire Gsym data contained in this object.

Parameters

OS	The output stream to dump to.

Definition at line 383 of file GsymReader.cpp.

References llvm::gsym::Header::AddrOffSize, llvm::sampleprof::Base, dump(), llvm::format(), getAddress(), getFile(), getFunctionInfoAtIndex(), getHeader(), HEX32, HEX64, I, llvm::logAllUnhandledErrors(), llvm::gsym::Header::NumAddresses, and OS.

Referenced by dump().

◆ dump() [2/8]

void GsymReader::dump	(	raw_ostream &	OS,
		const CallSiteInfo &	CSI
	)

Dump a CallSiteInfo object.

This function will output the details of a CallSiteInfo object in a human-readable format.

Parameters

OS	The output stream to dump to.
CSI	The CallSiteInfo object to dump.

Definition at line 463 of file GsymReader.cpp.

References llvm::gsym::CallSiteInfo::ExternalCall, getString(), HEX16, llvm::gsym::CallSiteInfo::InternalCall, llvm::gsym::CallSiteInfo::MatchRegex, llvm::gsym::CallSiteInfo::None, OS, and llvm::gsym::CallSiteInfo::ReturnOffset.

◆ dump() [3/8]

void GsymReader::dump	(	raw_ostream &	OS,
		const CallSiteInfoCollection &	CSIC,
		uint32_t	Indent = `0`
	)

Dump a CallSiteInfoCollection object.

This function will iterate over a collection of CallSiteInfo objects and dump each one.

Parameters

OS	The output stream to dump to.
CSIC	The CallSiteInfoCollection object to dump.
Indent	The indentation as number of spaces. Used when dumping as an item from within MergedFunctionsInfo.

Definition at line 495 of file GsymReader.cpp.

References llvm::gsym::CallSiteInfoCollection::CallSites, dump(), llvm::raw_ostream::indent(), and OS.

◆ dump() [4/8]

void GsymReader::dump	(	raw_ostream &	OS,
		const FunctionInfo &	FI,
		uint32_t	Indent = `0`
	)

Dump a FunctionInfo object.

This function will convert any string table indexes and file indexes into human readable format.

Parameters

OS	The output stream to dump to.
FI	The object to dump.
Indent	The indentation as number of spaces. Used when dumping as an item within MergedFunctionsInfo.

Definition at line 438 of file GsymReader.cpp.

References assert(), llvm::gsym::FunctionInfo::CallSites, dump(), getString(), llvm::raw_ostream::indent(), llvm::gsym::FunctionInfo::Inline, llvm::gsym::FunctionInfo::MergedFunctions, llvm::gsym::FunctionInfo::Name, llvm::gsym::FunctionInfo::OptLineTable, OS, and llvm::gsym::FunctionInfo::Range.

◆ dump() [5/8]

void GsymReader::dump	(	raw_ostream &	OS,
		const InlineInfo &	II,
		uint32_t	Indent = `0`
	)

Dump a InlineInfo object.

This function will convert any string table indexes and file indexes into human readable format.

Parameters

OS	The output stream to dump to.
II	The object to dump.
Indent	The indentation as number of spaces. Used for recurive dumping.

Definition at line 519 of file GsymReader.cpp.

References dump(), getFile(), getString(), II, llvm::raw_ostream::indent(), and OS.

◆ dump() [6/8]

void GsymReader::dump	(	raw_ostream &	OS,
		const LineTable &	LT,
		uint32_t	Indent = `0`
	)

Dump a LineTable object.

This function will convert any string table indexes and file indexes into human readable format.

Parameters

OS	The output stream to dump to.
LT	The object to dump.
Indent	The indentation as number of spaces. Used when dumping as an item from within MergedFunctionsInfo.

Definition at line 507 of file GsymReader.cpp.

References dump(), getFile(), HEX64, llvm::raw_ostream::indent(), and OS.

◆ dump() [7/8]

void GsymReader::dump	(	raw_ostream &	OS,
		const MergedFunctionsInfo &	MFI
	)

Dump a MergedFunctionsInfo object.

This function will dump a MergedFunctionsInfo object - basically by dumping the contained FunctionInfo objects with indentation.

Parameters

OS	The output stream to dump to.
MFI	The object to dump.

Definition at line 456 of file GsymReader.cpp.

References dump(), llvm::gsym::MergedFunctionsInfo::MergedFunctions, and OS.

◆ dump() [8/8]

void GsymReader::dump	(	raw_ostream &	OS,
		std::optional< FileEntry >	FE
	)

Dump a FileEntry object.

This function will convert any string table indexes into human readable format.

Parameters

OS	The output stream to dump to.
FE	The object to dump.

Definition at line 537 of file GsymReader.cpp.

References llvm::sampleprof::Base, llvm::StringRef::empty(), getString(), and OS.

◆ getAddress()

std::optional< uint64_t > GsymReader::getAddress ( size_t Index ) const

Gets an address from the address table.

Addresses are stored as offsets frrom the gsym::Header::BaseAddress.

Parameters

Index A index into the address table.

Returns: A resolved virtual address for adddress in the address table or std::nullopt if Index is out of bounds.

Definition at line 207 of file GsymReader.cpp.

References llvm::gsym::Header::AddrOffSize.

Referenced by dump(), and getFunctionInfoDataAtIndex().

◆ getAddressIndex()

Expected< uint64_t > GsymReader::getAddressIndex ( const uint64_t Addr ) const

protected

Given an address, find the address index.

Binary search the address table and find the matching address index.

Parameters

Addr	A virtual address that matches the original object file to lookup.

Returns: An index into the address table. This index can be used to extract the FunctionInfo data's offset from the AddrInfoOffsets array. Returns an error if the address isn't in the GSYM with details of why.

Definition at line 225 of file GsymReader.cpp.

References Addr, llvm::gsym::Header::AddrOffSize, llvm::gsym::Header::BaseAddress, and llvm::createStringError().

Referenced by getFunctionInfoDataForAddress().

◆ getAddressInfoOffset()

std::optional< uint64_t > GsymReader::getAddressInfoOffset ( size_t Index ) const

protected

Given an address index, get the offset for the FunctionInfo.

Looking up an address is done by finding the corresponding address index for the address. This index is then used to get the offset of the FunctionInfo data that we will decode using this function.

Parameters

Index An index into the address table.

Returns: An optional GSYM data offset for the offset of the FunctionInfo that needs to be decoded.

Definition at line 217 of file GsymReader.cpp.

References llvm::ArrayRef< T >::size().

◆ getAddressOffsetIndex()

template<class T >

std::optional< uint64_t > llvm::gsym::GsymReader::getAddressOffsetIndex ( const uint64_t AddrOffset ) const

inlineprotected

Lookup an address offset in the AddrOffsets table.

Given an address offset, look it up using a binary search of the AddrOffsets table.

Parameters

AddrOffset An address offset, that has already been computed by subtracting the gsym::Header::BaseAddress.

Returns: The matching address offset index. This index will be used to extract the FunctionInfo data's offset from the AddrInfoOffsets array.

Definition at line 326 of file GsymReader.h.

References llvm::ArrayRef< T >::begin(), llvm::ArrayRef< T >::end(), and End.

◆ getAddrOffsets()

template<class T >

ArrayRef< T > llvm::gsym::GsymReader::getAddrOffsets ( ) const

inlineprotected

Get an appropriate address info offsets array.

The address table in the GSYM file is stored as array of 1, 2, 4 or 8 byte offsets from the The gsym::Header::BaseAddress. The table is stored internally as a array of bytes that are in the correct endianness. When we access this table we must get an array that matches those sizes. This templatized helper function is used when accessing address offsets in the AddrOffsets member variable.

Returns: An ArrayRef of an appropriate address offset size.

Definition at line 291 of file GsymReader.h.

References llvm::ArrayRef< T >::data(), and llvm::ArrayRef< T >::size().

◆ getFile()

std::optional< FileEntry > llvm::gsym::GsymReader::getFile ( uint32_t Index ) const

inline

Get the a file entry for the suppplied file index.

Used to convert any file indexes in the FunctionInfo data back into files. This function can be used for iteration, but is more commonly used for random access when doing lookups.

Parameters

Index An index into the file table.

Returns: An optional FileInfo that will be valid if the file index is valid, or std::nullopt if the file index is out of bounds,

Definition at line 169 of file GsymReader.h.

References Index.

Referenced by dump(), lookup(), and llvm::gsym::FunctionInfo::lookup().

◆ getFunctionInfo()

llvm::Expected< FunctionInfo > GsymReader::getFunctionInfo ( uint64_t Addr ) const

Get the full function info for an address.

This should be called when a client will store a copy of the complete FunctionInfo for a given address. For one off lookups, use the lookup() function below.

Symbolication server processes might want to parse the entire function info for a given address and cache it if the process stays around to service many symbolication addresses, like for parsing profiling information.

Parameters

Addr	A virtual address from the orignal object file to lookup.

Returns: An expected FunctionInfo that contains the function info object or an error object that indicates reason for failing to lookup the address.

Definition at line 320 of file GsymReader.cpp.

References Addr, llvm::gsym::FunctionInfo::decode(), and getFunctionInfoDataForAddress().

◆ getFunctionInfoAtIndex()

llvm::Expected< FunctionInfo > GsymReader::getFunctionInfoAtIndex ( uint64_t AddrIdx ) const

Get the full function info given an address index.

Parameters

AddrIdx A address index for an address in the address table.

Returns: An expected FunctionInfo that contains the function info object or an error object that indicates reason for failing get the function info object.

Definition at line 329 of file GsymReader.cpp.

References llvm::gsym::FunctionInfo::decode(), getFunctionInfoDataAtIndex(), and Idx.

Referenced by dump().

◆ getFunctionInfoDataAtIndex()

llvm::Expected< DataExtractor > GsymReader::getFunctionInfoDataAtIndex	(	uint64_t	AddrIdx,
		uint64_t &	FuncStartAddr
	)		const

protected

Get the function data and address given an address index.

Parameters

AddrIdx A address index from the address table.

Returns: An expected FunctionInfo that contains the function info object or an error object that indicates reason for failing to lookup the address.

Definition at line 299 of file GsymReader.cpp.

References assert(), llvm::big, llvm::createStringError(), llvm::StringRef::empty(), getAddress(), getNumAddresses(), and llvm::little.

Referenced by getFunctionInfoAtIndex(), and getFunctionInfoDataForAddress().

◆ getFunctionInfoDataForAddress()

llvm::Expected< DataExtractor > GsymReader::getFunctionInfoDataForAddress	(	uint64_t	Addr,
		uint64_t &	FuncStartAddr
	)		const

protected

Given an address, find the correct function info data and function address.

Binary search the address table and find the matching address info and make sure that the function info contains the address. GSYM allows functions to overlap, and the most debug info is contained in the first entries due to the sorting when GSYM files are created. We can have multiple function info that start at the same address only if their address range doesn't match. So find the first entry that matches Addr and iterate forward until we find one that contains the address.

Parameters

[in]	Addr	A virtual address that matches the original object file to lookup.
[out]	FuncStartAddr	A virtual address that is the base address of the function that is used for decoding the FunctionInfo.

Returns: An valid data extractor on success, or an error if we fail to find the address in a function info or corrrectly decode the data

Definition at line 256 of file GsymReader.cpp.

References Addr, contains(), llvm::createStringError(), getAddressIndex(), getFunctionInfoDataAtIndex(), getNumAddresses(), llvm::Offset, and llvm::Expected< T >::takeError().

Referenced by getFunctionInfo(), and lookup().

◆ getHeader()

const Header & GsymReader::getHeader ( ) const

Access the GSYM header.

Returns: A native endian version of the GSYM header.

Definition at line 199 of file GsymReader.cpp.

References assert().

Referenced by dump().

◆ getNumAddresses()

uint32_t llvm::gsym::GsymReader::getNumAddresses ( ) const

inline

Get the number of addresses in this Gsym file.

Definition at line 265 of file GsymReader.h.

References llvm::gsym::Header::NumAddresses.

Referenced by getFunctionInfoDataAtIndex(), and getFunctionInfoDataForAddress().

◆ getString()

StringRef llvm::gsym::GsymReader::getString ( uint32_t Offset ) const

inline

Get a string from the string table.

Parameters

Offset The string table offset for the string to retrieve.

Returns: The string from the strin table.

Definition at line 158 of file GsymReader.h.

References llvm::Offset.

Referenced by dump(), lookup(), and llvm::gsym::FunctionInfo::lookup().

◆ lookup()

llvm::Expected< LookupResult > GsymReader::lookup	(	uint64_t	Addr,
		std::optional< DataExtractor > *	MergedFuncsData = `nullptr`
	)		const

Lookup an address in the a GSYM.

Lookup just the information needed for a specific address Addr. This function is faster that calling getFunctionInfo() as it will only return information that pertains to Addr and allows the parsing to skip any extra information encoded for other addresses. For example the line table parsing can stop when a matching LineEntry has been fouhnd, and the InlineInfo can stop parsing early once a match has been found and also skip information that doesn't match. This avoids memory allocations and is much faster for lookups.

Parameters

Addr	A virtual address from the orignal object file to lookup.
MergedFuncsData	A pointer to an optional DataExtractor that, if non-null, will be set to the raw data of the MergedFunctionInfo, if present.

Returns: An expected LookupResult that contains only the information needed for the current address, or an error object that indicates reason for failing to lookup the address.

Definition at line 338 of file GsymReader.cpp.

References Addr, getFunctionInfoDataForAddress(), and llvm::gsym::FunctionInfo::lookup().

Referenced by lookupAll().

◆ lookupAll()

llvm::Expected< std::vector< LookupResult > > GsymReader::lookupAll ( uint64_t Addr ) const

Lookup all merged functions for a given address.

This function performs a lookup for the specified address and then retrieves additional LookupResults from any merged functions associated with the primary LookupResult.

Parameters

Addr	The address to lookup.

Returns: A vector of LookupResult objects, where the first element is the primary result, followed by results for any merged functions

Definition at line 349 of file GsymReader.cpp.

References Addr, llvm::gsym::MergedFunctionsInfo::getFuncsDataExtractors(), llvm::gsym::FunctionInfo::lookup(), lookup(), and Results.

◆ openFile()

llvm::Expected< GsymReader > GsymReader::openFile ( StringRef Path )

static

Construct a GsymReader from a file on disk.

Parameters

Path	The file path the GSYM file to read.

Returns: An expected GsymReader that contains the object or an error object that indicates reason for failing to read the GSYM.

Definition at line 32 of file GsymReader.cpp.

References create(), llvm::errorCodeToError(), llvm::ErrorOr< T >::get(), llvm::ErrorOr< T >::getError(), and llvm::MemoryBuffer::getFileOrSTDIN().

Referenced by llvm::gsym::DwarfTransformer::verify().

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

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ GsymReader()

◆ ~GsymReader()

Member Function Documentation

◆ addressForIndex()

◆ copyBuffer()

◆ create()

◆ dump() [1/8]

◆ dump() [2/8]

◆ dump() [3/8]

◆ dump() [4/8]

◆ dump() [5/8]

◆ dump() [6/8]

◆ dump() [7/8]

◆ dump() [8/8]

◆ getAddress()

◆ getAddressIndex()

◆ getAddressInfoOffset()

◆ getAddressOffsetIndex()

◆ getAddrOffsets()

◆ getFile()

◆ getFunctionInfo()

◆ getFunctionInfoAtIndex()

◆ getFunctionInfoDataAtIndex()

◆ getFunctionInfoDataForAddress()

◆ getHeader()

◆ getNumAddresses()

◆ getString()

◆ lookup()

◆ lookupAll()

◆ openFile()