contrib/llvm-project/lldb/include/lldb/Utility/DataExtractor.h

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