include/llvm/DebugInfo/GSYM/Header.h

   1 //===- Header.h -------------------------------------------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8
   9 #ifndef LLVM_DEBUGINFO_GSYM_HEADER_H
  10 #define LLVM_DEBUGINFO_GSYM_HEADER_H
  11
  12 #include "llvm/Support/Error.h"
  13
  14 #include <cstddef>
  15 #include <cstdint>
  16
  17 namespace llvm {
  18 class raw_ostream;
  19 class DataExtractor;
  20
  21 namespace gsym {
  22 class FileWriter;
  23
  24 constexpr uint32_t GSYM_MAGIC = 0x4753594d; // 'GSYM'
  25 constexpr uint32_t GSYM_VERSION = 1;
  26 constexpr size_t GSYM_MAX_UUID_SIZE = 20;
  27
  28 /// The GSYM header.
  29 ///
  30 /// The GSYM header is found at the start of a stand alone GSYM file, or as
  31 /// the first bytes in a section when GSYM is contained in a section of an
  32 /// executable file (ELF, mach-o, COFF).
  33 ///
  34 /// The structure is encoded exactly as it appears in the structure definition
  35 /// with no gaps between members. Alignment should not change from system to
  36 /// system as the members were laid out so that they shouldn't align
  37 /// differently on different architectures.
  38 ///
  39 /// When endianness of the system loading a GSYM file matches, the file can
  40 /// be mmap'ed in and a pointer to the header can be cast to the first bytes
  41 /// of the file (stand alone GSYM file) or section data (GSYM in a section).
  42 /// When endianness is swapped, the Header::decode() function should be used to
  43 /// decode the header.
  44 struct Header {
  45   /// The magic bytes should be set to GSYM_MAGIC. This helps detect if a file
  46   /// is a GSYM file by scanning the first 4 bytes of a file or section.
  47   /// This value might appear byte swapped
  48   uint32_t Magic;
  49   /// The version can number determines how the header is decoded and how each
  50   /// InfoType in FunctionInfo is encoded/decoded. As version numbers increase,
  51   /// "Magic" and "Version" members should always appear at offset zero and 4
  52   /// respectively to ensure clients figure out if they can parse the format.
  53   uint16_t Version;
  54   /// The size in bytes of each address offset in the address offsets table.
  55   uint8_t AddrOffSize;
  56   /// The size in bytes of the UUID encoded in the "UUID" member.
  57   uint8_t UUIDSize;
  58   /// The 64 bit base address that all address offsets in the address offsets
  59   /// table are relative to. Storing a full 64 bit address allows our address
  60   /// offsets table to be smaller on disk.
  61   uint64_t BaseAddress;
  62   /// The number of addresses stored in the address offsets table.
  63   uint32_t NumAddresses;
  64   /// The file relative offset of the start of the string table for strings
  65   /// contained in the GSYM file. If the GSYM in contained in a stand alone
  66   /// file this will be the file offset of the start of the string table. If
  67   /// the GSYM is contained in a section within an executable file, this can
  68   /// be the offset of the first string used in the GSYM file and can possibly
  69   /// span one or more executable string tables. This allows the strings to
  70   /// share string tables in an ELF or mach-o file.
  71   uint32_t StrtabOffset;
  72   /// The size in bytes of the string table. For a stand alone GSYM file, this
  73   /// will be the exact size in bytes of the string table. When the GSYM data
  74   /// is in a section within an executable file, this size can span one or more
  75   /// sections that contains strings. This allows any strings that are already
  76   /// stored in the executable file to be re-used, and any extra strings could
  77   /// be added to another string table and the string table offset and size
  78   /// can be set to span all needed string tables.
  79   uint32_t StrtabSize;
  80   /// The UUID of the original executable file. This is stored to allow
  81   /// matching a GSYM file to an executable file when symbolication is
  82   /// required. Only the first "UUIDSize" bytes of the UUID are valid. Any
  83   /// bytes in the UUID value that appear after the first UUIDSize bytes should
  84   /// be set to zero.
  85   uint8_t UUID[GSYM_MAX_UUID_SIZE];
  86
  87   /// Check if a header is valid.
  88   ///
  89   /// \returns True if the header is valid and if the version is supported.
  90   bool isValid() const {
  91     if (Magic != GSYM_MAGIC)
  92       return false;
  93     if (Version != GSYM_VERSION)
  94       return false;
  95     return true;
  96   }
  97
  98   /// Decode an object from a binary data stream.
  99   ///
 100   /// \param Data The binary stream to read the data from. This object must
 101   /// have the data for the object starting at offset zero. The data
 102   /// can contain more data than needed.
 103   ///
 104   /// \returns A Header or an error describing the issue that was
 105   /// encountered during decoding.
 106   static llvm::Expected<Header> decode(DataExtractor &Data);
 107
 108   /// Encode this object into FileWriter stream.
 109   ///
 110   /// \param O The binary stream to write the data to at the current file
 111   /// position.
 112   ///
 113   /// \returns An error object that indicates success or failure of the
 114   /// encoding process.
 115   llvm::Error encode(FileWriter &O) const;
 116 };
 117
 118 bool operator==(const Header &LHS, const Header &RHS);
 119 raw_ostream &operator<<(raw_ostream &OS, const llvm::gsym::Header &H);
 120
 121 } // namespace gsym
 122 } // namespace llvm
 123
 124 #endif // #ifndef LLVM_DEBUGINFO_GSYM_HEADER_H