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 |
11 | |
12 | #include "llvm/Support/Error.h" |
13 | |
14 | #include <cstddef> |
15 | #include <cstdint> |
16 | |
17 | namespace llvm { |
18 | class raw_ostream; |
19 | class ; |
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 { |
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 ; |
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 ; |
55 | /// The size in bytes of each address offset in the address offsets table. |
56 | uint8_t ; |
57 | /// The size in bytes of the UUID encoded in the "UUID" member. |
58 | uint8_t ; |
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 ; |
63 | /// The number of addresses stored in the address offsets table. |
64 | uint32_t ; |
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 ; |
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 ; |
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 [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 () 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> (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 (FileWriter &O) const; |
121 | }; |
122 | |
123 | bool (const Header &LHS, const Header &RHS); |
124 | raw_ostream &(raw_ostream &OS, const llvm::gsym::Header &H); |
125 | |
126 | } // namespace gsym |
127 | } // namespace llvm |
128 | |
129 | #endif // LLVM_DEBUGINFO_GSYM_HEADER_H |
130 | |