GsymCreator is used to emit GSYM data to a stand alone file or section within a file. More...

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

Inheritance diagram for llvm::gsym::GsymCreator:

Public Member Functions
LLVM_ABI	GsymCreator (bool Quiet=false)
virtual	~GsymCreator ()=default
virtual uint8_t	getStringOffsetSize () const =0
	Get the size in bytes needed for encoding string offsets.
LLVM_ABI llvm::Error	save (StringRef Path, llvm::endianness ByteOrder, std::optional< uint64_t > SegmentSize=std::nullopt) const
	Save a GSYM file to a stand alone file.
virtual llvm::Error	encode (FileWriter &O) const =0
	Encode a GSYM into the file writer stream at the current position.
LLVM_ABI gsym_strp_t	insertString (StringRef S, bool Copy=true)
	Insert a string into the GSYM string table.
LLVM_ABI StringRef	getString (gsym_strp_t Offset)
	Retrieve a string from the GSYM string table given its offset.
LLVM_ABI uint32_t	insertFile (StringRef Path, sys::path::Style Style=sys::path::Style::native)
	Insert a file into this GSYM creator.
LLVM_ABI void	addFunctionInfo (FunctionInfo &&FI)
	Add a function info to this GSYM creator.
LLVM_ABI llvm::Error	loadCallSitesFromYAML (StringRef YAMLFile)
	Load call site information from a YAML file.
LLVM_ABI void	prepareMergedFunctions (OutputAggregator &Out)
	Organize merged FunctionInfo's.
LLVM_ABI llvm::Error	finalize (OutputAggregator &OS)
	Finalize the data in the GSYM creator prior to saving the data out.
void	setUUID (llvm::ArrayRef< uint8_t > UUIDBytes)
	Set the UUID value.
LLVM_ABI void	forEachFunctionInfo (std::function< bool(FunctionInfo &)> const &Callback)
	Thread safe iteration over all function infos.
LLVM_ABI void	forEachFunctionInfo (std::function< bool(const FunctionInfo &)> const &Callback) const
	Thread safe const iteration over all function infos.
LLVM_ABI size_t	getNumFunctionInfos () const
	Get the current number of FunctionInfo objects contained in this object.
void	SetValidTextRanges (AddressRanges &TextRanges)
	Set valid .text address ranges that all functions must be contained in.
const std::optional< AddressRanges >	GetValidTextRanges () const
	Get the valid text ranges.
LLVM_ABI bool	IsValidTextAddress (uint64_t Addr) const
	Check if an address is a valid code address.
void	setBaseAddress (uint64_t Addr)
	Set the base address to use for the GSYM file.
bool	isQuiet () const
	Whether the transformation should be quiet, i.e. not output warnings.
LLVM_ABI llvm::Expected< std::unique_ptr< GsymCreator > >	createSegment (uint64_t SegmentSize, size_t &FuncIdx) const
	Create a segmented GSYM creator starting with function info index FuncIdx.

Protected Member Functions
std::optional< uint64_t >	getFirstFunctionAddress () const
	Get the first function start address.
std::optional< uint64_t >	getLastFunctionAddress () const
	Get the last function address.
std::optional< uint64_t >	getBaseAddress () const
	Get the base address to use for this GSYM file.
uint8_t	getAddressOffsetSize () const
	Get the size of an address offset in the address offset table.
uint64_t	getMaxAddressOffset () const
	Get the maximum address offset for the current address offset size.
virtual uint64_t	calculateHeaderAndTableSize () const =0
	Calculate the byte size of the GSYM header and tables sizes.
uint64_t	copyFunctionInfo (const GsymCreator &SrcGC, size_t FuncInfoIdx)
	Copy a FunctionInfo from the SrcGC GSYM creator into this creator.
gsym_strp_t	copyString (const GsymCreator &SrcGC, gsym_strp_t StrOff)
	Copy a string from SrcGC into this object.
uint32_t	copyFile (const GsymCreator &SrcGC, uint32_t FileIdx)
	Copy a file from SrcGC into this object.
uint32_t	insertFileEntry (FileEntry FE)
	Inserts a FileEntry into the file table.
void	fixupInlineInfo (const GsymCreator &SrcGC, InlineInfo &II)
	Fixup any string and file references by updating any file indexes and strings offsets in the InlineInfo parameter.
llvm::Error	saveSegments (StringRef Path, llvm::endianness ByteOrder, uint64_t SegmentSize) const
	Save this GSYM file into segments that are roughly SegmentSize in size.
void	setIsSegment ()
	Let this creator know that this is a segment of another GsymCreator.
