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