LLDB  mainline
DataEncoder.h
Go to the documentation of this file.
1 //===-- DataEncoder.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_UTILITY_DATAENCODER_H
10 #define LLDB_UTILITY_DATAENCODER_H
11 
12 #if defined(__cplusplus)
13 
14 #include "lldb/lldb-defines.h"
15 #include "lldb/lldb-enumerations.h"
16 #include "lldb/lldb-forward.h"
17 #include "lldb/lldb-types.h"
18 
19 #include "llvm/ADT/ArrayRef.h"
20 #include "llvm/ADT/StringRef.h"
21 
22 #include <cstddef>
23 #include <cstdint>
24 
25 namespace lldb_private {
26 
27 /// \class DataEncoder
28 ///
29 /// An binary data encoding class.
30 ///
31 /// DataEncoder is a class that can encode binary data (swapping if needed) to
32 /// a data buffer. The DataEncoder can be constructed with data that will be
33 /// copied into the internally owned buffer. This allows data to be modified
34 /// in the internal buffer. The DataEncoder object can also be constructed with
35 /// just a byte order and address size and data can be appended to the
36 /// internally owned buffer.
37 ///
38 /// Clients can get a shared pointer to the data buffer when done modifying or
39 /// creating the data to keep the data around after the lifetime of a
40 /// DataEncoder object. \see GetDataBuffer
41 ///
42 /// Client can get a reference to the object owned data as an array by calling
43 /// the GetData method. \see GetData
44 class DataEncoder {
45 public:
46  /// Default constructor.
47  ///
48  /// Initialize all members to a default empty state and create a empty memory
49  /// buffer that can be appended to. The ByteOrder and address size will be set
50  /// to match the current host system.
51  DataEncoder();
52 
53  /// Construct an encoder that copies the specified data into the object owned
54  /// data buffer.
55  ///
56  /// This constructor is designed to be used when you have a data buffer and
57  /// want to modify values within the buffer. A copy of the data will be made
58  /// in the internally owned buffer and that data can be fixed up and appended
59  /// to.
60  ///
61  /// \param[in] data
62  /// A pointer to caller owned data.
63  ///
64  /// \param[in] data_length
65  /// The length in bytes of \a data.
66  ///
67  /// \param[in] byte_order
68  /// A byte order for the data that will be encoded.
69  ///
70  /// \param[in] addr_size
71  /// A size of an address in bytes. \see PutAddress, AppendAddress
72  DataEncoder(const void *data, uint32_t data_length,
73  lldb::ByteOrder byte_order, uint8_t addr_size);
74 
75  /// Construct an encoder that owns a heap based memory buffer.
76  ///
77  /// This allows clients to create binary data from scratch by appending values
78  /// with the methods that start with "Append".
79  ///
80  /// \param[in] byte_order
81  /// A byte order for the data that will be encoded.
82  ///
83  /// \param[in] addr_size
84  /// A size of an address in bytes. \see PutAddress, AppendAddress
85  DataEncoder(lldb::ByteOrder byte_order, uint8_t addr_size);
86 
87  ~DataEncoder();
88 
89  /// Encode an unsigned integer of size \a byte_size to \a offset.
90  ///
91  /// Encode a single integer value at \a offset and return the offset that
92  /// follows the newly encoded integer when the data is successfully encoded
93  /// into the existing data. There must be enough room in the existing data,
94  /// else UINT32_MAX will be returned to indicate that encoding failed.
95  ///
96  /// \param[in] offset
97  /// The offset within the contained data at which to put the encoded
98  /// integer.
99  ///
100  /// \param[in] byte_size
101  /// The size in byte of the integer to encode.
102  ///
103  /// \param[in] value
104  /// The integer value to write. The least significant bytes of
105  /// the integer value will be written if the size is less than
106  /// 8 bytes.
107  ///
108  /// \return
109  /// The next offset in the bytes of this data if the integer
110  /// was successfully encoded, UINT32_MAX if the encoding failed.
111  uint32_t PutUnsigned(uint32_t offset, uint32_t byte_size, uint64_t value);
112 
113  /// Encode an unsigned integer at offset \a offset.
114  ///
115  /// Encode a single unsigned integer value at \a offset and return the offset
116  /// that follows the newly encoded integer when the data is successfully
117  /// encoded into the existing data. There must be enough room in the data,
118  /// else UINT32_MAX will be returned to indicate that encoding failed.
119  ///
120  /// \param[in] offset
121  /// The offset within the contained data at which to put the encoded
122  /// integer.
123  ///
124  /// \param[in] value
125  /// The integer value to write.
126  ///
127  /// \return
128  /// The next offset in the bytes of this data if the integer was
129  /// successfully encoded, UINT32_MAX if the encoding failed.
130  uint32_t PutU8(uint32_t offset, uint8_t value);
131  uint32_t PutU16(uint32_t offset, uint16_t value);
132  uint32_t PutU32(uint32_t offset, uint32_t value);
133  uint32_t PutU64(uint32_t offset, uint64_t value);
134 
135  /// Append a unsigned integer to the end of the owned data.
136  ///
137  /// \param value
138  /// A unsigned integer value to append.
139  void AppendU8(uint8_t value);
140  void AppendU16(uint16_t value);
141  void AppendU32(uint32_t value);
142  void AppendU64(uint64_t value);
143 
144  /// Append an address sized integer to the end of the owned data.
145  ///
146  /// \param addr
147  /// A unsigned integer address value to append. The size of the address
148  /// will be determined by the address size specified in the constructor.
149  void AppendAddress(lldb::addr_t addr);
150 
151  /// Append a bytes to the end of the owned data.
152  ///
153  /// Append the bytes contained in the string reference. This function will
154  /// not append a NULL termination character for a C string. Use the
155  /// AppendCString function for this purpose.
156  ///
157  /// \param data
158  /// A string reference that contains bytes to append.
159  void AppendData(llvm::StringRef data);
160 
161  /// Append a bytes to the end of the owned data.
162  ///
163  /// Append the bytes contained in the array reference.
164  ///
165  /// \param data
166  /// A array reference that contains bytes to append.
167  void AppendData(llvm::ArrayRef<uint8_t> data);
168 
169  /// Append a C string to the end of the owned data.
170  ///
171  /// Append the bytes contained in the string reference along with an extra
172  /// NULL termination character if the StringRef bytes doesn't include one as
173  /// the last byte.
174  ///
175  /// \param data
176  /// A string reference that contains bytes to append.
177  void AppendCString(llvm::StringRef data);
178 
179  /// Encode an arbitrary number of bytes.
180  ///
181  /// \param[in] offset
182  /// The offset in bytes into the contained data at which to
183  /// start encoding.
184  ///
185  /// \param[in] src
186  /// The buffer that contains the bytes to encode.
187  ///
188  /// \param[in] src_len
189  /// The number of bytes to encode.
190  ///
191  /// \return
192  /// The next valid offset within data if the put operation
193  /// was successful, else UINT32_MAX to indicate the put failed.
194  uint32_t PutData(uint32_t offset, const void *src, uint32_t src_len);
195 
196  /// Encode an address in the existing buffer at \a offset bytes into the
197  /// buffer.
198  ///
199  /// Encode a single address to the data and return the next offset where
200  /// subsequent data would go. The size of the address comes from the \a
201  /// m_addr_size member variable and should be set correctly prior to encoding
202  /// any address values.
203  ///
204  /// \param[in] offset
205  /// The offset where to encode the address.
206  ///
207  /// \param[in] addr
208  /// The address to encode.
209  ///
210  /// \return
211  /// The next valid offset within data if the put operation
212  /// was successful, else UINT32_MAX to indicate the put failed.
213  uint32_t PutAddress(uint32_t offset, lldb::addr_t addr);
214 
215  /// Put a C string to \a offset.
216  ///
217  /// Encodes a C string into the existing data including the terminating. If
218  /// there is not enough room in the buffer to fit the entire C string and the
219  /// NULL terminator in the existing buffer bounds, then this function will
220  /// fail.
221  ///
222  /// \param[in] offset
223  /// The offset where to encode the string.
224  ///
225  /// \param[in] cstr
226  /// The string to encode.
227  ///
228  /// \return
229  /// The next valid offset within data if the put operation was successful,
230  /// else UINT32_MAX to indicate the put failed.
231  uint32_t PutCString(uint32_t offset, const char *cstr);
232 
233  /// Get a shared copy of the heap based memory buffer owned by this object.
234  ///
235  /// This allows a data encoder to be used to create a data buffer that can
236  /// be extracted and used elsewhere after this object is destroyed.
237  ///
238  /// \return
239  /// A shared pointer to the DataBufferHeap that contains the data that was
240  /// encoded into this object.
241  std::shared_ptr<lldb_private::DataBufferHeap> GetDataBuffer() {
242  return m_data_sp;
243  }
244 
245  /// Get a access to the bytes that this references.
246  ///
247  /// This value will always return the data that this object references even if
248  /// the object was constructed with caller owned data.
249  ///
250  /// \return
251  /// A array reference to the data that this object references.
252  llvm::ArrayRef<uint8_t> GetData() const;
253 
254  /// Get the number of bytes contained in this object.
255  ///
256  /// \return
257  /// The total number of bytes of data this object refers to.
258  size_t GetByteSize() const;
259 
260  lldb::ByteOrder GetByteOrder() const { return m_byte_order; }
261 
262  /// The address size to use when encoding pointers or addresses.
263  uint8_t GetAddressByteSize() const { return m_addr_size; }
264 
265 private:
266  uint32_t BytesLeft(uint32_t offset) const {
267  const uint32_t size = GetByteSize();
268  if (size > offset)
269  return size - offset;
270  return 0;
271  }
272 
273  /// Test the availability of \a length bytes of data from \a offset.
274  ///
275  /// \return
276  /// \b true if \a offset is a valid offset and there are \a
277  /// length bytes available at that offset, \b false otherwise.
278  bool ValidOffsetForDataOfSize(uint32_t offset, uint32_t length) const {
279  return length <= BytesLeft(offset);
280  }
281 
282  /// Test the validity of \a offset.
283  ///
284  /// \return
285  /// \b true if \a offset is a valid offset into the data in this
286  /// object, \b false otherwise.
287  bool ValidOffset(uint32_t offset) const { return offset < GetByteSize(); }
288 
289  /// The shared pointer to data that can grow as data is added
290  std::shared_ptr<lldb_private::DataBufferHeap> m_data_sp;
291 
292  /// The byte order of the data we are encoding to.
293  const lldb::ByteOrder m_byte_order;
294 
295  /// The address size to use when encoding pointers or addresses.
296  const uint8_t m_addr_size;
297 
298  DataEncoder(const DataEncoder &) = delete;
299  const DataEncoder &operator=(const DataEncoder &) = delete;
300 };
301 
302 } // namespace lldb_private
303 
304 #endif // #if defined (__cplusplus)
305 #endif // LLDB_UTILITY_DATAENCODER_H
lldb-defines.h
lldb::addr_t
uint64_t addr_t
Definition: lldb-types.h:83
lldb-enumerations.h
lldb-types.h
uint32_t
uint16_t
lldb-forward.h
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb::ByteOrder
ByteOrder
Byte ordering definitions.
Definition: lldb-enumerations.h:138