LLVM 19.0.0git
Classes | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | List of all members
llvm::gsym::GsymReader Class Reference

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 HeadergetHeader () const
 Access the GSYM header.
 
llvm::Expected< FunctionInfogetFunctionInfo (uint64_t Addr) const
 Get the full function info for an address.
 
llvm::Expected< FunctionInfogetFunctionInfoAtIndex (uint64_t AddrIdx) const
 Get the full function info given an address index.
 
llvm::Expected< LookupResultlookup (uint64_t Addr) const
 Lookup an address in the a GSYM.
 
StringRef getString (uint32_t Offset) const
 Get a string from the string table.
 
std::optional< FileEntrygetFile (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)
 Dump a FunctionInfo object.
 
void dump (raw_ostream &OS, const LineTable &LT)
 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_tgetAddress (size_t Index) const
 Gets an address from the address table.
 

Static Public Member Functions

static llvm::Expected< GsymReaderopenFile (StringRef Path)
 Construct a GsymReader from a file on disk.
 
static llvm::Expected< GsymReadercopyBuffer (StringRef Bytes)
 Construct a GsymReader from a buffer.
 

Protected Member Functions

template<class T >
ArrayRef< TgetAddrOffsets () const
 Get an appropriate address info offsets array.
 
template<class T >
std::optional< uint64_taddressForIndex (size_t Index) const
 Get an appropriate address from the address table.
 
template<class T >
std::optional< uint64_tgetAddressOffsetIndex (const uint64_t AddrOffset) const
 Lookup an address offset in the AddrOffsets table.
 
Expected< uint64_tgetAddressIndex (const uint64_t Addr) const
 Given an address, find the address index.
 
std::optional< uint64_tgetAddressInfoOffset (size_t Index) const
 Given an address index, get the offset for the FunctionInfo.
 
llvm::Expected< llvm::DataExtractorgetFunctionInfoDataForAddress (uint64_t Addr, uint64_t &FuncStartAddr) const
 Given an address, find the correct function info data and function address.
 
llvm::Expected< llvm::DataExtractorgetFunctionInfoDataAtIndex (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::GsymReadercreate (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
IndexAn 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 250 of file GsymReader.h.

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

◆ copyBuffer()

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

Construct a GsymReader from a buffer.

Parameters
BytesA 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 43 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
MemBufferA 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 49 of file GsymReader.cpp.

References llvm::createStringError().

Referenced by copyBuffer(), and openFile().

◆ dump() [1/5]

void GsymReader::dump ( raw_ostream OS)

Dump the entire Gsym data contained in this object.

Parameters
OSThe output stream to dump to.

Definition at line 346 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/5]

void GsymReader::dump ( raw_ostream OS,
const FunctionInfo FI 
)

Dump a FunctionInfo object.

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

Parameters
OSThe output stream to dump to.
FIThe object to dump.

Definition at line 401 of file GsymReader.cpp.

References dump(), getString(), llvm::gsym::FunctionInfo::Inline, llvm::gsym::FunctionInfo::Name, llvm::gsym::FunctionInfo::OptLineTable, OS, and llvm::gsym::FunctionInfo::Range.

◆ dump() [3/5]

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
OSThe output stream to dump to.
IIThe object to dump.
IndentThe indentation as number of spaces. Used for recurive dumping.

Definition at line 419 of file GsymReader.cpp.

References llvm::gsym::InlineInfo::CallFile, llvm::gsym::InlineInfo::CallLine, llvm::gsym::InlineInfo::Children, dump(), getFile(), getString(), llvm::raw_ostream::indent(), llvm::gsym::InlineInfo::Name, OS, and llvm::gsym::InlineInfo::Ranges.

◆ dump() [4/5]

void GsymReader::dump ( raw_ostream OS,
const LineTable LT 
)

Dump a LineTable object.

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

Parameters
OSThe output stream to dump to.
LTThe object to dump.

Definition at line 409 of file GsymReader.cpp.

References dump(), getFile(), HEX64, and OS.

◆ dump() [5/5]

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
OSThe output stream to dump to.
FEThe object to dump.

Definition at line 437 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
IndexA 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 208 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
AddrA 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 226 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
IndexAn 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 218 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
AddrOffsetAn 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 267 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 232 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
IndexAn 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 150 of file GsymReader.h.

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
AddrA 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 321 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
AddrIdxA 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 330 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
AddrIdxA 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 300 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]AddrA virtual address that matches the original object file to lookup.
[out]FuncStartAddrA 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 257 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 200 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 206 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
OffsetThe string table offset for the string to retrieve.
Returns
The string from the strin table.

Definition at line 139 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) 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
AddrA virtual address from the orignal object file to lookup.
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().

◆ openFile()

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

Construct a GsymReader from a file on disk.

Parameters
PathThe 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 33 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: