DataEncoder.h revision 341825
1820Sprappo//===-- DataEncoder.h -------------------------------------------*- C++ -*-===// 2820Sprappo// 3820Sprappo// The LLVM Compiler Infrastructure 4820Sprappo// 5820Sprappo// This file is distributed under the University of Illinois Open Source 6820Sprappo// License. See LICENSE.TXT for details. 7820Sprappo// 8820Sprappo//===----------------------------------------------------------------------===// 9820Sprappo 10820Sprappo#ifndef liblldb_DataEncoder_h_ 11820Sprappo#define liblldb_DataEncoder_h_ 12820Sprappo 13820Sprappo#if defined(__cplusplus) 14820Sprappo 15820Sprappo#include "lldb/lldb-defines.h" // for DISALLOW_COPY_AND_ASSIGN 16820Sprappo#include "lldb/lldb-enumerations.h" // for ByteOrder 17820Sprappo#include "lldb/lldb-forward.h" // for DataBufferSP 18820Sprappo#include "lldb/lldb-types.h" // for addr_t 19820Sprappo 20820Sprappo#include <stddef.h> // for size_t 21820Sprappo#include <stdint.h> 22820Sprappo 23820Sprapponamespace lldb_private { 24820Sprappo 25820Sprappo//---------------------------------------------------------------------- 26820Sprappo/// @class DataEncoder DataEncoder.h "lldb/Core/DataEncoder.h" An binary data 27820Sprappo/// encoding class. 28820Sprappo/// 29820Sprappo/// DataEncoder is a class that can encode binary data (swapping if needed) to 30820Sprappo/// a data buffer. The data buffer can be caller owned, or can be shared data 31820Sprappo/// that can be shared between multiple DataEncoder or DataEncoder instances. 32820Sprappo/// 33820Sprappo/// @see DataBuffer 34820Sprappo//---------------------------------------------------------------------- 35820Sprappoclass DataEncoder { 36820Sprappopublic: 37820Sprappo //------------------------------------------------------------------ 38820Sprappo /// Default constructor. 39820Sprappo /// 40820Sprappo /// Initialize all members to a default empty state. 41820Sprappo //------------------------------------------------------------------ 42820Sprappo DataEncoder(); 43820Sprappo 44820Sprappo //------------------------------------------------------------------ 45820Sprappo /// Construct with a buffer that is owned by the caller. 46820Sprappo /// 47820Sprappo /// This constructor allows us to use data that is owned by the caller. The 48820Sprappo /// data must stay around as long as this object is valid. 49820Sprappo /// 50820Sprappo /// @param[in] data 51820Sprappo /// A pointer to caller owned data. 52820Sprappo /// 53820Sprappo /// @param[in] data_length 54820Sprappo /// The length in bytes of \a data. 55820Sprappo /// 56820Sprappo /// @param[in] byte_order 57820Sprappo /// A byte order of the data that we are extracting from. 58820Sprappo /// 59820Sprappo /// @param[in] addr_size 60820Sprappo /// A new address byte size value. 61820Sprappo //------------------------------------------------------------------ 62820Sprappo DataEncoder(void *data, uint32_t data_length, lldb::ByteOrder byte_order, 63820Sprappo uint8_t addr_size); 64820Sprappo 65820Sprappo //------------------------------------------------------------------ 66820Sprappo /// Construct with shared data. 67820Sprappo /// 68820Sprappo /// Copies the data shared pointer which adds a reference to the contained 69820Sprappo /// in \a data_sp. The shared data reference is reference counted to ensure 70820Sprappo /// the data lives as long as anyone still has a valid shared pointer to the 71820Sprappo /// data in \a data_sp. 72820Sprappo /// 73820Sprappo /// @param[in] data_sp 74820Sprappo /// A shared pointer to data. 75820Sprappo /// 76820Sprappo /// @param[in] byte_order 77820Sprappo /// A byte order of the data that we are extracting from. 78820Sprappo /// 79820Sprappo /// @param[in] addr_size 80820Sprappo /// A new address byte size value. 81820Sprappo //------------------------------------------------------------------ 82820Sprappo DataEncoder(const lldb::DataBufferSP &data_sp, lldb::ByteOrder byte_order, 83820Sprappo uint8_t addr_size); 84820Sprappo 85 //------------------------------------------------------------------ 86 /// Destructor 87 /// 88 /// If this object contains a valid shared data reference, the reference 89 /// count on the data will be decremented, and if zero, the data will be 90 /// freed. 91 //------------------------------------------------------------------ 92 ~DataEncoder(); 93 94 //------------------------------------------------------------------ 95 /// Clears the object state. 96 /// 97 /// Clears the object contents back to a default invalid state, and release 98 /// any references to shared data that this object may contain. 99 //------------------------------------------------------------------ 100 void Clear(); 101 102 //------------------------------------------------------------------ 103 /// Get the current address size. 104 /// 105 /// Return the size in bytes of any address values this object will extract. 106 /// 107 /// @return 108 /// The size in bytes of address values that will be extracted. 109 //------------------------------------------------------------------ 110 uint8_t GetAddressByteSize() const { return m_addr_size; } 111 112 //------------------------------------------------------------------ 113 /// Get the number of bytes contained in this object. 114 /// 115 /// @return 116 /// The total number of bytes of data this object refers to. 117 //------------------------------------------------------------------ 118 size_t GetByteSize() const { return m_end - m_start; } 119 120 //------------------------------------------------------------------ 121 /// Get the data end pointer. 122 /// 123 /// @return 124 /// Returns a pointer to the next byte contained in this 125 /// object's data, or NULL of there is no data in this object. 126 //------------------------------------------------------------------ 127 uint8_t *GetDataEnd() { return m_end; } 128 129 const uint8_t *GetDataEnd() const { return m_end; } 130 131 //------------------------------------------------------------------ 132 /// Get the shared data offset. 133 /// 134 /// Get the offset of the first byte of data in the shared data (if any). 135 /// 136 /// @return 137 /// If this object contains shared data, this function returns 138 /// the offset in bytes into that shared data, zero otherwise. 139 //------------------------------------------------------------------ 140 size_t GetSharedDataOffset() const; 141 142 //------------------------------------------------------------------ 143 /// Get the current byte order value. 144 /// 145 /// @return 146 /// The current byte order value from this object's internal 147 /// state. 148 //------------------------------------------------------------------ 149 lldb::ByteOrder GetByteOrder() const { return m_byte_order; } 150 151 //------------------------------------------------------------------ 152 /// Get the data start pointer. 153 /// 154 /// @return 155 /// Returns a pointer to the first byte contained in this 156 /// object's data, or NULL of there is no data in this object. 157 //------------------------------------------------------------------ 158 uint8_t *GetDataStart() { return m_start; } 159 160 const uint8_t *GetDataStart() const { return m_start; } 161 162 //------------------------------------------------------------------ 163 /// Encode unsigned integer values into the data at \a offset. 164 /// 165 /// @param[in] offset 166 /// The offset within the contained data at which to put the 167 /// data. 168 /// 169 /// @param[in] value 170 /// The value to encode into the data. 171 /// 172 /// @return 173 /// The next offset in the bytes of this data if the data 174 /// was successfully encoded, UINT32_MAX if the encoding failed. 175 //------------------------------------------------------------------ 176 uint32_t PutU8(uint32_t offset, uint8_t value); 177 178 uint32_t PutU16(uint32_t offset, uint16_t value); 179 180 uint32_t PutU32(uint32_t offset, uint32_t value); 181 182 uint32_t PutU64(uint32_t offset, uint64_t value); 183 184 //------------------------------------------------------------------ 185 /// Encode an unsigned integer of size \a byte_size to \a offset. 186 /// 187 /// Encode a single integer value at \a offset and return the offset that 188 /// follows the newly encoded integer when the data is successfully encoded 189 /// into the existing data. There must be enough room in the data, else 190 /// UINT32_MAX will be returned to indicate that encoding failed. 191 /// 192 /// @param[in] offset 193 /// The offset within the contained data at which to put the 194 /// encoded integer. 195 /// 196 /// @param[in] byte_size 197 /// The size in byte of the integer to encode. 198 /// 199 /// @param[in] value 200 /// The integer value to write. The least significant bytes of 201 /// the integer value will be written if the size is less than 202 /// 8 bytes. 203 /// 204 /// @return 205 /// The next offset in the bytes of this data if the integer 206 /// was successfully encoded, UINT32_MAX if the encoding failed. 207 //------------------------------------------------------------------ 208 uint32_t PutMaxU64(uint32_t offset, uint32_t byte_size, uint64_t value); 209 210 //------------------------------------------------------------------ 211 /// Encode an arbitrary number of bytes. 212 /// 213 /// @param[in] offset 214 /// The offset in bytes into the contained data at which to 215 /// start encoding. 216 /// 217 /// @param[in] src 218 /// The buffer that contains the bytes to encode. 219 /// 220 /// @param[in] src_len 221 /// The number of bytes to encode. 222 /// 223 /// @return 224 /// The next valid offset within data if the put operation 225 /// was successful, else UINT32_MAX to indicate the put failed. 226 //------------------------------------------------------------------ 227 uint32_t PutData(uint32_t offset, const void *src, uint32_t src_len); 228 229 //------------------------------------------------------------------ 230 /// Encode an address in the existing buffer at \a offset bytes into the 231 /// buffer. 232 /// 233 /// Encode a single address (honoring the m_addr_size member) to the data 234 /// and return the next offset where subsequent data would go. pointed to by 235 /// \a offset_ptr. The size of the extracted address comes from the \a 236 /// m_addr_size member variable and should be set correctly prior to 237 /// extracting any address values. 238 /// 239 /// @param[in,out] offset_ptr 240 /// A pointer to an offset within the data that will be advanced 241 /// by the appropriate number of bytes if the value is extracted 242 /// correctly. If the offset is out of bounds or there are not 243 /// enough bytes to extract this value, the offset will be left 244 /// unmodified. 245 /// 246 /// @return 247 /// The next valid offset within data if the put operation 248 /// was successful, else UINT32_MAX to indicate the put failed. 249 //------------------------------------------------------------------ 250 uint32_t PutAddress(uint32_t offset, lldb::addr_t addr); 251 252 //------------------------------------------------------------------ 253 /// Put a C string to \a offset. 254 /// 255 /// Encodes a C string into the existing data including the terminating 256 /// 257 /// @param[in,out] offset_ptr 258 /// A pointer to an offset within the data that will be advanced 259 /// by the appropriate number of bytes if the value is extracted 260 /// correctly. If the offset is out of bounds or there are not 261 /// enough bytes to extract this value, the offset will be left 262 /// unmodified. 263 /// 264 /// @return 265 /// A pointer to the C string value in the data. If the offset 266 /// pointed to by \a offset_ptr is out of bounds, or if the 267 /// offset plus the length of the C string is out of bounds, 268 /// NULL will be returned. 269 //------------------------------------------------------------------ 270 uint32_t PutCString(uint32_t offset_ptr, const char *cstr); 271 272 lldb::DataBufferSP &GetSharedDataBuffer() { return m_data_sp; } 273 274 //------------------------------------------------------------------ 275 /// Set the address byte size. 276 /// 277 /// Set the size in bytes that will be used when extracting any address and 278 /// pointer values from data contained in this object. 279 /// 280 /// @param[in] addr_size 281 /// The size in bytes to use when extracting addresses. 282 //------------------------------------------------------------------ 283 void SetAddressByteSize(uint8_t addr_size) { m_addr_size = addr_size; } 284 285 //------------------------------------------------------------------ 286 /// Set data with a buffer that is caller owned. 287 /// 288 /// Use data that is owned by the caller when extracting values. The data 289 /// must stay around as long as this object, or any object that copies a 290 /// subset of this object's data, is valid. If \a bytes is NULL, or \a 291 /// length is zero, this object will contain no data. 292 /// 293 /// @param[in] bytes 294 /// A pointer to caller owned data. 295 /// 296 /// @param[in] length 297 /// The length in bytes of \a bytes. 298 /// 299 /// @param[in] byte_order 300 /// A byte order of the data that we are extracting from. 301 /// 302 /// @return 303 /// The number of bytes that this object now contains. 304 //------------------------------------------------------------------ 305 uint32_t SetData(void *bytes, uint32_t length, lldb::ByteOrder byte_order); 306 307 //------------------------------------------------------------------ 308 /// Adopt a subset of shared data in \a data_sp. 309 /// 310 /// Copies the data shared pointer which adds a reference to the contained 311 /// in \a data_sp. The shared data reference is reference counted to ensure 312 /// the data lives as long as anyone still has a valid shared pointer to the 313 /// data in \a data_sp. The byte order and address byte size settings remain 314 /// the same. If \a offset is not a valid offset in \a data_sp, then no 315 /// reference to the shared data will be added. If there are not \a length 316 /// bytes available in \a data starting at \a offset, the length will be 317 /// truncated to contains as many bytes as possible. 318 /// 319 /// @param[in] data_sp 320 /// A shared pointer to data. 321 /// 322 /// @param[in] offset 323 /// The offset into \a data_sp at which the subset starts. 324 /// 325 /// @param[in] length 326 /// The length in bytes of the subset of \a data_sp. 327 /// 328 /// @return 329 /// The number of bytes that this object now contains. 330 //------------------------------------------------------------------ 331 uint32_t SetData(const lldb::DataBufferSP &data_sp, uint32_t offset = 0, 332 uint32_t length = UINT32_MAX); 333 334 //------------------------------------------------------------------ 335 /// Set the byte_order value. 336 /// 337 /// Sets the byte order of the data to extract. Extracted values will be 338 /// swapped if necessary when decoding. 339 /// 340 /// @param[in] byte_order 341 /// The byte order value to use when extracting data. 342 //------------------------------------------------------------------ 343 void SetByteOrder(lldb::ByteOrder byte_order) { m_byte_order = byte_order; } 344 345 //------------------------------------------------------------------ 346 /// Test the validity of \a offset. 347 /// 348 /// @return 349 /// \b true if \a offset is a valid offset into the data in this 350 /// object, \b false otherwise. 351 //------------------------------------------------------------------ 352 bool ValidOffset(uint32_t offset) const { return offset < GetByteSize(); } 353 354 //------------------------------------------------------------------ 355 /// Test the availability of \a length bytes of data from \a offset. 356 /// 357 /// @return 358 /// \b true if \a offset is a valid offset and there are \a 359 /// length bytes available at that offset, \b false otherwise. 360 //------------------------------------------------------------------ 361 bool ValidOffsetForDataOfSize(uint32_t offset, uint32_t length) const { 362 return length <= BytesLeft(offset); 363 } 364 365 uint32_t BytesLeft(uint32_t offset) const { 366 const uint32_t size = GetByteSize(); 367 if (size > offset) 368 return size - offset; 369 return 0; 370 } 371 372protected: 373 //------------------------------------------------------------------ 374 // Member variables 375 //------------------------------------------------------------------ 376 uint8_t *m_start; ///< A pointer to the first byte of data. 377 uint8_t *m_end; ///< A pointer to the byte that is past the end of the data. 378 lldb::ByteOrder 379 m_byte_order; ///< The byte order of the data we are extracting from. 380 uint8_t m_addr_size; ///< The address size to use when extracting pointers or 381 /// addresses 382 mutable lldb::DataBufferSP m_data_sp; ///< The shared pointer to data that can 383 /// be shared among multiple instances 384 385private: 386 DISALLOW_COPY_AND_ASSIGN(DataEncoder); 387}; 388 389} // namespace lldb_private 390 391#endif // #if defined (__cplusplus) 392#endif // #ifndef liblldb_DataEncoder_h_ 393