DataExtractor.h revision 37f962e785be99dc4f0c5e9d02416992ff03bbd0
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, uint32_t data_length, lldb::ByteOrder byte_order, uint8_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, uint8_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, uint32_t offset, uint32_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 uint32_t 208 PutToLog (Log *log, 209 uint32_t offset, 210 uint32_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 uint32_t 277 Dump(Stream *s, 278 uint32_t offset, 279 lldb::Format item_format, 280 uint32_t item_byte_size, 281 uint32_t item_count, 282 uint32_t num_per_line, 283 uint64_t base_addr, 284 uint32_t item_bit_size, 285 uint32_t item_bit_offset) const; 286 287 //------------------------------------------------------------------ 288 /// Dump a UUID value at \a offset. 289 /// 290 /// Dump a UUID starting at \a offset bytes into this object's data. 291 /// If the stream \a s is NULL, the output will be sent to Log(). 292 /// 293 /// @param[in] s 294 /// The stream to dump the output to. If NULL the output will 295 /// be dumped to Log(). 296 /// 297 /// @param[in] offset 298 /// The offset into the data at which to extract and dump a 299 /// UUID value. 300 //------------------------------------------------------------------ 301 void 302 DumpUUID (Stream *s, uint32_t offset) const; 303 304 //------------------------------------------------------------------ 305 /// Extract an arbitrary number of bytes in the specified byte 306 /// order. 307 /// 308 /// Attemps to extract \a length bytes starting at \a offset bytes 309 /// into this data in the requested byte order (\a dst_byte_order) 310 /// and place the results in \a dst. \a dst must be at least \a 311 /// length bytes long. 312 /// 313 /// @param[in] offset 314 /// The offset in bytes into the contained data at which to 315 /// start extracting. 316 /// 317 /// @param[in] length 318 /// The number of bytes to extract. 319 /// 320 /// @param[in] dst_byte_order 321 /// A byte order of the data that we want when the value in 322 /// copied to \a dst. 323 /// 324 /// @param[out] dst 325 /// The buffer that will receive the extracted value if there 326 /// are enough bytes available in the current data. 327 /// 328 /// @return 329 /// The number of bytes that were extracted which will be \a 330 /// length when the value is successfully extracted, or zero 331 /// if there aren't enough bytes at the specified offset. 332 //------------------------------------------------------------------ 333 size_t 334 ExtractBytes (uint32_t offset, uint32_t length, lldb::ByteOrder dst_byte_order, void *dst) const; 335 336 //------------------------------------------------------------------ 337 /// Extract an address from \a *offset_ptr. 338 /// 339 /// Extract a single address from the data and update the offset 340 /// pointed to by \a offset_ptr. The size of the extracted address 341 /// comes from the \a m_addr_size member variable and should be 342 /// set correctly prior to extracting any address values. 343 /// 344 /// @param[in,out] offset_ptr 345 /// A pointer to an offset within the data that will be advanced 346 /// by the appropriate number of bytes if the value is extracted 347 /// correctly. If the offset is out of bounds or there are not 348 /// enough bytes to extract this value, the offset will be left 349 /// unmodified. 350 /// 351 /// @return 352 /// The extracted address value. 353 //------------------------------------------------------------------ 354 uint64_t 355 GetAddress (uint32_t *offset_ptr) const; 356 357 //------------------------------------------------------------------ 358 /// Get the current address size. 359 /// 360 /// Return the size in bytes of any address values this object will 361 /// extract. 362 /// 363 /// @return 364 /// The size in bytes of address values that will be extracted. 365 //------------------------------------------------------------------ 366 uint8_t 367 GetAddressByteSize () const; 368 369 //------------------------------------------------------------------ 370 /// Get the number of bytes contained in this object. 371 /// 372 /// @return 373 /// The total number of bytes of data this object refers to. 374 //------------------------------------------------------------------ 375 size_t 376 GetByteSize () const; 377 378 //------------------------------------------------------------------ 379 /// Extract a C string from \a *offset_ptr. 380 /// 381 /// Returns a pointer to a C String from the data at the offset 382 /// pointed to by \a offset_ptr. A variable length NULL terminated C 383 /// string will be extracted and the \a offset_ptr will be 384 /// updated with the offset of the byte that follows the NULL 385 /// terminator byte. 386 /// 387 /// @param[in,out] offset_ptr 388 /// A pointer to an offset within the data that will be advanced 389 /// by the appropriate number of bytes if the value is extracted 390 /// correctly. If the offset is out of bounds or there are not 391 /// enough bytes to extract this value, the offset will be left 392 /// unmodified. 393 /// 394 /// @return 395 /// A pointer to the C string value in the data. If the offset 396 /// pointed to by \a offset_ptr is out of bounds, or if the 397 /// offset plus the length of the C string is out of bounds, 398 /// NULL will be returned. 399 //------------------------------------------------------------------ 400 const char * 401 GetCStr (uint32_t *offset_ptr) const; 402 403 //------------------------------------------------------------------ 404 /// Extract \a length bytes from \a *offset_ptr. 405 /// 406 /// Returns a pointer to a bytes in this object's data at the offset 407 /// pointed to by \a offset_ptr. If \a length is zero or too large, 408 /// then the offset pointed to by \a offset_ptr will not be updated 409 /// and NULL will be returned. 410 /// 411 /// @param[in,out] offset_ptr 412 /// A pointer to an offset within the data that will be advanced 413 /// by the appropriate number of bytes if the value is extracted 414 /// correctly. If the offset is out of bounds or there are not 415 /// enough bytes to extract this value, the offset will be left 416 /// unmodified. 417 /// 418 /// @param[in] length 419 /// The optional length of a string to extract. If the value is 420 /// zero, a NULL terminated C string will be extracted. 421 /// 422 /// @return 423 /// A pointer to the bytes in this object's data if the offset 424 /// and length are valid, or NULL otherwise. 425 //------------------------------------------------------------------ 426 const void* 427 GetData (uint32_t *offset_ptr, uint32_t length) const; 428 429 //------------------------------------------------------------------ 430 /// Copy \a dst_len bytes from \a *offset_ptr and ensure the copied 431 /// data is treated as a value that can be swapped to match the 432 /// specified byte order. 433 /// 434 /// For values that are larger than the supported integer sizes, 435 /// this function can be used to extract data in a specified byte 436 /// order. It can also be used to copy a smaller integer value from 437 /// to a larger value. The extra bytes left over will be padded 438 /// correctly according to the byte order of this object and the 439 /// \a dst_byte_order. This can be very handy when say copying a 440 /// partial data value into a register. 441 /// 442 /// @param[in] src_offset 443 /// The offset into this data from which to start copying an 444 /// endian entity 445 /// 446 /// @param[in] src_len 447 /// The length of the endian data to copy from this object 448 /// into the \a dst object 449 /// 450 /// @param[out] dst 451 /// The buffer where to place the endian data. The data might 452 /// need to be byte swapped (and appropriately padded with 453 /// zeroes if \a src_len != \a dst_len) if \a dst_byte_order 454 /// does not match the byte order in this object. 455 /// 456 /// @param[in] dst_len 457 /// The length number of bytes that the endian value will 458 /// occupy is \a dst. 459 /// 460 /// @param[in] byte_order 461 /// The byte order that the endian value should be in the \a dst 462 /// buffer. 463 /// 464 /// @return 465 /// Returns the number of bytes that were copied, or zero if 466 /// anything goes wrong. 467 //------------------------------------------------------------------ 468 uint32_t 469 CopyByteOrderedData (uint32_t src_offset, 470 uint32_t src_len, 471 void *dst, 472 uint32_t dst_len, 473 lldb::ByteOrder dst_byte_order) const; 474 475 //------------------------------------------------------------------ 476 /// Get the data end pointer. 477 /// 478 /// @return 479 /// Returns a pointer to the next byte contained in this 480 /// object's data, or NULL of there is no data in this object. 481 //------------------------------------------------------------------ 482 const uint8_t * 483 GetDataEnd () const; 484 485 //------------------------------------------------------------------ 486 /// Get the shared data offset. 487 /// 488 /// Get the offset of the first byte of data in the shared data (if 489 /// any). 490 /// 491 /// @return 492 /// If this object contains shared data, this function returns 493 /// the offset in bytes into that shared data, zero otherwise. 494 //------------------------------------------------------------------ 495 size_t 496 GetSharedDataOffset () const; 497 498 //------------------------------------------------------------------ 499 /// Get a the data start pointer. 500 /// 501 /// @return 502 /// Returns a pointer to the first byte contained in this 503 /// object's data, or NULL of there is no data in this object. 504 //------------------------------------------------------------------ 505 const uint8_t * 506 GetDataStart () const; 507 508 509 //------------------------------------------------------------------ 510 /// Extract a float from \a *offset_ptr. 511 /// 512 /// Extract a single float value. 513 /// 514 /// @param[in,out] offset_ptr 515 /// A pointer to an offset within the data that will be advanced 516 /// by the appropriate number of bytes if the value is extracted 517 /// correctly. If the offset is out of bounds or there are not 518 /// enough bytes to extract this value, the offset will be left 519 /// unmodified. 520 /// 521 /// @return 522 /// The integer value that was extracted, or zero on failure. 523 //------------------------------------------------------------------ 524 float 525 GetFloat (uint32_t *offset_ptr) const; 526 527 double 528 GetDouble (uint32_t *offset_ptr) const; 529 530 long double 531 GetLongDouble (uint32_t *offset_ptr) const; 532 533 //------------------------------------------------------------------ 534 /// Extract a GNU encoded pointer value from \a *offset_ptr. 535 /// 536 /// @param[in,out] offset_ptr 537 /// A pointer to an offset within the data that will be advanced 538 /// by the appropriate number of bytes if the value is extracted 539 /// correctly. If the offset is out of bounds or there are not 540 /// enough bytes to extract this value, the offset will be left 541 /// unmodified. 542 /// 543 /// @param[in] eh_ptr_enc 544 /// The GNU pointer encoding type. 545 /// 546 /// @param[in] pc_rel_addr 547 /// The PC relative address to use when the encoding is 548 /// \c DW_GNU_EH_PE_pcrel. 549 /// 550 /// @param[in] text_addr 551 /// The text (code) relative address to use when the encoding is 552 /// \c DW_GNU_EH_PE_textrel. 553 /// 554 /// @param[in] data_addr 555 /// The data relative address to use when the encoding is 556 /// \c DW_GNU_EH_PE_datarel. 557 /// 558 /// @return 559 /// The extracted GNU encoded pointer value. 560 //------------------------------------------------------------------ 561 uint64_t 562 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); 563 564 //------------------------------------------------------------------ 565 /// Extract an integer of size \a byte_size from \a *offset_ptr. 566 /// 567 /// Extract a single integer value and update the offset pointed to 568 /// by \a offset_ptr. The size of the extracted integer is specified 569 /// by the \a byte_size argument. \a byte_size should have a value 570 /// >= 1 and <= 4 since the return value is only 32 bits wide. Any 571 /// \a byte_size values less than 1 or greater than 4 will result in 572 /// nothing being extracted, and zero being returned. 573 /// 574 /// @param[in,out] offset_ptr 575 /// A pointer to an offset within the data that will be advanced 576 /// by the appropriate number of bytes if the value is extracted 577 /// correctly. If the offset is out of bounds or there are not 578 /// enough bytes to extract this value, the offset will be left 579 /// unmodified. 580 /// 581 /// @param[in] byte_size 582 /// The size in byte of the integer to extract. 583 /// 584 /// @return 585 /// The integer value that was extracted, or zero on failure. 586 //------------------------------------------------------------------ 587 uint32_t 588 GetMaxU32 (uint32_t *offset_ptr, uint32_t byte_size) const; 589 590 //------------------------------------------------------------------ 591 /// Extract an unsigned integer of size \a byte_size from \a 592 /// *offset_ptr. 593 /// 594 /// Extract a single unsigned integer value and update the offset 595 /// pointed to by \a offset_ptr. The size of the extracted integer 596 /// is specified by the \a byte_size argument. \a byte_size should 597 /// have a value greater than or equal to one and less than or equal 598 /// to eight since the return value is 64 bits wide. Any 599 /// \a byte_size values less than 1 or greater than 8 will result in 600 /// nothing being extracted, and zero being returned. 601 /// 602 /// @param[in,out] offset_ptr 603 /// A pointer to an offset within the data that will be advanced 604 /// by the appropriate number of bytes if the value is extracted 605 /// correctly. If the offset is out of bounds or there are not 606 /// enough bytes to extract this value, the offset will be left 607 /// unmodified. 608 /// 609 /// @param[in] byte_size 610 /// The size in byte of the integer to extract. 611 /// 612 /// @return 613 /// The unsigned integer value that was extracted, or zero on 614 /// failure. 615 //------------------------------------------------------------------ 616 uint64_t 617 GetMaxU64 (uint32_t *offset_ptr, uint32_t byte_size) const; 618 619 //------------------------------------------------------------------ 620 /// Extract an signed integer of size \a byte_size from \a *offset_ptr. 621 /// 622 /// Extract a single signed integer value (sign extending if required) 623 /// and update the offset pointed to by \a offset_ptr. The size of 624 /// the extracted integer is specified by the \a byte_size argument. 625 /// \a byte_size should have a value greater than or equal to one 626 /// and less than or equal to eight since the return value is 64 627 /// bits wide. Any \a byte_size values less than 1 or greater than 628 /// 8 will result in nothing being extracted, and zero being returned. 629 /// 630 /// @param[in,out] offset_ptr 631 /// A pointer to an offset within the data that will be advanced 632 /// by the appropriate number of bytes if the value is extracted 633 /// correctly. If the offset is out of bounds or there are not 634 /// enough bytes to extract this value, the offset will be left 635 /// unmodified. 636 /// 637 /// @param[in] byte_size 638 /// The size in byte of the integer to extract. 639 /// 640 /// @return 641 /// The sign extended signed integer value that was extracted, 642 /// or zero on failure. 643 //------------------------------------------------------------------ 644 int64_t 645 GetMaxS64 (uint32_t *offset_ptr, uint32_t size) const; 646 647 //------------------------------------------------------------------ 648 /// Extract an unsigned integer of size \a byte_size from \a 649 /// *offset_ptr, then extract the bitfield from this value if 650 /// \a bitfield_bit_size is non-zero. 651 /// 652 /// Extract a single unsigned integer value and update the offset 653 /// pointed to by \a offset_ptr. The size of the extracted integer 654 /// is specified by the \a byte_size argument. \a byte_size should 655 /// have a value greater than or equal to one and less than or equal 656 /// to 8 since the return value is 64 bits wide. Any 657 /// \a byte_size values less than 1 or greater than 8 will result in 658 /// nothing being extracted, and zero being returned. 659 /// 660 /// @param[in,out] offset_ptr 661 /// A pointer to an offset within the data that will be advanced 662 /// by the appropriate number of bytes if the value is extracted 663 /// correctly. If the offset is out of bounds or there are not 664 /// enough bytes to extract this value, the offset will be left 665 /// unmodified. 666 /// 667 /// @param[in] byte_size 668 /// The size in byte of the integer to extract. 669 /// 670 /// @param[in] bitfield_bit_size 671 /// The size in bits of the bitfield value to extract, or zero 672 /// to just extract the entire integer value. 673 /// 674 /// @param[in] bitfield_bit_offset 675 /// The bit offset of the bitfield value in the extracted 676 /// integer (the number of bits to shift the integer to the 677 /// right). 678 /// 679 /// @return 680 /// The unsigned bitfield integer value that was extracted, or 681 /// zero on failure. 682 //------------------------------------------------------------------ 683 uint64_t 684 GetMaxU64Bitfield (uint32_t *offset_ptr, uint32_t size, uint32_t bitfield_bit_size, uint32_t bitfield_bit_offset) const; 685 686 //------------------------------------------------------------------ 687 /// Extract an signed integer of size \a byte_size from \a 688 /// *offset_ptr, then extract and signe extend the bitfield from 689 /// this value if \a bitfield_bit_size is non-zero. 690 /// 691 /// Extract a single signed integer value (sign extending if required) 692 /// and update the offset pointed to by \a offset_ptr. The size of 693 /// the extracted integer is specified by the \a byte_size argument. 694 /// \a byte_size should have a value greater than or equal to one 695 /// and less than or equal to eight since the return value is 64 696 /// bits wide. Any \a byte_size values less than 1 or greater than 697 /// 8 will result in nothing being extracted, and zero being returned. 698 /// 699 /// @param[in,out] offset_ptr 700 /// A pointer to an offset within the data that will be advanced 701 /// by the appropriate number of bytes if the value is extracted 702 /// correctly. If the offset is out of bounds or there are not 703 /// enough bytes to extract this value, the offset will be left 704 /// unmodified. 705 /// 706 /// @param[in] byte_size 707 /// The size in bytes of the integer to extract. 708 /// 709 /// @param[in] bitfield_bit_size 710 /// The size in bits of the bitfield value to extract, or zero 711 /// to just extract the entire integer value. 712 /// 713 /// @param[in] bitfield_bit_offset 714 /// The bit offset of the bitfield value in the extracted 715 /// integer (the number of bits to shift the integer to the 716 /// right). 717 /// 718 /// @return 719 /// The signed bitfield integer value that was extracted, or 720 /// zero on failure. 721 //------------------------------------------------------------------ 722 int64_t 723 GetMaxS64Bitfield (uint32_t *offset_ptr, uint32_t size, uint32_t bitfield_bit_size, uint32_t bitfield_bit_offset) const; 724 725 //------------------------------------------------------------------ 726 /// Extract an pointer from \a *offset_ptr. 727 /// 728 /// Extract a single pointer from the data and update the offset 729 /// pointed to by \a offset_ptr. The size of the extracted pointer 730 /// comes from the \a m_addr_size member variable and should be 731 /// set correctly prior to extracting any pointer values. 732 /// 733 /// @param[in,out] offset_ptr 734 /// A pointer to an offset within the data that will be advanced 735 /// by the appropriate number of bytes if the value is extracted 736 /// correctly. If the offset is out of bounds or there are not 737 /// enough bytes to extract this value, the offset will be left 738 /// unmodified. 739 /// 740 /// @return 741 /// The extracted pointer value as a 64 integer. 742 //------------------------------------------------------------------ 743 uint64_t 744 GetPointer (uint32_t *offset_ptr) const; 745 746 //------------------------------------------------------------------ 747 /// Get the current byte order value. 748 /// 749 /// @return 750 /// The current byte order value from this object's internal 751 /// state. 752 //------------------------------------------------------------------ 753 lldb::ByteOrder 754 GetByteOrder() const; 755 756 //------------------------------------------------------------------ 757 /// Extract a uint8_t value from \a *offset_ptr. 758 /// 759 /// Extract a single uint8_t from the binary data at the offset 760 /// pointed to by \a offset_ptr, and advance the offset on success. 761 /// 762 /// @param[in,out] offset_ptr 763 /// A pointer to an offset within the data that will be advanced 764 /// by the appropriate number of bytes if the value is extracted 765 /// correctly. If the offset is out of bounds or there are not 766 /// enough bytes to extract this value, the offset will be left 767 /// unmodified. 768 /// 769 /// @return 770 /// The extracted uint8_t value. 771 //------------------------------------------------------------------ 772 uint8_t 773 GetU8 ( uint32_t *offset_ptr) const; 774 775 uint8_t 776 GetU8_unchecked (uint32_t *offset_ptr) const 777 { 778 uint8_t val = m_start[*offset_ptr]; 779 *offset_ptr += 1; 780 return val; 781 } 782 783 uint16_t 784 GetU16_unchecked (uint32_t *offset_ptr) const; 785 786 uint32_t 787 GetU32_unchecked (uint32_t *offset_ptr) const; 788 789 uint64_t 790 GetU64_unchecked (uint32_t *offset_ptr) const; 791 //------------------------------------------------------------------ 792 /// Extract \a count uint8_t values from \a *offset_ptr. 793 /// 794 /// Extract \a count uint8_t values from the binary data at the 795 /// offset pointed to by \a offset_ptr, and advance the offset on 796 /// success. The extracted values are copied into \a dst. 797 /// 798 /// @param[in,out] offset_ptr 799 /// A pointer to an offset within the data that will be advanced 800 /// by the appropriate number of bytes if the value is extracted 801 /// correctly. If the offset is out of bounds or there are not 802 /// enough bytes to extract this value, the offset will be left 803 /// unmodified. 804 /// 805 /// @param[out] dst 806 /// A buffer to copy \a count uint8_t values into. \a dst must 807 /// be large enough to hold all requested data. 808 /// 809 /// @param[in] count 810 /// The number of uint8_t values to extract. 811 /// 812 /// @return 813 /// \a dst if all values were properly extracted and copied, 814 /// NULL otherise. 815 //------------------------------------------------------------------ 816 void * 817 GetU8 ( uint32_t *offset_ptr, void *dst, uint32_t count) const; 818 819 //------------------------------------------------------------------ 820 /// Extract a uint16_t value from \a *offset_ptr. 821 /// 822 /// Extract a single uint16_t from the binary data at the offset 823 /// pointed to by \a offset_ptr, and update 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 uint16_t value. 834 //------------------------------------------------------------------ 835 uint16_t 836 GetU16 (uint32_t *offset_ptr) const; 837 838 //------------------------------------------------------------------ 839 /// Extract \a count uint16_t values from \a *offset_ptr. 840 /// 841 /// Extract \a count uint16_t values from the binary data at the 842 /// offset pointed to by \a offset_ptr, and advance the offset on 843 /// success. The extracted values are copied into \a dst. 844 /// 845 /// @param[in,out] offset_ptr 846 /// A pointer to an offset within the data that will be advanced 847 /// by the appropriate number of bytes if the value is extracted 848 /// correctly. If the offset is out of bounds or there are not 849 /// enough bytes to extract this value, the offset will be left 850 /// unmodified. 851 /// 852 /// @param[out] dst 853 /// A buffer to copy \a count uint16_t values into. \a dst must 854 /// be large enough to hold all requested data. 855 /// 856 /// @param[in] count 857 /// The number of uint16_t values to extract. 858 /// 859 /// @return 860 /// \a dst if all values were properly extracted and copied, 861 /// NULL otherise. 862 //------------------------------------------------------------------ 863 void * 864 GetU16 (uint32_t *offset_ptr, void *dst, uint32_t count) const; 865 866 //------------------------------------------------------------------ 867 /// Extract a uint32_t value from \a *offset_ptr. 868 /// 869 /// Extract a single uint32_t from the binary data at the offset 870 /// pointed to by \a offset_ptr, and update the offset on success. 871 /// 872 /// @param[in,out] offset_ptr 873 /// A pointer to an offset within the data that will be advanced 874 /// by the appropriate number of bytes if the value is extracted 875 /// correctly. If the offset is out of bounds or there are not 876 /// enough bytes to extract this value, the offset will be left 877 /// unmodified. 878 /// 879 /// @return 880 /// The extracted uint32_t value. 881 //------------------------------------------------------------------ 882 uint32_t 883 GetU32 (uint32_t *offset_ptr) const; 884 885 //------------------------------------------------------------------ 886 /// Extract \a count uint32_t values from \a *offset_ptr. 887 /// 888 /// Extract \a count uint32_t values from the binary data at the 889 /// offset pointed to by \a offset_ptr, and advance the offset on 890 /// success. The extracted values are copied into \a dst. 891 /// 892 /// @param[in,out] offset_ptr 893 /// A pointer to an offset within the data that will be advanced 894 /// by the appropriate number of bytes if the value is extracted 895 /// correctly. If the offset is out of bounds or there are not 896 /// enough bytes to extract this value, the offset will be left 897 /// unmodified. 898 /// 899 /// @param[out] dst 900 /// A buffer to copy \a count uint32_t values into. \a dst must 901 /// be large enough to hold all requested data. 902 /// 903 /// @param[in] count 904 /// The number of uint32_t values to extract. 905 /// 906 /// @return 907 /// \a dst if all values were properly extracted and copied, 908 /// NULL otherise. 909 //------------------------------------------------------------------ 910 void * 911 GetU32 (uint32_t *offset_ptr, void *dst, uint32_t count) const; 912 913 //------------------------------------------------------------------ 914 /// Extract a uint64_t value from \a *offset_ptr. 915 /// 916 /// Extract a single uint64_t from the binary data at the offset 917 /// pointed to by \a offset_ptr, and update the offset on success. 918 /// 919 /// @param[in,out] offset_ptr 920 /// A pointer to an offset within the data that will be advanced 921 /// by the appropriate number of bytes if the value is extracted 922 /// correctly. If the offset is out of bounds or there are not 923 /// enough bytes to extract this value, the offset will be left 924 /// unmodified. 925 /// 926 /// @return 927 /// The extracted uint64_t value. 928 //------------------------------------------------------------------ 929 uint64_t 930 GetU64 (uint32_t *offset_ptr) const; 931 932 //------------------------------------------------------------------ 933 /// Extract \a count uint64_t values from \a *offset_ptr. 934 /// 935 /// Extract \a count uint64_t values from the binary data at the 936 /// offset pointed to by \a offset_ptr, and advance the offset on 937 /// success. The extracted values are copied into \a dst. 938 /// 939 /// @param[in,out] offset_ptr 940 /// A pointer to an offset within the data that will be advanced 941 /// by the appropriate number of bytes if the value is extracted 942 /// correctly. If the offset is out of bounds or there are not 943 /// enough bytes to extract this value, the offset will be left 944 /// unmodified. 945 /// 946 /// @param[out] dst 947 /// A buffer to copy \a count uint64_t values into. \a dst must 948 /// be large enough to hold all requested data. 949 /// 950 /// @param[in] count 951 /// The number of uint64_t values to extract. 952 /// 953 /// @return 954 /// \a dst if all values were properly extracted and copied, 955 /// NULL otherise. 956 //------------------------------------------------------------------ 957 void * 958 GetU64 ( uint32_t *offset_ptr, void *dst, uint32_t count) const; 959 960 //------------------------------------------------------------------ 961 /// Extract a signed LEB128 value from \a *offset_ptr. 962 /// 963 /// Extracts an signed LEB128 number from this object's data 964 /// starting at the offset pointed to by \a offset_ptr. The offset 965 /// pointed to by \a offset_ptr will be updated with the offset of 966 /// the byte following the last extracted byte. 967 /// 968 /// @param[in,out] offset_ptr 969 /// A pointer to an offset within the data that will be advanced 970 /// by the appropriate number of bytes if the value is extracted 971 /// correctly. If the offset is out of bounds or there are not 972 /// enough bytes to extract this value, the offset will be left 973 /// unmodified. 974 /// 975 /// @return 976 /// The extracted signed integer value. 977 //------------------------------------------------------------------ 978 int64_t 979 GetSLEB128 (uint32_t *offset_ptr) const; 980 981 //------------------------------------------------------------------ 982 /// Extract a unsigned LEB128 value from \a *offset_ptr. 983 /// 984 /// Extracts an unsigned LEB128 number from this object's data 985 /// starting at the offset pointed to by \a offset_ptr. The offset 986 /// pointed to by \a offset_ptr will be updated with the offset of 987 /// the byte following the last extracted byte. 988 /// 989 /// @param[in,out] offset_ptr 990 /// A pointer to an offset within the data that will be advanced 991 /// by the appropriate number of bytes if the value is extracted 992 /// correctly. If the offset is out of bounds or there are not 993 /// enough bytes to extract this value, the offset will be left 994 /// unmodified. 995 /// 996 /// @return 997 /// The extracted unsigned integer value. 998 //------------------------------------------------------------------ 999 uint64_t 1000 GetULEB128 (uint32_t *offset_ptr) const; 1001 1002 lldb::DataBufferSP & 1003 GetSharedDataBuffer () 1004 { 1005 return m_data_sp; 1006 } 1007 1008 //------------------------------------------------------------------ 1009 /// Peek at a C string at \a offset. 1010 /// 1011 /// Peeks at a string in the contained data. No verification is done 1012 /// to make sure the entire string lies within the bounds of this 1013 /// object's data, only \a offset is verified to be a valid offset. 1014 /// 1015 /// @param[in] offset 1016 /// An offset into the data. 1017 /// 1018 /// @return 1019 /// A non-NULL C string pointer if \a offset is a valid offset, 1020 /// NULL otherwise. 1021 //------------------------------------------------------------------ 1022 const char * 1023 PeekCStr (uint32_t offset) const; 1024 1025 //------------------------------------------------------------------ 1026 /// Peek at a bytes at \a offset. 1027 /// 1028 /// Returns a pointer to \a length bytes at \a offset as long as 1029 /// there are \a length bytes available starting at \a offset. 1030 /// 1031 /// @return 1032 /// A non-NULL data pointer if \a offset is a valid offset and 1033 /// there are \a length bytes available at that offset, NULL 1034 /// otherwise. 1035 //------------------------------------------------------------------ 1036 const uint8_t* 1037 PeekData (uint32_t offset, uint32_t length) const; 1038 1039 //------------------------------------------------------------------ 1040 /// Set the address byte size. 1041 /// 1042 /// Set the size in bytes that will be used when extracting any 1043 /// address and pointer values from data contained in this object. 1044 /// 1045 /// @param[in] addr_size 1046 /// The size in bytes to use when extracting addresses. 1047 //------------------------------------------------------------------ 1048 void 1049 SetAddressByteSize (uint8_t addr_size); 1050 1051 //------------------------------------------------------------------ 1052 /// Set data with a buffer that is caller owned. 1053 /// 1054 /// Use data that is owned by the caller when extracting values. 1055 /// The data must stay around as long as this object, or any object 1056 /// that copies a subset of this object's data, is valid. If \a 1057 /// bytes is NULL, or \a length is zero, this object will contain 1058 /// no data. 1059 /// 1060 /// @param[in] bytes 1061 /// A pointer to caller owned data. 1062 /// 1063 /// @param[in] length 1064 /// The length in bytes of \a bytes. 1065 /// 1066 /// @param[in] byte_order 1067 /// A byte order of the data that we are extracting from. 1068 /// 1069 /// @return 1070 /// The number of bytes that this object now contains. 1071 //------------------------------------------------------------------ 1072 uint32_t 1073 SetData (const void *bytes, uint32_t length, lldb::ByteOrder byte_order); 1074 1075 //------------------------------------------------------------------ 1076 /// Adopt a subset of \a data. 1077 /// 1078 /// Set this object's data to be a subset of the data bytes in \a 1079 /// data. If \a data contains shared data, then a reference to the 1080 /// shared data will be added to ensure the shared data stays around 1081 /// as long as any objects have references to the shared data. The 1082 /// byte order and the address size settings are copied from \a 1083 /// data. If \a offset is not a valid offset in \a data, then no 1084 /// reference to the shared data will be added. If there are not 1085 /// \a length bytes available in \a data starting at \a offset, 1086 /// the length will be truncated to contains as many bytes as 1087 /// possible. 1088 /// 1089 /// @param[in] data 1090 /// Another DataExtractor object that contains data. 1091 /// 1092 /// @param[in] offset 1093 /// The offset into \a data at which the subset starts. 1094 /// 1095 /// @param[in] length 1096 /// The length in bytes of the subset of \a data. 1097 /// 1098 /// @return 1099 /// The number of bytes that this object now contains. 1100 //------------------------------------------------------------------ 1101 uint32_t 1102 SetData (const DataExtractor& data, uint32_t offset, uint32_t length); 1103 1104 //------------------------------------------------------------------ 1105 /// Adopt a subset of shared data in \a data_sp. 1106 /// 1107 /// Copies the data shared pointer which adds a reference to the 1108 /// contained in \a data_sp. The shared data reference is reference 1109 /// counted to ensure the data lives as long as anyone still has a 1110 /// valid shared pointer to the data in \a data_sp. The byte order 1111 /// and address byte size settings remain the same. If 1112 /// \a offset is not a valid offset in \a data_sp, then no reference 1113 /// to the shared data will be added. If there are not \a length 1114 /// bytes available in \a data starting at \a offset, the length 1115 /// will be truncated to contains as many bytes as possible. 1116 /// 1117 /// @param[in] data_sp 1118 /// A shared pointer to data. 1119 /// 1120 /// @param[in] offset 1121 /// The offset into \a data_sp at which the subset starts. 1122 /// 1123 /// @param[in] length 1124 /// The length in bytes of the subset of \a data_sp. 1125 /// 1126 /// @return 1127 /// The number of bytes that this object now contains. 1128 //------------------------------------------------------------------ 1129 uint32_t 1130 SetData (const lldb::DataBufferSP& data_sp, uint32_t offset = 0, uint32_t length = UINT32_MAX); 1131 1132 //------------------------------------------------------------------ 1133 /// Set the byte_order value. 1134 /// 1135 /// Sets the byte order of the data to extract. Extracted values 1136 /// will be swapped if necessary when decoding. 1137 /// 1138 /// @param[in] byte_order 1139 /// The byte order value to use when extracting data. 1140 //------------------------------------------------------------------ 1141 void 1142 SetByteOrder (lldb::ByteOrder byte_order); 1143 1144 //------------------------------------------------------------------ 1145 /// Skip an LEB128 number at \a *offset_ptr. 1146 /// 1147 /// Skips a LEB128 number (signed or unsigned) from this object's 1148 /// data starting at the offset pointed to by \a offset_ptr. The 1149 /// offset pointed to by \a offset_ptr will be updated with the 1150 /// offset of the byte following the last extracted byte. 1151 /// 1152 /// @param[in,out] offset_ptr 1153 /// A pointer to an offset within the data that will be advanced 1154 /// by the appropriate number of bytes if the value is extracted 1155 /// correctly. If the offset is out of bounds or there are not 1156 /// enough bytes to extract this value, the offset will be left 1157 /// unmodified. 1158 /// 1159 /// @return 1160 // The number of bytes consumed during the extraction. 1161 //------------------------------------------------------------------ 1162 uint32_t 1163 Skip_LEB128 (uint32_t *offset_ptr) const; 1164 1165 //------------------------------------------------------------------ 1166 /// Test the validity of \a offset. 1167 /// 1168 /// @return 1169 /// \b true if \a offset is a valid offset into the data in this 1170 /// object, \b false otherwise. 1171 //------------------------------------------------------------------ 1172 bool 1173 ValidOffset (uint32_t offset) const; 1174 1175 //------------------------------------------------------------------ 1176 /// Test the availability of \a length bytes of data from \a offset. 1177 /// 1178 /// @return 1179 /// \b true if \a offset is a valid offset and there are \a 1180 /// length bytes available at that offset, \b false otherwise. 1181 //------------------------------------------------------------------ 1182 bool 1183 ValidOffsetForDataOfSize (uint32_t offset, uint32_t length) const; 1184 1185protected: 1186 //------------------------------------------------------------------ 1187 // Member variables 1188 //------------------------------------------------------------------ 1189 const uint8_t * m_start; ///< A pointer to the first byte of data. 1190 const uint8_t * m_end; ///< A pointer to the byte that is past the end of the data. 1191 lldb::ByteOrder m_byte_order; ///< The byte order of the data we are extracting from. 1192 uint8_t m_addr_size; ///< The address size to use when extracting pointers or addresses 1193 mutable lldb::DataBufferSP m_data_sp; ///< The shared pointer to data that can be shared among multilple instances 1194}; 1195 1196} // namespace lldb_private 1197 1198#endif // #if defined (__cplusplus) 1199#endif // #ifndef liblldb_DataExtractor_h_ 1200