1 //===-- DataExtractor.h -----------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef LLDB_UTILITY_DATAEXTRACTOR_H
10 #define LLDB_UTILITY_DATAEXTRACTOR_H
12 #include "lldb/lldb-defines.h"
13 #include "lldb/lldb-enumerations.h"
14 #include "lldb/lldb-forward.h"
15 #include "lldb/lldb-types.h"
16 #include "llvm/ADT/ArrayRef.h"
17 #include "llvm/Support/DataExtractor.h"
23 namespace lldb_private {
28 template <typename T> class SmallVectorImpl;
32 namespace lldb_private {
34 /// \class DataExtractor DataExtractor.h "lldb/Core/DataExtractor.h" An data
37 /// DataExtractor is a class that can extract data (swapping if needed) from a
38 /// data buffer. The data buffer can be caller owned, or can be shared data
39 /// that can be shared between multiple DataExtractor instances. Multiple
40 /// DataExtractor objects can share the same data, yet extract values in
41 /// different address sizes and byte order modes. Each object can have a
42 /// unique position in the shared data and extract data from different
48 /// \typedef DataExtractor::Type
49 /// Type enumerations used in the dump routines.
51 TypeUInt8, ///< Format output as unsigned 8 bit integers
52 TypeChar, ///< Format output as characters
53 TypeUInt16, ///< Format output as unsigned 16 bit integers
54 TypeUInt32, ///< Format output as unsigned 32 bit integers
55 TypeUInt64, ///< Format output as unsigned 64 bit integers
56 TypePointer, ///< Format output as pointers
57 TypeULEB128, ///< Format output as ULEB128 numbers
58 TypeSLEB128 ///< Format output as SLEB128 numbers
61 /// Default constructor.
63 /// Initialize all members to a default empty state.
66 /// Construct with a buffer that is owned by the caller.
68 /// This constructor allows us to use data that is owned by the caller. The
69 /// data must stay around as long as this object is valid.
72 /// A pointer to caller owned data.
74 /// \param[in] data_length
75 /// The length in bytes of \a data.
77 /// \param[in] byte_order
78 /// A byte order of the data that we are extracting from.
80 /// \param[in] addr_size
81 /// A new address byte size value.
83 /// \param[in] target_byte_size
84 /// A size of a target byte in 8-bit host bytes
85 DataExtractor(const void *data, lldb::offset_t data_length,
86 lldb::ByteOrder byte_order, uint32_t addr_size,
87 uint32_t target_byte_size = 1);
89 /// Construct with shared data.
91 /// Copies the data shared pointer which adds a reference to the contained
92 /// in \a data_sp. The shared data reference is reference counted to ensure
93 /// the data lives as long as anyone still has a valid shared pointer to the
94 /// data in \a data_sp.
96 /// \param[in] data_sp
97 /// A shared pointer to data.
99 /// \param[in] byte_order
100 /// A byte order of the data that we are extracting from.
102 /// \param[in] addr_size
103 /// A new address byte size value.
105 /// \param[in] target_byte_size
106 /// A size of a target byte in 8-bit host bytes
107 DataExtractor(const lldb::DataBufferSP &data_sp, lldb::ByteOrder byte_order,
108 uint32_t addr_size, uint32_t target_byte_size = 1);
110 /// Construct with a subset of \a data.
112 /// Initialize this object with a subset of the data bytes in \a data. If \a
113 /// data contains shared data, then a reference to the shared data will be
114 /// added to ensure the shared data stays around as long as any objects have
115 /// references to the shared data. The byte order value and the address size
116 /// settings are copied from \a data. If \a offset is not a valid offset in
117 /// \a data, then no reference to the shared data will be added. If there
118 /// are not \a length bytes available in \a data starting at \a offset, the
119 /// length will be truncated to contain as many bytes as possible.
122 /// Another DataExtractor object that contains data.
124 /// \param[in] offset
125 /// The offset into \a data at which the subset starts.
127 /// \param[in] length
128 /// The length in bytes of the subset of data.
130 /// \param[in] target_byte_size
131 /// A size of a target byte in 8-bit host bytes
132 DataExtractor(const DataExtractor &data, lldb::offset_t offset,
133 lldb::offset_t length, uint32_t target_byte_size = 1);
135 DataExtractor(const DataExtractor &rhs);
137 /// Assignment operator.
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 shared
141 /// data will be added.
144 /// Another DataExtractor object to copy.
147 /// A const reference to this object.
148 const DataExtractor &operator=(const DataExtractor &rhs);
152 /// If this object contains a valid shared data reference, the reference
153 /// count on the data will be decremented, and if zero, the data will be
155 virtual ~DataExtractor();
157 uint32_t getTargetByteSize() const { return m_target_byte_size; }
159 /// Clears the object state.
161 /// Clears the object contents back to a default invalid state, and release
162 /// any references to shared data that this object may contain.
165 /// Dumps the binary data as \a type objects to stream \a s (or to Log() if
166 /// \a s is nullptr) starting \a offset bytes into the data and stopping
167 /// after dumping \a length bytes. The offset into the data is displayed at
168 /// the beginning of each line and can be offset by base address \a
169 /// base_addr. \a num_per_line objects will be displayed on each line.
172 /// The log to dump the output to.
174 /// \param[in] offset
175 /// The offset into the data at which to start dumping.
177 /// \param[in] length
178 /// The number of bytes to dump.
180 /// \param[in] base_addr
181 /// The base address that gets added to the offset displayed on
184 /// \param[in] num_per_line
185 /// The number of \a type objects to display on each line.
188 /// The type of objects to use when dumping data from this
189 /// object. See DataExtractor::Type.
192 /// The offset at which dumping ended.
193 lldb::offset_t PutToLog(Log *log, lldb::offset_t offset,
194 lldb::offset_t length, uint64_t base_addr,
195 uint32_t num_per_line, Type type) const;
197 /// Extract an arbitrary number of bytes in the specified byte order.
199 /// Attemps to extract \a length bytes starting at \a offset bytes into this
200 /// data in the requested byte order (\a dst_byte_order) and place the
201 /// results in \a dst. \a dst must be at least \a length bytes long.
203 /// \param[in] offset
204 /// The offset in bytes into the contained data at which to
205 /// start extracting.
207 /// \param[in] length
208 /// The number of bytes to extract.
210 /// \param[in] dst_byte_order
211 /// A byte order of the data that we want when the value in
212 /// copied to \a dst.
215 /// The buffer that will receive the extracted value if there
216 /// are enough bytes available in the current data.
219 /// The number of bytes that were extracted which will be \a
220 /// length when the value is successfully extracted, or zero
221 /// if there aren't enough bytes at the specified offset.
222 size_t ExtractBytes(lldb::offset_t offset, lldb::offset_t length,
223 lldb::ByteOrder dst_byte_order, void *dst) const;
225 /// Extract an address from \a *offset_ptr.
227 /// Extract a single address from the data and update the offset pointed to
228 /// by \a offset_ptr. The size of the extracted address comes from the \a
229 /// m_addr_size member variable and should be set correctly prior to
230 /// extracting any address values.
232 /// \param[in,out] offset_ptr
233 /// A pointer to an offset within the data that will be advanced
234 /// by the appropriate number of bytes if the value is extracted
235 /// correctly. If the offset is out of bounds or there are not
236 /// enough bytes to extract this value, the offset will be left
240 /// The extracted address value.
241 uint64_t GetAddress(lldb::offset_t *offset_ptr) const;
243 uint64_t GetAddress_unchecked(lldb::offset_t *offset_ptr) const;
245 /// Get the current address size.
247 /// Return the size in bytes of any address values this object will extract.
250 /// The size in bytes of address values that will be extracted.
251 uint32_t GetAddressByteSize() const { return m_addr_size; }
253 /// Get the number of bytes contained in this object.
256 /// The total number of bytes of data this object refers to.
257 uint64_t GetByteSize() const { return m_end - m_start; }
259 /// Extract a C string from \a *offset_ptr.
261 /// Returns a pointer to a C String from the data at the offset pointed to
262 /// by \a offset_ptr. A variable length NULL terminated C string will be
263 /// extracted and the \a offset_ptr will be updated with the offset of the
264 /// byte that follows the NULL terminator byte.
266 /// \param[in,out] offset_ptr
267 /// A pointer to an offset within the data that will be advanced
268 /// by the appropriate number of bytes if the value is extracted
269 /// correctly. If the offset is out of bounds or there are not
270 /// enough bytes to extract this value, the offset will be left
274 /// A pointer to the C string value in the data. If the offset
275 /// pointed to by \a offset_ptr is out of bounds, or if the
276 /// offset plus the length of the C string is out of bounds,
277 /// nullptr will be returned.
278 const char *GetCStr(lldb::offset_t *offset_ptr) const;
280 /// Extract a C string from \a *offset_ptr with field size \a len.
282 /// Returns a pointer to a C String from the data at the offset pointed to
283 /// by \a offset_ptr, with a field length of \a len.
284 /// A NULL terminated C string will be extracted and the \a offset_ptr
285 /// will be updated with the offset of the byte that follows the fixed
288 /// \param[in,out] offset_ptr
289 /// A pointer to an offset within the data that will be advanced
290 /// by the appropriate number of bytes if the value is extracted
291 /// correctly. If the offset is out of bounds or there are not
292 /// enough bytes to extract this value, the offset will be left
296 /// A pointer to the C string value in the data. If the offset
297 /// pointed to by \a offset_ptr is out of bounds, or if the
298 /// offset plus the length of the field is out of bounds, or if
299 /// the field does not contain a NULL terminator byte, nullptr will
301 const char *GetCStr(lldb::offset_t *offset_ptr, lldb::offset_t len) const;
303 /// Extract \a length bytes from \a *offset_ptr.
305 /// Returns a pointer to a bytes in this object's data at the offset pointed
306 /// to by \a offset_ptr. If \a length is zero or too large, then the offset
307 /// pointed to by \a offset_ptr will not be updated and nullptr will be
310 /// \param[in,out] offset_ptr
311 /// A pointer to an offset within the data that will be advanced
312 /// by the appropriate number of bytes if the value is extracted
313 /// correctly. If the offset is out of bounds or there are not
314 /// enough bytes to extract this value, the offset will be left
317 /// \param[in] length
318 /// The optional length of a string to extract. If the value is
319 /// zero, a NULL terminated C string will be extracted.
322 /// A pointer to the bytes in this object's data if the offset
323 /// and length are valid, or nullptr otherwise.
324 const void *GetData(lldb::offset_t *offset_ptr, lldb::offset_t length) const {
325 const uint8_t *ptr = PeekData(*offset_ptr, length);
327 *offset_ptr += length;
331 /// Copy \a length bytes from \a *offset, without swapping bytes.
333 /// \param[in] offset
334 /// The offset into this data from which to start copying
336 /// \param[in] length
337 /// The length of the data to copy from this object
340 /// The buffer to place the output data.
343 /// Returns the number of bytes that were copied, or zero if
344 /// anything goes wrong.
345 lldb::offset_t CopyData(lldb::offset_t offset, lldb::offset_t length,
348 /// Copy \a dst_len bytes from \a *offset_ptr and ensure the copied data is
349 /// treated as a value that can be swapped to match the specified byte
352 /// For values that are larger than the supported integer sizes, this
353 /// function can be used to extract data in a specified byte order. It can
354 /// also be used to copy a smaller integer value from to a larger value. The
355 /// extra bytes left over will be padded correctly according to the byte
356 /// order of this object and the \a dst_byte_order. This can be very handy
357 /// when say copying a partial data value into a register.
359 /// \param[in] src_offset
360 /// The offset into this data from which to start copying an endian
363 /// \param[in] src_len
364 /// The length of the endian data to copy from this object into the \a
368 /// The buffer where to place the endian data. The data might need to be
369 /// byte swapped (and appropriately padded with zeroes if \a src_len !=
370 /// \a dst_len) if \a dst_byte_order does not match the byte order in
373 /// \param[in] dst_len
374 /// The length number of bytes that the endian value will occupy is \a
377 /// \param[in] dst_byte_order
378 /// The byte order that the endian value should be in the \a dst buffer.
381 /// Returns the number of bytes that were copied, or zero if anything
383 lldb::offset_t CopyByteOrderedData(lldb::offset_t src_offset,
384 lldb::offset_t src_len, void *dst,
385 lldb::offset_t dst_len,
386 lldb::ByteOrder dst_byte_order) const;
388 /// Get the data end pointer.
391 /// Returns a pointer to the next byte contained in this
392 /// object's data, or nullptr of there is no data in this object.
393 const uint8_t *GetDataEnd() const { return m_end; }
395 /// Get the shared data offset.
397 /// Get the offset of the first byte of data in the shared data (if any).
400 /// If this object contains shared data, this function returns
401 /// the offset in bytes into that shared data, zero otherwise.
402 size_t GetSharedDataOffset() const;
404 /// Get the data start pointer.
407 /// Returns a pointer to the first byte contained in this
408 /// object's data, or nullptr of there is no data in this object.
409 const uint8_t *GetDataStart() const { return m_start; }
411 /// Extract a float from \a *offset_ptr.
413 /// Extract a single float value.
415 /// \param[in,out] offset_ptr
416 /// A pointer to an offset within the data that will be advanced
417 /// by the appropriate number of bytes if the value is extracted
418 /// correctly. If the offset is out of bounds or there are not
419 /// enough bytes to extract this value, the offset will be left
423 /// The floating value that was extracted, or zero on failure.
424 float GetFloat(lldb::offset_t *offset_ptr) const;
426 double GetDouble(lldb::offset_t *offset_ptr) const;
428 long double GetLongDouble(lldb::offset_t *offset_ptr) const;
430 /// Extract an integer of size \a byte_size from \a *offset_ptr.
432 /// Extract a single integer value and update the offset pointed to by \a
433 /// offset_ptr. The size of the extracted integer is specified by the \a
434 /// byte_size argument. \a byte_size must have a value >= 1 and <= 4 since
435 /// the return value is only 32 bits wide.
437 /// \param[in,out] offset_ptr
438 /// A pointer to an offset within the data that will be advanced
439 /// by the appropriate number of bytes if the value is extracted
440 /// correctly. If the offset is out of bounds or there are not
441 /// enough bytes to extract this value, the offset will be left
444 /// \param[in] byte_size
445 /// The size in byte of the integer to extract.
448 /// The integer value that was extracted, or zero on failure.
449 uint32_t GetMaxU32(lldb::offset_t *offset_ptr, size_t byte_size) const;
451 /// Extract an unsigned integer of size \a byte_size from \a *offset_ptr.
453 /// Extract a single unsigned integer value and update the offset pointed to
454 /// by \a offset_ptr. The size of the extracted integer is specified by the
455 /// \a byte_size argument. \a byte_size must have a value greater than or
456 /// equal to one and less than or equal to eight since the return value is
459 /// \param[in,out] offset_ptr
460 /// A pointer to an offset within the data that will be advanced
461 /// by the appropriate number of bytes if the value is extracted
462 /// correctly. If the offset is out of bounds or there are not
463 /// enough bytes to extract this value, the offset will be left
466 /// \param[in] byte_size
467 /// The size in byte of the integer to extract.
470 /// The unsigned integer value that was extracted, or zero on
472 uint64_t GetMaxU64(lldb::offset_t *offset_ptr, size_t byte_size) const;
474 uint64_t GetMaxU64_unchecked(lldb::offset_t *offset_ptr,
475 size_t byte_size) const;
477 /// Extract an signed integer of size \a byte_size from \a *offset_ptr.
479 /// Extract a single signed integer value (sign extending if required) and
480 /// update the offset pointed to by \a offset_ptr. The size of the extracted
481 /// integer is specified by the \a byte_size argument. \a byte_size must
482 /// have a value greater than or equal to one and less than or equal to
483 /// eight since the return value is 64 bits wide.
485 /// \param[in,out] offset_ptr
486 /// A pointer to an offset within the data that will be advanced
487 /// by the appropriate number of bytes if the value is extracted
488 /// correctly. If the offset is out of bounds or there are not
489 /// enough bytes to extract this value, the offset will be left
492 /// \param[in] byte_size
493 /// The size in byte of the integer to extract.
496 /// The sign extended signed integer value that was extracted,
497 /// or zero on failure.
498 int64_t GetMaxS64(lldb::offset_t *offset_ptr, size_t byte_size) const;
500 /// Extract an unsigned integer of size \a byte_size from \a *offset_ptr,
501 /// then extract the bitfield from this value if \a bitfield_bit_size is
504 /// Extract a single unsigned integer value and update the offset pointed to
505 /// by \a offset_ptr. The size of the extracted integer is specified by the
506 /// \a byte_size argument. \a byte_size must have a value greater than or
507 /// equal to one and less than or equal to 8 since the return value is 64
510 /// \param[in,out] offset_ptr
511 /// A pointer to an offset within the data that will be advanced
512 /// by the appropriate number of bytes if the value is extracted
513 /// correctly. If the offset is out of bounds or there are not
514 /// enough bytes to extract this value, the offset will be left
518 /// The size in byte of the integer to extract.
520 /// \param[in] bitfield_bit_size
521 /// The size in bits of the bitfield value to extract, or zero
522 /// to just extract the entire integer value.
524 /// \param[in] bitfield_bit_offset
525 /// The bit offset of the bitfield value in the extracted
526 /// integer. For little-endian data, this is the offset of
527 /// the LSB of the bitfield from the LSB of the integer.
528 /// For big-endian data, this is the offset of the MSB of the
529 /// bitfield from the MSB of the integer.
532 /// The unsigned bitfield integer value that was extracted, or
534 uint64_t GetMaxU64Bitfield(lldb::offset_t *offset_ptr, size_t size,
535 uint32_t bitfield_bit_size,
536 uint32_t bitfield_bit_offset) const;
538 /// Extract an signed integer of size \a byte_size from \a *offset_ptr, then
539 /// extract and signe extend the bitfield from this value if \a
540 /// bitfield_bit_size is non-zero.
542 /// Extract a single signed integer value (sign extending if required) and
543 /// update the offset pointed to by \a offset_ptr. The size of the extracted
544 /// integer is specified by the \a byte_size argument. \a byte_size must
545 /// have a value greater than or equal to one and less than or equal to
546 /// eight since the return value is 64 bits wide.
548 /// \param[in,out] offset_ptr
549 /// A pointer to an offset within the data that will be advanced
550 /// by the appropriate number of bytes if the value is extracted
551 /// correctly. If the offset is out of bounds or there are not
552 /// enough bytes to extract this value, the offset will be left
556 /// The size in bytes of the integer to extract.
558 /// \param[in] bitfield_bit_size
559 /// The size in bits of the bitfield value to extract, or zero
560 /// to just extract the entire integer value.
562 /// \param[in] bitfield_bit_offset
563 /// The bit offset of the bitfield value in the extracted
564 /// integer. For little-endian data, this is the offset of
565 /// the LSB of the bitfield from the LSB of the integer.
566 /// For big-endian data, this is the offset of the MSB of the
567 /// bitfield from the MSB of the integer.
570 /// The signed bitfield integer value that was extracted, or
572 int64_t GetMaxS64Bitfield(lldb::offset_t *offset_ptr, size_t size,
573 uint32_t bitfield_bit_size,
574 uint32_t bitfield_bit_offset) const;
576 /// Extract an pointer from \a *offset_ptr.
578 /// Extract a single pointer from the data and update the offset pointed to
579 /// by \a offset_ptr. The size of the extracted pointer comes from the \a
580 /// m_addr_size member variable and should be set correctly prior to
581 /// extracting any pointer values.
583 /// \param[in,out] offset_ptr
584 /// A pointer to an offset within the data that will be advanced
585 /// by the appropriate number of bytes if the value is extracted
586 /// correctly. If the offset is out of bounds or there are not
587 /// enough bytes to extract this value, the offset will be left
591 /// The extracted pointer value as a 64 integer.
592 uint64_t GetPointer(lldb::offset_t *offset_ptr) const;
594 /// Get the current byte order value.
597 /// The current byte order value from this object's internal
599 lldb::ByteOrder GetByteOrder() const { return m_byte_order; }
601 /// Extract a uint8_t value from \a *offset_ptr.
603 /// Extract a single uint8_t from the binary data at the offset pointed to
604 /// by \a offset_ptr, and advance the offset on success.
606 /// \param[in,out] offset_ptr
607 /// A pointer to an offset within the data that will be advanced
608 /// by the appropriate number of bytes if the value is extracted
609 /// correctly. If the offset is out of bounds or there are not
610 /// enough bytes to extract this value, the offset will be left
614 /// The extracted uint8_t value.
615 uint8_t GetU8(lldb::offset_t *offset_ptr) const;
617 uint8_t GetU8_unchecked(lldb::offset_t *offset_ptr) const {
618 uint8_t val = m_start[*offset_ptr];
623 uint16_t GetU16_unchecked(lldb::offset_t *offset_ptr) const;
625 uint32_t GetU32_unchecked(lldb::offset_t *offset_ptr) const;
627 uint64_t GetU64_unchecked(lldb::offset_t *offset_ptr) const;
628 /// Extract \a count uint8_t values from \a *offset_ptr.
630 /// Extract \a count uint8_t values from the binary data at the offset
631 /// pointed to by \a offset_ptr, and advance the offset on success. The
632 /// extracted values are copied into \a dst.
634 /// \param[in,out] offset_ptr
635 /// A pointer to an offset within the data that will be advanced
636 /// by the appropriate number of bytes if the value is extracted
637 /// correctly. If the offset is out of bounds or there are not
638 /// enough bytes to extract this value, the offset will be left
642 /// A buffer to copy \a count uint8_t values into. \a dst must
643 /// be large enough to hold all requested data.
646 /// The number of uint8_t values to extract.
649 /// \a dst if all values were properly extracted and copied,
650 /// nullptr otherwise.
651 void *GetU8(lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
653 /// Extract a uint16_t value from \a *offset_ptr.
655 /// Extract a single uint16_t from the binary data at the offset pointed to
656 /// by \a offset_ptr, and update the offset on success.
658 /// \param[in,out] offset_ptr
659 /// A pointer to an offset within the data that will be advanced
660 /// by the appropriate number of bytes if the value is extracted
661 /// correctly. If the offset is out of bounds or there are not
662 /// enough bytes to extract this value, the offset will be left
666 /// The extracted uint16_t value.
667 uint16_t GetU16(lldb::offset_t *offset_ptr) const;
669 /// Extract \a count uint16_t values from \a *offset_ptr.
671 /// Extract \a count uint16_t values from the binary data at the offset
672 /// pointed to by \a offset_ptr, and advance the offset on success. The
673 /// extracted values are copied into \a dst.
675 /// \param[in,out] offset_ptr
676 /// A pointer to an offset within the data that will be advanced
677 /// by the appropriate number of bytes if the value is extracted
678 /// correctly. If the offset is out of bounds or there are not
679 /// enough bytes to extract this value, the offset will be left
683 /// A buffer to copy \a count uint16_t values into. \a dst must
684 /// be large enough to hold all requested data.
687 /// The number of uint16_t values to extract.
690 /// \a dst if all values were properly extracted and copied,
691 /// nullptr otherwise.
692 void *GetU16(lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
694 /// Extract a uint32_t value from \a *offset_ptr.
696 /// Extract a single uint32_t from the binary data at the offset pointed to
697 /// by \a offset_ptr, and update the offset on success.
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
707 /// The extracted uint32_t value.
708 uint32_t GetU32(lldb::offset_t *offset_ptr) const;
710 /// Extract \a count uint32_t values from \a *offset_ptr.
712 /// Extract \a count uint32_t values from the binary data at the offset
713 /// pointed to by \a offset_ptr, and advance the offset on success. The
714 /// extracted values are copied into \a dst.
716 /// \param[in,out] offset_ptr
717 /// A pointer to an offset within the data that will be advanced
718 /// by the appropriate number of bytes if the value is extracted
719 /// correctly. If the offset is out of bounds or there are not
720 /// enough bytes to extract this value, the offset will be left
724 /// A buffer to copy \a count uint32_t values into. \a dst must
725 /// be large enough to hold all requested data.
728 /// The number of uint32_t values to extract.
731 /// \a dst if all values were properly extracted and copied,
732 /// nullptr otherwise.
733 void *GetU32(lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
735 /// Extract a uint64_t value from \a *offset_ptr.
737 /// Extract a single uint64_t from the binary data at the offset pointed to
738 /// by \a offset_ptr, and update the offset on success.
740 /// \param[in,out] offset_ptr
741 /// A pointer to an offset within the data that will be advanced
742 /// by the appropriate number of bytes if the value is extracted
743 /// correctly. If the offset is out of bounds or there are not
744 /// enough bytes to extract this value, the offset will be left
748 /// The extracted uint64_t value.
749 uint64_t GetU64(lldb::offset_t *offset_ptr) const;
751 /// Extract \a count uint64_t values from \a *offset_ptr.
753 /// Extract \a count uint64_t values from the binary data at the offset
754 /// pointed to by \a offset_ptr, and advance the offset on success. The
755 /// extracted values are copied into \a dst.
757 /// \param[in,out] offset_ptr
758 /// A pointer to an offset within the data that will be advanced
759 /// by the appropriate number of bytes if the value is extracted
760 /// correctly. If the offset is out of bounds or there are not
761 /// enough bytes to extract this value, the offset will be left
765 /// A buffer to copy \a count uint64_t values into. \a dst must
766 /// be large enough to hold all requested data.
769 /// The number of uint64_t values to extract.
772 /// \a dst if all values were properly extracted and copied,
773 /// nullptr otherwise.
774 void *GetU64(lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
776 /// Extract a signed LEB128 value from \a *offset_ptr.
778 /// Extracts an signed LEB128 number from this object's data starting at the
779 /// offset pointed to by \a offset_ptr. The offset pointed to by \a
780 /// offset_ptr will be updated with the offset of the byte following the
781 /// last extracted byte.
783 /// \param[in,out] offset_ptr
784 /// A pointer to an offset within the data that will be advanced
785 /// by the appropriate number of bytes if the value is extracted
786 /// correctly. If the offset is out of bounds or there are not
787 /// enough bytes to extract this value, the offset will be left
791 /// The extracted signed integer value.
792 int64_t GetSLEB128(lldb::offset_t *offset_ptr) const;
794 /// Extract a unsigned LEB128 value from \a *offset_ptr.
796 /// Extracts an unsigned LEB128 number from this object's data starting at
797 /// the offset pointed to by \a offset_ptr. The offset pointed to by \a
798 /// offset_ptr will be updated with the offset of the byte following the
799 /// last extracted byte.
801 /// \param[in,out] offset_ptr
802 /// A pointer to an offset within the data that will be advanced
803 /// by the appropriate number of bytes if the value is extracted
804 /// correctly. If the offset is out of bounds or there are not
805 /// enough bytes to extract this value, the offset will be left
809 /// The extracted unsigned integer value.
810 uint64_t GetULEB128(lldb::offset_t *offset_ptr) const;
812 lldb::DataBufferSP &GetSharedDataBuffer() { return m_data_sp; }
814 /// Peek at a C string at \a offset.
816 /// Peeks at a string in the contained data. No verification is done to make
817 /// sure the entire string lies within the bounds of this object's data,
818 /// only \a offset is verified to be a valid offset.
820 /// \param[in] offset
821 /// An offset into the data.
824 /// A non-nullptr C string pointer if \a offset is a valid offset,
825 /// nullptr otherwise.
826 const char *PeekCStr(lldb::offset_t offset) const;
828 /// Peek at a bytes at \a offset.
830 /// Returns a pointer to \a length bytes at \a offset as long as there are
831 /// \a length bytes available starting at \a offset.
834 /// A non-nullptr data pointer if \a offset is a valid offset and
835 /// there are \a length bytes available at that offset, nullptr
837 const uint8_t *PeekData(lldb::offset_t offset, lldb::offset_t length) const {
838 if (ValidOffsetForDataOfSize(offset, length))
839 return m_start + offset;
843 /// Set the address byte size.
845 /// Set the size in bytes that will be used when extracting any address and
846 /// pointer values from data contained in this object.
848 /// \param[in] addr_size
849 /// The size in bytes to use when extracting addresses.
850 void SetAddressByteSize(uint32_t addr_size) {
851 #ifdef LLDB_CONFIGURATION_DEBUG
852 assert(addr_size == 4 || addr_size == 8);
854 m_addr_size = addr_size;
857 /// Set data with a buffer that is caller owned.
859 /// Use data that is owned by the caller when extracting values. The data
860 /// must stay around as long as this object, or any object that copies a
861 /// subset of this object's data, is valid. If \a bytes is nullptr, or \a
862 /// length is zero, this object will contain no data.
865 /// A pointer to caller owned data.
867 /// \param[in] length
868 /// The length in bytes of \a bytes.
870 /// \param[in] byte_order
871 /// A byte order of the data that we are extracting from.
874 /// The number of bytes that this object now contains.
875 lldb::offset_t SetData(const void *bytes, lldb::offset_t length,
876 lldb::ByteOrder byte_order);
878 /// Adopt a subset of \a data.
880 /// Set this object's data to be a subset of the data bytes in \a data. If
881 /// \a data contains shared data, then a reference to the shared data will
882 /// be added to ensure the shared data stays around as long as any objects
883 /// have references to the shared data. The byte order and the address size
884 /// settings are copied from \a data. If \a offset is not a valid offset in
885 /// \a data, then no reference to the shared data will be added. If there
886 /// are not \a length bytes available in \a data starting at \a offset, the
887 /// length will be truncated to contains as many bytes as possible.
890 /// Another DataExtractor object that contains data.
892 /// \param[in] offset
893 /// The offset into \a data at which the subset starts.
895 /// \param[in] length
896 /// The length in bytes of the subset of \a data.
899 /// The number of bytes that this object now contains.
900 lldb::offset_t SetData(const DataExtractor &data, lldb::offset_t offset,
901 lldb::offset_t length);
903 /// Adopt a subset of shared data in \a data_sp.
905 /// Copies the data shared pointer which adds a reference to the contained
906 /// in \a data_sp. The shared data reference is reference counted to ensure
907 /// the data lives as long as anyone still has a valid shared pointer to the
908 /// data in \a data_sp. The byte order and address byte size settings remain
909 /// the same. If \a offset is not a valid offset in \a data_sp, then no
910 /// reference to the shared data will be added. If there are not \a length
911 /// bytes available in \a data starting at \a offset, the length will be
912 /// truncated to contains as many bytes as possible.
914 /// \param[in] data_sp
915 /// A shared pointer to data.
917 /// \param[in] offset
918 /// The offset into \a data_sp at which the subset starts.
920 /// \param[in] length
921 /// The length in bytes of the subset of \a data_sp.
924 /// The number of bytes that this object now contains.
925 lldb::offset_t SetData(const lldb::DataBufferSP &data_sp,
926 lldb::offset_t offset = 0,
927 lldb::offset_t length = LLDB_INVALID_OFFSET);
929 /// Set the byte_order value.
931 /// Sets the byte order of the data to extract. Extracted values will be
932 /// swapped if necessary when decoding.
934 /// \param[in] byte_order
935 /// The byte order value to use when extracting data.
936 void SetByteOrder(lldb::ByteOrder byte_order) { m_byte_order = byte_order; }
938 /// Skip an LEB128 number at \a *offset_ptr.
940 /// Skips a LEB128 number (signed or unsigned) from this object's data
941 /// starting at the offset pointed to by \a offset_ptr. The offset pointed
942 /// to by \a offset_ptr will be updated with the offset of the byte
943 /// following the last extracted byte.
945 /// \param[in,out] offset_ptr
946 /// A pointer to an offset within the data that will be advanced
947 /// by the appropriate number of bytes if the value is extracted
948 /// correctly. If the offset is out of bounds or there are not
949 /// enough bytes to extract this value, the offset will be left
953 /// The number of bytes consumed during the extraction.
954 uint32_t Skip_LEB128(lldb::offset_t *offset_ptr) const;
956 /// Test the validity of \a offset.
959 /// true if \a offset is a valid offset into the data in this object,
961 bool ValidOffset(lldb::offset_t offset) const {
962 return offset < GetByteSize();
965 /// Test the availability of \a length bytes of data from \a offset.
968 /// true if \a offset is a valid offset and there are \a
969 /// length bytes available at that offset, false otherwise.
970 bool ValidOffsetForDataOfSize(lldb::offset_t offset,
971 lldb::offset_t length) const {
972 return length <= BytesLeft(offset);
975 size_t Copy(DataExtractor &dest_data) const;
977 bool Append(DataExtractor &rhs);
979 bool Append(void *bytes, lldb::offset_t length);
981 lldb::offset_t BytesLeft(lldb::offset_t offset) const {
982 const lldb::offset_t size = GetByteSize();
984 return size - offset;
988 void Checksum(llvm::SmallVectorImpl<uint8_t> &dest, uint64_t max_data = 0);
990 llvm::ArrayRef<uint8_t> GetData() const {
991 return {GetDataStart(), size_t(GetByteSize())};
994 llvm::DataExtractor GetAsLLVM() const {
995 return {GetData(), GetByteOrder() == lldb::eByteOrderLittle,
996 uint8_t(GetAddressByteSize())};
1001 const uint8_t *m_start; ///< A pointer to the first byte of data.
1003 *m_end; ///< A pointer to the byte that is past the end of the data.
1005 m_byte_order; ///< The byte order of the data we are extracting from.
1006 uint32_t m_addr_size; ///< The address size to use when extracting pointers or
1008 mutable lldb::DataBufferSP m_data_sp; ///< The shared pointer to data that can
1009 /// be shared among multiple instances
1010 const uint32_t m_target_byte_size;
1013 } // namespace lldb_private
1015 #endif // liblldb_DataExtractor_h_