LLVM  11.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. More...
 
llvm::Expected< FunctionInfogetFunctionInfo (uint64_t Addr) const
 Get the full function info for an address. More...
 
llvm::Expected< LookupResultlookup (uint64_t Addr) const
 Lookup an address in the a GSYM. More...
 
StringRef getString (uint32_t Offset) const
 Get a string from the string table. More...
 
Optional< FileEntrygetFile (uint32_t Index) const
 Get the a file entry for the suppplied file index. More...
 
void dump (raw_ostream &OS)
 Dump the entire Gsym data contained in this object. More...
 
void dump (raw_ostream &OS, const FunctionInfo &FI)
 Dump a FunctionInfo object. More...
 
void dump (raw_ostream &OS, const LineTable &LT)
 Dump a LineTable object. More...
 
void dump (raw_ostream &OS, const InlineInfo &II, uint32_t Indent=0)
 Dump a InlineInfo object. More...
 
void dump (raw_ostream &OS, Optional< FileEntry > FE)
 Dump a FileEntry object. More...
 
uint32_t getNumAddresses () const
 Get the number of addresses in this Gsym file. More...
 
Optional< uint64_t > getAddress (size_t Index) const
 Gets an address from the address table. More...
 

Static Public Member Functions

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

Protected Member Functions

template<class T >
ArrayRef< TgetAddrOffsets () const
 Get an appropriate address info offsets array. More...
 
template<class T >
Optional< uint64_t > addressForIndex (size_t Index) const
 Get an appropriate address from the address table. More...
 
template<class T >
llvm::Optional< uint64_t > getAddressOffsetIndex (const uint64_t AddrOffset) const
 Lookup an address offset in the AddrOffsets table. More...
 
Expected< uint64_t > getAddressIndex (const uint64_t Addr) const
 Given an address, find the address index. More...
 
Optional< uint64_t > getAddressInfoOffset (size_t Index) const
 Given an address index, get the offset for the FunctionInfo. More...
 

Static Protected Member Functions

static llvm::Expected< llvm::gsym::GsymReadercreate (std::unique_ptr< MemoryBuffer > &MemBuffer)
 Create a GSYM from a memory buffer. More...
 

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

Constructor & Destructor Documentation

◆ GsymReader()

GsymReader::GsymReader ( GsymReader &&  RHS)
default

◆ ~GsymReader()

GsymReader::~GsymReader ( )
default

Member Function Documentation

◆ addressForIndex()

template<class T >
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 llvm::None if Index is out of bounds.

Definition at line 244 of file GsymReader.h.

References llvm::gsym::Header::BaseAddress, llvm::None, 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 44 of file GsymReader.cpp.

References 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 50 of file GsymReader.cpp.

References llvm::createStringError().

◆ 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 294 of file GsymReader.cpp.

References llvm::dump(), llvm::format(), HEX32, HEX64, I, and llvm::logAllUnhandledErrors().

Referenced by getFile().

◆ 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 349 of file GsymReader.cpp.

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

◆ dump() [3/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 357 of file GsymReader.cpp.

References llvm::dump(), HEX64, and llvm::AArch64CC::LE.

◆ dump() [4/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 367 of file GsymReader.cpp.

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

◆ dump() [5/5]

void GsymReader::dump ( raw_ostream OS,
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 385 of file GsymReader.cpp.

References llvm::gsym::FileEntry::Base, llvm::gsym::FileEntry::Dir, and llvm::StringRef::empty().

◆ getAddress()

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 llvm::None if Index is out of bounds.

Definition at line 209 of file GsymReader.cpp.

References llvm::None.

Referenced by getNumAddresses().

◆ 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 227 of file GsymReader.cpp.

References llvm::createStringError().

◆ getAddressInfoOffset()

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 219 of file GsymReader.cpp.

References llvm::None.

◆ getAddressOffsetIndex()

template<class T >
llvm::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 260 of file GsymReader.h.

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

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

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

◆ getFile()

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 llvm::None if the file index is out of bounds,

Definition at line 144 of file GsymReader.h.

References dump(), llvm::AArch64CC::LT, llvm::None, and llvm::ArrayRef< T >::size().

Referenced by 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 257 of file GsymReader.cpp.

References assert(), llvm::createStringError(), llvm::Data, llvm::gsym::FunctionInfo::decode(), and llvm::Expected< T >::takeError().

◆ getHeader()

const Header & GsymReader::getHeader ( ) const

Access the GSYM header.

Returns
A native endian version of the GSYM header.

Definition at line 201 of file GsymReader.cpp.

References assert().

◆ getNumAddresses()

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

Get the number of addresses in this Gsym file.

Definition at line 200 of file GsymReader.h.

References getAddress(), and llvm::gsym::Header::NumAddresses.

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

Referenced by 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 279 of file GsymReader.cpp.

References assert(), llvm::createStringError(), llvm::Data, llvm::gsym::FunctionInfo::lookup(), and llvm::Expected< T >::takeError().

◆ 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 34 of file GsymReader.cpp.

References llvm::MemoryBuffer::getFileOrSTDIN().

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


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