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 C string to the end of the owned data.
162   ///
163   /// Append the bytes contained in the string reference along with an extra
164   /// NULL termination character if the StringRef bytes doesn't include one as
165   /// the last byte.
166   ///
167   /// \param data
168   ///     A string reference that contains bytes to append.
169   void AppendCString(llvm::StringRef data);
170 
171   /// Encode an arbitrary number of bytes.
172   ///
173   /// \param[in] offset
174   ///     The offset in bytes into the contained data at which to
175   ///     start encoding.
176   ///
177   /// \param[in] src
178   ///     The buffer that contains the bytes to encode.
179   ///
180   /// \param[in] src_len
181   ///     The number of bytes to encode.
182   ///
183   /// \return
184   ///     The next valid offset within data if the put operation
185   ///     was successful, else UINT32_MAX to indicate the put failed.
186   uint32_t PutData(uint32_t offset, const void *src, uint32_t src_len);
187 
188   /// Encode an address in the existing buffer at \a offset bytes into the
189   /// buffer.
190   ///
191   /// Encode a single address to the data and return the next offset where
192   /// subsequent data would go. The size of the address comes from the \a
193   /// m_addr_size member variable and should be set correctly prior to encoding
194   /// any address values.
195   ///
196   /// \param[in] offset
197   ///     The offset where to encode the address.
198   ///
199   /// \param[in] addr
200   ///     The address to encode.
201   ///
202   /// \return
203   ///     The next valid offset within data if the put operation
204   ///     was successful, else UINT32_MAX to indicate the put failed.
205   uint32_t PutAddress(uint32_t offset, lldb::addr_t addr);
206 
207   /// Put a C string to \a offset.
208   ///
209   /// Encodes a C string into the existing data including the terminating. If
210   /// there is not enough room in the buffer to fit the entire C string and the
211   /// NULL terminator in the existing buffer bounds, then this function will
212   /// fail.
213   ///
214   /// \param[in] offset
215   ///     The offset where to encode the string.
216   ///
217   /// \param[in] cstr
218   ///     The string to encode.
219   ///
220   /// \return
221   ///     The next valid offset within data if the put operation was successful,
222   ///     else UINT32_MAX to indicate the put failed.
223   uint32_t PutCString(uint32_t offset, const char *cstr);
224 
225   /// Get a shared copy of the heap based memory buffer owned by this object.
226   ///
227   /// This allows a data encoder to be used to create a data buffer that can
228   /// be extracted and used elsewhere after this object is destroyed.
229   ///
230   /// \return
231   ///     A shared pointer to the DataBufferHeap that contains the data that was
232   ///     encoded into this object.
233   std::shared_ptr<lldb_private::DataBufferHeap> GetDataBuffer() {
234     return m_data_sp;
235   }
236 
237   /// Get a access to the bytes that this references.
238   ///
239   /// This value will always return the data that this object references even if
240   /// the object was constructed with caller owned data.
241   ///
242   /// \return
243   ///     A array reference to the data that this object references.
244   llvm::ArrayRef<uint8_t> GetData() const;
245 
246 private:
247   uint32_t BytesLeft(uint32_t offset) const {
248     const uint32_t size = GetByteSize();
249     if (size > offset)
250       return size - offset;
251     return 0;
252   }
253 
254   /// Test the availability of \a length bytes of data from \a offset.
255   ///
256   /// \return
257   ///     \b true if \a offset is a valid offset and there are \a
258   ///     length bytes available at that offset, \b false otherwise.
259   bool ValidOffsetForDataOfSize(uint32_t offset, uint32_t length) const {
260     return length <= BytesLeft(offset);
261   }
262 
263   /// Test the validity of \a offset.
264   ///
265   /// \return
266   ///     \b true if \a offset is a valid offset into the data in this
267   ///     object, \b false otherwise.
268   bool ValidOffset(uint32_t offset) const { return offset < GetByteSize(); }
269 
270   /// Get the number of bytes contained in this object.
271   ///
272   /// \return
273   ///     The total number of bytes of data this object refers to.
274   size_t GetByteSize() const;
275 
276   /// The shared pointer to data that can grow as data is added
277   std::shared_ptr<lldb_private::DataBufferHeap> m_data_sp;
278 
279   /// The byte order of the data we are encoding to.
280   lldb::ByteOrder m_byte_order;
281 
282   /// The address size to use when encoding pointers or addresses.
283   uint8_t m_addr_size;
284 
285   DataEncoder(const DataEncoder &) = delete;
286   const DataEncoder &operator=(const DataEncoder &) = delete;
287 };
288 
289 } // namespace lldb_private
290 
291 #endif // #if defined (__cplusplus)
292 #endif // LLDB_UTILITY_DATAENCODER_H
293