LLVM  10.0.0svn
Header.h
Go to the documentation of this file.
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
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.
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.
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.
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.
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.
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);
125 
126 } // namespace gsym
127 } // namespace llvm
128 
129 #endif // #ifndef LLVM_DEBUGINFO_GSYM_HEADER_H
uint16_t Version
The version can number determines how the header is decoded and how each InfoType in FunctionInfo is ...
Definition: Header.h:54
This class represents lattice values for constants.
Definition: AllocatorList.h:23
uint32_t Magic
The magic bytes should be set to GSYM_MAGIC.
Definition: Header.h:49
llvm::Error encode(FileWriter &O) const
Encode this object into FileWriter stream.
Definition: Header.cpp:85
uint8_t UUIDSize
The size in bytes of the UUID encoded in the "UUID" member.
Definition: Header.h:58
constexpr uint32_t GSYM_CIGAM
Definition: Header.h:25
uint64_t BaseAddress
The 64 bit base address that all address offsets in the address offsets table are relative to...
Definition: Header.h:62
Tagged union holding either a T or a Error.
Definition: yaml2obj.h:21
#define H(x, y, z)
Definition: MD5.cpp:57
A simplified binary data writer class that doesn&#39;t require targets, target definitions, architectures, or require any other optional compile time libraries to be enabled via the build process.
Definition: FileWriter.h:29
uint32_t StrtabSize
The size in bytes of the string table.
Definition: Header.h:80
bool operator==(const FunctionInfo &LHS, const FunctionInfo &RHS)
Definition: FunctionInfo.h:158
uint32_t StrtabOffset
The file relative offset of the start of the string table for strings contained in the GSYM file...
Definition: Header.h:72
std::pair< llvm::MachO::Target, std::string > UUID
llvm::Error checkForError() const
Check if a header is valid and return an error if anything is wrong.
Definition: Header.cpp:41
The GSYM header.
Definition: Header.h:45
constexpr size_t GSYM_MAX_UUID_SIZE
Definition: Header.h:27
uint8_t AddrOffSize
The size in bytes of each address offset in the address offsets table.
Definition: Header.h:56
Lightweight error class with error context and mandatory checking.
Definition: Error.h:157
static llvm::Expected< Header > decode(DataExtractor &Data)
Decode an object from a binary data stream.
Definition: Header.cpp:64
This class implements an extremely fast bulk output stream that can only output to a stream...
Definition: raw_ostream.h:45
constexpr uint32_t GSYM_MAGIC
Definition: Header.h:24
raw_ostream & operator<<(raw_ostream &OS, const FunctionInfo &R)
constexpr uint32_t GSYM_VERSION
Definition: Header.h:26
uint32_t NumAddresses
The number of addresses stored in the address offsets table.
Definition: Header.h:64