llvm::Error	validateForEncoding (std::optional< uint64_t > &BaseAddr) const
	Validate that the creator is ready for encoding.
void	encodeAddrOffsets (FileWriter &O, uint8_t AddrOffSize, uint64_t BaseAddr) const
	Write the address offsets table to the output stream.
llvm::Error	encodeFileTable (FileWriter &O) const
	Write the file table to the output stream.
virtual std::unique_ptr< GsymCreator >	createNew (bool Quiet) const =0
	Create a new empty creator of the same version.

Protected Attributes
std::mutex	Mutex
std::vector< FunctionInfo >	Funcs
StringTableBuilder	StrTab
StringSet	StringStorage
DenseMap< llvm::gsym::FileEntry, uint32_t >	FileEntryToIndex
DenseMap< uint64_t, CachedHashStringRef >	StringOffsetMap
std::vector< llvm::gsym::FileEntry >	Files
std::vector< uint8_t >	UUID
std::optional< AddressRanges >	ValidTextRanges
std::optional< uint64_t >	BaseAddress
bool	IsSegment = false
bool	Finalized = false
bool	Quiet

Detailed Description

GsymCreator is used to emit GSYM data to a stand alone file or section within a file.

The GsymCreator is designed to be used in 3 stages:

Create FunctionInfo objects and add them
Finalize the GsymCreator object
Save to file or section

The first stage involves creating FunctionInfo objects from another source of information like compiler debug info metadata, DWARF or Breakpad files. Any strings in the FunctionInfo or contained information, like InlineInfo or LineTable objects, should get the string table offsets by calling GsymCreator::insertString(...). Any file indexes that are needed should be obtained by calling GsymCreator::insertFile(...). All of the function calls in GsymCreator are thread safe. This allows multiple threads to create and add FunctionInfo objects while parsing debug information.

Once all of the FunctionInfo objects have been added, the GsymCreator::finalize(...) must be called prior to saving. This function will sort the FunctionInfo objects, finalize the string table, and do any other passes on the information needed to prepare the information to be saved.

Once the object has been finalized, it can be saved to a file or section.

ENCODING

GSYM files are designed to be memory mapped into a process as shared, read only data, and used as is.

The GSYM file format when in a stand alone file consists of:

Header
Address Table
Function Info Offsets
File Table
String Table
Function Info Data

HEADER

The header is fully described in "llvm/DebugInfo/GSYM/Header.h".

ADDRESS TABLE

The address table immediately follows the header in the file and consists of Header.NumAddresses address offsets. These offsets are sorted and can be binary searched for efficient lookups. Addresses in the address table are stored as offsets from a 64 bit base address found in Header.BaseAddress. This allows the address table to contain 8, 16, or 32 offsets. This allows the address table to not require full 64 bit addresses for each address. The resulting GSYM size is smaller and causes fewer pages to be touched during address lookups when the address table is smaller. The size of the address offsets in the address table is specified in the header in Header.AddrOffSize. The first offset in the address table is aligned to Header.AddrOffSize alignment to ensure efficient access when loaded into memory.

FUNCTION INFO OFFSETS TABLE

The function info offsets table immediately follows the address table and consists of Header.NumAddresses 32 bit file offsets: one for each address in the address table. This data is aligned to a 4 byte boundary. The offsets in this table are the relative offsets from the start offset of the GSYM header and point to the function info data for each address in the address table. Keeping this data separate from the address table helps to reduce the number of pages that are touched when address lookups occur on a GSYM file.

FILE TABLE

The file table immediately follows the function info offsets table. The encoding of the FileTable is:

struct FileTable { uint32_t Count; FileEntry Files[]; };

The file table starts with a 32 bit count of the number of files that are used in all of the function info, followed by that number of FileEntry structures. The file table is aligned to a 4 byte boundary, Each file in the file table is represented with a FileEntry structure. See "llvm/DebugInfo/GSYM/FileEntry.h" for details.

STRING TABLE

The string table follows the file table in stand alone GSYM files and contains all strings for everything contained in the GSYM file. Any string data should be added to the string table and any references to strings inside GSYM information must be stored as 32 bit string table offsets into this string table. The string table always starts with an empty string at offset zero and is followed by any strings needed by the GSYM information. The start of the string table is not aligned to any boundary.

FUNCTION INFO DATA

The function info data is the payload that contains information about the address that is being looked up. It contains all of the encoded FunctionInfo objects. Each encoded FunctionInfo's data is pointed to by an entry in the Function Info Offsets Table. For details on the exact encoding of FunctionInfo objects, see "llvm/DebugInfo/GSYM/FunctionInfo.h".

