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
17namespace llvm {
18class raw_ostream;
19class DataExtractor;
20
21namespace gsym {
22class FileWriter;
23
24constexpr uint32_t GSYM_MAGIC = 0x4753594d; // 'GSYM'
25constexpr uint32_t GSYM_CIGAM = 0x4d595347; // 'MYSG'
26constexpr uint32_t GSYM_VERSION = 1;
27constexpr 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.
45struct 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
123bool operator==(const Header &LHS, const Header &RHS);
124raw_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

source code of llvm/include/llvm/DebugInfo/GSYM/Header.h