1 //===-- AddressRange.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_CORE_ADDRESSRANGE_H
10 #define LLDB_CORE_ADDRESSRANGE_H
11 
12 #include "lldb/Core/Address.h"
13 #include "lldb/lldb-forward.h"
14 #include "lldb/lldb-types.h"
15 
16 #include <cstddef>
17 
18 namespace lldb_private {
19 class SectionList;
20 class Stream;
21 class Target;
22 
23 /// \class AddressRange AddressRange.h "lldb/Core/AddressRange.h"
24 /// A section + offset based address range class.
25 class AddressRange {
26 public:
27   /// Default constructor.
28   ///
29   /// Initialize with a invalid section (NULL), an invalid offset
30   /// (LLDB_INVALID_ADDRESS), and zero byte size.
31   AddressRange();
32 
33   /// Construct with a section pointer, offset, and byte_size.
34   ///
35   /// Initialize the address with the supplied \a section, \a offset and \a
36   /// byte_size.
37   ///
38   /// \param[in] section
39   ///     A section pointer to a valid lldb::Section, or NULL if the
40   ///     address doesn't have a section or will get resolved later.
41   ///
42   /// \param[in] offset
43   ///     The offset in bytes into \a section.
44   ///
45   /// \param[in] byte_size
46   ///     The size in bytes of the address range.
47   AddressRange(const lldb::SectionSP &section, lldb::addr_t offset,
48                lldb::addr_t byte_size);
49 
50   /// Construct with a virtual address, section list and byte size.
51   ///
52   /// Initialize and resolve the address with the supplied virtual address \a
53   /// file_addr, and byte size \a byte_size.
54   ///
55   /// \param[in] file_addr
56   ///     A virtual address.
57   ///
58   /// \param[in] byte_size
59   ///     The size in bytes of the address range.
60   ///
61   /// \param[in] section_list
62   ///     A list of sections, one of which may contain the \a vaddr.
63   AddressRange(lldb::addr_t file_addr, lldb::addr_t byte_size,
64                const SectionList *section_list = nullptr);
65 
66   /// Construct with a Address object address and byte size.
67   ///
68   /// Initialize by copying the section offset address in \a so_addr, and
69   /// setting the byte size to \a byte_size.
70   ///
71   /// \param[in] so_addr
72   ///     A section offset address object.
73   ///
74   /// \param[in] byte_size
75   ///     The size in bytes of the address range.
76   AddressRange(const Address &so_addr, lldb::addr_t byte_size);
77 
78   /// Destructor.
79   ///
80   /// The destructor is virtual in case this class is subclassed.
81   ~AddressRange();
82 
83   /// Clear the object's state.
84   ///
85   /// Sets the section to an invalid value (NULL), an invalid offset
86   /// (LLDB_INVALID_ADDRESS) and a zero byte size.
87   void Clear();
88 
89   /// Check if a section offset address is contained in this range.
90   ///
91   /// \param[in] so_addr
92   ///     A section offset address object reference.
93   ///
94   /// \return
95   ///     Returns \b true if \a so_addr is contained in this range,
96   ///     \b false otherwise.
97   bool Contains(const Address &so_addr) const;
98 
99   /// Check if a section offset address is contained in this range.
100   ///
101   /// \param[in] so_addr_ptr
102   ///     A section offset address object pointer.
103   ///
104   /// \return
105   ///     Returns \b true if \a so_addr is contained in this range,
106   ///     \b false otherwise.
107   //    bool
108   //    Contains (const Address *so_addr_ptr) const;
109 
110   /// Check if a section offset \a so_addr when represented as a file address
111   /// is contained within this object's file address range.
112   ///
113   /// \param[in] so_addr
114   ///     A section offset address object reference.
115   ///
116   /// \return
117   ///     Returns \b true if both \a this and \a so_addr have
118   ///     resolvable file address values and \a so_addr is contained
119   ///     in the address range, \b false otherwise.
120   bool ContainsFileAddress(const Address &so_addr) const;
121 
122   /// Check if the resolved file address \a file_addr is contained within this
123   /// object's file address range.
124   ///
125   /// \param[in] file_addr
126   ///     A section offset address object reference.
127   ///
128   /// \return
129   ///     Returns \b true if both \a this has a resolvable file
130   ///     address value and \a so_addr is contained in the address
131   ///     range, \b false otherwise.
132   bool ContainsFileAddress(lldb::addr_t file_addr) const;
133 
134   /// Check if a section offset \a so_addr when represented as a load address
135   /// is contained within this object's load address range.
136   ///
137   /// \param[in] so_addr
138   ///     A section offset address object reference.
139   ///
140   /// \return
141   ///     Returns \b true if both \a this and \a so_addr have
142   ///     resolvable load address values and \a so_addr is contained
143   ///     in the address range, \b false otherwise.
144   bool ContainsLoadAddress(const Address &so_addr, Target *target) const;
145 
146   /// Check if the resolved load address \a load_addr is contained within this
147   /// object's load address range.
148   ///
149   /// \return
150   ///     Returns \b true if both \a this has a resolvable load
151   ///     address value and \a so_addr is contained in the address
152   ///     range, \b false otherwise.
153   bool ContainsLoadAddress(lldb::addr_t load_addr, Target *target) const;
154 
155   //------------------------------------------------------------------
156   /// Extends this range with \b rhs_range if it overlaps this range on the
157   /// right side. The range overlaps on the right side if the base address
158   /// of \b rhs_range lies within this range or if it's contiguous on its
159   /// right side.
160   ///
161   /// @param[in] rhs_range
162   ///     The range to extend at the right side.
163   ///
164   /// @return
165   ///     Returns \b true if this range was extended, \b false otherwise.
166   //------------------------------------------------------------------
167   bool Extend(const AddressRange &rhs_range);
168 
169   /// Dump a description of this object to a Stream.
170   ///
171   /// Dump a description of the contents of this object to the supplied stream
172   /// \a s. There are many ways to display a section offset based address
173   /// range, and \a style lets the user choose how the base address gets
174   /// displayed.
175   ///
176   /// \param[in] s
177   ///     The stream to which to dump the object description.
178   ///
179   /// \param[in] style
180   ///     The display style for the address.
181   ///
182   /// \return
183   ///     Returns \b true if the address was able to be displayed.
184   ///     File and load addresses may be unresolved and it may not be
185   ///     possible to display a valid value, \b false will be returned
186   ///     in such cases.
187   ///
188   /// \see Address::DumpStyle
189   bool
190   Dump(Stream *s, Target *target, Address::DumpStyle style,
191        Address::DumpStyle fallback_style = Address::DumpStyleInvalid) const;
192 
193   /// Dump a debug description of this object to a Stream.
194   ///
195   /// Dump a debug description of the contents of this object to the supplied
196   /// stream \a s.
197   ///
198   /// The debug description contains verbose internal state such and pointer
199   /// values, reference counts, etc.
200   ///
201   /// \param[in] s
202   ///     The stream to which to dump the object description.
203   void DumpDebug(Stream *s) const;
204 
205   /// Get accessor for the base address of the range.
206   ///
207   /// \return
208   ///     A reference to the base address object.
209   Address &GetBaseAddress() { return m_base_addr; }
210 
211   /// Get const accessor for the base address of the range.
212   ///
213   /// \return
214   ///     A const reference to the base address object.
215   const Address &GetBaseAddress() const { return m_base_addr; }
216 
217   /// Get accessor for the byte size of this range.
218   ///
219   /// \return
220   ///     The size in bytes of this address range.
221   lldb::addr_t GetByteSize() const { return m_byte_size; }
222 
223   /// Get the memory cost of this object.
224   ///
225   /// \return
226   ///     The number of bytes that this object occupies in memory.
227   size_t MemorySize() const {
228     // Noting special for the memory size of a single AddressRange object, it
229     // is just the size of itself.
230     return sizeof(AddressRange);
231   }
232 
233   /// Set accessor for the byte size of this range.
234   ///
235   /// \param[in] byte_size
236   ///     The new size in bytes of this address range.
237   void SetByteSize(lldb::addr_t byte_size) { m_byte_size = byte_size; }
238 
239 protected:
240   // Member variables
241   Address m_base_addr;      ///< The section offset base address of this range.
242   lldb::addr_t m_byte_size = 0; ///< The size in bytes of this address range.
243 };
244 
245 } // namespace lldb_private
246 
247 #endif // LLDB_CORE_ADDRESSRANGE_H
248