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

   1 //===-- DataExtractor.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 LLDB_UTILITY_DATAEXTRACTOR_H
  11 #define LLDB_UTILITY_DATAEXTRACTOR_H
  12
  13 #include "lldb/lldb-defines.h"
  14 #include "lldb/lldb-enumerations.h" // for ByteOrder
  15 #include "lldb/lldb-forward.h"      // for DataBufferSP
  16 #include "lldb/lldb-types.h"
  17
  18 #include <cassert>
  19 #include <stdint.h>
  20 #include <string.h>
  21
  22 namespace lldb_private {
  23 class Log;
  24 }
  25 namespace lldb_private {
  26 class Stream;
  27 }
  28 namespace llvm {
  29 template <typename T> class SmallVectorImpl;
  30 }
  31
  32 // C++ Includes
  33
  34 namespace lldb_private {
  35
  36 //----------------------------------------------------------------------
  37 /// @class DataExtractor DataExtractor.h "lldb/Core/DataExtractor.h"
  38 /// @brief An data extractor class.
  39 ///
  40 /// DataExtractor is a class that can extract data (swapping if needed)
  41 /// from a data buffer. The data buffer can be caller owned, or can be
  42 /// shared data that can be shared between multiple DataExtractor
  43 /// instances. Multiple DataExtractor objects can share the same data,
  44 /// yet extract values in different address sizes and byte order modes.
  45 /// Each object can have a unique position in the shared data and extract
  46 /// data from different offsets.
  47 ///
  48 /// @see DataBuffer
  49 //----------------------------------------------------------------------
  50 class DataExtractor {
  51 public:
  52   //------------------------------------------------------------------
  53   /// @typedef DataExtractor::Type
  54   /// @brief Type enumerations used in the dump routines.
  55   //------------------------------------------------------------------
  56   typedef enum {
  57     TypeUInt8,   ///< Format output as unsigned 8 bit integers
  58     TypeChar,    ///< Format output as characters
  59     TypeUInt16,  ///< Format output as unsigned 16 bit integers
  60     TypeUInt32,  ///< Format output as unsigned 32 bit integers
  61     TypeUInt64,  ///< Format output as unsigned 64 bit integers
  62     TypePointer, ///< Format output as pointers
  63     TypeULEB128, ///< Format output as ULEB128 numbers
  64     TypeSLEB128  ///< Format output as SLEB128 numbers
  65   } Type;
  66
  67   //------------------------------------------------------------------
  68   /// Default constructor.
  69   ///
  70   /// Initialize all members to a default empty state.
  71   //------------------------------------------------------------------
  72   DataExtractor();
  73
  74   //------------------------------------------------------------------
  75   /// Construct with a buffer that is owned by the caller.
  76   ///
  77   /// This constructor allows us to use data that is owned by the
  78   /// caller. The data must stay around as long as this object is
  79   /// valid.
  80   ///
  81   /// @param[in] data
  82   ///     A pointer to caller owned data.
  83   ///
  84   /// @param[in] data_length
  85   ///     The length in bytes of \a data.
  86   ///
  87   /// @param[in] byte_order
  88   ///     A byte order of the data that we are extracting from.
  89   ///
  90   /// @param[in] addr_size
  91   ///     A new address byte size value.
  92   ///
  93   /// @param[in] target_byte_size
  94   ///     A size of a target byte in 8-bit host bytes
  95   //------------------------------------------------------------------
  96   DataExtractor(const void *data, lldb::offset_t data_length,
  97                 lldb::ByteOrder byte_order, uint32_t addr_size,
  98                 uint32_t target_byte_size = 1);
  99
 100   //------------------------------------------------------------------
 101   /// Construct with shared data.
 102   ///
 103   /// Copies the data shared pointer which adds a reference to the
 104   /// contained in \a data_sp. The shared data reference is reference
 105   /// counted to ensure the data lives as long as anyone still has a
 106   /// valid shared pointer to the data in \a data_sp.
 107   ///
 108   /// @param[in] data_sp
 109   ///     A shared pointer to data.
 110   ///
 111   /// @param[in] byte_order
 112   ///     A byte order of the data that we are extracting from.
 113   ///
 114   /// @param[in] addr_size
 115   ///     A new address byte size value.
 116   ///
 117   /// @param[in] target_byte_size
 118   ///     A size of a target byte in 8-bit host bytes
 119   //------------------------------------------------------------------
 120   DataExtractor(const lldb::DataBufferSP &data_sp, lldb::ByteOrder byte_order,
 121                 uint32_t addr_size, uint32_t target_byte_size = 1);
 122
 123   //------------------------------------------------------------------
 124   /// Construct with a subset of \a data.
 125   ///
 126   /// Initialize this object with a subset of the data bytes in \a
 127   /// data. If \a data contains shared data, then a reference to the
 128   /// shared data will be added to ensure the shared data stays around
 129   /// as long as any objects have references to the shared data. The
 130   /// byte order value and the address size settings are copied from \a
 131   /// data. If \a offset is not a valid offset in \a data, then no
 132   /// reference to the shared data will be added. If there are not
 133   /// \a length bytes available in \a data starting at \a offset,
 134   /// the length will be truncated to contain as many bytes as
 135   /// possible.
 136   ///
 137   /// @param[in] data
 138   ///     Another DataExtractor object that contains data.
 139   ///
 140   /// @param[in] offset
 141   ///     The offset into \a data at which the subset starts.
 142   ///
 143   /// @param[in] length
 144   ///     The length in bytes of the subset of data.
 145   ///
 146   /// @param[in] target_byte_size
 147   ///     A size of a target byte in 8-bit host bytes
 148   //------------------------------------------------------------------
 149   DataExtractor(const DataExtractor &data, lldb::offset_t offset,
 150                 lldb::offset_t length, uint32_t target_byte_size = 1);
 151
 152   DataExtractor(const DataExtractor &rhs);
 153
 154   //------------------------------------------------------------------
 155   /// Assignment operator.
 156   ///
 157   /// Copies all data, byte order and address size settings from \a rhs into
 158   /// this object. If \a rhs contains shared data, a reference to that
 159   /// shared data will be added.
 160   ///
 161   /// @param[in] rhs
 162   ///     Another DataExtractor object to copy.
 163   ///
 164   /// @return
 165   ///     A const reference to this object.
 166   //------------------------------------------------------------------
 167   const DataExtractor &operator=(const DataExtractor &rhs);
 168
 169   //------------------------------------------------------------------
 170   /// Destructor
 171   ///
 172   /// If this object contains a valid shared data reference, the
 173   /// reference count on the data will be decremented, and if zero,
 174   /// the data will be freed.
 175   //------------------------------------------------------------------
 176   virtual ~DataExtractor();
 177
 178   uint32_t getTargetByteSize() const { return m_target_byte_size; }
 179
 180   //------------------------------------------------------------------
 181   /// Clears the object state.
 182   ///
 183   /// Clears the object contents back to a default invalid state, and
 184   /// release any references to shared data that this object may
 185   /// contain.
 186   //------------------------------------------------------------------
 187   void Clear();
 188
 189   //------------------------------------------------------------------
 190   /// Dumps the binary data as \a type objects to stream \a s (or to
 191   /// Log() if \a s is nullptr) starting \a offset bytes into the data
 192   /// and stopping after dumping \a length bytes. The offset into the
 193   /// data is displayed at the beginning of each line and can be
 194   /// offset by base address \a base_addr. \a num_per_line objects
 195   /// will be displayed on each line.
 196   ///
 197   /// @param[in] s
 198   ///     The stream to dump the output to. If nullptr the output will
 199   ///     be dumped to Log().
 200   ///
 201   /// @param[in] offset
 202   ///     The offset into the data at which to start dumping.
 203   ///
 204   /// @param[in] length
 205   ///     The number of bytes to dump.
 206   ///
 207   /// @param[in] base_addr
 208   ///     The base address that gets added to the offset displayed on
 209   ///     each line.
 210   ///
 211   /// @param[in] num_per_line
 212   ///     The number of \a type objects to display on each line.
 213   ///
 214   /// @param[in] type
 215   ///     The type of objects to use when dumping data from this
 216   ///     object. See DataExtractor::Type.
 217   ///
 218   /// @param[in] type_format
 219   ///     The optional format to use for the \a type objects. If this
 220   ///     is nullptr, the default format for the \a type will be used.
 221   ///
 222   /// @return
 223   ///     The offset at which dumping ended.
 224   //------------------------------------------------------------------
 225   lldb::offset_t PutToLog(Log *log, lldb::offset_t offset,
 226                           lldb::offset_t length, uint64_t base_addr,
 227                           uint32_t num_per_line, Type type,
 228                           const char *type_format = nullptr) const;
 229
 230   //------------------------------------------------------------------
 231   /// Dump a UUID value at \a offset.
 232   ///
 233   /// Dump a UUID starting at \a offset bytes into this object's data.
 234   /// If the stream \a s is nullptr, the output will be sent to Log().
 235   ///
 236   /// @param[in] s
 237   ///     The stream to dump the output to. If nullptr the output will
 238   ///     be dumped to Log().
 239   ///
 240   /// @param[in] offset
 241   ///     The offset into the data at which to extract and dump a
 242   ///     UUID value.
 243   //------------------------------------------------------------------
 244   void DumpUUID(Stream *s, lldb::offset_t offset) const;
 245
 246   //------------------------------------------------------------------
 247   /// Extract an arbitrary number of bytes in the specified byte
 248   /// order.
 249   ///
 250   /// Attemps to extract \a length bytes starting at \a offset bytes
 251   /// into this data in the requested byte order (\a dst_byte_order)
 252   /// and place the results in \a dst. \a dst must be at least \a
 253   /// length bytes long.
 254   ///
 255   /// @param[in] offset
 256   ///     The offset in bytes into the contained data at which to
 257   ///     start extracting.
 258   ///
 259   /// @param[in] length
 260   ///     The number of bytes to extract.
 261   ///
 262   /// @param[in] dst_byte_order
 263   ///     A byte order of the data that we want when the value in
 264   ///     copied to \a dst.
 265   ///
 266   /// @param[out] dst
 267   ///     The buffer that will receive the extracted value if there
 268   ///     are enough bytes available in the current data.
 269   ///
 270   /// @return
 271   ///     The number of bytes that were extracted which will be \a
 272   ///     length when the value is successfully extracted, or zero
 273   ///     if there aren't enough bytes at the specified offset.
 274   //------------------------------------------------------------------
 275   size_t ExtractBytes(lldb::offset_t offset, lldb::offset_t length,
 276                       lldb::ByteOrder dst_byte_order, void *dst) const;
 277
 278   //------------------------------------------------------------------
 279   /// Extract an address from \a *offset_ptr.
 280   ///
 281   /// Extract a single address from the data and update the offset
 282   /// pointed to by \a offset_ptr. The size of the extracted address
 283   /// comes from the \a m_addr_size member variable and should be
 284   /// set correctly prior to extracting any address values.
 285   ///
 286   /// @param[in,out] offset_ptr
 287   ///     A pointer to an offset within the data that will be advanced
 288   ///     by the appropriate number of bytes if the value is extracted
 289   ///     correctly. If the offset is out of bounds or there are not
 290   ///     enough bytes to extract this value, the offset will be left
 291   ///     unmodified.
 292   ///
 293   /// @return
 294   ///     The extracted address value.
 295   //------------------------------------------------------------------
 296   uint64_t GetAddress(lldb::offset_t *offset_ptr) const;
 297
 298   uint64_t GetAddress_unchecked(lldb::offset_t *offset_ptr) const;
 299
 300   //------------------------------------------------------------------
 301   /// Get the current address size.
 302   ///
 303   /// Return the size in bytes of any address values this object will
 304   /// extract.
 305   ///
 306   /// @return
 307   ///     The size in bytes of address values that will be extracted.
 308   //------------------------------------------------------------------
 309   uint32_t GetAddressByteSize() const { return m_addr_size; }
 310
 311   //------------------------------------------------------------------
 312   /// Get the number of bytes contained in this object.
 313   ///
 314   /// @return
 315   ///     The total number of bytes of data this object refers to.
 316   //------------------------------------------------------------------
 317   uint64_t GetByteSize() const { return m_end - m_start; }
 318
 319   //------------------------------------------------------------------
 320   /// Extract a C string from \a *offset_ptr.
 321   ///
 322   /// Returns a pointer to a C String from the data at the offset
 323   /// pointed to by \a offset_ptr. A variable length NULL terminated C
 324   /// string will be extracted and the \a offset_ptr will be
 325   /// updated with the offset of the byte that follows the NULL
 326   /// terminator byte.
 327   ///
 328   /// @param[in,out] offset_ptr
 329   ///     A pointer to an offset within the data that will be advanced
 330   ///     by the appropriate number of bytes if the value is extracted
 331   ///     correctly. If the offset is out of bounds or there are not
 332   ///     enough bytes to extract this value, the offset will be left
 333   ///     unmodified.
 334   ///
 335   /// @return
 336   ///     A pointer to the C string value in the data. If the offset
 337   ///     pointed to by \a offset_ptr is out of bounds, or if the
 338   ///     offset plus the length of the C string is out of bounds,
 339   ///     nullptr will be returned.
 340   //------------------------------------------------------------------
 341   const char *GetCStr(lldb::offset_t *offset_ptr) const;
 342
 343   //------------------------------------------------------------------
 344   /// Extract a C string from \a *offset_ptr with field size \a len.
 345   ///
 346   /// Returns a pointer to a C String from the data at the offset
 347   /// pointed to by \a offset_ptr, with a field length of \a len.
 348   /// A NULL terminated C string will be extracted and the \a offset_ptr
 349   /// will be updated with the offset of the byte that follows the fixed
 350   /// length field.
 351   ///
 352   /// @param[in,out] offset_ptr
 353   ///     A pointer to an offset within the data that will be advanced
 354   ///     by the appropriate number of bytes if the value is extracted
 355   ///     correctly. If the offset is out of bounds or there are not
 356   ///     enough bytes to extract this value, the offset will be left
 357   ///     unmodified.
 358   ///
 359   /// @return
 360   ///     A pointer to the C string value in the data. If the offset
 361   ///     pointed to by \a offset_ptr is out of bounds, or if the
 362   ///     offset plus the length of the field is out of bounds, or if
 363   ///     the field does not contain a NULL terminator byte, nullptr will
 364   ///     be returned.
 365   const char *GetCStr(lldb::offset_t *offset_ptr, lldb::offset_t len) const;
 366
 367   //------------------------------------------------------------------
 368   /// Extract \a length bytes from \a *offset_ptr.
 369   ///
 370   /// Returns a pointer to a bytes in this object's data at the offset
 371   /// pointed to by \a offset_ptr. If \a length is zero or too large,
 372   /// then the offset pointed to by \a offset_ptr will not be updated
 373   /// and nullptr will be returned.
 374   ///
 375   /// @param[in,out] offset_ptr
 376   ///     A pointer to an offset within the data that will be advanced
 377   ///     by the appropriate number of bytes if the value is extracted
 378   ///     correctly. If the offset is out of bounds or there are not
 379   ///     enough bytes to extract this value, the offset will be left
 380   ///     unmodified.
 381   ///
 382   /// @param[in] length
 383   ///     The optional length of a string to extract. If the value is
 384   ///     zero, a NULL terminated C string will be extracted.
 385   ///
 386   /// @return
 387   ///     A pointer to the bytes in this object's data if the offset
 388   ///     and length are valid, or nullptr otherwise.
 389   //------------------------------------------------------------------
 390   const void *GetData(lldb::offset_t *offset_ptr, lldb::offset_t length) const {
 391     const uint8_t *ptr = PeekData(*offset_ptr, length);
 392     if (ptr)
 393       *offset_ptr += length;
 394     return ptr;
 395   }
 396
 397   //------------------------------------------------------------------
 398   /// Copy \a length bytes from \a *offset, without swapping bytes.
 399   ///
 400   /// @param[in] offset
 401   ///     The offset into this data from which to start copying
 402   ///
 403   /// @param[in] length
 404   ///     The length of the data to copy from this object
 405   ///
 406   /// @param[out] dst
 407   ///     The buffer to place the output data.
 408   ///
 409   /// @return
 410   ///     Returns the number of bytes that were copied, or zero if
 411   ///     anything goes wrong.
 412   //------------------------------------------------------------------
 413   lldb::offset_t CopyData(lldb::offset_t offset, lldb::offset_t length,
 414                           void *dst) const;
 415
 416   //------------------------------------------------------------------
 417   /// Copy \a dst_len bytes from \a *offset_ptr and ensure the copied
 418   /// data is treated as a value that can be swapped to match the
 419   /// specified byte order.
 420   ///
 421   /// For values that are larger than the supported integer sizes,
 422   /// this function can be used to extract data in a specified byte
 423   /// order. It can also be used to copy a smaller integer value from
 424   /// to a larger value. The extra bytes left over will be padded
 425   /// correctly according to the byte order of this object and the
 426   /// \a dst_byte_order. This can be very handy when say copying a
 427   /// partial data value into a register.
 428   ///
 429   /// @param[in] src_offset
 430   ///     The offset into this data from which to start copying an
 431   ///     endian entity
 432   ///
 433   /// @param[in] src_len
 434   ///     The length of the endian data to copy from this object
 435   ///     into the \a dst object
 436   ///
 437   /// @param[out] dst
 438   ///     The buffer where to place the endian data. The data might
 439   ///     need to be byte swapped (and appropriately padded with
 440   ///     zeroes if \a src_len != \a dst_len) if \a dst_byte_order
 441   ///     does not match the byte order in this object.
 442   ///
 443   /// @param[in] dst_len
 444   ///     The length number of bytes that the endian value will
 445   ///     occupy is \a dst.
 446   ///
 447   /// @param[in] byte_order
 448   ///     The byte order that the endian value should be in the \a dst
 449   ///     buffer.
 450   ///
 451   /// @return
 452   ///     Returns the number of bytes that were copied, or zero if
 453   ///     anything goes wrong.
 454   //------------------------------------------------------------------
 455   lldb::offset_t CopyByteOrderedData(lldb::offset_t src_offset,
 456                                      lldb::offset_t src_len, void *dst,
 457                                      lldb::offset_t dst_len,
 458                                      lldb::ByteOrder dst_byte_order) const;
 459
 460   //------------------------------------------------------------------
 461   /// Get the data end pointer.
 462   ///
 463   /// @return
 464   ///     Returns a pointer to the next byte contained in this
 465   ///     object's data, or nullptr of there is no data in this object.
 466   //------------------------------------------------------------------
 467   const uint8_t *GetDataEnd() const { return m_end; }
 468
 469   //------------------------------------------------------------------
 470   /// Get the shared data offset.
 471   ///
 472   /// Get the offset of the first byte of data in the shared data (if
 473   /// any).
 474   ///
 475   /// @return
 476   ///     If this object contains shared data, this function returns
 477   ///     the offset in bytes into that shared data, zero otherwise.
 478   //------------------------------------------------------------------
 479   size_t GetSharedDataOffset() const;
 480
 481   //------------------------------------------------------------------
 482   /// Get the data start pointer.
 483   ///
 484   /// @return
 485   ///     Returns a pointer to the first byte contained in this
 486   ///     object's data, or nullptr of there is no data in this object.
 487   //------------------------------------------------------------------
 488   const uint8_t *GetDataStart() const { return m_start; }
 489
 490   //------------------------------------------------------------------
 491   /// Extract a float from \a *offset_ptr.
 492   ///
 493   /// Extract a single float value.
 494   ///
 495   /// @param[in,out] offset_ptr
 496   ///     A pointer to an offset within the data that will be advanced
 497   ///     by the appropriate number of bytes if the value is extracted
 498   ///     correctly. If the offset is out of bounds or there are not
 499   ///     enough bytes to extract this value, the offset will be left
 500   ///     unmodified.
 501   ///
 502   /// @return
 503   ///     The floating value that was extracted, or zero on failure.
 504   //------------------------------------------------------------------
 505   float GetFloat(lldb::offset_t *offset_ptr) const;
 506
 507   double GetDouble(lldb::offset_t *offset_ptr) const;
 508
 509   long double GetLongDouble(lldb::offset_t *offset_ptr) const;
 510
 511   //------------------------------------------------------------------
 512   /// Extract an integer of size \a byte_size from \a *offset_ptr.
 513   ///
 514   /// Extract a single integer value and update the offset pointed to
 515   /// by \a offset_ptr. The size of the extracted integer is specified
 516   /// by the \a byte_size argument. \a byte_size must have a value
 517   /// >= 1 and <= 4 since the return value is only 32 bits wide.
 518   ///
 519   /// @param[in,out] offset_ptr
 520   ///     A pointer to an offset within the data that will be advanced
 521   ///     by the appropriate number of bytes if the value is extracted
 522   ///     correctly. If the offset is out of bounds or there are not
 523   ///     enough bytes to extract this value, the offset will be left
 524   ///     unmodified.
 525   ///
 526   /// @param[in] byte_size
 527   ///     The size in byte of the integer to extract.
 528   ///
 529   /// @return
 530   ///     The integer value that was extracted, or zero on failure.
 531   //------------------------------------------------------------------
 532   uint32_t GetMaxU32(lldb::offset_t *offset_ptr, size_t byte_size) const;
 533
 534   //------------------------------------------------------------------
 535   /// Extract an unsigned integer of size \a byte_size from \a
 536   /// *offset_ptr.
 537   ///
 538   /// Extract a single unsigned integer value and update the offset
 539   /// pointed to by \a offset_ptr. The size of the extracted integer
 540   /// is specified by the \a byte_size argument. \a byte_size must
 541   /// have a value greater than or equal to one and less than or equal
 542   /// to eight since the return value is 64 bits wide.
 543   ///
 544   /// @param[in,out] offset_ptr
 545   ///     A pointer to an offset within the data that will be advanced
 546   ///     by the appropriate number of bytes if the value is extracted
 547   ///     correctly. If the offset is out of bounds or there are not
 548   ///     enough bytes to extract this value, the offset will be left
 549   ///     unmodified.
 550   ///
 551   /// @param[in] byte_size
 552   ///     The size in byte of the integer to extract.
 553   ///
 554   /// @return
 555   ///     The unsigned integer value that was extracted, or zero on
 556   ///     failure.
 557   //------------------------------------------------------------------
 558   uint64_t GetMaxU64(lldb::offset_t *offset_ptr, size_t byte_size) const;
 559
 560   uint64_t GetMaxU64_unchecked(lldb::offset_t *offset_ptr,
 561                                size_t byte_size) const;
 562
 563   //------------------------------------------------------------------
 564   /// Extract an signed integer of size \a byte_size from \a *offset_ptr.
 565   ///
 566   /// Extract a single signed integer value (sign extending if required)
 567   /// and update the offset pointed to by \a offset_ptr. The size of
 568   /// the extracted integer is specified by the \a byte_size argument.
 569   /// \a byte_size must have a value greater than or equal to one and
 570   /// less than or equal to eight since the return value is 64 bits
 571   /// wide.
 572   ///
 573   /// @param[in,out] offset_ptr
 574   ///     A pointer to an offset within the data that will be advanced
 575   ///     by the appropriate number of bytes if the value is extracted
 576   ///     correctly. If the offset is out of bounds or there are not
 577   ///     enough bytes to extract this value, the offset will be left
 578   ///     unmodified.
 579   ///
 580   /// @param[in] byte_size
 581   ///     The size in byte of the integer to extract.
 582   ///
 583   /// @return
 584   ///     The sign extended signed integer value that was extracted,
 585   ///     or zero on failure.
 586   //------------------------------------------------------------------
 587   int64_t GetMaxS64(lldb::offset_t *offset_ptr, size_t byte_size) const;
 588
 589   //------------------------------------------------------------------
 590   /// Extract an unsigned integer of size \a byte_size from \a
 591   /// *offset_ptr, then extract the bitfield from this value if
 592   /// \a bitfield_bit_size is non-zero.
 593   ///
 594   /// Extract a single unsigned integer value and update the offset
 595   /// pointed to by \a offset_ptr. The size of the extracted integer
 596   /// is specified by the \a byte_size argument. \a byte_size must
 597   /// have a value greater than or equal to one and less than or equal
 598   /// to 8 since the return value is 64 bits wide.
 599   ///
 600   /// @param[in,out] offset_ptr
 601   ///     A pointer to an offset within the data that will be advanced
 602   ///     by the appropriate number of bytes if the value is extracted
 603   ///     correctly. If the offset is out of bounds or there are not
 604   ///     enough bytes to extract this value, the offset will be left
 605   ///     unmodified.
 606   ///
 607   /// @param[in] byte_size
 608   ///     The size in byte of the integer to extract.
 609   ///
 610   /// @param[in] bitfield_bit_size
 611   ///     The size in bits of the bitfield value to extract, or zero
 612   ///     to just extract the entire integer value.
 613   ///
 614   /// @param[in] bitfield_bit_offset
 615   ///     The bit offset of the bitfield value in the extracted
 616   ///     integer.  For little-endian data, this is the offset of
 617   ///     the LSB of the bitfield from the LSB of the integer.
 618   ///     For big-endian data, this is the offset of the MSB of the
 619   ///     bitfield from the MSB of the integer.
 620   ///
 621   /// @return
 622   ///     The unsigned bitfield integer value that was extracted, or
 623   ///     zero on failure.
 624   //------------------------------------------------------------------
 625   uint64_t GetMaxU64Bitfield(lldb::offset_t *offset_ptr, size_t size,
 626                              uint32_t bitfield_bit_size,
 627                              uint32_t bitfield_bit_offset) const;
 628
 629   //------------------------------------------------------------------
 630   /// Extract an signed integer of size \a byte_size from \a
 631   /// *offset_ptr, then extract and signe extend the bitfield from
 632   /// this value if \a bitfield_bit_size is non-zero.
 633   ///
 634   /// Extract a single signed integer value (sign extending if required)
 635   /// and update the offset pointed to by \a offset_ptr. The size of
 636   /// the extracted integer is specified by the \a byte_size argument.
 637   /// \a byte_size must have a value greater than or equal to one and
 638   /// less than or equal to eight since the return value is 64 bits
 639   /// wide.
 640   ///
 641   /// @param[in,out] offset_ptr
 642   ///     A pointer to an offset within the data that will be advanced
 643   ///     by the appropriate number of bytes if the value is extracted
 644   ///     correctly. If the offset is out of bounds or there are not
 645   ///     enough bytes to extract this value, the offset will be left
 646   ///     unmodified.
 647   ///
 648   /// @param[in] byte_size
 649   ///     The size in bytes of the integer to extract.
 650   ///
 651   /// @param[in] bitfield_bit_size
 652   ///     The size in bits of the bitfield value to extract, or zero
 653   ///     to just extract the entire integer value.
 654   ///
 655   /// @param[in] bitfield_bit_offset
 656   ///     The bit offset of the bitfield value in the extracted
 657   ///     integer.  For little-endian data, this is the offset of
 658   ///     the LSB of the bitfield from the LSB of the integer.
 659   ///     For big-endian data, this is the offset of the MSB of the
 660   ///     bitfield from the MSB of the integer.
 661   ///
 662   /// @return
 663   ///     The signed bitfield integer value that was extracted, or
 664   ///     zero on failure.
 665   //------------------------------------------------------------------
 666   int64_t GetMaxS64Bitfield(lldb::offset_t *offset_ptr, size_t size,
 667                             uint32_t bitfield_bit_size,
 668                             uint32_t bitfield_bit_offset) const;
 669
 670   //------------------------------------------------------------------
 671   /// Extract an pointer from \a *offset_ptr.
 672   ///
 673   /// Extract a single pointer from the data and update the offset
 674   /// pointed to by \a offset_ptr. The size of the extracted pointer
 675   /// comes from the \a m_addr_size member variable and should be
 676   /// set correctly prior to extracting any pointer values.
 677   ///
 678   /// @param[in,out] offset_ptr
 679   ///     A pointer to an offset within the data that will be advanced
 680   ///     by the appropriate number of bytes if the value is extracted
 681   ///     correctly. If the offset is out of bounds or there are not
 682   ///     enough bytes to extract this value, the offset will be left
 683   ///     unmodified.
 684   ///
 685   /// @return
 686   ///     The extracted pointer value as a 64 integer.
 687   //------------------------------------------------------------------
 688   uint64_t GetPointer(lldb::offset_t *offset_ptr) const;
 689
 690   //------------------------------------------------------------------
 691   /// Get the current byte order value.
 692   ///
 693   /// @return
 694   ///     The current byte order value from this object's internal
 695   ///     state.
 696   //------------------------------------------------------------------
 697   lldb::ByteOrder GetByteOrder() const { return m_byte_order; }
 698
 699   //------------------------------------------------------------------
 700   /// Extract a uint8_t value from \a *offset_ptr.
 701   ///
 702   /// Extract a single uint8_t from the binary data at the offset
 703   /// pointed to by \a offset_ptr, and advance the offset on success.
 704   ///
 705   /// @param[in,out] offset_ptr
 706   ///     A pointer to an offset within the data that will be advanced
 707   ///     by the appropriate number of bytes if the value is extracted
 708   ///     correctly. If the offset is out of bounds or there are not
 709   ///     enough bytes to extract this value, the offset will be left
 710   ///     unmodified.
 711   ///
 712   /// @return
 713   ///     The extracted uint8_t value.
 714   //------------------------------------------------------------------
 715   uint8_t GetU8(lldb::offset_t *offset_ptr) const;
 716
 717   uint8_t GetU8_unchecked(lldb::offset_t *offset_ptr) const {
 718     uint8_t val = m_start[*offset_ptr];
 719     *offset_ptr += 1;
 720     return val;
 721   }
 722
 723   uint16_t GetU16_unchecked(lldb::offset_t *offset_ptr) const;
 724
 725   uint32_t GetU32_unchecked(lldb::offset_t *offset_ptr) const;
 726
 727   uint64_t GetU64_unchecked(lldb::offset_t *offset_ptr) const;
 728   //------------------------------------------------------------------
 729   /// Extract \a count uint8_t values from \a *offset_ptr.
 730   ///
 731   /// Extract \a count uint8_t values from the binary data at the
 732   /// offset pointed to by \a offset_ptr, and advance the offset on
 733   /// success. The extracted values are copied into \a dst.
 734   ///
 735   /// @param[in,out] offset_ptr
 736   ///     A pointer to an offset within the data that will be advanced
 737   ///     by the appropriate number of bytes if the value is extracted
 738   ///     correctly. If the offset is out of bounds or there are not
 739   ///     enough bytes to extract this value, the offset will be left
 740   ///     unmodified.
 741   ///
 742   /// @param[out] dst
 743   ///     A buffer to copy \a count uint8_t values into. \a dst must
 744   ///     be large enough to hold all requested data.
 745   ///
 746   /// @param[in] count
 747   ///     The number of uint8_t values to extract.
 748   ///
 749   /// @return
 750   ///     \a dst if all values were properly extracted and copied,
 751   ///     nullptr otherwise.
 752   //------------------------------------------------------------------
 753   void *GetU8(lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
 754
 755   //------------------------------------------------------------------
 756   /// Extract a uint16_t value from \a *offset_ptr.
 757   ///
 758   /// Extract a single uint16_t from the binary data at the offset
 759   /// pointed to by \a offset_ptr, and update the offset on success.
 760   ///
 761   /// @param[in,out] offset_ptr
 762   ///     A pointer to an offset within the data that will be advanced
 763   ///     by the appropriate number of bytes if the value is extracted
 764   ///     correctly. If the offset is out of bounds or there are not
 765   ///     enough bytes to extract this value, the offset will be left
 766   ///     unmodified.
 767   ///
 768   /// @return
 769   ///     The extracted uint16_t value.
 770   //------------------------------------------------------------------
 771   uint16_t GetU16(lldb::offset_t *offset_ptr) const;
 772
 773   //------------------------------------------------------------------
 774   /// Extract \a count uint16_t values from \a *offset_ptr.
 775   ///
 776   /// Extract \a count uint16_t values from the binary data at the
 777   /// offset pointed to by \a offset_ptr, and advance the offset on
 778   /// success. The extracted values are copied into \a dst.
 779   ///
 780   /// @param[in,out] offset_ptr
 781   ///     A pointer to an offset within the data that will be advanced
 782   ///     by the appropriate number of bytes if the value is extracted
 783   ///     correctly. If the offset is out of bounds or there are not
 784   ///     enough bytes to extract this value, the offset will be left
 785   ///     unmodified.
 786   ///
 787   /// @param[out] dst
 788   ///     A buffer to copy \a count uint16_t values into. \a dst must
 789   ///     be large enough to hold all requested data.
 790   ///
 791   /// @param[in] count
 792   ///     The number of uint16_t values to extract.
 793   ///
 794   /// @return
 795   ///     \a dst if all values were properly extracted and copied,
 796   ///     nullptr otherwise.
 797   //------------------------------------------------------------------
 798   void *GetU16(lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
 799
 800   //------------------------------------------------------------------
 801   /// Extract a uint32_t value from \a *offset_ptr.
 802   ///
 803   /// Extract a single uint32_t from the binary data at the offset
 804   /// pointed to by \a offset_ptr, and update the offset on success.
 805   ///
 806   /// @param[in,out] offset_ptr
 807   ///     A pointer to an offset within the data that will be advanced
 808   ///     by the appropriate number of bytes if the value is extracted
 809   ///     correctly. If the offset is out of bounds or there are not
 810   ///     enough bytes to extract this value, the offset will be left
 811   ///     unmodified.
 812   ///
 813   /// @return
 814   ///     The extracted uint32_t value.
 815   //------------------------------------------------------------------
 816   uint32_t GetU32(lldb::offset_t *offset_ptr) const;
 817
 818   //------------------------------------------------------------------
 819   /// Extract \a count uint32_t values from \a *offset_ptr.
 820   ///
 821   /// Extract \a count uint32_t values from the binary data at the
 822   /// offset pointed to by \a offset_ptr, and advance the offset on
 823   /// success. The extracted values are copied into \a dst.
 824   ///
 825   /// @param[in,out] offset_ptr
 826   ///     A pointer to an offset within the data that will be advanced
 827   ///     by the appropriate number of bytes if the value is extracted
 828   ///     correctly. If the offset is out of bounds or there are not
 829   ///     enough bytes to extract this value, the offset will be left
 830   ///     unmodified.
 831   ///
 832   /// @param[out] dst
 833   ///     A buffer to copy \a count uint32_t values into. \a dst must
 834   ///     be large enough to hold all requested data.
 835   ///
 836   /// @param[in] count
 837   ///     The number of uint32_t values to extract.
 838   ///
 839   /// @return
 840   ///     \a dst if all values were properly extracted and copied,
 841   ///     nullptr otherwise.
 842   //------------------------------------------------------------------
 843   void *GetU32(lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
 844
 845   //------------------------------------------------------------------
 846   /// Extract a uint64_t value from \a *offset_ptr.
 847   ///
 848   /// Extract a single uint64_t from the binary data at the offset
 849   /// pointed to by \a offset_ptr, and update the offset on success.
 850   ///
 851   /// @param[in,out] offset_ptr
 852   ///     A pointer to an offset within the data that will be advanced
 853   ///     by the appropriate number of bytes if the value is extracted
 854   ///     correctly. If the offset is out of bounds or there are not
 855   ///     enough bytes to extract this value, the offset will be left
 856   ///     unmodified.
 857   ///
 858   /// @return
 859   ///     The extracted uint64_t value.
 860   //------------------------------------------------------------------
 861   uint64_t GetU64(lldb::offset_t *offset_ptr) const;
 862
 863   //------------------------------------------------------------------
 864   /// Extract \a count uint64_t values from \a *offset_ptr.
 865   ///
 866   /// Extract \a count uint64_t values from the binary data at the
 867   /// offset pointed to by \a offset_ptr, and advance the offset on
 868   /// success. The extracted values are copied into \a dst.
 869   ///
 870   /// @param[in,out] offset_ptr
 871   ///     A pointer to an offset within the data that will be advanced
 872   ///     by the appropriate number of bytes if the value is extracted
 873   ///     correctly. If the offset is out of bounds or there are not
 874   ///     enough bytes to extract this value, the offset will be left
 875   ///     unmodified.
 876   ///
 877   /// @param[out] dst
 878   ///     A buffer to copy \a count uint64_t values into. \a dst must
 879   ///     be large enough to hold all requested data.
 880   ///
 881   /// @param[in] count
 882   ///     The number of uint64_t values to extract.
 883   ///
 884   /// @return
 885   ///     \a dst if all values were properly extracted and copied,
 886   ///     nullptr otherwise.
 887   //------------------------------------------------------------------
 888   void *GetU64(lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
 889
 890   //------------------------------------------------------------------
 891   /// Extract a signed LEB128 value from \a *offset_ptr.
 892   ///
 893   /// Extracts an signed LEB128 number from this object's data
 894   /// starting at the offset pointed to by \a offset_ptr. The offset
 895   /// pointed to by \a offset_ptr will be updated with the offset of
 896   /// the byte following the last extracted byte.
 897   ///
 898   /// @param[in,out] offset_ptr
 899   ///     A pointer to an offset within the data that will be advanced
 900   ///     by the appropriate number of bytes if the value is extracted
 901   ///     correctly. If the offset is out of bounds or there are not
 902   ///     enough bytes to extract this value, the offset will be left
 903   ///     unmodified.
 904   ///
 905   /// @return
 906   ///     The extracted signed integer value.
 907   //------------------------------------------------------------------
 908   int64_t GetSLEB128(lldb::offset_t *offset_ptr) const;
 909
 910   //------------------------------------------------------------------
 911   /// Extract a unsigned LEB128 value from \a *offset_ptr.
 912   ///
 913   /// Extracts an unsigned LEB128 number from this object's data
 914   /// starting at the offset pointed to by \a offset_ptr. The offset
 915   /// pointed to by \a offset_ptr will be updated with the offset of
 916   /// the byte following the last extracted byte.
 917   ///
 918   /// @param[in,out] offset_ptr
 919   ///     A pointer to an offset within the data that will be advanced
 920   ///     by the appropriate number of bytes if the value is extracted
 921   ///     correctly. If the offset is out of bounds or there are not
 922   ///     enough bytes to extract this value, the offset will be left
 923   ///     unmodified.
 924   ///
 925   /// @return
 926   ///     The extracted unsigned integer value.
 927   //------------------------------------------------------------------
 928   uint64_t GetULEB128(lldb::offset_t *offset_ptr) const;
 929
 930   lldb::DataBufferSP &GetSharedDataBuffer() { return m_data_sp; }
 931
 932   //------------------------------------------------------------------
 933   /// Peek at a C string at \a offset.
 934   ///
 935   /// Peeks at a string in the contained data. No verification is done
 936   /// to make sure the entire string lies within the bounds of this
 937   /// object's data, only \a offset is verified to be a valid offset.
 938   ///
 939   /// @param[in] offset
 940   ///     An offset into the data.
 941   ///
 942   /// @return
 943   ///     A non-nullptr C string pointer if \a offset is a valid offset,
 944   ///     nullptr otherwise.
 945   //------------------------------------------------------------------
 946   const char *PeekCStr(lldb::offset_t offset) const;
 947
 948   //------------------------------------------------------------------
 949   /// Peek at a bytes at \a offset.
 950   ///
 951   /// Returns a pointer to \a length bytes at \a offset as long as
 952   /// there are \a length bytes available starting at \a offset.
 953   ///
 954   /// @return
 955   ///     A non-nullptr data pointer if \a offset is a valid offset and
 956   ///     there are \a length bytes available at that offset, nullptr
 957   ///     otherwise.
 958   //------------------------------------------------------------------
 959   const uint8_t *PeekData(lldb::offset_t offset, lldb::offset_t length) const {
 960     if (ValidOffsetForDataOfSize(offset, length))
 961       return m_start + offset;
 962     return nullptr;
 963   }
 964
 965   //------------------------------------------------------------------
 966   /// Set the address byte size.
 967   ///
 968   /// Set the size in bytes that will be used when extracting any
 969   /// address and pointer values from data contained in this object.
 970   ///
 971   /// @param[in] addr_size
 972   ///     The size in bytes to use when extracting addresses.
 973   //------------------------------------------------------------------
 974   void SetAddressByteSize(uint32_t addr_size) {
 975 #ifdef LLDB_CONFIGURATION_DEBUG
 976     assert(addr_size == 4 || addr_size == 8);
 977 #endif
 978     m_addr_size = addr_size;
 979   }
 980
 981   //------------------------------------------------------------------
 982   /// Set data with a buffer that is caller owned.
 983   ///
 984   /// Use data that is owned by the caller when extracting values.
 985   /// The data must stay around as long as this object, or any object
 986   /// that copies a subset of this object's data, is valid. If \a
 987   /// bytes is nullptr, or \a length is zero, this object will contain
 988   /// no data.
 989   ///
 990   /// @param[in] bytes
 991   ///     A pointer to caller owned data.
 992   ///
 993   /// @param[in] length
 994   ///     The length in bytes of \a bytes.
 995   ///
 996   /// @param[in] byte_order
 997   ///     A byte order of the data that we are extracting from.
 998   ///
 999   /// @return
1000   ///     The number of bytes that this object now contains.
1001   //------------------------------------------------------------------
1002   lldb::offset_t SetData(const void *bytes, lldb::offset_t length,
1003                          lldb::ByteOrder byte_order);
1004
1005   //------------------------------------------------------------------
1006   /// Adopt a subset of \a data.
1007   ///
1008   /// Set this object's data to be a subset of the data bytes in \a
1009   /// data. If \a data contains shared data, then a reference to the
1010   /// shared data will be added to ensure the shared data stays around
1011   /// as long as any objects have references to the shared data. The
1012   /// byte order and the address size settings are copied from \a
1013   /// data. If \a offset is not a valid offset in \a data, then no
1014   /// reference to the shared data will be added. If there are not
1015   /// \a length bytes available in \a data starting at \a offset,
1016   /// the length will be truncated to contains as many bytes as
1017   /// possible.
1018   ///
1019   /// @param[in] data
1020   ///     Another DataExtractor object that contains data.
1021   ///
1022   /// @param[in] offset
1023   ///     The offset into \a data at which the subset starts.
1024   ///
1025   /// @param[in] length
1026   ///     The length in bytes of the subset of \a data.
1027   ///
1028   /// @return
1029   ///     The number of bytes that this object now contains.
1030   //------------------------------------------------------------------
1031   lldb::offset_t SetData(const DataExtractor &data, lldb::offset_t offset,
1032                          lldb::offset_t length);
1033
1034   //------------------------------------------------------------------
1035   /// Adopt a subset of shared data in \a data_sp.
1036   ///
1037   /// Copies the data shared pointer which adds a reference to the
1038   /// contained in \a data_sp. The shared data reference is reference
1039   /// counted to ensure the data lives as long as anyone still has a
1040   /// valid shared pointer to the data in \a data_sp. The byte order
1041   /// and address byte size settings remain the same. If
1042   /// \a offset is not a valid offset in \a data_sp, then no reference
1043   /// to the shared data will be added. If there are not \a length
1044   /// bytes available in \a data starting at \a offset, the length
1045   /// will be truncated to contains as many bytes as possible.
1046   ///
1047   /// @param[in] data_sp
1048   ///     A shared pointer to data.
1049   ///
1050   /// @param[in] offset
1051   ///     The offset into \a data_sp at which the subset starts.
1052   ///
1053   /// @param[in] length
1054   ///     The length in bytes of the subset of \a data_sp.
1055   ///
1056   /// @return
1057   ///     The number of bytes that this object now contains.
1058   //------------------------------------------------------------------
1059   lldb::offset_t SetData(const lldb::DataBufferSP &data_sp,
1060                          lldb::offset_t offset = 0,
1061                          lldb::offset_t length = LLDB_INVALID_OFFSET);
1062
1063   //------------------------------------------------------------------
1064   /// Set the byte_order value.
1065   ///
1066   /// Sets the byte order of the data to extract. Extracted values
1067   /// will be swapped if necessary when decoding.
1068   ///
1069   /// @param[in] byte_order
1070   ///     The byte order value to use when extracting data.
1071   //------------------------------------------------------------------
1072   void SetByteOrder(lldb::ByteOrder byte_order) { m_byte_order = byte_order; }
1073
1074   //------------------------------------------------------------------
1075   /// Skip an LEB128 number at \a *offset_ptr.
1076   ///
1077   /// Skips a LEB128 number (signed or unsigned) from this object's
1078   /// data starting at the offset pointed to by \a offset_ptr. The
1079   /// offset pointed to by \a offset_ptr will be updated with the
1080   /// offset of the byte following the last extracted byte.
1081   ///
1082   /// @param[in,out] offset_ptr
1083   ///     A pointer to an offset within the data that will be advanced
1084   ///     by the appropriate number of bytes if the value is extracted
1085   ///     correctly. If the offset is out of bounds or there are not
1086   ///     enough bytes to extract this value, the offset will be left
1087   ///     unmodified.
1088   ///
1089   /// @return
1090   //      The number of bytes consumed during the extraction.
1091   //------------------------------------------------------------------
1092   uint32_t Skip_LEB128(lldb::offset_t *offset_ptr) const;
1093
1094   //------------------------------------------------------------------
1095   /// Test the validity of \a offset.
1096   ///
1097   /// @return
1098   ///     \b true if \a offset is a valid offset into the data in this
1099   ///     object, \b false otherwise.
1100   //------------------------------------------------------------------
1101   bool ValidOffset(lldb::offset_t offset) const {
1102     return offset < GetByteSize();
1103   }
1104
1105   //------------------------------------------------------------------
1106   /// Test the availability of \a length bytes of data from \a offset.
1107   ///
1108   /// @return
1109   ///     \b true if \a offset is a valid offset and there are \a
1110   ///     length bytes available at that offset, \b false otherwise.
1111   //------------------------------------------------------------------
1112   bool ValidOffsetForDataOfSize(lldb::offset_t offset,
1113                                 lldb::offset_t length) const {
1114     return length <= BytesLeft(offset);
1115   }
1116
1117   size_t Copy(DataExtractor &dest_data) const;
1118
1119   bool Append(DataExtractor &rhs);
1120
1121   bool Append(void *bytes, lldb::offset_t length);
1122
1123   lldb::offset_t BytesLeft(lldb::offset_t offset) const {
1124     const lldb::offset_t size = GetByteSize();
1125     if (size > offset)
1126       return size - offset;
1127     return 0;
1128   }
1129
1130   void Checksum(llvm::SmallVectorImpl<uint8_t> &dest, uint64_t max_data = 0);
1131
1132 protected:
1133   //------------------------------------------------------------------
1134   // Member variables
1135   //------------------------------------------------------------------
1136   const uint8_t *m_start; ///< A pointer to the first byte of data.
1137   const uint8_t
1138       *m_end; ///< A pointer to the byte that is past the end of the data.
1139   lldb::ByteOrder
1140       m_byte_order;     ///< The byte order of the data we are extracting from.
1141   uint32_t m_addr_size; ///< The address size to use when extracting pointers or
1142                         /// addresses
1143   mutable lldb::DataBufferSP m_data_sp; ///< The shared pointer to data that can
1144                                         /// be shared among multiple instances
1145   const uint32_t m_target_byte_size;
1146 };
1147
1148 } // namespace lldb_private
1149
1150 #endif // liblldb_DataExtractor_h_