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