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 
21 * file addresses
22 * load addresses
23 
24 File addresses represents the virtual addresses that are in the 'on
25 disk' object files. These virtual addresses are converted to be
26 relative to unique sections scoped to the object file so that
27 when/if the addresses slide when the images are loaded/unloaded
28 in memory, we can easily track these changes without having to
29 update every object (compile unit ranges, line tables, function
30 address ranges, lexical block and inlined subroutine address
31 ranges, global and static variables) each time an image is loaded or
32 unloaded.
33 
34 Load addresses represents the virtual addresses where each section
35 ends up getting loaded at runtime. Before executing a program, it
36 is common for all of the load addresses to be unresolved. When a
37 DynamicLoader plug-in receives notification that shared libraries
38 have been loaded/unloaded, the load addresses of the main executable
39 and any images (shared libraries) will be  resolved/unresolved. When
40 this happens, breakpoints that are in one of these sections can be
41 set/cleared.
42 
43 See docstring of SBFunction for example usage of SBAddress."
44 ) SBAddress;
45 class SBAddress
46 {
47 public:
48 
49     SBAddress ();
50 
51     SBAddress (const lldb::SBAddress &rhs);
52 
53     SBAddress (lldb::SBSection section,
54                lldb::addr_t offset);
55 
56     %feature("docstring", "
57     Create an address by resolving a load address using the supplied target.") SBAddress;
58     SBAddress (lldb::addr_t load_addr, lldb::SBTarget &target);
59 
60     ~SBAddress ();
61 
62     bool
63     IsValid () const;
64 
65     explicit operator bool() const;
66 
67 #ifdef SWIGPYTHON
68     // operator== is a free function, which swig does not handle, so we inject
69     // our own equality operator here
70     %pythoncode%{
71     def __eq__(self, other):
72       return not self.__ne__(other)
73     %}
74 #endif
75 
76     bool operator!=(const SBAddress &rhs) const;
77 
78     void
79     Clear ();
80 
81     addr_t
82     GetFileAddress () const;
83 
84     addr_t
85     GetLoadAddress (const lldb::SBTarget &target) const;
86 
87     void
88     SetLoadAddress (lldb::addr_t load_addr,
89                     lldb::SBTarget &target);
90 
91     bool
92     OffsetAddress (addr_t offset);
93 
94     bool
95     GetDescription (lldb::SBStream &description);
96 
97     lldb::SBSection
98     GetSection ();
99 
100     lldb::addr_t
101     SBAddress::GetOffset ();
102 
103     void
104     SetAddress (lldb::SBSection section,
105                 lldb::addr_t offset);
106 
107     %feature("docstring", "
108     GetSymbolContext() and the following can lookup symbol information for a given address.
109     An address might refer to code or data from an existing module, or it
110     might refer to something on the stack or heap. The following functions
111     will only return valid values if the address has been resolved to a code
112     or data address using :py:class:`SBAddress.SetLoadAddress' or
113     :py:class:`SBTarget.ResolveLoadAddress`.") GetSymbolContext;
114     lldb::SBSymbolContext
115     GetSymbolContext (uint32_t resolve_scope);
116 
117     %feature("docstring", "
118     GetModule() and the following grab individual objects for a given address and
119     are less efficient if you want more than one symbol related objects.
120     Use :py:class:`SBAddress.GetSymbolContext` or
121     :py:class:`SBTarget.ResolveSymbolContextForAddress` when you want multiple
122     debug symbol related objects for an address.
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         __runtime_error_str = 'This resolves the 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). For things like Python based commands and breakpoint callbacks use GetLoadAddress instead.'
148 
149         def __get_load_addr_property__ (self):
150             '''Get the load address for a lldb.SBAddress using the current target. This resolves the 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). For things like Python based commands and breakpoint callbacks use GetLoadAddress instead.'''
151             if not target:
152                 raise RuntimeError(self.__runtime_error_str)
153             return self.GetLoadAddress (target)
154 
155         def __set_load_addr_property__ (self, load_addr):
156             '''Set the load address for a lldb.SBAddress using the current target. This resolves the 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). For things like Python based commands and breakpoint callbacks use GetLoadAddress instead.'''
157             if not target:
158                 raise RuntimeError(self.__runtime_error_str)
159             return self.SetLoadAddress (load_addr, target)
160 
161         def __int__(self):
162             '''Convert an address to a load address if there is a process and that process is alive, or to a file address otherwise. This resolves the 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). For things like Python based commands and breakpoint callbacks use GetLoadAddress instead.'''
163             if not process or not target:
164                 raise RuntimeError(self.__runtime_error_str)
165             if process.is_alive:
166                 return self.GetLoadAddress (target)
167             return self.GetFileAddress ()
168 
169         def __oct__(self):
170             '''Convert the address to an octal string. This resolves the 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). For things like Python based commands and breakpoint callbacks use GetLoadAddress instead.'''
171             return '%o' % int(self)
172 
173         def __hex__(self):
174             '''Convert the address to an hex string. This resolves the 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). For things like Python based commands and breakpoint callbacks use GetLoadAddress instead.'''
175             return '0x%x' % int(self)
176 
177         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.''')
178         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.''')
179         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.''')
180         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.''')
181         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.''')
182         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.''')
183         offset = property(GetOffset, None, doc='''A read only property that returns the section offset in bytes as an integer.''')
184         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.''')
185         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.''')
186         load_addr = property(__get_load_addr_property__, __set_load_addr_property__, doc='''A read/write property that gets/sets the SBAddress using load address. This resolves the 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). For things like Python based commands and breakpoint callbacks use GetLoadAddress instead.''')
187     %}
188 #endif
189 
190 };
191 
192 } // namespace lldb
193