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" An binary data
  27 /// encoding class.
  28 ///
  29 /// DataEncoder is a class that can encode binary data (swapping if needed) to
  30 /// a data buffer. The data buffer can be caller owned, or can be shared data
  31 /// that can be shared between multiple DataEncoder or DataEncoder instances.
  32 ///
  33 /// @see DataBuffer
  34 //----------------------------------------------------------------------
  35 class DataEncoder {
  36 public:
  37   //------------------------------------------------------------------
  38   /// Default constructor.
  39   ///
  40   /// Initialize all members to a default empty state.
  41   //------------------------------------------------------------------
  42   DataEncoder();
  43
  44   //------------------------------------------------------------------
  45   /// Construct with a buffer that is owned by the caller.
  46   ///
  47   /// This constructor allows us to use data that is owned by the caller. The
  48   /// data must stay around as long as this object is valid.
  49   ///
  50   /// @param[in] data
  51   ///     A pointer to caller owned data.
  52   ///
  53   /// @param[in] data_length
  54   ///     The length in bytes of \a data.
  55   ///
  56   /// @param[in] byte_order
  57   ///     A byte order of the data that we are extracting from.
  58   ///
  59   /// @param[in] addr_size
  60   ///     A new address byte size value.
  61   //------------------------------------------------------------------
  62   DataEncoder(void *data, uint32_t data_length, lldb::ByteOrder byte_order,
  63               uint8_t addr_size);
  64
  65   //------------------------------------------------------------------
  66   /// Construct with shared data.
  67   ///
  68   /// Copies the data shared pointer which adds a reference to the contained
  69   /// in \a data_sp. The shared data reference is reference counted to ensure
  70   /// the data lives as long as anyone still has a valid shared pointer to the
  71   /// data in \a data_sp.
  72   ///
  73   /// @param[in] data_sp
  74   ///     A shared pointer to data.
  75   ///
  76   /// @param[in] byte_order
  77   ///     A byte order of the data that we are extracting from.
  78   ///
  79   /// @param[in] addr_size
  80   ///     A new address byte size value.
  81   //------------------------------------------------------------------
  82   DataEncoder(const lldb::DataBufferSP &data_sp, lldb::ByteOrder byte_order,
  83               uint8_t addr_size);
  84
  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
 372 protected:
 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
 385 private:
 386   DISALLOW_COPY_AND_ASSIGN(DataEncoder);
 387 };
 388
 389 } // namespace lldb_private
 390
 391 #endif // #if defined (__cplusplus)
 392 #endif // #ifndef liblldb_DataEncoder_h_