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