Definition at line 135 of file GsymCreator.h.

Constructor & Destructor Documentation

◆ GsymCreator()

GsymCreator::GsymCreator ( bool Quiet = false )

Definition at line 24 of file GsymCreator.cpp.

References insertFile(), Quiet, and StrTab.

Referenced by calculateHeaderAndTableSize(), copyFile(), copyFunctionInfo(), copyString(), fixupInlineInfo(), llvm::gsym::GsymCreatorV1::GsymCreatorV1(), llvm::gsym::GsymCreatorV2::GsymCreatorV2(), and saveSegments().

◆ ~GsymCreator()

virtual llvm::gsym::GsymCreator::~GsymCreator ( )

virtualdefault

Member Function Documentation

◆ addFunctionInfo()

void GsymCreator::addFunctionInfo ( FunctionInfo && FI )

Add a function info to this GSYM creator.

All information in the FunctionInfo object must use the GsymCreator::insertString(...) function when creating string table offsets for names and other strings.

Parameters

FI	The function info object to emplace into our functions list.

Definition at line 286 of file GsymCreator.cpp.

References Funcs, and Mutex.

Referenced by llvm::gsym::ObjectFileTransformer::convert().

◆ calculateHeaderAndTableSize()

virtual uint64_t llvm::gsym::GsymCreator::calculateHeaderAndTableSize ( ) const

protectedpure virtual

Calculate the byte size of the GSYM header and tables sizes.

This is used to help split GSYM files into segments.

Returns: Size in bytes the GSYM header and tables.

References GsymCreator(), and II.

◆ copyFile()

uint32_t GsymCreator::copyFile	(	const GsymCreator &	SrcGC,
		uint32_t	FileIdx )

protected

Copy a file from SrcGC into this object.

Copy a file from SrcGC by file index into this GSYM creator. Files consist of two string table entries, one for the directory and one for the filename, this function will copy any needed strings ensure the file is uniqued within this object. If a file already exists in this GSYM creator the uniqued index will be returned, else the stirngs will be copied and the new file index will be returned.

Parameters

SrcGC	The source gsym creator to copy from.
FileIdx	The 1 based file table index within SrcGC to copy. A file index of zero will always return zero as the zero is a reserved file index that means no file.

Returns: The new file index of the file within this object.

Definition at line 51 of file GsymCreator.cpp.

References llvm::gsym::FileEntry::Base, llvm::sampleprof::Base, llvm::gsym::FileEntry::Dir, Files, GsymCreator(), insertFileEntry(), StringOffsetMap, and StrTab.

Referenced by copyFunctionInfo(), and fixupInlineInfo().

◆ copyFunctionInfo()

uint64_t GsymCreator::copyFunctionInfo	(	const GsymCreator &	SrcGC,
		size_t	FuncInfoIdx )

protected

Copy a FunctionInfo from the SrcGC GSYM creator into this creator.

Copy the function info and only the needed files and strings and add a converted FunctionInfo into this object. This is used to segment GSYM files into separate files while only transferring the files and strings that are needed from SrcGC.

Parameters

SrcGC	The source gsym creator to copy from.
FuncInfoIdx	The function info index within SrcGC to copy.

Returns: The number of bytes it will take to encode the function info in this GsymCreator. This helps calculate the size of the current GSYM segment file.

Definition at line 445 of file GsymCreator.cpp.

References copyFile(), copyString(), fixupInlineInfo(), Funcs, llvm::gsym::LineTable::get(), GsymCreator(), I, llvm::gsym::FunctionInfo::Inline, Mutex, llvm::gsym::FunctionInfo::Name, llvm::gsym::FunctionInfo::OptLineTable, llvm::gsym::FunctionInfo::Range, and llvm::gsym::LineTable::size().

◆ copyString()

gsym_strp_t GsymCreator::copyString	(	const GsymCreator &	SrcGC,
		gsym_strp_t	StrOff )

protected

Copy a string from SrcGC into this object.

Copy a string from SrcGC by string table offset into this GSYM creator. If a string has already been copied, the uniqued string table offset will be returned, otherwise the string will be copied and a unique offset will be returned.

Parameters

SrcGC	The source gsym creator to copy from.
StrOff	The string table offset from SrcGC to copy.

Returns: The new string table offset of the string within this object.

Definition at line 245 of file GsymCreator.cpp.

References GsymCreator(), StringOffsetMap, and StrTab.

Referenced by copyFunctionInfo(), and fixupInlineInfo().

◆ createNew()

virtual std::unique_ptr< GsymCreator > llvm::gsym::GsymCreator::createNew ( bool Quiet ) const

