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 // LLVM_DEBUGINFO_GSYM_HEADER_H 130