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