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