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