protectedpure virtual

Create a new empty creator of the same version.

Used by createSegment() to create segment creators of the correct version type.

References LLVM_ABI, and Quiet.

Referenced by createSegment().

◆ createSegment()

llvm::Expected< std::unique_ptr< GsymCreator > > GsymCreator::createSegment	(	uint64_t	SegmentSize,
		size_t &	FuncIdx ) const

Create a segmented GSYM creator starting with function info index FuncIdx.

This function will create a GsymCreator object that will encode into roughly SegmentSize bytes and return it. It is used by the private saveSegments(...) function and also is used by the GSYM unit tests to test segmenting of GSYM files. The returned GsymCreator can be finalized and encoded.

Parameters

[in]	SegmentSize	The size in bytes to roughly segment the GSYM file into.
[in,out]	FuncIdx	The index of the first function info to encode into the returned GsymCreator. This index will be updated so it can be used in subsequent calls to this function to allow more segments to be created.

Returns: An expected unique pointer to a GsymCreator or an error. The returned unique pointer can be NULL if there are no more functions to encode.

Definition at line 517 of file GsymCreator.cpp.

References llvm::alignTo(), BaseAddress, createNew(), llvm::createStringError(), Funcs, and UUID.

Referenced by saveSegments().

◆ encode()

virtual llvm::Error llvm::gsym::GsymCreator::encode ( FileWriter & O ) const

pure virtual

Encode a GSYM into the file writer stream at the current position.

Parameters

O	The stream to save the binary data to

Returns: An error object that indicates success or failure of the save.

Implemented in llvm::gsym::GsymCreatorV1, and llvm::gsym::GsymCreatorV2.

References LLVM_ABI, llvm::sys::path::native, and llvm::Offset.

Referenced by save().

◆ encodeAddrOffsets()

void GsymCreator::encodeAddrOffsets	(	FileWriter &	O,
		uint8_t	AddrOffSize,
		uint64_t	BaseAddr ) const

protected

Write the address offsets table to the output stream.

Parameters

O	The file writer to write to.
AddrOffSize	The byte width of each address offset.
BaseAddr	The base address to subtract from each function address.

Definition at line 390 of file GsymCreator.cpp.

References assert(), Funcs, getMaxAddressOffset(), and llvm_unreachable.

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

◆ encodeFileTable()

llvm::Error GsymCreator::encodeFileTable ( FileWriter & O ) const

protected

Write the file table to the output stream.

Parameters

O	The file writer to write to.

Returns: An error if the file table is too large, or Error::success().

Definition at line 421 of file GsymCreator.cpp.

References assert(), llvm::sampleprof::Base, llvm::createStringError(), Files, and llvm::Error::success().

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

◆ finalize()

llvm::Error GsymCreator::finalize ( OutputAggregator & OS )

Finalize the data in the GSYM creator prior to saving the data out.

Finalize must be called after all FunctionInfo objects have been added and before GsymCreator::save() is called.

Parameters

OS	Output stream to report duplicate function infos, overlapping function infos, and function infos that were merged or removed.

Returns: An error object that indicates success or failure of the finalize.

Definition at line 130 of file GsymCreator.cpp.

References llvm::AddressRange::contains(), llvm::createStringError(), Finalized, Funcs, llvm::gsym::FunctionInfo::hasRichInfo(), llvm::AddressRange::intersects(), IsSegment, Mutex, llvm::gsym::FunctionInfo::Range, Range, llvm::gsym::OutputAggregator::Report(), llvm::AddressRange::size(), llvm::stable_sort(), llvm::AddressRange::start(), StrTab, llvm::Error::success(), std::swap(), and ValidTextRanges.

◆ fixupInlineInfo()

void GsymCreator::fixupInlineInfo	(	const GsymCreator &	SrcGC,
		InlineInfo &	II )

protected

Fixup any string and file references by updating any file indexes and strings offsets in the InlineInfo parameter.

When copying InlineInfo entries, we can simply make a copy of the object and then fixup the files and strings for efficiency.

Parameters

SrcGC	The source gsym creator to copy from.
II	The inline info that contains file indexes and string offsets that come from SrcGC. The entries will be updated by coping any files and strings over into this object.

Definition at line 438 of file GsymCreator.cpp.

References copyFile(), copyString(), fixupInlineInfo(), GsymCreator(), and II.

Referenced by copyFunctionInfo(), and fixupInlineInfo().

◆ forEachFunctionInfo() [1/2]

void GsymCreator::forEachFunctionInfo ( std::function< bool(const FunctionInfo &)> const & Callback ) const

Thread safe const iteration over all function infos.

