contrib/llvm/tools/lldb/include/lldb/Utility/DataEncoder.h

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