DataExtractor.h revision 0bf2d699067d434fe3dd187caf526ff94f19494f
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 dst_len bytes from \a *offset_ptr and ensure the copied 472 /// data is treated as a value that can be swapped to match the 473 /// specified byte order. 474 /// 475 /// For values that are larger than the supported integer sizes, 476 /// this function can be used to extract data in a specified byte 477 /// order. It can also be used to copy a smaller integer value from 478 /// to a larger value. The extra bytes left over will be padded 479 /// correctly according to the byte order of this object and the 480 /// \a dst_byte_order. This can be very handy when say copying a 481 /// partial data value into a register. 482 /// 483 /// @param[in] src_offset 484 /// The offset into this data from which to start copying an 485 /// endian entity 486 /// 487 /// @param[in] src_len 488 /// The length of the endian data to copy from this object 489 /// into the \a dst object 490 /// 491 /// @param[out] dst 492 /// The buffer where to place the endian data. The data might 493 /// need to be byte swapped (and appropriately padded with 494 /// zeroes if \a src_len != \a dst_len) if \a dst_byte_order 495 /// does not match the byte order in this object. 496 /// 497 /// @param[in] dst_len 498 /// The length number of bytes that the endian value will 499 /// occupy is \a dst. 500 /// 501 /// @param[in] byte_order 502 /// The byte order that the endian value should be in the \a dst 503 /// buffer. 504 /// 505 /// @return 506 /// Returns the number of bytes that were copied, or zero if 507 /// anything goes wrong. 508 //------------------------------------------------------------------ 509 lldb::offset_t 510 CopyByteOrderedData (lldb::offset_t src_offset, 511 lldb::offset_t src_len, 512 void *dst, 513 lldb::offset_t dst_len, 514 lldb::ByteOrder dst_byte_order) const; 515 516 //------------------------------------------------------------------ 517 /// Get the data end pointer. 518 /// 519 /// @return 520 /// Returns a pointer to the next byte contained in this 521 /// object's data, or NULL of there is no data in this object. 522 //------------------------------------------------------------------ 523 const uint8_t * 524 GetDataEnd () const 525 { 526 return m_end; 527 } 528 529 //------------------------------------------------------------------ 530 /// Get the shared data offset. 531 /// 532 /// Get the offset of the first byte of data in the shared data (if 533 /// any). 534 /// 535 /// @return 536 /// If this object contains shared data, this function returns 537 /// the offset in bytes into that shared data, zero otherwise. 538 //------------------------------------------------------------------ 539 size_t 540 GetSharedDataOffset () const; 541 542 //------------------------------------------------------------------ 543 /// Get a the data start pointer. 544 /// 545 /// @return 546 /// Returns a pointer to the first byte contained in this 547 /// object's data, or NULL of there is no data in this object. 548 //------------------------------------------------------------------ 549 const uint8_t * 550 GetDataStart () const 551 { 552 return m_start; 553 } 554 555 556 //------------------------------------------------------------------ 557 /// Extract a float from \a *offset_ptr. 558 /// 559 /// Extract a single float value. 560 /// 561 /// @param[in,out] offset_ptr 562 /// A pointer to an offset within the data that will be advanced 563 /// by the appropriate number of bytes if the value is extracted 564 /// correctly. If the offset is out of bounds or there are not 565 /// enough bytes to extract this value, the offset will be left 566 /// unmodified. 567 /// 568 /// @return 569 /// The floating value that was extracted, or zero on failure. 570 //------------------------------------------------------------------ 571 float 572 GetFloat (lldb::offset_t *offset_ptr) const; 573 574 double 575 GetDouble (lldb::offset_t *offset_ptr) const; 576 577 long double 578 GetLongDouble (lldb::offset_t *offset_ptr) const; 579 580 //------------------------------------------------------------------ 581 /// Extract a GNU encoded pointer value from \a *offset_ptr. 582 /// 583 /// @param[in,out] offset_ptr 584 /// A pointer to an offset within the data that will be advanced 585 /// by the appropriate number of bytes if the value is extracted 586 /// correctly. If the offset is out of bounds or there are not 587 /// enough bytes to extract this value, the offset will be left 588 /// unmodified. 589 /// 590 /// @param[in] eh_ptr_enc 591 /// The GNU pointer encoding type. 592 /// 593 /// @param[in] pc_rel_addr 594 /// The PC relative address to use when the encoding is 595 /// \c DW_GNU_EH_PE_pcrel. 596 /// 597 /// @param[in] text_addr 598 /// The text (code) relative address to use when the encoding is 599 /// \c DW_GNU_EH_PE_textrel. 600 /// 601 /// @param[in] data_addr 602 /// The data relative address to use when the encoding is 603 /// \c DW_GNU_EH_PE_datarel. 604 /// 605 /// @return 606 /// The extracted GNU encoded pointer value. 607 //------------------------------------------------------------------ 608 uint64_t 609 GetGNUEHPointer (lldb::offset_t *offset_ptr, 610 uint32_t eh_ptr_enc, 611 lldb::addr_t pc_rel_addr, 612 lldb::addr_t text_addr, 613 lldb::addr_t data_addr); 614 615 //------------------------------------------------------------------ 616 /// Extract an integer of size \a byte_size from \a *offset_ptr. 617 /// 618 /// Extract a single integer value and update the offset pointed to 619 /// by \a offset_ptr. The size of the extracted integer is specified 620 /// by the \a byte_size argument. \a byte_size should have a value 621 /// >= 1 and <= 4 since the return value is only 32 bits wide. Any 622 /// \a byte_size values less than 1 or greater than 4 will result in 623 /// nothing being extracted, and zero being returned. 624 /// 625 /// @param[in,out] offset_ptr 626 /// A pointer to an offset within the data that will be advanced 627 /// by the appropriate number of bytes if the value is extracted 628 /// correctly. If the offset is out of bounds or there are not 629 /// enough bytes to extract this value, the offset will be left 630 /// unmodified. 631 /// 632 /// @param[in] byte_size 633 /// The size in byte of the integer to extract. 634 /// 635 /// @return 636 /// The integer value that was extracted, or zero on failure. 637 //------------------------------------------------------------------ 638 uint32_t 639 GetMaxU32 (lldb::offset_t *offset_ptr, size_t byte_size) const; 640 641 //------------------------------------------------------------------ 642 /// Extract an unsigned integer of size \a byte_size from \a 643 /// *offset_ptr. 644 /// 645 /// Extract a single unsigned integer value and update the offset 646 /// pointed to by \a offset_ptr. The size of the extracted integer 647 /// is specified by the \a byte_size argument. \a byte_size should 648 /// have a value greater than or equal to one and less than or equal 649 /// to eight since the return value is 64 bits wide. Any 650 /// \a byte_size values less than 1 or greater than 8 will result in 651 /// nothing being extracted, and zero being returned. 652 /// 653 /// @param[in,out] offset_ptr 654 /// A pointer to an offset within the data that will be advanced 655 /// by the appropriate number of bytes if the value is extracted 656 /// correctly. If the offset is out of bounds or there are not 657 /// enough bytes to extract this value, the offset will be left 658 /// unmodified. 659 /// 660 /// @param[in] byte_size 661 /// The size in byte of the integer to extract. 662 /// 663 /// @return 664 /// The unsigned integer value that was extracted, or zero on 665 /// failure. 666 //------------------------------------------------------------------ 667 uint64_t 668 GetMaxU64 (lldb::offset_t *offset_ptr, size_t byte_size) const; 669 670 uint64_t 671 GetMaxU64_unchecked (lldb::offset_t *offset_ptr, size_t byte_size) const; 672 673 //------------------------------------------------------------------ 674 /// Extract an signed integer of size \a byte_size from \a *offset_ptr. 675 /// 676 /// Extract a single signed integer value (sign extending if required) 677 /// and update the offset pointed to by \a offset_ptr. The size of 678 /// the extracted integer is specified by the \a byte_size argument. 679 /// \a byte_size should have a value greater than or equal to one 680 /// and less than or equal to eight since the return value is 64 681 /// bits wide. Any \a byte_size values less than 1 or greater than 682 /// 8 will result in nothing being extracted, and zero being returned. 683 /// 684 /// @param[in,out] offset_ptr 685 /// A pointer to an offset within the data that will be advanced 686 /// by the appropriate number of bytes if the value is extracted 687 /// correctly. If the offset is out of bounds or there are not 688 /// enough bytes to extract this value, the offset will be left 689 /// unmodified. 690 /// 691 /// @param[in] byte_size 692 /// The size in byte of the integer to extract. 693 /// 694 /// @return 695 /// The sign extended signed integer value that was extracted, 696 /// or zero on failure. 697 //------------------------------------------------------------------ 698 int64_t 699 GetMaxS64 (lldb::offset_t *offset_ptr, size_t size) const; 700 701 //------------------------------------------------------------------ 702 /// Extract an unsigned integer of size \a byte_size from \a 703 /// *offset_ptr, then extract the bitfield from this value if 704 /// \a bitfield_bit_size is non-zero. 705 /// 706 /// Extract a single unsigned integer value and update the offset 707 /// pointed to by \a offset_ptr. The size of the extracted integer 708 /// is specified by the \a byte_size argument. \a byte_size should 709 /// have a value greater than or equal to one and less than or equal 710 /// to 8 since the return value is 64 bits wide. Any 711 /// \a byte_size values less than 1 or greater than 8 will result in 712 /// nothing being extracted, and zero being returned. 713 /// 714 /// @param[in,out] offset_ptr 715 /// A pointer to an offset within the data that will be advanced 716 /// by the appropriate number of bytes if the value is extracted 717 /// correctly. If the offset is out of bounds or there are not 718 /// enough bytes to extract this value, the offset will be left 719 /// unmodified. 720 /// 721 /// @param[in] byte_size 722 /// The size in byte of the integer to extract. 723 /// 724 /// @param[in] bitfield_bit_size 725 /// The size in bits of the bitfield value to extract, or zero 726 /// to just extract the entire integer value. 727 /// 728 /// @param[in] bitfield_bit_offset 729 /// The bit offset of the bitfield value in the extracted 730 /// integer (the number of bits to shift the integer to the 731 /// right). 732 /// 733 /// @return 734 /// The unsigned bitfield integer value that was extracted, or 735 /// zero on failure. 736 //------------------------------------------------------------------ 737 uint64_t 738 GetMaxU64Bitfield (lldb::offset_t *offset_ptr, 739 size_t size, 740 uint32_t bitfield_bit_size, 741 uint32_t bitfield_bit_offset) const; 742 743 //------------------------------------------------------------------ 744 /// Extract an signed integer of size \a byte_size from \a 745 /// *offset_ptr, then extract and signe extend the bitfield from 746 /// this value if \a bitfield_bit_size is non-zero. 747 /// 748 /// Extract a single signed integer value (sign extending if required) 749 /// and update the offset pointed to by \a offset_ptr. The size of 750 /// the extracted integer is specified by the \a byte_size argument. 751 /// \a byte_size should have a value greater than or equal to one 752 /// and less than or equal to eight since the return value is 64 753 /// bits wide. Any \a byte_size values less than 1 or greater than 754 /// 8 will result in nothing being extracted, and zero being returned. 755 /// 756 /// @param[in,out] offset_ptr 757 /// A pointer to an offset within the data that will be advanced 758 /// by the appropriate number of bytes if the value is extracted 759 /// correctly. If the offset is out of bounds or there are not 760 /// enough bytes to extract this value, the offset will be left 761 /// unmodified. 762 /// 763 /// @param[in] byte_size 764 /// The size in bytes of the integer to extract. 765 /// 766 /// @param[in] bitfield_bit_size 767 /// The size in bits of the bitfield value to extract, or zero 768 /// to just extract the entire integer value. 769 /// 770 /// @param[in] bitfield_bit_offset 771 /// The bit offset of the bitfield value in the extracted 772 /// integer (the number of bits to shift the integer to the 773 /// right). 774 /// 775 /// @return 776 /// The signed bitfield integer value that was extracted, or 777 /// zero on failure. 778 //------------------------------------------------------------------ 779 int64_t 780 GetMaxS64Bitfield (lldb::offset_t *offset_ptr, 781 size_t size, 782 uint32_t bitfield_bit_size, 783 uint32_t bitfield_bit_offset) const; 784 785 //------------------------------------------------------------------ 786 /// Extract an pointer from \a *offset_ptr. 787 /// 788 /// Extract a single pointer from the data and update the offset 789 /// pointed to by \a offset_ptr. The size of the extracted pointer 790 /// comes from the \a m_addr_size member variable and should be 791 /// set correctly prior to extracting any pointer values. 792 /// 793 /// @param[in,out] offset_ptr 794 /// A pointer to an offset within the data that will be advanced 795 /// by the appropriate number of bytes if the value is extracted 796 /// correctly. If the offset is out of bounds or there are not 797 /// enough bytes to extract this value, the offset will be left 798 /// unmodified. 799 /// 800 /// @return 801 /// The extracted pointer value as a 64 integer. 802 //------------------------------------------------------------------ 803 uint64_t 804 GetPointer (lldb::offset_t *offset_ptr) const; 805 806 //------------------------------------------------------------------ 807 /// Get the current byte order value. 808 /// 809 /// @return 810 /// The current byte order value from this object's internal 811 /// state. 812 //------------------------------------------------------------------ 813 lldb::ByteOrder 814 GetByteOrder() const 815 { 816 return m_byte_order; 817 } 818 819 //------------------------------------------------------------------ 820 /// Extract a uint8_t value from \a *offset_ptr. 821 /// 822 /// Extract a single uint8_t from the binary data at the offset 823 /// pointed to by \a offset_ptr, and advance the offset on success. 824 /// 825 /// @param[in,out] offset_ptr 826 /// A pointer to an offset within the data that will be advanced 827 /// by the appropriate number of bytes if the value is extracted 828 /// correctly. If the offset is out of bounds or there are not 829 /// enough bytes to extract this value, the offset will be left 830 /// unmodified. 831 /// 832 /// @return 833 /// The extracted uint8_t value. 834 //------------------------------------------------------------------ 835 uint8_t 836 GetU8 ( lldb::offset_t *offset_ptr) const; 837 838 uint8_t 839 GetU8_unchecked (lldb::offset_t *offset_ptr) const 840 { 841 uint8_t val = m_start[*offset_ptr]; 842 *offset_ptr += 1; 843 return val; 844 } 845 846 uint16_t 847 GetU16_unchecked (lldb::offset_t *offset_ptr) const; 848 849 uint32_t 850 GetU32_unchecked (lldb::offset_t *offset_ptr) const; 851 852 uint64_t 853 GetU64_unchecked (lldb::offset_t *offset_ptr) const; 854 //------------------------------------------------------------------ 855 /// Extract \a count uint8_t values from \a *offset_ptr. 856 /// 857 /// Extract \a count uint8_t values from the binary data at the 858 /// offset pointed to by \a offset_ptr, and advance the offset on 859 /// success. The extracted values are copied into \a dst. 860 /// 861 /// @param[in,out] offset_ptr 862 /// A pointer to an offset within the data that will be advanced 863 /// by the appropriate number of bytes if the value is extracted 864 /// correctly. If the offset is out of bounds or there are not 865 /// enough bytes to extract this value, the offset will be left 866 /// unmodified. 867 /// 868 /// @param[out] dst 869 /// A buffer to copy \a count uint8_t values into. \a dst must 870 /// be large enough to hold all requested data. 871 /// 872 /// @param[in] count 873 /// The number of uint8_t values to extract. 874 /// 875 /// @return 876 /// \a dst if all values were properly extracted and copied, 877 /// NULL otherise. 878 //------------------------------------------------------------------ 879 void * 880 GetU8 (lldb::offset_t *offset_ptr, void *dst, uint32_t count) const; 881 882 //------------------------------------------------------------------ 883 /// Extract a uint16_t value from \a *offset_ptr. 884 /// 885 /// Extract a single uint16_t from the binary data at the offset 886 /// pointed to by \a offset_ptr, and update the offset on success. 887 /// 888 /// @param[in,out] offset_ptr 889 /// A pointer to an offset within the data that will be advanced 890 /// by the appropriate number of bytes if the value is extracted 891 /// correctly. If the offset is out of bounds or there are not 892 /// enough bytes to extract this value, the offset will be left 893 /// unmodified. 894 /// 895 /// @return 896 /// The extracted uint16_t value. 897 //------------------------------------------------------------------ 898 uint16_t 899 GetU16 (lldb::offset_t *offset_ptr) const; 900 901 //------------------------------------------------------------------ 902 /// Extract \a count uint16_t values from \a *offset_ptr. 903 /// 904 /// Extract \a count uint16_t values from the binary data at the 905 /// offset pointed to by \a offset_ptr, and advance the offset on 906 /// success. The extracted values are copied into \a dst. 907 /// 908 /// @param[in,out] offset_ptr 909 /// A pointer to an offset within the data that will be advanced 910 /// by the appropriate number of bytes if the value is extracted 911 /// correctly. If the offset is out of bounds or there are not 912 /// enough bytes to extract this value, the offset will be left 913 /// unmodified. 914 /// 915 /// @param[out] dst 916 /// A buffer to copy \a count uint16_t values into. \a dst must 917 /// be large enough to hold all requested data. 918 /// 919 /// @param[in] count 920 /// The number of uint16_t values to extract. 921 /// 922 /// @return 923 /// \a dst if all values were properly extracted and copied, 924 /// NULL otherise. 925 //------------------------------------------------------------------ 926 void * 927 GetU16 (lldb::offset_t *offset_ptr, void *dst, uint32_t count) const; 928 929 //------------------------------------------------------------------ 930 /// Extract a uint32_t value from \a *offset_ptr. 931 /// 932 /// Extract a single uint32_t from the binary data at the offset 933 /// pointed to by \a offset_ptr, and update the offset on success. 934 /// 935 /// @param[in,out] offset_ptr 936 /// A pointer to an offset within the data that will be advanced 937 /// by the appropriate number of bytes if the value is extracted 938 /// correctly. If the offset is out of bounds or there are not 939 /// enough bytes to extract this value, the offset will be left 940 /// unmodified. 941 /// 942 /// @return 943 /// The extracted uint32_t value. 944 //------------------------------------------------------------------ 945 uint32_t 946 GetU32 (lldb::offset_t *offset_ptr) const; 947 948 //------------------------------------------------------------------ 949 /// Extract \a count uint32_t values from \a *offset_ptr. 950 /// 951 /// Extract \a count uint32_t values from the binary data at the 952 /// offset pointed to by \a offset_ptr, and advance the offset on 953 /// success. The extracted values are copied into \a dst. 954 /// 955 /// @param[in,out] offset_ptr 956 /// A pointer to an offset within the data that will be advanced 957 /// by the appropriate number of bytes if the value is extracted 958 /// correctly. If the offset is out of bounds or there are not 959 /// enough bytes to extract this value, the offset will be left 960 /// unmodified. 961 /// 962 /// @param[out] dst 963 /// A buffer to copy \a count uint32_t values into. \a dst must 964 /// be large enough to hold all requested data. 965 /// 966 /// @param[in] count 967 /// The number of uint32_t values to extract. 968 /// 969 /// @return 970 /// \a dst if all values were properly extracted and copied, 971 /// NULL otherise. 972 //------------------------------------------------------------------ 973 void * 974 GetU32 (lldb::offset_t *offset_ptr, void *dst, uint32_t count) const; 975 976 //------------------------------------------------------------------ 977 /// Extract a uint64_t value from \a *offset_ptr. 978 /// 979 /// Extract a single uint64_t from the binary data at the offset 980 /// pointed to by \a offset_ptr, and update the offset on success. 981 /// 982 /// @param[in,out] offset_ptr 983 /// A pointer to an offset within the data that will be advanced 984 /// by the appropriate number of bytes if the value is extracted 985 /// correctly. If the offset is out of bounds or there are not 986 /// enough bytes to extract this value, the offset will be left 987 /// unmodified. 988 /// 989 /// @return 990 /// The extracted uint64_t value. 991 //------------------------------------------------------------------ 992 uint64_t 993 GetU64 (lldb::offset_t *offset_ptr) const; 994 995 //------------------------------------------------------------------ 996 /// Extract \a count uint64_t values from \a *offset_ptr. 997 /// 998 /// Extract \a count uint64_t values from the binary data at the 999 /// offset pointed to by \a offset_ptr, and advance the offset on 1000 /// success. The extracted values are copied into \a dst. 1001 /// 1002 /// @param[in,out] offset_ptr 1003 /// A pointer to an offset within the data that will be advanced 1004 /// by the appropriate number of bytes if the value is extracted 1005 /// correctly. If the offset is out of bounds or there are not 1006 /// enough bytes to extract this value, the offset will be left 1007 /// unmodified. 1008 /// 1009 /// @param[out] dst 1010 /// A buffer to copy \a count uint64_t values into. \a dst must 1011 /// be large enough to hold all requested data. 1012 /// 1013 /// @param[in] count 1014 /// The number of uint64_t values to extract. 1015 /// 1016 /// @return 1017 /// \a dst if all values were properly extracted and copied, 1018 /// NULL otherise. 1019 //------------------------------------------------------------------ 1020 void * 1021 GetU64 ( lldb::offset_t *offset_ptr, void *dst, uint32_t count) const; 1022 1023 //------------------------------------------------------------------ 1024 /// Extract a signed LEB128 value from \a *offset_ptr. 1025 /// 1026 /// Extracts an signed LEB128 number from this object's data 1027 /// starting at the offset pointed to by \a offset_ptr. The offset 1028 /// pointed to by \a offset_ptr will be updated with the offset of 1029 /// the byte following the last extracted byte. 1030 /// 1031 /// @param[in,out] offset_ptr 1032 /// A pointer to an offset within the data that will be advanced 1033 /// by the appropriate number of bytes if the value is extracted 1034 /// correctly. If the offset is out of bounds or there are not 1035 /// enough bytes to extract this value, the offset will be left 1036 /// unmodified. 1037 /// 1038 /// @return 1039 /// The extracted signed integer value. 1040 //------------------------------------------------------------------ 1041 int64_t 1042 GetSLEB128 (lldb::offset_t *offset_ptr) const; 1043 1044 //------------------------------------------------------------------ 1045 /// Extract a unsigned LEB128 value from \a *offset_ptr. 1046 /// 1047 /// Extracts an unsigned 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 unsigned integer value. 1061 //------------------------------------------------------------------ 1062 uint64_t 1063 GetULEB128 (lldb::offset_t *offset_ptr) const; 1064 1065 lldb::DataBufferSP & 1066 GetSharedDataBuffer () 1067 { 1068 return m_data_sp; 1069 } 1070 1071 //------------------------------------------------------------------ 1072 /// Peek at a C string at \a offset. 1073 /// 1074 /// Peeks at a string in the contained data. No verification is done 1075 /// to make sure the entire string lies within the bounds of this 1076 /// object's data, only \a offset is verified to be a valid offset. 1077 /// 1078 /// @param[in] offset 1079 /// An offset into the data. 1080 /// 1081 /// @return 1082 /// A non-NULL C string pointer if \a offset is a valid offset, 1083 /// NULL otherwise. 1084 //------------------------------------------------------------------ 1085 const char * 1086 PeekCStr (lldb::offset_t offset) const; 1087 1088 //------------------------------------------------------------------ 1089 /// Peek at a bytes at \a offset. 1090 /// 1091 /// Returns a pointer to \a length bytes at \a offset as long as 1092 /// there are \a length bytes available starting at \a offset. 1093 /// 1094 /// @return 1095 /// A non-NULL data pointer if \a offset is a valid offset and 1096 /// there are \a length bytes available at that offset, NULL 1097 /// otherwise. 1098 //------------------------------------------------------------------ 1099 const uint8_t* 1100 PeekData (lldb::offset_t offset, lldb::offset_t length) const 1101 { 1102 if (length > 0 && ValidOffsetForDataOfSize(offset, length)) 1103 return m_start + offset; 1104 return NULL; 1105 } 1106 1107 //------------------------------------------------------------------ 1108 /// Set the address byte size. 1109 /// 1110 /// Set the size in bytes that will be used when extracting any 1111 /// address and pointer values from data contained in this object. 1112 /// 1113 /// @param[in] addr_size 1114 /// The size in bytes to use when extracting addresses. 1115 //------------------------------------------------------------------ 1116 void 1117 SetAddressByteSize (uint32_t addr_size) 1118 { 1119 m_addr_size = addr_size; 1120 } 1121 1122 //------------------------------------------------------------------ 1123 /// Set data with a buffer that is caller owned. 1124 /// 1125 /// Use data that is owned by the caller when extracting values. 1126 /// The data must stay around as long as this object, or any object 1127 /// that copies a subset of this object's data, is valid. If \a 1128 /// bytes is NULL, or \a length is zero, this object will contain 1129 /// no data. 1130 /// 1131 /// @param[in] bytes 1132 /// A pointer to caller owned data. 1133 /// 1134 /// @param[in] length 1135 /// The length in bytes of \a bytes. 1136 /// 1137 /// @param[in] byte_order 1138 /// A byte order of the data that we are extracting from. 1139 /// 1140 /// @return 1141 /// The number of bytes that this object now contains. 1142 //------------------------------------------------------------------ 1143 lldb::offset_t 1144 SetData (const void *bytes, lldb::offset_t length, lldb::ByteOrder byte_order); 1145 1146 //------------------------------------------------------------------ 1147 /// Adopt a subset of \a data. 1148 /// 1149 /// Set this object's data to be a subset of the data bytes in \a 1150 /// data. If \a data contains shared data, then a reference to the 1151 /// shared data will be added to ensure the shared data stays around 1152 /// as long as any objects have references to the shared data. The 1153 /// byte order and the address size settings are copied from \a 1154 /// data. If \a offset is not a valid offset in \a data, then no 1155 /// reference to the shared data will be added. If there are not 1156 /// \a length bytes available in \a data starting at \a offset, 1157 /// the length will be truncated to contains as many bytes as 1158 /// possible. 1159 /// 1160 /// @param[in] data 1161 /// Another DataExtractor object that contains data. 1162 /// 1163 /// @param[in] offset 1164 /// The offset into \a data at which the subset starts. 1165 /// 1166 /// @param[in] length 1167 /// The length in bytes of the subset of \a data. 1168 /// 1169 /// @return 1170 /// The number of bytes that this object now contains. 1171 //------------------------------------------------------------------ 1172 lldb::offset_t 1173 SetData (const DataExtractor& data, lldb::offset_t offset, lldb::offset_t length); 1174 1175 //------------------------------------------------------------------ 1176 /// Adopt a subset of shared data in \a data_sp. 1177 /// 1178 /// Copies the data shared pointer which adds a reference to the 1179 /// contained in \a data_sp. The shared data reference is reference 1180 /// counted to ensure the data lives as long as anyone still has a 1181 /// valid shared pointer to the data in \a data_sp. The byte order 1182 /// and address byte size settings remain the same. If 1183 /// \a offset is not a valid offset in \a data_sp, then no reference 1184 /// to the shared data will be added. If there are not \a length 1185 /// bytes available in \a data starting at \a offset, the length 1186 /// will be truncated to contains as many bytes as possible. 1187 /// 1188 /// @param[in] data_sp 1189 /// A shared pointer to data. 1190 /// 1191 /// @param[in] offset 1192 /// The offset into \a data_sp at which the subset starts. 1193 /// 1194 /// @param[in] length 1195 /// The length in bytes of the subset of \a data_sp. 1196 /// 1197 /// @return 1198 /// The number of bytes that this object now contains. 1199 //------------------------------------------------------------------ 1200 lldb::offset_t 1201 SetData (const lldb::DataBufferSP& data_sp, lldb::offset_t offset = 0, lldb::offset_t length = LLDB_INVALID_OFFSET); 1202 1203 //------------------------------------------------------------------ 1204 /// Set the byte_order value. 1205 /// 1206 /// Sets the byte order of the data to extract. Extracted values 1207 /// will be swapped if necessary when decoding. 1208 /// 1209 /// @param[in] byte_order 1210 /// The byte order value to use when extracting data. 1211 //------------------------------------------------------------------ 1212 void 1213 SetByteOrder (lldb::ByteOrder byte_order) 1214 { 1215 m_byte_order = byte_order; 1216 } 1217 1218 //------------------------------------------------------------------ 1219 /// Skip an LEB128 number at \a *offset_ptr. 1220 /// 1221 /// Skips a LEB128 number (signed or unsigned) from this object's 1222 /// data starting at the offset pointed to by \a offset_ptr. The 1223 /// offset pointed to by \a offset_ptr will be updated with the 1224 /// offset of the byte following the last extracted byte. 1225 /// 1226 /// @param[in,out] offset_ptr 1227 /// A pointer to an offset within the data that will be advanced 1228 /// by the appropriate number of bytes if the value is extracted 1229 /// correctly. If the offset is out of bounds or there are not 1230 /// enough bytes to extract this value, the offset will be left 1231 /// unmodified. 1232 /// 1233 /// @return 1234 // The number of bytes consumed during the extraction. 1235 //------------------------------------------------------------------ 1236 uint32_t 1237 Skip_LEB128 (lldb::offset_t *offset_ptr) const; 1238 1239 //------------------------------------------------------------------ 1240 /// Test the validity of \a offset. 1241 /// 1242 /// @return 1243 /// \b true if \a offset is a valid offset into the data in this 1244 /// object, \b false otherwise. 1245 //------------------------------------------------------------------ 1246 bool 1247 ValidOffset (lldb::offset_t offset) const 1248 { 1249 return offset < GetByteSize(); 1250 } 1251 1252 //------------------------------------------------------------------ 1253 /// Test the availability of \a length bytes of data from \a offset. 1254 /// 1255 /// @return 1256 /// \b true if \a offset is a valid offset and there are \a 1257 /// length bytes available at that offset, \b false otherwise. 1258 //------------------------------------------------------------------ 1259 bool 1260 ValidOffsetForDataOfSize (lldb::offset_t offset, lldb::offset_t length) const 1261 { 1262 return length <= BytesLeft (offset); 1263 } 1264 1265 size_t 1266 Copy (DataExtractor& dest_data) const; 1267 1268 bool 1269 Append (DataExtractor& rhs); 1270 1271 bool 1272 Append (void* bytes, lldb::offset_t length); 1273 1274 lldb::offset_t 1275 BytesLeft (lldb::offset_t offset) const 1276 { 1277 const lldb::offset_t size = GetByteSize(); 1278 if (size > offset) 1279 return size - offset; 1280 return 0; 1281 } 1282 1283protected: 1284 1285 //------------------------------------------------------------------ 1286 // Member variables 1287 //------------------------------------------------------------------ 1288 const uint8_t * m_start; ///< A pointer to the first byte of data. 1289 const uint8_t * m_end; ///< A pointer to the byte that is past the end of the data. 1290 lldb::ByteOrder m_byte_order; ///< The byte order of the data we are extracting from. 1291 uint32_t m_addr_size; ///< The address size to use when extracting pointers or addresses 1292 mutable lldb::DataBufferSP m_data_sp; ///< The shared pointer to data that can be shared among multilple instances 1293}; 1294 1295} // namespace lldb_private 1296 1297#endif // #if defined (__cplusplus) 1298#endif // #ifndef liblldb_DataExtractor_h_ 1299