Parameters

Callback A callback function that will get called with each FunctionInfo. If the callback returns false, stop iterating.

Definition at line 300 of file GsymCreator.cpp.

References Funcs, and Mutex.

◆ forEachFunctionInfo() [2/2]

void GsymCreator::forEachFunctionInfo ( std::function< bool(FunctionInfo &)> const & Callback )

Thread safe iteration over all function infos.

Parameters

Callback A callback function that will get called with each FunctionInfo. If the callback returns false, stop iterating.

Definition at line 291 of file GsymCreator.cpp.

References Funcs, and Mutex.

◆ getAddressOffsetSize()

uint8_t GsymCreator::getAddressOffsetSize ( ) const

protected

Get the size of an address offset in the address offset table.

GSYM files store offsets from the base address in the address offset table and we store the size of the address offsets in the GSYM header. This function will calculate the size in bytes of these address offsets based on the current contents of the GSYM file.

Returns: The size in byets of the address offsets.

Definition at line 356 of file GsymCreator.cpp.

References BaseAddress, getBaseAddress(), and getLastFunctionAddress().

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

◆ getBaseAddress()

std::optional< uint64_t > GsymCreator::getBaseAddress ( ) const

protected

Get the base address to use for this GSYM file.

Returns: The base address to put into the header and to use when creating the address offset table or std::nullpt if there are no valid function infos or if the base address wasn't specified.

Definition at line 340 of file GsymCreator.cpp.

References BaseAddress, and getFirstFunctionAddress().

Referenced by getAddressOffsetSize(), and validateForEncoding().

◆ getFirstFunctionAddress()

std::optional< uint64_t > GsymCreator::getFirstFunctionAddress ( ) const

protected

Get the first function start address.

Returns: The start address of the first FunctionInfo or std::nullopt if there are no function infos.

Definition at line 320 of file GsymCreator.cpp.

References Finalized, Funcs, and IsSegment.

Referenced by getBaseAddress().

◆ getLastFunctionAddress()

std::optional< uint64_t > GsymCreator::getLastFunctionAddress ( ) const

protected

Get the last function address.

Returns: The start address of the last FunctionInfo or std::nullopt if there are no function infos.

Definition at line 330 of file GsymCreator.cpp.

References Finalized, Funcs, and IsSegment.

Referenced by getAddressOffsetSize().

◆ getMaxAddressOffset()

uint64_t GsymCreator::getMaxAddressOffset ( ) const

protected

Get the maximum address offset for the current address offset size.

This is used when creating the address offset table to ensure we have values that are in range so we don't end up truncating address offsets when creating GSYM files as the code evolves.

Returns: The maximum address offset value that will be encoded into a GSYM file.

Definition at line 346 of file GsymCreator.cpp.

References getAddressOffsetSize(), llvm_unreachable, and UINT64_MAX.

Referenced by encodeAddrOffsets().

◆ getNumFunctionInfos()

size_t GsymCreator::getNumFunctionInfos ( ) const

Get the current number of FunctionInfo objects contained in this object.

Definition at line 309 of file GsymCreator.cpp.

References Funcs, and Mutex.

Referenced by llvm::gsym::ObjectFileTransformer::convert().

◆ getString()

StringRef GsymCreator::getString ( gsym_strp_t Offset )

Retrieve a string from the GSYM string table given its offset.

The offset is assumed to be a valid offset into the string table. otherwise an assert will be triggered.

Parameters

Offset The offset of the string to retrieve, previously returned by insertString.

Returns: The string at the given offset in the string table.

Definition at line 279 of file GsymCreator.cpp.

References assert(), I, llvm::Offset, and StringOffsetMap.

◆ getStringOffsetSize()

virtual uint8_t llvm::gsym::GsymCreator::getStringOffsetSize ( ) const

pure virtual

Get the size in bytes needed for encoding string offsets.

Implemented in llvm::gsym::GsymCreatorV1, and llvm::gsym::GsymCreatorV2.

References LLVM_ABI.

Referenced by save().

◆ GetValidTextRanges()

const std::optional< AddressRanges > llvm::gsym::GsymCreator::GetValidTextRanges ( ) const

inline

Get the valid text ranges.

Definition at line 453 of file GsymCreator.h.

References ValidTextRanges.

◆ insertFile()

uint32_t GsymCreator::insertFile	(	StringRef	Path,
		sys::path::Style	Style = sys::path::Style::native )

Insert a file into this GSYM creator.

Inserts a file by adding a FileEntry into the "Files" member variable if the file has not already been added. The file path is split into directory and filename which are both added to the string table. This allows paths to be stored efficiently by reusing the directories that are common between multiple files.

