LLDB mainline
Symbol.h
Go to the documentation of this file.
1//===-- Symbol.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 LLDB_SYMBOL_SYMBOL_H
10#define LLDB_SYMBOL_SYMBOL_H
11
13#include "lldb/Core/Mangled.h"
14#include "lldb/Core/Section.h"
16#include "lldb/Utility/UserID.h"
17#include "lldb/lldb-private.h"
18#include "llvm/Support/JSON.h"
19
20namespace lldb_private {
21
22struct JSONSymbol {
23 std::optional<uint64_t> address;
24 std::optional<uint64_t> value;
25 std::optional<uint64_t> size;
26 std::optional<uint64_t> id;
27 std::optional<lldb::SymbolType> type;
28 std::string name;
29};
30
31class Symbol : public SymbolContextScope {
32public:
33 // ObjectFile readers can classify their symbol table entries and searches
34 // can be made on specific types where the symbol values will have
35 // drastically different meanings and sorting requirements.
36 Symbol();
37
38 Symbol(uint32_t symID, llvm::StringRef name, lldb::SymbolType type,
39 bool external, bool is_debug, bool is_trampoline, bool is_artificial,
40 const lldb::SectionSP &section_sp, lldb::addr_t value,
41 lldb::addr_t size, bool size_is_valid,
42 bool contains_linker_annotations, uint32_t flags);
43
44 Symbol(uint32_t symID, const Mangled &mangled, lldb::SymbolType type,
45 bool external, bool is_debug, bool is_trampoline, bool is_artificial,
46 const AddressRange &range, bool size_is_valid,
47 bool contains_linker_annotations, uint32_t flags);
48
49 Symbol(const Symbol &rhs);
50
51 const Symbol &operator=(const Symbol &rhs);
52
53 static llvm::Expected<Symbol> FromJSON(const JSONSymbol &symbol,
54 SectionList *section_list);
55
56 void Clear();
57
58 bool Compare(ConstString name, lldb::SymbolType type) const;
59
60 void Dump(Stream *s, Target *target, uint32_t index,
61 Mangled::NamePreference name_preference =
63
64 bool ValueIsAddress() const;
65
66 // The GetAddressRef() accessor functions should only be called if you
67 // previously call ValueIsAddress() otherwise you might get an reference to
68 // an Address object that contains an constant integer value in
69 // m_addr_range.m_base_addr.m_offset which could be incorrectly used to
70 // represent an absolute address since it has no section.
72
73 const Address &GetAddressRef() const { return m_addr_range.GetBaseAddress(); }
74
75 // Makes sure the symbol's value is an address and returns the file address.
76 // Returns LLDB_INVALID_ADDRESS if the symbol's value isn't an address.
78
79 // Makes sure the symbol's value is an address and gets the load address
80 // using \a target if it is. Returns LLDB_INVALID_ADDRESS if the symbol's
81 // value isn't an address or if the section isn't loaded in \a target.
82 lldb::addr_t GetLoadAddress(Target *target) const;
83
84 // Access the address value. Do NOT hand out the AddressRange as an object as
85 // the byte size of the address range may not be filled in and it should be
86 // accessed via GetByteSize().
88 // Make sure the our value is an address before we hand a copy out. We use
89 // the Address inside m_addr_range to contain the value for symbols that
90 // are not address based symbols so we are using it for more than just
91 // addresses. For example undefined symbols on MacOSX have a nlist.n_value
92 // of 0 (zero) and this will get placed into
93 // m_addr_range.m_base_addr.m_offset and it will have no section. So in the
94 // GetAddress() accessor, we need to hand out an invalid address if the
95 // symbol's value isn't an address.
96 if (ValueIsAddress())
98 else
99 return Address();
100 }
101
102 /// Get the raw value of the symbol from the symbol table.
103 ///
104 /// If the symbol's value is an address, return the file address, else return
105 /// the raw value that is stored in the m_addr_range. If the base address has
106 /// no section, then getting the file address will return the correct value
107 /// as it will return the offset in the base address which is the value.
108 uint64_t GetRawValue() const {
110 }
111
112 // When a symbol's value isn't an address, we need to access the raw value.
113 // This function will ensure this symbol's value isn't an address and return
114 // the integer value if this checks out, otherwise it will return
115 // "fail_value" if the symbol is an address value.
116 uint64_t GetIntegerValue(uint64_t fail_value = 0) const {
117 if (ValueIsAddress()) {
118 // This symbol's value is an address. Use Symbol::GetAddress() to get the
119 // address.
120 return fail_value;
121 } else {
122 // The value is stored in the base address' offset
124 }
125 }
126
128
129 ConstString GetName() const;
130
132
134
135 uint32_t GetID() const { return m_uid; }
136
138 // TODO: See if there is a way to determine the language for a symbol
139 // somehow, for now just return our best guess
140 return GetMangled().GuessLanguage();
141 }
142
143 void SetID(uint32_t uid) { m_uid = uid; }
144
147 return m_mangled;
148 }
149
150 const Mangled &GetMangled() const {
152 return m_mangled;
153 }
154
156
158
160
162
163 Symbol *ResolveReExportedSymbol(Target &target) const;
164
165 uint32_t GetSiblingIndex() const;
166
168
170
171 const char *GetTypeAsString() const;
172
173 uint32_t GetFlags() const { return m_flags; }
174
175 void SetFlags(uint32_t flags) { m_flags = flags; }
176
178 Target *target) const;
179
180 bool IsSynthetic() const { return m_is_synthetic; }
181
183
184 void SetIsSynthetic(bool b) { m_is_synthetic = b; }
185
187
189
190 bool IsDebug() const { return m_is_debug; }
191
192 void SetDebug(bool b) { m_is_debug = b; }
193
194 bool IsExternal() const { return m_is_external; }
195
196 void SetExternal(bool b) { m_is_external = b; }
197
198 bool IsTrampoline() const;
199
200 bool IsIndirect() const;
201
202 bool IsWeak() const { return m_is_weak; }
203
204 void SetIsWeak(bool b) { m_is_weak = b; }
205
206 bool GetByteSizeIsValid() const { return m_size_is_valid; }
207
209
211 m_size_is_valid = size > 0;
213 }
214
215 bool GetSizeIsSibling() const { return m_size_is_sibling; }
216
218
219 // If m_type is "Code" or "Function" then this will return the prologue size
220 // in bytes, else it will return zero.
221 uint32_t GetPrologueByteSize();
222
225 }
226
228
231 }
234 }
235 /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
236 ///
237 /// \see SymbolContextScope
238 void CalculateSymbolContext(SymbolContext *sc) override;
239
241
243
244 /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
245 ///
246 /// \see SymbolContextScope
247 void DumpSymbolContext(Stream *s) override;
248
250 const char *flavor,
251 bool prefer_file_cache);
252
253 bool GetDisassembly(const ExecutionContext &exe_ctx, const char *flavor,
254 bool prefer_file_cache, Stream &strm);
255
256 bool ContainsFileAddress(lldb::addr_t file_addr) const;
257
258 static llvm::StringRef GetSyntheticSymbolPrefix() {
259 return "___lldb_unnamed_symbol";
260 }
261
262 /// Decode a serialized version of this object from data.
263 ///
264 /// \param data
265 /// The decoder object that references the serialized data.
266 ///
267 /// \param offset_ptr
268 /// A pointer that contains the offset from which the data will be decoded
269 /// from that gets updated as data gets decoded.
270 ///
271 /// \param section_list
272 /// A section list that allows lldb_private::Address objects to be filled
273 /// in. The address information for symbols are serilized as file addresses
274 /// and must be converted into Address objects with the right section and
275 /// offset.
276 ///
277 /// \param strtab
278 /// All strings in cache files are put into string tables for efficiency
279 /// and cache file size reduction. Strings are stored as uint32_t string
280 /// table offsets in the cache data.
281 ///
282 /// \return
283 /// True if the symbol is successfully decoded, false otherwise.
284 bool Decode(const DataExtractor &data, lldb::offset_t *offset_ptr,
285 const SectionList *section_list, const StringTableReader &strtab);
286
287 /// Encode this object into a data encoder object.
288 ///
289 /// This allows this object to be serialized to disk.
290 ///
291 /// \param encoder
292 /// A data encoder object that serialized bytes will be encoded into.
293 ///
294 /// \param strtab
295 /// All strings in cache files are put into string tables for efficiency
296 /// and cache file size reduction. Strings are stored as uint32_t string
297 /// table offsets in the cache data.
298 void Encode(DataEncoder &encoder, ConstStringTable &strtab) const;
299
300 bool operator==(const Symbol &rhs) const;
301
302protected:
303 // This is the internal guts of ResolveReExportedSymbol, it assumes
304 // reexport_name is not null, and that module_spec is valid. We track the
305 // modules we've already seen to make sure we don't get caught in a cycle.
306
308 Target &target, ConstString &reexport_name,
309 lldb_private::ModuleSpec &module_spec,
310 lldb_private::ModuleList &seen_modules) const;
311
312 void SynthesizeNameIfNeeded() const;
313
314 uint32_t m_uid =
315 UINT32_MAX; // User ID (usually the original symbol table index)
316 uint16_t m_type_data = 0; // data specific to m_type
317 uint16_t m_type_data_resolved : 1, // True if the data in m_type_data has
318 // already been calculated
319 m_is_synthetic : 1, // non-zero if this symbol is not actually in the
320 // symbol table, but synthesized from other info in
321 // the object file.
322 m_is_debug : 1, // non-zero if this symbol is debug information in a
323 // symbol
324 m_is_external : 1, // non-zero if this symbol is globally visible
325 m_size_is_sibling : 1, // m_size contains the index of this symbol's
326 // sibling
327 m_size_is_synthesized : 1, // non-zero if this symbol's size was
328 // calculated using a delta between this
329 // symbol and the next
331 m_demangled_is_synthesized : 1, // The demangled name was created should
332 // not be used for expressions or other
333 // lookups
334 m_contains_linker_annotations : 1, // The symbol name contains linker
335 // annotations, which are optional when
336 // doing name lookups
338 m_type : 6; // Values from the lldb::SymbolType enum.
339 mutable Mangled m_mangled; // uniqued symbol name/mangled name pair
340 AddressRange m_addr_range; // Contains the value, or the section offset
341 // address when the value is an address in a
342 // section, and the size (if any)
343 uint32_t m_flags = 0; // A copy of the flags from the original symbol table,
344 // the ObjectFile plug-in can interpret these
345};
346
347} // namespace lldb_private
348
349namespace llvm {
350namespace json {
351
352bool fromJSON(const llvm::json::Value &value, lldb_private::JSONSymbol &symbol,
353 llvm::json::Path path);
354
355bool fromJSON(const llvm::json::Value &value, lldb::SymbolType &type,
356 llvm::json::Path path);
357
358} // namespace json
359} // namespace llvm
360
361#endif // LLDB_SYMBOL_SYMBOL_H
A section + offset based address range class.
Definition: AddressRange.h:25
Address & GetBaseAddress()
Get accessor for the base address of the range.
Definition: AddressRange.h:209
void SetByteSize(lldb::addr_t byte_size)
Set accessor for the byte size of this range.
Definition: AddressRange.h:237
A section + offset based address class.
Definition: Address.h:59
lldb::addr_t GetFileAddress() const
Get the file address.
Definition: Address.cpp:291
lldb::addr_t GetOffset() const
Get the section relative offset value.
Definition: Address.h:319
Many cache files require string tables to store data efficiently.
A uniqued constant string class.
Definition: ConstString.h:40
An binary data encoding class.
Definition: DataEncoder.h:42
An data extractor class.
Definition: DataExtractor.h:48
"lldb/Target/ExecutionContext.h" A class that contains an execution context.
A file utility class.
Definition: FileSpec.h:57
A class that handles mangled names.
Definition: Mangled.h:33
lldb::LanguageType GuessLanguage() const
Try to guess the language from the mangling.
Definition: Mangled.cpp:379
A collection class for Module objects.
Definition: ModuleList.h:82
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
Many cache files require string tables to store data efficiently.
"lldb/Symbol/SymbolContextScope.h" Inherit from this if your object is part of a symbol context and c...
Defines a symbol context baton that can be handed other debug core functions.
Definition: SymbolContext.h:33
bool Decode(const DataExtractor &data, lldb::offset_t *offset_ptr, const SectionList *section_list, const StringTableReader &strtab)
Decode a serialized version of this object from data.
Definition: Symbol.cpp:643
uint32_t m_uid
Definition: Symbol.h:314
uint32_t GetSiblingIndex() const
Definition: Symbol.cpp:219
uint16_t m_is_external
Definition: Symbol.h:324
uint64_t GetIntegerValue(uint64_t fail_value=0) const
Definition: Symbol.h:116
uint32_t GetID() const
Definition: Symbol.h:135
lldb::addr_t GetLoadAddress(Target *target) const
Definition: Symbol.cpp:537
bool ValueIsAddress() const
Definition: Symbol.cpp:167
bool IsExternal() const
Definition: Symbol.h:194
uint16_t m_type_data_resolved
Definition: Symbol.h:317
void SetReExportedSymbolName(ConstString name)
Definition: Symbol.cpp:201
void SetType(lldb::SymbolType type)
Definition: Symbol.h:169
void SetSizeIsSynthesized(bool b)
Definition: Symbol.h:188
void SetSizeIsSibling(bool b)
Definition: Symbol.h:217
void CalculateSymbolContext(SymbolContext *sc) override
Reconstruct the object's symbol context into sc.
Definition: Symbol.cpp:432
bool IsIndirect() const
Definition: Symbol.cpp:225
bool IsDebug() const
Definition: Symbol.h:190
void SynthesizeNameIfNeeded() const
Definition: Symbol.cpp:625
const char * GetTypeAsString() const
Definition: Symbol.cpp:395
Symbol * ResolveReExportedSymbolInModuleSpec(Target &target, ConstString &reexport_name, lldb_private::ModuleSpec &module_spec, lldb_private::ModuleList &seen_modules) const
Definition: Symbol.cpp:466
bool IsSynthetic() const
Definition: Symbol.h:180
uint16_t m_is_synthetic
Definition: Symbol.h:319
uint16_t m_demangled_is_synthesized
Definition: Symbol.h:331
lldb::DisassemblerSP GetInstructions(const ExecutionContext &exe_ctx, const char *flavor, bool prefer_file_cache)
Definition: Symbol.cpp:585
bool ContainsLinkerAnnotations() const
Definition: Symbol.h:229
lldb::addr_t GetFileAddress() const
Definition: Symbol.cpp:530
void DumpSymbolContext(Stream *s) override
Dump the object's symbol context to the stream s.
Definition: Symbol.cpp:449
lldb::ModuleSP CalculateSymbolContextModule() override
Definition: Symbol.cpp:441
bool ContainsFileAddress(lldb::addr_t file_addr) const
Definition: Symbol.cpp:612
bool GetDemangledNameIsSynthesized() const
Definition: Symbol.h:223
bool GetByteSizeIsValid() const
Definition: Symbol.h:206
Mangled & GetMangled()
Definition: Symbol.h:145
uint32_t m_flags
Definition: Symbol.h:343
uint16_t m_contains_linker_annotations
Definition: Symbol.h:334
uint16_t m_size_is_valid
Definition: Symbol.h:330
lldb::LanguageType GetLanguage() const
Definition: Symbol.h:137
bool IsTrampoline() const
Definition: Symbol.cpp:223
Address & GetAddressRef()
Definition: Symbol.h:71
const Symbol & operator=(const Symbol &rhs)
Definition: Symbol.cpp:76
void SetContainsLinkerAnnotations(bool b)
Definition: Symbol.h:232
void SetIsWeak(bool b)
Definition: Symbol.h:204
bool IsSyntheticWithAutoGeneratedName() const
Definition: Symbol.cpp:616
void Encode(DataEncoder &encoder, ConstStringTable &strtab) const
Encode this object into a data encoder object.
Definition: Symbol.cpp:696
uint32_t GetFlags() const
Definition: Symbol.h:173
Mangled m_mangled
Definition: Symbol.h:339
bool GetSizeIsSibling() const
Definition: Symbol.h:215
uint16_t m_type
Definition: Symbol.h:338
const Mangled & GetMangled() const
Definition: Symbol.h:150
ConstString GetReExportedSymbolName() const
Definition: Symbol.cpp:175
bool Compare(ConstString name, lldb::SymbolType type) const
Definition: Symbol.cpp:382
uint16_t m_is_debug
Definition: Symbol.h:322
bool SetReExportedSymbolSharedLibrary(const FileSpec &fspec)
Definition: Symbol.cpp:208
bool operator==(const Symbol &rhs) const
Definition: Symbol.cpp:733
static llvm::StringRef GetSyntheticSymbolPrefix()
Definition: Symbol.h:258
lldb::addr_t GetByteSize() const
Definition: Symbol.cpp:464
ConstString GetName() const
Definition: Symbol.cpp:544
lldb::SymbolType GetType() const
Definition: Symbol.h:167
void SetFlags(uint32_t flags)
Definition: Symbol.h:175
Address GetAddress() const
Definition: Symbol.h:87
AddressRange m_addr_range
Definition: Symbol.h:340
ConstString GetNameNoArguments() const
Definition: Symbol.cpp:546
uint16_t m_size_is_sibling
Definition: Symbol.h:325
Symbol * ResolveReExportedSymbol(Target &target) const
Definition: Symbol.cpp:516
FileSpec GetReExportedSymbolSharedLibrary() const
Definition: Symbol.cpp:189
uint16_t m_is_weak
Definition: Symbol.h:337
bool IsWeak() const
Definition: Symbol.h:202
void SetIsSynthetic(bool b)
Definition: Symbol.h:184
bool GetSizeIsSynthesized() const
Definition: Symbol.h:186
void SetByteSize(lldb::addr_t size)
Definition: Symbol.h:210
uint32_t GetPrologueByteSize()
Definition: Symbol.cpp:309
uint16_t m_type_data
Definition: Symbol.h:316
void SetDemangledNameIsSynthesized(bool b)
Definition: Symbol.h:227
ConstString GetDisplayName() const
Definition: Symbol.cpp:171
bool GetDisassembly(const ExecutionContext &exe_ctx, const char *flavor, bool prefer_file_cache, Stream &strm)
Definition: Symbol.cpp:597
lldb::addr_t ResolveCallableAddress(Target &target) const
Definition: Symbol.cpp:550
void SetExternal(bool b)
Definition: Symbol.h:196
void GetDescription(Stream *s, lldb::DescriptionLevel level, Target *target) const
Definition: Symbol.cpp:227
uint16_t m_size_is_synthesized
Definition: Symbol.h:327
Symbol * CalculateSymbolContextSymbol() override
Definition: Symbol.cpp:447
void SetDebug(bool b)
Definition: Symbol.h:192
uint64_t GetRawValue() const
Get the raw value of the symbol from the symbol table.
Definition: Symbol.h:108
const Address & GetAddressRef() const
Definition: Symbol.h:73
void SetID(uint32_t uid)
Definition: Symbol.h:143
static llvm::Expected< Symbol > FromJSON(const JSONSymbol &symbol, SectionList *section_list)
Definition: Symbol.cpp:99
void Dump(Stream *s, Target *target, uint32_t index, Mangled::NamePreference name_preference=Mangled::ePreferDemangled) const
Definition: Symbol.cpp:262
#define UINT32_MAX
Definition: lldb-defines.h:19
A class that represents a running process on the host machine.
Definition: SBAttachInfo.h:14
DescriptionLevel
Description levels for "void GetDescription(Stream *, DescriptionLevel)" calls.
uint64_t offset_t
Definition: lldb-types.h:83
LanguageType
Programming language type.
SymbolType
Symbol types.
std::shared_ptr< lldb_private::Disassembler > DisassemblerSP
Definition: lldb-forward.h:329
std::shared_ptr< lldb_private::Section > SectionSP
Definition: lldb-forward.h:402
uint64_t addr_t
Definition: lldb-types.h:79
std::shared_ptr< lldb_private::Module > ModuleSP
Definition: lldb-forward.h:361
bool fromJSON(const llvm::json::Value &value, lldb_private::JSONSection &section, llvm::json::Path path)
Definition: Section.cpp:686
Definition: Debugger.h:53
std::string name
Definition: Symbol.h:28
std::optional< uint64_t > address
Definition: Symbol.h:23
std::optional< uint64_t > id
Definition: Symbol.h:26
std::optional< lldb::SymbolType > type
Definition: Symbol.h:27
std::optional< uint64_t > value
Definition: Symbol.h:24
std::optional< uint64_t > size
Definition: Symbol.h:25