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 liblldb_DataEncoder_h_ 10 #define liblldb_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 <stddef.h> 20 #include <stdint.h> 21 22 namespace lldb_private { 23 24 //---------------------------------------------------------------------- 25 /// \class DataEncoder DataEncoder.h "lldb/Core/DataEncoder.h" An binary data 26 /// encoding class. 27 /// 28 /// DataEncoder is a class that can encode binary data (swapping if needed) to 29 /// a data buffer. The data buffer can be caller owned, or can be shared data 30 /// that can be shared between multiple DataEncoder or DataEncoder instances. 31 /// 32 /// \see DataBuffer 33 //---------------------------------------------------------------------- 34 class DataEncoder { 35 public: 36 //------------------------------------------------------------------ 37 /// Default constructor. 38 /// 39 /// Initialize all members to a default empty state. 40 //------------------------------------------------------------------ 41 DataEncoder(); 42 43 //------------------------------------------------------------------ 44 /// Construct with a buffer that is owned by the caller. 45 /// 46 /// This constructor allows us to use data that is owned by the caller. The 47 /// data must stay around as long as this object is valid. 48 /// 49 /// \param[in] data 50 /// A pointer to caller owned data. 51 /// 52 /// \param[in] data_length 53 /// The length in bytes of \a data. 54 /// 55 /// \param[in] byte_order 56 /// A byte order of the data that we are extracting from. 57 /// 58 /// \param[in] addr_size 59 /// A new address byte size value. 60 //------------------------------------------------------------------ 61 DataEncoder(void *data, uint32_t data_length, lldb::ByteOrder byte_order, 62 uint8_t addr_size); 63 64 //------------------------------------------------------------------ 65 /// Construct with shared data. 66 /// 67 /// Copies the data shared pointer which adds a reference to the contained 68 /// in \a data_sp. The shared data reference is reference counted to ensure 69 /// the data lives as long as anyone still has a valid shared pointer to the 70 /// data in \a data_sp. 71 /// 72 /// \param[in] data_sp 73 /// A shared pointer to data. 74 /// 75 /// \param[in] byte_order 76 /// A byte order of the data that we are extracting from. 77 /// 78 /// \param[in] addr_size 79 /// A new address byte size value. 80 //------------------------------------------------------------------ 81 DataEncoder(const lldb::DataBufferSP &data_sp, lldb::ByteOrder byte_order, 82 uint8_t addr_size); 83 84 //------------------------------------------------------------------ 85 /// Destructor 86 /// 87 /// If this object contains a valid shared data reference, the reference 88 /// count on the data will be decremented, and if zero, the data will be 89 /// freed. 90 //------------------------------------------------------------------ 91 ~DataEncoder(); 92 93 //------------------------------------------------------------------ 94 /// Clears the object state. 95 /// 96 /// Clears the object contents back to a default invalid state, and release 97 /// any references to shared data that this object may contain. 98 //------------------------------------------------------------------ 99 void Clear(); 100 101 //------------------------------------------------------------------ 102 /// Get the current address size. 103 /// 104 /// Return the size in bytes of any address values this object will extract. 105 /// 106 /// \return 107 /// The size in bytes of address values that will be extracted. 108 //------------------------------------------------------------------ 109 uint8_t GetAddressByteSize() const { return m_addr_size; } 110 111 //------------------------------------------------------------------ 112 /// Get the number of bytes contained in this object. 113 /// 114 /// \return 115 /// The total number of bytes of data this object refers to. 116 //------------------------------------------------------------------ 117 size_t GetByteSize() const { return m_end - m_start; } 118 119 //------------------------------------------------------------------ 120 /// Get the data end pointer. 121 /// 122 /// \return 123 /// Returns a pointer to the next byte contained in this 124 /// object's data, or NULL of there is no data in this object. 125 //------------------------------------------------------------------ 126 uint8_t *GetDataEnd() { return m_end; } 127 128 const uint8_t *GetDataEnd() const { return m_end; } 129 130 //------------------------------------------------------------------ 131 /// Get the shared data offset. 132 /// 133 /// Get the offset of the first byte of data in the shared data (if any). 134 /// 135 /// \return 136 /// If this object contains shared data, this function returns 137 /// the offset in bytes into that shared data, zero otherwise. 138 //------------------------------------------------------------------ 139 size_t GetSharedDataOffset() const; 140 141 //------------------------------------------------------------------ 142 /// Get the current byte order value. 143 /// 144 /// \return 145 /// The current byte order value from this object's internal 146 /// state. 147 //------------------------------------------------------------------ 148 lldb::ByteOrder GetByteOrder() const { return m_byte_order; } 149 150 //------------------------------------------------------------------ 151 /// Get the data start pointer. 152 /// 153 /// \return 154 /// Returns a pointer to the first byte contained in this 155 /// object's data, or NULL of there is no data in this object. 156 //------------------------------------------------------------------ 157 uint8_t *GetDataStart() { return m_start; } 158 159 const uint8_t *GetDataStart() const { return m_start; } 160 161 //------------------------------------------------------------------ 162 /// Encode unsigned integer values into the data at \a offset. 163 /// 164 /// \param[in] offset 165 /// The offset within the contained data at which to put the 166 /// data. 167 /// 168 /// \param[in] value 169 /// The value to encode into the data. 170 /// 171 /// \return 172 /// The next offset in the bytes of this data if the data 173 /// was successfully encoded, UINT32_MAX if the encoding failed. 174 //------------------------------------------------------------------ 175 uint32_t PutU8(uint32_t offset, uint8_t value); 176 177 uint32_t PutU16(uint32_t offset, uint16_t value); 178 179 uint32_t PutU32(uint32_t offset, uint32_t value); 180 181 uint32_t PutU64(uint32_t offset, uint64_t value); 182 183 //------------------------------------------------------------------ 184 /// Encode an unsigned integer of size \a byte_size to \a offset. 185 /// 186 /// Encode a single integer value at \a offset and return the offset that 187 /// follows the newly encoded integer when the data is successfully encoded 188 /// into the existing data. There must be enough room in the data, else 189 /// UINT32_MAX will be returned to indicate that encoding failed. 190 /// 191 /// \param[in] offset 192 /// The offset within the contained data at which to put the 193 /// encoded integer. 194 /// 195 /// \param[in] byte_size 196 /// The size in byte of the integer to encode. 197 /// 198 /// \param[in] value 199 /// The integer value to write. The least significant bytes of 200 /// the integer value will be written if the size is less than 201 /// 8 bytes. 202 /// 203 /// \return 204 /// The next offset in the bytes of this data if the integer 205 /// was successfully encoded, UINT32_MAX if the encoding failed. 206 //------------------------------------------------------------------ 207 uint32_t PutMaxU64(uint32_t offset, uint32_t byte_size, uint64_t value); 208 209 //------------------------------------------------------------------ 210 /// Encode an arbitrary number of bytes. 211 /// 212 /// \param[in] offset 213 /// The offset in bytes into the contained data at which to 214 /// start encoding. 215 /// 216 /// \param[in] src 217 /// The buffer that contains the bytes to encode. 218 /// 219 /// \param[in] src_len 220 /// The number of bytes to encode. 221 /// 222 /// \return 223 /// The next valid offset within data if the put operation 224 /// was successful, else UINT32_MAX to indicate the put failed. 225 //------------------------------------------------------------------ 226 uint32_t PutData(uint32_t offset, const void *src, uint32_t src_len); 227 228 //------------------------------------------------------------------ 229 /// Encode an address in the existing buffer at \a offset bytes into the 230 /// buffer. 231 /// 232 /// Encode a single address (honoring the m_addr_size member) to the data 233 /// and return the next offset where subsequent data would go. pointed to by 234 /// \a offset_ptr. The size of the extracted address comes from the \a 235 /// m_addr_size member variable and should be set correctly prior to 236 /// extracting any address values. 237 /// 238 /// \param[in,out] offset_ptr 239 /// A pointer to an offset within the data that will be advanced 240 /// by the appropriate number of bytes if the value is extracted 241 /// correctly. If the offset is out of bounds or there are not 242 /// enough bytes to extract this value, the offset will be left 243 /// unmodified. 244 /// 245 /// \return 246 /// The next valid offset within data if the put operation 247 /// was successful, else UINT32_MAX to indicate the put failed. 248 //------------------------------------------------------------------ 249 uint32_t PutAddress(uint32_t offset, lldb::addr_t addr); 250 251 //------------------------------------------------------------------ 252 /// Put a C string to \a offset. 253 /// 254 /// Encodes a C string into the existing data including the terminating 255 /// 256 /// \param[in,out] offset_ptr 257 /// A pointer to an offset within the data that will be advanced 258 /// by the appropriate number of bytes if the value is extracted 259 /// correctly. If the offset is out of bounds or there are not 260 /// enough bytes to extract this value, the offset will be left 261 /// unmodified. 262 /// 263 /// \return 264 /// A pointer to the C string value in the data. If the offset 265 /// pointed to by \a offset_ptr is out of bounds, or if the 266 /// offset plus the length of the C string is out of bounds, 267 /// NULL will be returned. 268 //------------------------------------------------------------------ 269 uint32_t PutCString(uint32_t offset_ptr, const char *cstr); 270 271 lldb::DataBufferSP &GetSharedDataBuffer() { return m_data_sp; } 272 273 //------------------------------------------------------------------ 274 /// Set the address byte size. 275 /// 276 /// Set the size in bytes that will be used when extracting any address and 277 /// pointer values from data contained in this object. 278 /// 279 /// \param[in] addr_size 280 /// The size in bytes to use when extracting addresses. 281 //------------------------------------------------------------------ 282 void SetAddressByteSize(uint8_t addr_size) { m_addr_size = addr_size; } 283 284 //------------------------------------------------------------------ 285 /// Set data with a buffer that is caller owned. 286 /// 287 /// Use data that is owned by the caller when extracting values. The data 288 /// must stay around as long as this object, or any object that copies a 289 /// subset of this object's data, is valid. If \a bytes is NULL, or \a 290 /// length is zero, this object will contain no data. 291 /// 292 /// \param[in] bytes 293 /// A pointer to caller owned data. 294 /// 295 /// \param[in] length 296 /// The length in bytes of \a bytes. 297 /// 298 /// \param[in] byte_order 299 /// A byte order of the data that we are extracting from. 300 /// 301 /// \return 302 /// The number of bytes that this object now contains. 303 //------------------------------------------------------------------ 304 uint32_t SetData(void *bytes, uint32_t length, lldb::ByteOrder byte_order); 305 306 //------------------------------------------------------------------ 307 /// Adopt a subset of shared data in \a data_sp. 308 /// 309 /// Copies the data shared pointer which adds a reference to the contained 310 /// in \a data_sp. The shared data reference is reference counted to ensure 311 /// the data lives as long as anyone still has a valid shared pointer to the 312 /// data in \a data_sp. The byte order and address byte size settings remain 313 /// the same. If \a offset is not a valid offset in \a data_sp, then no 314 /// reference to the shared data will be added. If there are not \a length 315 /// bytes available in \a data starting at \a offset, the length will be 316 /// truncated to contains as many bytes as possible. 317 /// 318 /// \param[in] data_sp 319 /// A shared pointer to data. 320 /// 321 /// \param[in] offset 322 /// The offset into \a data_sp at which the subset starts. 323 /// 324 /// \param[in] length 325 /// The length in bytes of the subset of \a data_sp. 326 /// 327 /// \return 328 /// The number of bytes that this object now contains. 329 //------------------------------------------------------------------ 330 uint32_t SetData(const lldb::DataBufferSP &data_sp, uint32_t offset = 0, 331 uint32_t length = UINT32_MAX); 332 333 //------------------------------------------------------------------ 334 /// Set the byte_order value. 335 /// 336 /// Sets the byte order of the data to extract. Extracted values will be 337 /// swapped if necessary when decoding. 338 /// 339 /// \param[in] byte_order 340 /// The byte order value to use when extracting data. 341 //------------------------------------------------------------------ 342 void SetByteOrder(lldb::ByteOrder byte_order) { m_byte_order = byte_order; } 343 344 //------------------------------------------------------------------ 345 /// Test the validity of \a offset. 346 /// 347 /// \return 348 /// \b true if \a offset is a valid offset into the data in this 349 /// object, \b false otherwise. 350 //------------------------------------------------------------------ 351 bool ValidOffset(uint32_t offset) const { return offset < GetByteSize(); } 352 353 //------------------------------------------------------------------ 354 /// Test the availability of \a length bytes of data from \a offset. 355 /// 356 /// \return 357 /// \b true if \a offset is a valid offset and there are \a 358 /// length bytes available at that offset, \b false otherwise. 359 //------------------------------------------------------------------ 360 bool ValidOffsetForDataOfSize(uint32_t offset, uint32_t length) const { 361 return length <= BytesLeft(offset); 362 } 363 364 uint32_t BytesLeft(uint32_t offset) const { 365 const uint32_t size = GetByteSize(); 366 if (size > offset) 367 return size - offset; 368 return 0; 369 } 370 371 protected: 372 //------------------------------------------------------------------ 373 // Member variables 374 //------------------------------------------------------------------ 375 uint8_t *m_start; ///< A pointer to the first byte of data. 376 uint8_t *m_end; ///< A pointer to the byte that is past the end of the data. 377 lldb::ByteOrder 378 m_byte_order; ///< The byte order of the data we are extracting from. 379 uint8_t m_addr_size; ///< The address size to use when extracting pointers or 380 /// addresses 381 mutable lldb::DataBufferSP m_data_sp; ///< The shared pointer to data that can 382 /// be shared among multiple instances 383 384 private: 385 DISALLOW_COPY_AND_ASSIGN(DataEncoder); 386 }; 387 388 } // namespace lldb_private 389 390 #endif // #if defined (__cplusplus) 391 #endif // #ifndef liblldb_DataEncoder_h_ 392