Parameters

Path	The path to the file to insert.
Style	The path style for the "Path" parameter.

Returns: The unique file index for the inserted file.

Definition at line 29 of file GsymCreator.cpp.

References llvm::sampleprof::Base, llvm::sys::path::filename(), insertFileEntry(), insertString(), and llvm::sys::path::parent_path().

Referenced by convertFunctionLineTable(), llvm::gsym::CUInfo::DWARFToGSYMFileIndex(), and GsymCreator().

◆ insertFileEntry()

uint32_t GsymCreator::insertFileEntry ( FileEntry FE )

protected

Inserts a FileEntry into the file table.

This is used to insert a file entry in a thread safe way into this object.

Parameters

FE	A file entry object that contains valid string table offsets from this object already.

Definition at line 41 of file GsymCreator.cpp.

References FileEntryToIndex, Files, and Mutex.

Referenced by copyFile(), and insertFile().

◆ insertString()

gsym_strp_t GsymCreator::insertString	(	StringRef	S,
		bool	Copy = true )

Insert a string into the GSYM string table.

All strings used by GSYM files must be uniqued by adding them to this string pool and using the returned offset for any string values.

Parameters

S	The string to insert into the string table.
Copy	If true, then make a backing copy of the string. If false, the string is owned by another object that will stay around long enough for the GsymCreator to save the GSYM file.

Returns: The unique 32 bit offset into the string table.

Definition at line 253 of file GsymCreator.cpp.

References llvm::StringRef::empty(), llvm::CachedHashStringRef::hash(), Mutex, StringOffsetMap, StringStorage, and StrTab.

Referenced by llvm::gsym::ObjectFileTransformer::convert(), getQualifiedNameIndex(), and insertFile().

◆ isQuiet()

bool llvm::gsym::GsymCreator::isQuiet ( ) const

inline

Whether the transformation should be quiet, i.e. not output warnings.

Definition at line 494 of file GsymCreator.h.

References Quiet.

◆ IsValidTextAddress()

bool GsymCreator::IsValidTextAddress ( uint64_t Addr ) const

Check if an address is a valid code address.

Any functions whose addresses do not exist within these function bounds will not be converted into the final GSYM. This allows the object file to figure out the valid file address ranges of all the code sections and ensure we don't add invalid functions to the final output. Many linkers have issues when dead stripping functions from DWARF debug info where they set the DW_AT_low_pc to zero, but newer DWARF has the DW_AT_high_pc as an offset from the DW_AT_low_pc and these size attributes have no relocations that can be applied. This results in DWARF where many functions have an DW_AT_low_pc of zero and a valid offset size for DW_AT_high_pc. If we extract all valid ranges from an object file that are marked with executable permissions, we can properly ensure that these functions are removed.

Parameters

Addr	An address to check.

Returns: True if the address is in the valid text ranges or if no valid text ranges have been set, false otherwise.

Definition at line 314 of file GsymCreator.cpp.

References ValidTextRanges.

Referenced by llvm::gsym::ObjectFileTransformer::convert().

◆ loadCallSitesFromYAML()

llvm::Error GsymCreator::loadCallSitesFromYAML ( StringRef YAMLFile )

Load call site information from a YAML file.

This function reads call site information from a specified YAML file and adds it to the GSYM data.

Parameters

YAMLFile The path to the YAML file containing call site information.

Definition at line 81 of file GsymCreator.cpp.

References Funcs, and llvm::gsym::CallSiteInfoLoader::loadYAML().

◆ prepareMergedFunctions()

void GsymCreator::prepareMergedFunctions ( OutputAggregator & Out )

Organize merged FunctionInfo's.

This method processes the list of function infos (Funcs) to identify and group functions with overlapping address ranges.

Parameters

Out	Output stream to report information about how merged FunctionInfo's were handled.

Definition at line 87 of file GsymCreator.cpp.

References Funcs, llvm::gsym::FunctionInfo::MergedFunctions, MergedFunctionsInfo, llvm::gsym::FunctionInfo::Range, llvm::stable_sort(), and std::swap().

◆ save()

llvm::Error GsymCreator::save	(	StringRef	Path,
		llvm::endianness	ByteOrder,
		std::optional< uint64_t >	SegmentSize = std::nullopt ) const

Save a GSYM file to a stand alone file.

Parameters

Path	The file path to save the GSYM file to.
ByteOrder	The endianness to use when saving the file.
SegmentSize	The size in bytes to segment the GSYM file into. If this option is set this function will create N segments that are all around SegmentSize bytes in size. This allows a very large GSYM file to be broken up into shards. Each GSYM file will have its own file table, and string table that only have the files and strings needed for the shared. If this argument has no value, a single GSYM file that contains all function information will be created.

