contrib/llvm-project/lldb/bindings/interface/SBAddress.i

   1 //===-- SWIG Interface for SBAddress ----------------------------*- 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 namespace lldb {
  10
  11 %feature("docstring",
  12 "A section + offset based address class.
  13
  14 The SBAddress class allows addresses to be relative to a section
  15 that can move during runtime due to images (executables, shared
  16 libraries, bundles, frameworks) being loaded at different
  17 addresses than the addresses found in the object file that
  18 represents them on disk. There are currently two types of addresses
  19 for a section:
  20     o file addresses
  21     o load addresses
  22
  23 File addresses represents the virtual addresses that are in the 'on
  24 disk' object files. These virtual addresses are converted to be
  25 relative to unique sections scoped to the object file so that
  26 when/if the addresses slide when the images are loaded/unloaded
  27 in memory, we can easily track these changes without having to
  28 update every object (compile unit ranges, line tables, function
  29 address ranges, lexical block and inlined subroutine address
  30 ranges, global and static variables) each time an image is loaded or
  31 unloaded.
  32
  33 Load addresses represents the virtual addresses where each section
  34 ends up getting loaded at runtime. Before executing a program, it
  35 is common for all of the load addresses to be unresolved. When a
  36 DynamicLoader plug-in receives notification that shared libraries
  37 have been loaded/unloaded, the load addresses of the main executable
  38 and any images (shared libraries) will be  resolved/unresolved. When
  39 this happens, breakpoints that are in one of these sections can be
  40 set/cleared.
  41
  42 See docstring of SBFunction for example usage of SBAddress."
  43 ) SBAddress;
  44 class SBAddress
  45 {
  46 public:
  47
  48     SBAddress ();
  49
  50     SBAddress (const lldb::SBAddress &rhs);
  51
  52     SBAddress (lldb::SBSection section,
  53                lldb::addr_t offset);
  54
  55     %feature("docstring", "
  56     Create an address by resolving a load address using the supplied target.") SBAddress;
  57     SBAddress (lldb::addr_t load_addr, lldb::SBTarget &target);
  58
  59     ~SBAddress ();
  60
  61     bool
  62     IsValid () const;
  63
  64     explicit operator bool() const;
  65
  66 #ifdef SWIGPYTHON
  67     // operator== is a free function, which swig does not handle, so we inject
  68     // our own equality operator here
  69     %pythoncode%{
  70     def __eq__(self, other):
  71       return not self.__ne__(other)
  72     %}
  73 #endif
  74
  75     bool operator!=(const SBAddress &rhs) const;
  76
  77     void
  78     Clear ();
  79
  80     addr_t
  81     GetFileAddress () const;
  82
  83     addr_t
  84     GetLoadAddress (const lldb::SBTarget &target) const;
  85
  86     void
  87     SetLoadAddress (lldb::addr_t load_addr,
  88                     lldb::SBTarget &target);
  89
  90     bool
  91     OffsetAddress (addr_t offset);
  92
  93     bool
  94     GetDescription (lldb::SBStream &description);
  95
  96     lldb::SBSection
  97     GetSection ();
  98
  99     lldb::addr_t
 100     SBAddress::GetOffset ();
 101
 102     void
 103     SetAddress (lldb::SBSection section,
 104                 lldb::addr_t offset);
 105
 106     %feature("docstring", "
 107     GetSymbolContext() and the following can lookup symbol information for a given address.
 108     An address might refer to code or data from an existing module, or it
 109     might refer to something on the stack or heap. The following functions
 110     will only return valid values if the address has been resolved to a code
 111     or data address using 'void SBAddress::SetLoadAddress(...)' or
 112     'lldb::SBAddress SBTarget::ResolveLoadAddress (...)'.") GetSymbolContext;
 113     lldb::SBSymbolContext
 114     GetSymbolContext (uint32_t resolve_scope);
 115
 116     %feature("docstring", "
 117     GetModule() and the following grab individual objects for a given address and
 118     are less efficient if you want more than one symbol related objects.
 119     Use one of the following when you want multiple debug symbol related
 120     objects for an address:
 121        lldb::SBSymbolContext SBAddress::GetSymbolContext (uint32_t resolve_scope);
 122        lldb::SBSymbolContext SBTarget::ResolveSymbolContextForAddress (const SBAddress &addr, uint32_t resolve_scope);
 123     One or more bits from the SymbolContextItem enumerations can be logically
 124     OR'ed together to more efficiently retrieve multiple symbol objects.") GetModule;
 125     lldb::SBModule
 126     GetModule ();
 127
 128     lldb::SBCompileUnit
 129     GetCompileUnit ();
 130
 131     lldb::SBFunction
 132     GetFunction ();
 133
 134     lldb::SBBlock
 135     GetBlock ();
 136
 137     lldb::SBSymbol
 138     GetSymbol ();
 139
 140     lldb::SBLineEntry
 141     GetLineEntry ();
 142
 143     STRING_EXTENSION(SBAddress)
 144
 145 #ifdef SWIGPYTHON
 146     %pythoncode %{
 147         def __get_load_addr_property__ (self):
 148             '''Get the load address for a lldb.SBAddress using the current target.'''
 149             return self.GetLoadAddress (target)
 150
 151         def __set_load_addr_property__ (self, load_addr):
 152             '''Set the load address for a lldb.SBAddress using the current target.'''
 153             return self.SetLoadAddress (load_addr, target)
 154
 155         def __int__(self):
 156             '''Convert an address to a load address if there is a process and that process is alive, or to a file address otherwise.'''
 157             if process.is_alive:
 158                 return self.GetLoadAddress (target)
 159             else:
 160                 return self.GetFileAddress ()
 161
 162         def __oct__(self):
 163             '''Convert the address to an octal string'''
 164             return '%o' % int(self)
 165
 166         def __hex__(self):
 167             '''Convert the address to an hex string'''
 168             return '0x%x' % int(self)
 169
 170         module = property(GetModule, None, doc='''A read only property that returns an lldb object that represents the module (lldb.SBModule) that this address resides within.''')
 171         compile_unit = property(GetCompileUnit, None, doc='''A read only property that returns an lldb object that represents the compile unit (lldb.SBCompileUnit) that this address resides within.''')
 172         line_entry = property(GetLineEntry, None, doc='''A read only property that returns an lldb object that represents the line entry (lldb.SBLineEntry) that this address resides within.''')
 173         function = property(GetFunction, None, doc='''A read only property that returns an lldb object that represents the function (lldb.SBFunction) that this address resides within.''')
 174         block = property(GetBlock, None, doc='''A read only property that returns an lldb object that represents the block (lldb.SBBlock) that this address resides within.''')
 175         symbol = property(GetSymbol, None, doc='''A read only property that returns an lldb object that represents the symbol (lldb.SBSymbol) that this address resides within.''')
 176         offset = property(GetOffset, None, doc='''A read only property that returns the section offset in bytes as an integer.''')
 177         section = property(GetSection, None, doc='''A read only property that returns an lldb object that represents the section (lldb.SBSection) that this address resides within.''')
 178         file_addr = property(GetFileAddress, None, doc='''A read only property that returns file address for the section as an integer. This is the address that represents the address as it is found in the object file that defines it.''')
 179         load_addr = property(__get_load_addr_property__, __set_load_addr_property__, doc='''A read/write property that gets/sets the SBAddress using load address. The setter resolves SBAddress using the SBTarget from lldb.target so this property can ONLY be used in the interactive script interpreter (i.e. under the lldb script command) and not in Python based commands, or breakpoint commands.''')
 180     %}
 181 #endif
 182
 183 };
 184
 185 } // namespace lldb