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"
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
25namespace 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
44class DataEncoder {
45public:
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
265private:
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
A class that represents a running process on the host machine.
Definition: SBAttachInfo.h:14
ByteOrder
Byte ordering definitions.
uint64_t addr_t
Definition: lldb-types.h:79