Returns: An error object that indicates success or failure of the save.

Definition at line 68 of file GsymCreator.cpp.

References encode(), llvm::errorCodeToError(), getStringOffsetSize(), and saveSegments().

◆ saveSegments()

llvm::Error GsymCreator::saveSegments	(	StringRef	Path,
		llvm::endianness	ByteOrder,
		uint64_t	SegmentSize ) const

protected

Save this GSYM file into segments that are roughly SegmentSize in size.

When segemented GSYM files are saved to disk, they will use Path as a prefix and then have the first function info address appended to the path when each segment is saved. Each segmented GSYM file has a only the strings and files that are needed to save the function infos that are in each segment. These smaller files are easy to compress and download separately and allow for efficient lookups with very large GSYM files and segmenting them allows servers to download only the segments that are needed.

Parameters

Path	The path prefix to use when saving the GSYM files.
ByteOrder	The endianness to use when saving the file.
SegmentSize	The size in bytes to segment the GSYM file into.

Definition at line 479 of file GsymCreator.cpp.

References createSegment(), llvm::createStringError(), llvm::format_hex(), Funcs, llvm::Expected< T >::get(), GsymCreator(), llvm::Error::success(), and llvm::Expected< T >::takeError().

Referenced by save().

◆ setBaseAddress()

void llvm::gsym::GsymCreator::setBaseAddress ( uint64_t Addr )

inline

Set the base address to use for the GSYM file.

Setting the base address to use for the GSYM file. Object files typically get loaded from a base address when the OS loads them into memory. Using GSYM files for symbolication becomes easier if the base address in the GSYM header is the same address as it allows addresses to be easily slid and allows symbolication without needing to find the original base address in the original object file.

Parameters

Addr	The address to use as the base address of the GSYM file when it is saved to disk.

Definition at line 489 of file GsymCreator.h.

References BaseAddress.

◆ setIsSegment()

void llvm::gsym::GsymCreator::setIsSegment ( )

inlineprotected

Let this creator know that this is a segment of another GsymCreator.

When we have a segment, we know that function infos will be added in ascending address range order without having to be finalized. We also don't need to sort and unique entries during the finalize function call.

Definition at line 284 of file GsymCreator.h.

References IsSegment.

◆ setUUID()

void llvm::gsym::GsymCreator::setUUID ( llvm::ArrayRef< uint8_t > UUIDBytes )

inline

Set the UUID value.

Parameters

UUIDBytes The new UUID bytes.

Definition at line 425 of file GsymCreator.h.

References llvm::ArrayRef< T >::begin(), llvm::ArrayRef< T >::end(), and UUID.

Referenced by llvm::gsym::ObjectFileTransformer::convert().

◆ SetValidTextRanges()

void llvm::gsym::GsymCreator::SetValidTextRanges ( AddressRanges & TextRanges )

inline

Set valid .text address ranges that all functions must be contained in.

Definition at line 448 of file GsymCreator.h.

References ValidTextRanges.

◆ validateForEncoding()

llvm::Error GsymCreator::validateForEncoding ( std::optional< uint64_t > & BaseAddr ) const

protected

Validate that the creator is ready for encoding.

Checks that functions exist, the creator is finalized, the function count fits in 32 bits, and the base address is valid.

Parameters

[out] BaseAddr Set to the base address on success.

Returns: An error if validation fails, or Error::success().

Definition at line 373 of file GsymCreator.cpp.

References llvm::createStringError(), Finalized, Funcs, getBaseAddress(), and llvm::Error::success().

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

Member Data Documentation

◆ BaseAddress

std::optional<uint64_t> llvm::gsym::GsymCreator::BaseAddress

protected

Definition at line 148 of file GsymCreator.h.

Referenced by createSegment(), llvm::gsym::GsymCreatorV1::encode(), getAddressOffsetSize(), getBaseAddress(), and setBaseAddress().

◆ FileEntryToIndex

DenseMap<llvm::gsym::FileEntry, uint32_t> llvm::gsym::GsymCreator::FileEntryToIndex

protected

Definition at line 142 of file GsymCreator.h.

Referenced by insertFileEntry().

◆ Files

std::vector<llvm::gsym::FileEntry> llvm::gsym::GsymCreator::Files

protected

Definition at line 145 of file GsymCreator.h.

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

◆ Finalized

bool llvm::gsym::GsymCreator::Finalized = false

protected

Definition at line 150 of file GsymCreator.h.

