The GSYM V2 header. More...

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

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

Static Public Member Functions
static constexpr uint32_t	getVersion ()
	Return the version of this header.
static constexpr uint64_t	getEncodedSize ()
	Return the on-disk encoded size of the header in bytes.
static constexpr uint8_t	getAddressInfoOffsetSize ()
	Return the size in bytes of address info offsets.
static constexpr uint8_t	getStringOffsetSize ()
	Return the size in bytes of string table offsets.
static LLVM_ABI llvm::Expected< HeaderV2 >	decode (GsymDataExtractor &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 number determines how the header is decoded.
uint8_t	AddrOffSize
	The size in bytes of each address offset in the address offsets table.
StringTableEncoding	StrTableEncoding
	String table encoding. Allows for future encoding for string table.
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 and the address info offsets table.

Detailed Description

The GSYM V2 header.

The GSYM V2 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 header 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 are laid out so that they will align the same 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, HeaderV2::decode() is used to read the header.

The V2 file layout is: [HeaderV2 - 20 bytes fixed] [GlobalData entries - array of 20-byte entries, terminated by EndOfList] [Data sections at arbitrary file offsets, zero-padded for alignment]

Each GlobalData entry (see GlobalData.h) describes a section by its type, file offset, and file size. The sections can appear in any order in the file since each GlobalData entry contains an offset from the first byte of the GSYM header. The GlobalData array is terminated by an entry with type EndOfList and all other fields set to zero. See GlobalInfoType (in GlobalData.h) for all section types.

Definition at line 60 of file HeaderV2.h.

Member Function Documentation

◆ checkForError()

llvm::Error HeaderV2::checkForError ( ) const

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

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 string table encoding is supported

Returns: An error if anything is wrong in the header, or Error::success() if there are no errors.

Definition at line 35 of file HeaderV2.cpp.

References AddrOffSize, llvm::createStringError(), llvm::gsym::Default, getVersion(), llvm::gsym::GSYM_MAGIC, Magic, StrTableEncoding, llvm::Error::success(), and Version.

Referenced by encode().

◆ decode()

llvm::Expected< HeaderV2 > HeaderV2::decode ( GsymDataExtractor & Data )

static

Decode an object from a binary data stream.

Parameters

Data	The 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 HeaderV2 or an error describing the issue that was encountered during decoding.

Definition at line 56 of file HeaderV2.cpp.

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

◆ encode()

llvm::Error HeaderV2::encode ( FileWriter & O ) const

Encode this object into FileWriter stream.

Parameters

O	The 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 77 of file HeaderV2.cpp.

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

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

◆ getAddressInfoOffsetSize()

constexpr uint8_t llvm::gsym::HeaderV2::getAddressInfoOffsetSize ( )

inlinestaticconstexpr

Return the size in bytes of address info offsets.

Definition at line 90 of file HeaderV2.h.

Referenced by llvm::gsym::GsymReaderV2::getAddressInfoOffsetSize().

◆ getEncodedSize()

constexpr uint64_t llvm::gsym::HeaderV2::getEncodedSize ( )

inlinestaticconstexpr

Return the on-disk encoded size of the header in bytes.

This may differ from sizeof(HeaderV2) due to struct padding at the end.

Definition at line 87 of file HeaderV2.h.

Referenced by decode(), llvm::gsym::GsymReaderV2::dump(), llvm::gsym::GsymCreatorV2::encode(), and llvm::gsym::GsymReaderV2::parseHeaderAndGlobalDataEntries().

◆ getStringOffsetSize()

constexpr uint8_t llvm::gsym::HeaderV2::getStringOffsetSize ( )

inlinestaticconstexpr

Return the size in bytes of string table offsets.

Definition at line 93 of file HeaderV2.h.

Referenced by llvm::gsym::GsymCreatorV2::getStringOffsetSize(), and llvm::gsym::GsymReaderV2::getStringOffsetSize().

◆ getVersion()

constexpr uint32_t llvm::gsym::HeaderV2::getVersion ( )

inlinestaticconstexpr

Return the version of this header.

Definition at line 83 of file HeaderV2.h.

Referenced by checkForError(), llvm::gsym::GsymReader::create(), llvm::gsym::GsymCreatorV2::encode(), llvm::gsym::GsymReaderV2::getVersion(), and llvm::gsym::GsymReader::parseGlobalDataEntries().

Member Data Documentation

◆ AddrOffSize

uint8_t llvm::gsym::HeaderV2::AddrOffSize

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

Definition at line 71 of file HeaderV2.h.

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

◆ BaseAddress

uint64_t llvm::gsym::HeaderV2::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 77 of file HeaderV2.h.

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

◆ Magic

uint32_t llvm::gsym::HeaderV2::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 when endianness is swapped.

Definition at line 64 of file HeaderV2.h.

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

◆ NumAddresses

uint32_t llvm::gsym::HeaderV2::NumAddresses

The number of addresses stored in the address offsets table and the address info offsets table.

Definition at line 80 of file HeaderV2.h.

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

◆ StrTableEncoding

StringTableEncoding llvm::gsym::HeaderV2::StrTableEncoding

String table encoding. Allows for future encoding for string table.

Definition at line 73 of file HeaderV2.h.

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

◆ Version

uint16_t llvm::gsym::HeaderV2::Version

The version number determines how the header is 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 69 of file HeaderV2.h.

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

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

include/llvm/DebugInfo/GSYM/HeaderV2.h
lib/DebugInfo/GSYM/HeaderV2.cpp

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ checkForError()

◆ decode()

◆ encode()

◆ getAddressInfoOffsetSize()

◆ getEncodedSize()

◆ getStringOffsetSize()

◆ getVersion()

Member Data Documentation

◆ AddrOffSize

◆ BaseAddress

◆ Magic

◆ NumAddresses

◆ StrTableEncoding

◆ Version