1 | //===-- SBModule.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_API_SBMODULE_H |
10 | #define LLDB_API_SBMODULE_H |
11 | |
12 | #include "lldb/API/SBDefines.h" |
13 | #include "lldb/API/SBError.h" |
14 | #include "lldb/API/SBSection.h" |
15 | #include "lldb/API/SBSymbolContext.h" |
16 | #include "lldb/API/SBValueList.h" |
17 | |
18 | namespace lldb { |
19 | |
20 | class LLDB_API SBModule { |
21 | public: |
22 | SBModule(); |
23 | |
24 | SBModule(const SBModule &rhs); |
25 | |
26 | SBModule(const SBModuleSpec &module_spec); |
27 | |
28 | const SBModule &operator=(const SBModule &rhs); |
29 | |
30 | SBModule(lldb::SBProcess &process, lldb::addr_t ); |
31 | |
32 | ~SBModule(); |
33 | |
34 | explicit operator bool() const; |
35 | |
36 | bool IsValid() const; |
37 | |
38 | void Clear(); |
39 | |
40 | bool IsFileBacked() const; |
41 | |
42 | /// Get const accessor for the module file specification. |
43 | /// |
44 | /// This function returns the file for the module on the host system |
45 | /// that is running LLDB. This can differ from the path on the |
46 | /// platform since we might be doing remote debugging. |
47 | /// |
48 | /// \return |
49 | /// A const reference to the file specification object. |
50 | lldb::SBFileSpec GetFileSpec() const; |
51 | |
52 | /// Get accessor for the module platform file specification. |
53 | /// |
54 | /// Platform file refers to the path of the module as it is known on |
55 | /// the remote system on which it is being debugged. For local |
56 | /// debugging this is always the same as Module::GetFileSpec(). But |
57 | /// remote debugging might mention a file '/usr/lib/liba.dylib' |
58 | /// which might be locally downloaded and cached. In this case the |
59 | /// platform file could be something like: |
60 | /// '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib' |
61 | /// The file could also be cached in a local developer kit directory. |
62 | /// |
63 | /// \return |
64 | /// A const reference to the file specification object. |
65 | lldb::SBFileSpec GetPlatformFileSpec() const; |
66 | |
67 | bool SetPlatformFileSpec(const lldb::SBFileSpec &platform_file); |
68 | |
69 | /// Get accessor for the remote install path for a module. |
70 | /// |
71 | /// When debugging to a remote platform by connecting to a remote |
72 | /// platform, the install path of the module can be set. If the |
73 | /// install path is set, every time the process is about to launch |
74 | /// the target will install this module on the remote platform prior |
75 | /// to launching. |
76 | /// |
77 | /// \return |
78 | /// A file specification object. |
79 | lldb::SBFileSpec GetRemoteInstallFileSpec(); |
80 | |
81 | /// Set accessor for the remote install path for a module. |
82 | /// |
83 | /// When debugging to a remote platform by connecting to a remote |
84 | /// platform, the install path of the module can be set. If the |
85 | /// install path is set, every time the process is about to launch |
86 | /// the target will install this module on the remote platform prior |
87 | /// to launching. |
88 | /// |
89 | /// If \a file specifies a full path to an install location, the |
90 | /// module will be installed to this path. If the path is relative |
91 | /// (no directory specified, or the path is partial like "usr/lib" |
92 | /// or "./usr/lib", then the install path will be resolved using |
93 | /// the platform's current working directory as the base path. |
94 | /// |
95 | /// \param[in] file |
96 | /// A file specification object. |
97 | bool SetRemoteInstallFileSpec(lldb::SBFileSpec &file); |
98 | |
99 | lldb::ByteOrder GetByteOrder(); |
100 | |
101 | uint32_t GetAddressByteSize(); |
102 | |
103 | const char *GetTriple(); |
104 | |
105 | const uint8_t *GetUUIDBytes() const; |
106 | |
107 | const char *GetUUIDString() const; |
108 | |
109 | bool operator==(const lldb::SBModule &rhs) const; |
110 | |
111 | bool operator!=(const lldb::SBModule &rhs) const; |
112 | |
113 | lldb::SBSection FindSection(const char *sect_name); |
114 | |
115 | lldb::SBAddress ResolveFileAddress(lldb::addr_t vm_addr); |
116 | |
117 | lldb::SBSymbolContext |
118 | ResolveSymbolContextForAddress(const lldb::SBAddress &addr, |
119 | uint32_t resolve_scope); |
120 | |
121 | bool GetDescription(lldb::SBStream &description); |
122 | |
123 | uint32_t GetNumCompileUnits(); |
124 | |
125 | lldb::SBCompileUnit GetCompileUnitAtIndex(uint32_t); |
126 | |
127 | /// Find compile units related to *this module and passed source |
128 | /// file. |
129 | /// |
130 | /// \param[in] sb_file_spec |
131 | /// A lldb::SBFileSpec object that contains source file |
132 | /// specification. |
133 | /// |
134 | /// \return |
135 | /// A lldb::SBSymbolContextList that gets filled in with all of |
136 | /// the symbol contexts for all the matches. |
137 | lldb::SBSymbolContextList |
138 | FindCompileUnits(const lldb::SBFileSpec &sb_file_spec); |
139 | |
140 | size_t GetNumSymbols(); |
141 | |
142 | lldb::SBSymbol GetSymbolAtIndex(size_t idx); |
143 | |
144 | lldb::SBSymbol FindSymbol(const char *name, |
145 | lldb::SymbolType type = eSymbolTypeAny); |
146 | |
147 | lldb::SBSymbolContextList FindSymbols(const char *name, |
148 | lldb::SymbolType type = eSymbolTypeAny); |
149 | |
150 | size_t GetNumSections(); |
151 | |
152 | lldb::SBSection GetSectionAtIndex(size_t idx); |
153 | /// Find functions by name. |
154 | /// |
155 | /// \param[in] name |
156 | /// The name of the function we are looking for. |
157 | /// |
158 | /// \param[in] name_type_mask |
159 | /// A logical OR of one or more FunctionNameType enum bits that |
160 | /// indicate what kind of names should be used when doing the |
161 | /// lookup. Bits include fully qualified names, base names, |
162 | /// C++ methods, or ObjC selectors. |
163 | /// See FunctionNameType for more details. |
164 | /// |
165 | /// \return |
166 | /// A lldb::SBSymbolContextList that gets filled in with all of |
167 | /// the symbol contexts for all the matches. |
168 | lldb::SBSymbolContextList |
169 | FindFunctions(const char *name, |
170 | uint32_t name_type_mask = lldb::eFunctionNameTypeAny); |
171 | |
172 | /// Find global and static variables by name. |
173 | /// |
174 | /// \param[in] target |
175 | /// A valid SBTarget instance representing the debuggee. |
176 | /// |
177 | /// \param[in] name |
178 | /// The name of the global or static variable we are looking |
179 | /// for. |
180 | /// |
181 | /// \param[in] max_matches |
182 | /// Allow the number of matches to be limited to \a max_matches. |
183 | /// |
184 | /// \return |
185 | /// A list of matched variables in an SBValueList. |
186 | lldb::SBValueList FindGlobalVariables(lldb::SBTarget &target, |
187 | const char *name, uint32_t max_matches); |
188 | |
189 | /// Find the first global (or static) variable by name. |
190 | /// |
191 | /// \param[in] target |
192 | /// A valid SBTarget instance representing the debuggee. |
193 | /// |
194 | /// \param[in] name |
195 | /// The name of the global or static variable we are looking |
196 | /// for. |
197 | /// |
198 | /// \return |
199 | /// An SBValue that gets filled in with the found variable (if any). |
200 | lldb::SBValue FindFirstGlobalVariable(lldb::SBTarget &target, |
201 | const char *name); |
202 | |
203 | lldb::SBType FindFirstType(const char *name); |
204 | |
205 | lldb::SBTypeList FindTypes(const char *type); |
206 | |
207 | /// Get a type using its type ID. |
208 | /// |
209 | /// Each symbol file reader will assign different user IDs to their |
210 | /// types, but it is sometimes useful when debugging type issues to |
211 | /// be able to grab a type using its type ID. |
212 | /// |
213 | /// For DWARF debug info, the type ID is the DIE offset. |
214 | /// |
215 | /// \param[in] uid |
216 | /// The type user ID. |
217 | /// |
218 | /// \return |
219 | /// An SBType for the given type ID, or an empty SBType if the |
220 | /// type was not found. |
221 | lldb::SBType GetTypeByID(lldb::user_id_t uid); |
222 | |
223 | lldb::SBType GetBasicType(lldb::BasicType type); |
224 | |
225 | /// Get all types matching \a type_mask from debug info in this |
226 | /// module. |
227 | /// |
228 | /// \param[in] type_mask |
229 | /// A bitfield that consists of one or more bits logically OR'ed |
230 | /// together from the lldb::TypeClass enumeration. This allows |
231 | /// you to request only structure types, or only class, struct |
232 | /// and union types. Passing in lldb::eTypeClassAny will return |
233 | /// all types found in the debug information for this module. |
234 | /// |
235 | /// \return |
236 | /// A list of types in this module that match \a type_mask |
237 | lldb::SBTypeList GetTypes(uint32_t type_mask = lldb::eTypeClassAny); |
238 | |
239 | /// Get the module version numbers. |
240 | /// |
241 | /// Many object files have a set of version numbers that describe |
242 | /// the version of the executable or shared library. Typically there |
243 | /// are major, minor and build, but there may be more. This function |
244 | /// will extract the versions from object files if they are available. |
245 | /// |
246 | /// If \a versions is NULL, or if \a num_versions is 0, the return |
247 | /// value will indicate how many version numbers are available in |
248 | /// this object file. Then a subsequent call can be made to this |
249 | /// function with a value of \a versions and \a num_versions that |
250 | /// has enough storage to store some or all version numbers. |
251 | /// |
252 | /// \param[out] versions |
253 | /// A pointer to an array of uint32_t types that is \a num_versions |
254 | /// long. If this value is NULL, the return value will indicate |
255 | /// how many version numbers are required for a subsequent call |
256 | /// to this function so that all versions can be retrieved. If |
257 | /// the value is non-NULL, then at most \a num_versions of the |
258 | /// existing versions numbers will be filled into \a versions. |
259 | /// If there is no version information available, \a versions |
260 | /// will be filled with \a num_versions UINT32_MAX values |
261 | /// and zero will be returned. |
262 | /// |
263 | /// \param[in] num_versions |
264 | /// The maximum number of entries to fill into \a versions. If |
265 | /// this value is zero, then the return value will indicate |
266 | /// how many version numbers there are in total so another call |
267 | /// to this function can be make with adequate storage in |
268 | /// \a versions to get all of the version numbers. If \a |
269 | /// num_versions is less than the actual number of version |
270 | /// numbers in this object file, only \a num_versions will be |
271 | /// filled into \a versions (if \a versions is non-NULL). |
272 | /// |
273 | /// \return |
274 | /// This function always returns the number of version numbers |
275 | /// that this object file has regardless of the number of |
276 | /// version numbers that were copied into \a versions. |
277 | uint32_t GetVersion(uint32_t *versions, uint32_t num_versions); |
278 | |
279 | /// Get accessor for the symbol file specification. |
280 | /// |
281 | /// When debugging an object file an additional debug information can |
282 | /// be provided in separate file. Therefore if you debugging something |
283 | /// like '/usr/lib/liba.dylib' then debug information can be located |
284 | /// in folder like '/usr/lib/liba.dylib.dSYM/'. |
285 | /// |
286 | /// \return |
287 | /// A const reference to the file specification object. |
288 | lldb::SBFileSpec GetSymbolFileSpec() const; |
289 | |
290 | lldb::SBAddress () const; |
291 | lldb::SBAddress GetObjectFileEntryPointAddress() const; |
292 | |
293 | /// Get the number of global modules. |
294 | static uint32_t GetNumberAllocatedModules(); |
295 | |
296 | /// Remove any global modules which are no longer needed. |
297 | static void GarbageCollectAllocatedModules(); |
298 | |
299 | private: |
300 | friend class SBAddress; |
301 | friend class SBFrame; |
302 | friend class SBSection; |
303 | friend class SBSymbolContext; |
304 | friend class SBTarget; |
305 | friend class SBType; |
306 | |
307 | explicit SBModule(const lldb::ModuleSP &module_sp); |
308 | |
309 | ModuleSP GetSP() const; |
310 | |
311 | void SetSP(const ModuleSP &module_sp); |
312 | |
313 | lldb::ModuleSP m_opaque_sp; |
314 | }; |
315 | |
316 | } // namespace lldb |
317 | |
318 | #endif // LLDB_API_SBMODULE_H |
319 | |