Referenced by finalize(), getFirstFunctionAddress(), getLastFunctionAddress(), and validateForEncoding().

◆ Funcs

std::vector<FunctionInfo> llvm::gsym::GsymCreator::Funcs

protected

Definition at line 139 of file GsymCreator.h.

Referenced by addFunctionInfo(), copyFunctionInfo(), createSegment(), llvm::gsym::GsymCreatorV1::encode(), llvm::gsym::GsymCreatorV2::encode(), encodeAddrOffsets(), finalize(), forEachFunctionInfo(), forEachFunctionInfo(), getFirstFunctionAddress(), getLastFunctionAddress(), getNumFunctionInfos(), loadCallSitesFromYAML(), prepareMergedFunctions(), saveSegments(), and validateForEncoding().

◆ IsSegment

bool llvm::gsym::GsymCreator::IsSegment = false

protected

Definition at line 149 of file GsymCreator.h.

Referenced by finalize(), getFirstFunctionAddress(), getLastFunctionAddress(), and setIsSegment().

◆ Mutex

std::mutex llvm::gsym::GsymCreator::Mutex

mutableprotected

Definition at line 138 of file GsymCreator.h.

Referenced by addFunctionInfo(), copyFunctionInfo(), llvm::gsym::GsymCreatorV1::encode(), llvm::gsym::GsymCreatorV2::encode(), finalize(), forEachFunctionInfo(), forEachFunctionInfo(), getNumFunctionInfos(), insertFileEntry(), and insertString().

◆ Quiet

bool llvm::gsym::GsymCreator::Quiet

protected

Definition at line 151 of file GsymCreator.h.

Referenced by createNew(), GsymCreator(), llvm::gsym::GsymCreatorV1::GsymCreatorV1(), llvm::gsym::GsymCreatorV2::GsymCreatorV2(), and isQuiet().

◆ StringOffsetMap

DenseMap<uint64_t, CachedHashStringRef> llvm::gsym::GsymCreator::StringOffsetMap

protected

Definition at line 144 of file GsymCreator.h.

Referenced by copyFile(), copyString(), getString(), and insertString().

◆ StringStorage

StringSet llvm::gsym::GsymCreator::StringStorage

protected

Definition at line 141 of file GsymCreator.h.

Referenced by insertString().

◆ StrTab

StringTableBuilder llvm::gsym::GsymCreator::StrTab

protected

Definition at line 140 of file GsymCreator.h.

Referenced by copyFile(), copyString(), llvm::gsym::GsymCreatorV1::encode(), llvm::gsym::GsymCreatorV2::encode(), finalize(), GsymCreator(), and insertString().

◆ UUID

std::vector<uint8_t> llvm::gsym::GsymCreator::UUID

protected

Definition at line 146 of file GsymCreator.h.

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

◆ ValidTextRanges

std::optional<AddressRanges> llvm::gsym::GsymCreator::ValidTextRanges

protected

Definition at line 147 of file GsymCreator.h.

Referenced by finalize(), GetValidTextRanges(), IsValidTextAddress(), and SetValidTextRanges().

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

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

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ GsymCreator()

◆ ~GsymCreator()

Member Function Documentation

◆ addFunctionInfo()

◆ calculateHeaderAndTableSize()

◆ copyFile()

◆ copyFunctionInfo()

◆ copyString()

◆ createNew()

◆ createSegment()

◆ encode()

◆ encodeAddrOffsets()

◆ encodeFileTable()

◆ finalize()

◆ fixupInlineInfo()

◆ forEachFunctionInfo() [1/2]

◆ forEachFunctionInfo() [2/2]

◆ getAddressOffsetSize()

◆ getBaseAddress()

◆ getFirstFunctionAddress()

◆ getLastFunctionAddress()

◆ getMaxAddressOffset()

◆ getNumFunctionInfos()

◆ getString()

◆ getStringOffsetSize()

◆ GetValidTextRanges()

◆ insertFile()

◆ insertFileEntry()

◆ insertString()

◆ isQuiet()

◆ IsValidTextAddress()

◆ loadCallSitesFromYAML()

◆ prepareMergedFunctions()

◆ save()

◆ saveSegments()

◆ setBaseAddress()

◆ setIsSegment()

◆ setUUID()

◆ SetValidTextRanges()

◆ validateForEncoding()

Member Data Documentation

◆ BaseAddress

◆ FileEntryToIndex

◆ Files

◆ Finalized

◆ Funcs

◆ IsSegment

◆ Mutex

◆ Quiet

◆ StringOffsetMap

◆ StringStorage

◆ StrTab

◆ UUID

◆ ValidTextRanges