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