Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

//===- GsymCreator.h --------------------------------------------*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

#ifndef LLVM_DEBUGINFO_GSYM_GSYMCREATOR_H

#define LLVM_DEBUGINFO_GSYM_GSYMCREATOR_H

#include <functional>

#include <memory>

#include <mutex>

#include <thread>

#include "llvm/ADT/AddressRanges.h"

#include "llvm/ADT/ArrayRef.h"

#include "llvm/ADT/StringSet.h"

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

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

#include "llvm/MC/StringTableBuilder.h"

#include "llvm/Support/Endian.h"

#include "llvm/Support/Error.h"

#include "llvm/Support/Path.h"

namespace llvm {

namespace gsym {

class FileWriter;

/// 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".

class GsymCreator {

  // Private member variables require Mutex protections

  mutable std::mutex Mutex;

  std::vector<FunctionInfo> Funcs;

  StringTableBuilder StrTab;

  StringSet<> StringStorage;

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

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

  std::vector<uint8_t> UUID;

  std::optional<AddressRanges> ValidTextRanges;

  AddressRanges Ranges;

  std::optional<uint64_t> BaseAddress;

  bool Finalized = false;

  bool Quiet;

public:

  GsymCreator(bool Quiet = false);

  /// Save a GSYM file to a stand alone file.

  ///

  /// \param Path The file path to save the GSYM file to.

  /// \param ByteOrder The endianness to use when saving the file.

  /// \returns An error object that indicates success or failure of the save.

  llvm::Error save(StringRef Path, llvm::support::endianness ByteOrder) const;

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

  ///

  /// \param O The stream to save the binary data to

  /// \returns An error object that indicates success or failure of the save.

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

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

  ///

  /// \param S The string to insert into the string table.

  /// \param 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.

  uint32_t insertString(StringRef S, bool Copy = true);

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

  ///

  /// \param   Path The path to the file to insert.

  /// \param   Style The path style for the "Path" parameter.

  /// \returns The unique file index for the inserted file.

  uint32_t insertFile(StringRef Path,

                      sys::path::Style Style = sys::path::Style::native);

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

  ///

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

  void addFunctionInfo(FunctionInfo &&FI);

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

  ///

  /// \param  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.

  llvm::Error finalize(llvm::raw_ostream &OS);

  /// Set the UUID value.

  ///

  /// \param UUIDBytes The new UUID bytes.

  void setUUID(llvm::ArrayRef<uint8_t> UUIDBytes) {

    UUID.assign(UUIDBytes.begin(), UUIDBytes.end());

  }

  /// Thread safe iteration over all function infos.

  ///

  /// \param  Callback A callback function that will get called with each

  ///         FunctionInfo. If the callback returns false, stop iterating.

  void forEachFunctionInfo(

      std::function<bool(FunctionInfo &)> const &Callback);

  /// Thread safe const iteration over all function infos.

  ///

  /// \param  Callback A callback function that will get called with each

  ///         FunctionInfo. If the callback returns false, stop iterating.

  void forEachFunctionInfo(

      std::function<bool(const FunctionInfo &)> const &Callback) const;

  /// Get the current number of FunctionInfo objects contained in this

  /// object.

  size_t getNumFunctionInfos() const;

  /// Check if an address has already been added as a function info.

  ///

  /// FunctionInfo data can come from many sources: debug info, symbol tables,

  /// exception information, and more. Symbol tables should be added after

  /// debug info and can use this function to see if a symbol's start address

  /// has already been added to the GsymReader. Calling this before adding

  /// a function info from a source other than debug info avoids clients adding

  /// many redundant FunctionInfo objects from many sources only for them to be

  /// removed during the finalize() call.

  bool hasFunctionInfoForAddress(uint64_t Addr) const;

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

  void SetValidTextRanges(AddressRanges &TextRanges) {

    ValidTextRanges = TextRanges;

  }

  /// Get the valid text ranges.

  const std::optional<AddressRanges> GetValidTextRanges() const {

    return ValidTextRanges;

  }

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

  ///

  /// \param 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.

  bool IsValidTextAddress(uint64_t Addr) const;

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

  ///

  /// \param  Addr The address to use as the base address of the GSYM file

  ///              when it is saved to disk.

  void setBaseAddress(uint64_t Addr) {

    BaseAddress = Addr;

  }

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

  bool isQuiet() const { return Quiet; }

};

} // namespace gsym

} // namespace llvm

#endif // LLVM_DEBUGINFO_GSYM_GSYMCREATOR_H