LLVM 20.0.0git
Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
llvm::gsym::Header Struct Reference

The GSYM header. More...

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

Public Member Functions

llvm::Error checkForError () const
 Check if a header is valid and return an error if anything is wrong.
 
llvm::Error encode (FileWriter &O) const
 Encode this object into FileWriter stream.
 

Static Public Member Functions

static llvm::Expected< Headerdecode (DataExtractor &Data)
 Decode an object from a binary data stream.
 

Public Attributes

uint32_t Magic
 The magic bytes should be set to GSYM_MAGIC.
 
uint16_t Version
 The version can number determines how the header is decoded and how each InfoType in FunctionInfo is encoded/decoded.
 
uint8_t AddrOffSize
 The size in bytes of each address offset in the address offsets table.
 
uint8_t UUIDSize
 The size in bytes of the UUID encoded in the "UUID" member.
 
uint64_t BaseAddress
 The 64 bit base address that all address offsets in the address offsets table are relative to.
 
uint32_t NumAddresses
 The number of addresses stored in the address offsets table.
 
uint32_t StrtabOffset
 The file relative offset of the start of the string table for strings contained in the GSYM file.
 
uint32_t StrtabSize
 The size in bytes of the string table.
 
uint8_t UUID [GSYM_MAX_UUID_SIZE]
 The UUID of the original executable file.
 

Detailed Description

The GSYM header.

The GSYM header is found at the start of a stand alone GSYM file, or as the first bytes in a section when GSYM is contained in a section of an executable file (ELF, mach-o, COFF).

The structure is encoded exactly as it appears in the structure definition with no gaps between members. Alignment should not change from system to system as the members were laid out so that they shouldn't align differently on different architectures.

When endianness of the system loading a GSYM file matches, the file can be mmap'ed in and a pointer to the header can be cast to the first bytes of the file (stand alone GSYM file) or section data (GSYM in a section). When endianness is swapped, the Header::decode() function should be used to decode the header.

Definition at line 45 of file Header.h.

Member Function Documentation

◆ checkForError()

llvm::Error Header::checkForError ( ) const

Check if a header is valid and return an error if anything is wrong.

Check the header and detect any errors.

This function can be used prior to encoding a header to ensure it is valid, or after decoding a header to ensure it is valid and supported.

Check a correctly byte swapped header for errors:

  • check magic value
  • check that version number is supported
  • check that the address offset size is supported
  • check that the UUID size is valid
Returns
An error if anything is wrong in the header, or Error::success() if there are no errors.

Definition at line 41 of file Header.cpp.

References AddrOffSize, llvm::createStringError(), llvm::gsym::GSYM_MAGIC, llvm::gsym::GSYM_MAX_UUID_SIZE, llvm::gsym::GSYM_VERSION, Magic, llvm::Error::success(), UUIDSize, and Version.

Referenced by encode().

◆ decode()

llvm::Expected< Header > Header::decode ( DataExtractor Data)
static

Decode an object from a binary data stream.

Parameters
DataThe binary stream to read the data from. This object must have the data for the object starting at offset zero. The data can contain more data than needed.
Returns
A Header or an error describing the issue that was encountered during decoding.

Definition at line 64 of file Header.cpp.

References llvm::createStringError(), llvm::Data, llvm::gsym::GSYM_MAX_UUID_SIZE, H, and llvm::Offset.

◆ encode()

llvm::Error Header::encode ( FileWriter O) const

Encode this object into FileWriter stream.

Parameters
OThe binary stream to write the data to at the current file position.
Returns
An error object that indicates success or failure of the encoding process.

Definition at line 85 of file Header.cpp.

References AddrOffSize, BaseAddress, checkForError(), Magic, NumAddresses, StrtabOffset, StrtabSize, llvm::Error::success(), UUIDSize, and Version.

Referenced by llvm::gsym::GsymCreator::encode().

Member Data Documentation

◆ AddrOffSize

uint8_t llvm::gsym::Header::AddrOffSize

The size in bytes of each address offset in the address offsets table.

Definition at line 56 of file Header.h.

Referenced by checkForError(), llvm::gsym::GsymReader::dump(), llvm::gsym::GsymCreator::encode(), encode(), llvm::gsym::GsymReader::getAddress(), and llvm::gsym::GsymReader::getAddressIndex().

◆ BaseAddress

uint64_t llvm::gsym::Header::BaseAddress

The 64 bit base address that all address offsets in the address offsets table are relative to.

Storing a full 64 bit address allows our address offsets table to be smaller on disk.

Definition at line 62 of file Header.h.

Referenced by llvm::gsym::GsymReader::addressForIndex(), llvm::gsym::GsymCreator::encode(), encode(), and llvm::gsym::GsymReader::getAddressIndex().

◆ Magic

uint32_t llvm::gsym::Header::Magic

The magic bytes should be set to GSYM_MAGIC.

This helps detect if a file is a GSYM file by scanning the first 4 bytes of a file or section. This value might appear byte swapped

Definition at line 49 of file Header.h.

Referenced by checkForError(), llvm::gsym::GsymCreator::encode(), and encode().

◆ NumAddresses

uint32_t llvm::gsym::Header::NumAddresses

The number of addresses stored in the address offsets table.

Definition at line 64 of file Header.h.

Referenced by llvm::gsym::GsymReader::dump(), llvm::gsym::GsymCreator::encode(), encode(), and llvm::gsym::GsymReader::getNumAddresses().

◆ StrtabOffset

uint32_t llvm::gsym::Header::StrtabOffset

The file relative offset of the start of the string table for strings contained in the GSYM file.

If the GSYM in contained in a stand alone file this will be the file offset of the start of the string table. If the GSYM is contained in a section within an executable file, this can be the offset of the first string used in the GSYM file and can possibly span one or more executable string tables. This allows the strings to share string tables in an ELF or mach-o file.

Definition at line 72 of file Header.h.

Referenced by llvm::gsym::GsymCreator::encode(), and encode().

◆ StrtabSize

uint32_t llvm::gsym::Header::StrtabSize

The size in bytes of the string table.

For a stand alone GSYM file, this will be the exact size in bytes of the string table. When the GSYM data is in a section within an executable file, this size can span one or more sections that contains strings. This allows any strings that are already stored in the executable file to be re-used, and any extra strings could be added to another string table and the string table offset and size can be set to span all needed string tables.

Definition at line 80 of file Header.h.

Referenced by llvm::gsym::GsymCreator::encode(), and encode().

◆ UUID

uint8_t llvm::gsym::Header::UUID[GSYM_MAX_UUID_SIZE]

The UUID of the original executable file.

This is stored to allow matching a GSYM file to an executable file when symbolication is required. Only the first "UUIDSize" bytes of the UUID are valid. Any bytes in the UUID value that appear after the first UUIDSize bytes should be set to zero.

Definition at line 86 of file Header.h.

Referenced by llvm::gsym::GsymCreator::encode().

◆ UUIDSize

uint8_t llvm::gsym::Header::UUIDSize

The size in bytes of the UUID encoded in the "UUID" member.

Definition at line 58 of file Header.h.

Referenced by checkForError(), llvm::gsym::GsymCreator::encode(), and encode().

◆ Version

uint16_t llvm::gsym::Header::Version

The version can number determines how the header is decoded and how each InfoType in FunctionInfo is encoded/decoded.

As version numbers increase, "Magic" and "Version" members should always appear at offset zero and 4 respectively to ensure clients figure out if they can parse the format.

Definition at line 54 of file Header.h.

Referenced by checkForError(), llvm::gsym::GsymCreator::encode(), and encode().


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