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
306