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