class GsymReader

Declaration

class GsymReader { /* full declaration omitted */ };

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(...).

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:47

Method Overview

• public GsymReader(llvm::gsym::GsymReader && RHS)
• protected template <class T>Optional<uint64_t> addressForIndex(size_t Index) const
• public static llvm::Expected<GsymReader> copyBuffer(llvm::StringRef Bytes)
• protected static llvm::Expected<llvm::gsym::GsymReader> create(std::unique_ptr<MemoryBuffer> & MemBuffer)
• protected template <class T>ArrayRef<T> getAddrOffsets() const
• protected Optional<uint64_t> getAddress(size_t Index) const
• protected Expected<uint64_t> getAddressIndex(const uint64_t Addr) const
• protected Optional<uint64_t> getAddressInfoOffset(size_t Index) const
• protected template <class T>uint64_t getAddressOffsetIndex(const uint64_t AddrOffset) const
• public Optional<llvm::gsym::FileEntry> getFile(uint32_t Index) const
• public llvm::Expected<FunctionInfo> getFunctionInfo(uint64_t Addr) const
• public const llvm::gsym::Header & getHeader() const
• public llvm::StringRef getString(uint32_t Offset) const
• public llvm::Expected<LookupResult> lookup(uint64_t Addr) const
• public static llvm::Expected<GsymReader> openFile(llvm::StringRef Path)
• public ~GsymReader()

Methods

¶GsymReader(llvm::gsym::GsymReader&& RHS)

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:72

Parameters

llvm::gsym::GsymReader&& RHS

¶template <class T>
Optional<uint64_t> addressForIndex(
    size_t Index) const

Description

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.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:189

Templates

T

Parameters

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

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

Description

Construct a GsymReader from a buffer.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:88

Parameters

llvm::StringRef 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.

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

Description

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.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:225

Parameters

std::unique_ptr<MemoryBuffer>& 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.

¶template <class T>
ArrayRef<T> getAddrOffsets() const

Description

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.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:171

Templates

T

Returns

An ArrayRef of an appropriate address offset size.

¶Optional<uint64_t> getAddress(size_t Index) const

Description

Gets an address from the address table. Addresses are stored as offsets frrom the gsym::Header::BaseAddress.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:158

Parameters

size_t Index

A 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.

¶Expected<uint64_t> getAddressIndex(
    const uint64_t Addr) const

Description

Given an address, find the address index. Binary search the address table and find the matching address index.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:237

Parameters

const uint64_t 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.

¶Optional<uint64_t> getAddressInfoOffset(
    size_t Index) const

Description

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.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:248

Parameters

size_t Index

An index into the address table.

Returns

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

¶template <class T>
uint64_t getAddressOffsetIndex(
    const uint64_t AddrOffset) const

Description

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

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:205

Templates

T

Parameters

const uint64_t 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.

¶Optional<llvm::gsym::FileEntry> getFile(
    uint32_t Index) const

Description

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.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:144

Parameters

uint32_t Index

An 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,

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

Description

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.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:110

Parameters

uint64_t 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.

¶const llvm::gsym::Header& getHeader() const

Description

Access the GSYM header.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:92

Returns

A native endian version of the GSYM header.

¶llvm::StringRef getString(uint32_t Offset) const

Description

Get a string from the string table.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:133

Parameters

uint32_t Offset

The string table offset for the string to retrieve.

Returns

The string from the strin table.

¶llvm::Expected<LookupResult> lookup(
    uint64_t Addr) const

Description

Lookup an address in the a GSYM. Lookup just the information needed for a specific address \a Addr. This function is faster that calling getFunctionInfo() as it will only return information that pertains to \a 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.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:127

Parameters

uint64_t Addr

A 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.

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

Description

Construct a GsymReader from a file on disk.

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:80

Parameters

llvm::StringRef 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.

¶~GsymReader()

Declared at: llvm/include/llvm/DebugInfo/GSYM/GsymReader.h:73