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