130 lines
5.5 KiB
C++
130 lines
5.5 KiB
C++
//===- Header.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_HEADER_H
|
|
#define LLVM_DEBUGINFO_GSYM_HEADER_H
|
|
|
|
#include "llvm/Support/Error.h"
|
|
|
|
#include <cstddef>
|
|
#include <cstdint>
|
|
|
|
namespace llvm {
|
|
class raw_ostream;
|
|
class DataExtractor;
|
|
|
|
namespace gsym {
|
|
class FileWriter;
|
|
|
|
constexpr uint32_t GSYM_MAGIC = 0x4753594d; // 'GSYM'
|
|
constexpr uint32_t GSYM_CIGAM = 0x4d595347; // 'MYSG'
|
|
constexpr uint32_t GSYM_VERSION = 1;
|
|
constexpr size_t GSYM_MAX_UUID_SIZE = 20;
|
|
|
|
/// 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.
|
|
struct Header {
|
|
/// 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
|
|
uint32_t Magic;
|
|
/// 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.
|
|
uint16_t Version;
|
|
/// The size in bytes of each address offset in the address offsets table.
|
|
uint8_t AddrOffSize;
|
|
/// The size in bytes of the UUID encoded in the "UUID" member.
|
|
uint8_t UUIDSize;
|
|
/// 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.
|
|
uint64_t BaseAddress;
|
|
/// The number of addresses stored in the address offsets table.
|
|
uint32_t NumAddresses;
|
|
/// 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.
|
|
uint32_t StrtabOffset;
|
|
/// 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.
|
|
uint32_t StrtabSize;
|
|
/// 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.
|
|
uint8_t UUID[GSYM_MAX_UUID_SIZE];
|
|
|
|
/// 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 UUID size is valid
|
|
///
|
|
/// \returns An error if anything is wrong in the header, or Error::success()
|
|
/// if there are no errors.
|
|
llvm::Error checkForError() const;
|
|
|
|
/// Decode an object from a binary data stream.
|
|
///
|
|
/// \param 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 Header or an error describing the issue that was
|
|
/// encountered during decoding.
|
|
static llvm::Expected<Header> decode(DataExtractor &Data);
|
|
|
|
/// Encode this object into FileWriter stream.
|
|
///
|
|
/// \param 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.
|
|
llvm::Error encode(FileWriter &O) const;
|
|
};
|
|
|
|
bool operator==(const Header &LHS, const Header &RHS);
|
|
raw_ostream &operator<<(raw_ostream &OS, const llvm::gsym::Header &H);
|
|
|
|
} // namespace gsym
|
|
} // namespace llvm
|
|
|
|
#endif // #ifndef LLVM_DEBUGINFO_GSYM_HEADER_H
|