LLVM: llvm::gsym::GsymReader Class Reference (original) (raw)

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

#include "[llvm/DebugInfo/GSYM/GsymReader.h](GsymReader%5F8h%5Fsource.html)"

Public Member Functions
LLVM_ABI GsymReader (GsymReader &&RHS)
LLVM_ABI ~GsymReader ()
LLVM_ABI const Header & getHeader () const
Access the GSYM header.
LLVM_ABI llvm::Expected< FunctionInfo > getFunctionInfo (uint64_t Addr) const
Get the full function info for an address.
LLVM_ABI llvm::Expected< FunctionInfo > getFunctionInfoAtIndex (uint64_t AddrIdx) const
Get the full function info given an address index.
LLVM_ABI llvm::Expected< LookupResult > lookup (uint64_t Addr, std::optional< DataExtractor > *MergedFuncsData=nullptr) const
Lookup an address in the a GSYM.
LLVM_ABI 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.
LLVM_ABI void dump (raw_ostream &OS)
Dump the entire Gsym data contained in this object.
LLVM_ABI void dump (raw_ostream &OS, const FunctionInfo &FI, uint32_t Indent=0)
Dump a FunctionInfo object.
LLVM_ABI void dump (raw_ostream &OS, const MergedFunctionsInfo &MFI)
Dump a MergedFunctionsInfo object.
LLVM_ABI void dump (raw_ostream &OS, const CallSiteInfo &CSI)
Dump a CallSiteInfo object.
LLVM_ABI void dump (raw_ostream &OS, const CallSiteInfoCollection &CSIC, uint32_t Indent=0)
Dump a CallSiteInfoCollection object.
LLVM_ABI void dump (raw_ostream &OS, const LineTable &LT, uint32_t Indent=0)
Dump a LineTable object.
LLVM_ABI void dump (raw_ostream &OS, const InlineInfo &II, uint32_t Indent=0)
Dump a InlineInfo object.
LLVM_ABI 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.
LLVM_ABI std::optional< uint64_t > getAddress (size_t Index) const
Gets an address from the address table.
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.
LLVM_ABI Expected< uint64_t > getAddressIndex (const uint64_t Addr) const
Given an address, find the address index.
LLVM_ABI std::optional< uint64_t > getAddressInfoOffset (size_t Index) const
Given an address index, get the offset for the FunctionInfo.
LLVM_ABI 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_ABI llvm::Expected< llvm::DataExtractor > getFunctionInfoDataAtIndex (uint64_t AddrIdx, uint64_t &FuncStartAddr) const
Get the function data and address given an address index.

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 45 of file GsymReader.h.

GsymReader::GsymReader ( GsymReader && RHS) default

◆ ~GsymReader()

GsymReader::~GsymReader ( ) default

◆ 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 314 of file GsymReader.h.

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

Referenced by getAddress().

◆ copyBuffer()

◆ create()

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]

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::sampleprof::Base, dump(), llvm::format(), getAddress(), getFile(), getFunctionInfoAtIndex(), getHeader(), HEX32, HEX64, I, llvm::logAllUnhandledErrors(), and llvm::gsym::Header::NumAddresses.

Referenced by dump(), dump(), dump(), dump(), dump(), and dump().

◆ dump() [2/8]

◆ dump() [3/8]

◆ dump() [4/8]

◆ dump() [5/8]

◆ dump() [6/8]

◆ dump() [7/8]

◆ dump() [8/8]

◆ getAddress()

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

◆ getAddressIndex()

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 llvm::createStringError(), and getAddressOffsetIndex().

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.

◆ getAddressOffsetIndex()

template<class T>

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

◆ 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 296 of file GsymReader.h.

References T.

Referenced by addressForIndex(), and getAddressOffsetIndex().

◆ 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 172 of file GsymReader.h.

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

◆ getFunctionInfo()

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 llvm::gsym::FunctionInfo::decode(), and getFunctionInfoDataForAddress().

◆ getFunctionInfoAtIndex()

◆ getFunctionInfoDataAtIndex()

◆ getFunctionInfoDataForAddress()

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 contains(), llvm::createStringError(), getAddressIndex(), getFunctionInfoDataAtIndex(), getNumAddresses(), llvm::Offset, and llvm::Expected< T >::takeError().

Referenced by getFunctionInfo(), and lookup().

◆ getHeader()

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

◆ getString()

◆ lookup()

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 getFunctionInfoDataForAddress(), and llvm::gsym::FunctionInfo::lookup().

Referenced by lookupAll().

◆ lookupAll()

◆ openFile()

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