1 //===-- DataExtractor.h -----------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef LLDB_UTILITY_DATAEXTRACTOR_H
11 #define LLDB_UTILITY_DATAEXTRACTOR_H
13 #include "lldb/lldb-defines.h"
14 #include "lldb/lldb-enumerations.h" // for ByteOrder
15 #include "lldb/lldb-forward.h" // for DataBufferSP
16 #include "lldb/lldb-types.h"
22 namespace lldb_private {
25 namespace lldb_private {
29 template <typename T> class SmallVectorImpl;
34 namespace lldb_private {
36 //----------------------------------------------------------------------
37 /// @class DataExtractor DataExtractor.h "lldb/Core/DataExtractor.h"
38 /// @brief An data extractor class.
40 /// DataExtractor is a class that can extract data (swapping if needed)
41 /// from a data buffer. The data buffer can be caller owned, or can be
42 /// shared data that can be shared between multiple DataExtractor
43 /// instances. Multiple DataExtractor objects can share the same data,
44 /// yet extract values in different address sizes and byte order modes.
45 /// Each object can have a unique position in the shared data and extract
46 /// data from different offsets.
49 //----------------------------------------------------------------------
52 //------------------------------------------------------------------
53 /// @typedef DataExtractor::Type
54 /// @brief Type enumerations used in the dump routines.
55 //------------------------------------------------------------------
57 TypeUInt8, ///< Format output as unsigned 8 bit integers
58 TypeChar, ///< Format output as characters
59 TypeUInt16, ///< Format output as unsigned 16 bit integers
60 TypeUInt32, ///< Format output as unsigned 32 bit integers
61 TypeUInt64, ///< Format output as unsigned 64 bit integers
62 TypePointer, ///< Format output as pointers
63 TypeULEB128, ///< Format output as ULEB128 numbers
64 TypeSLEB128 ///< Format output as SLEB128 numbers
67 //------------------------------------------------------------------
68 /// Default constructor.
70 /// Initialize all members to a default empty state.
71 //------------------------------------------------------------------
74 //------------------------------------------------------------------
75 /// Construct with a buffer that is owned by the caller.
77 /// This constructor allows us to use data that is owned by the
78 /// caller. The data must stay around as long as this object is
82 /// A pointer to caller owned data.
84 /// @param[in] data_length
85 /// The length in bytes of \a data.
87 /// @param[in] byte_order
88 /// A byte order of the data that we are extracting from.
90 /// @param[in] addr_size
91 /// A new address byte size value.
93 /// @param[in] target_byte_size
94 /// A size of a target byte in 8-bit host bytes
95 //------------------------------------------------------------------
96 DataExtractor(const void *data, lldb::offset_t data_length,
97 lldb::ByteOrder byte_order, uint32_t addr_size,
98 uint32_t target_byte_size = 1);
100 //------------------------------------------------------------------
101 /// Construct with shared data.
103 /// Copies the data shared pointer which adds a reference to the
104 /// contained in \a data_sp. The shared data reference is reference
105 /// counted to ensure the data lives as long as anyone still has a
106 /// valid shared pointer to the data in \a data_sp.
108 /// @param[in] data_sp
109 /// A shared pointer to data.
111 /// @param[in] byte_order
112 /// A byte order of the data that we are extracting from.
114 /// @param[in] addr_size
115 /// A new address byte size value.
117 /// @param[in] target_byte_size
118 /// A size of a target byte in 8-bit host bytes
119 //------------------------------------------------------------------
120 DataExtractor(const lldb::DataBufferSP &data_sp, lldb::ByteOrder byte_order,
121 uint32_t addr_size, uint32_t target_byte_size = 1);
123 //------------------------------------------------------------------
124 /// Construct with a subset of \a data.
126 /// Initialize this object with a subset of the data bytes in \a
127 /// data. If \a data contains shared data, then a reference to the
128 /// shared data will be added to ensure the shared data stays around
129 /// as long as any objects have references to the shared data. The
130 /// byte order value and the address size settings are copied from \a
131 /// data. If \a offset is not a valid offset in \a data, then no
132 /// reference to the shared data will be added. If there are not
133 /// \a length bytes available in \a data starting at \a offset,
134 /// the length will be truncated to contain as many bytes as
138 /// Another DataExtractor object that contains data.
140 /// @param[in] offset
141 /// The offset into \a data at which the subset starts.
143 /// @param[in] length
144 /// The length in bytes of the subset of data.
146 /// @param[in] target_byte_size
147 /// A size of a target byte in 8-bit host bytes
148 //------------------------------------------------------------------
149 DataExtractor(const DataExtractor &data, lldb::offset_t offset,
150 lldb::offset_t length, uint32_t target_byte_size = 1);
152 DataExtractor(const DataExtractor &rhs);
154 //------------------------------------------------------------------
155 /// Assignment operator.
157 /// Copies all data, byte order and address size settings from \a rhs into
158 /// this object. If \a rhs contains shared data, a reference to that
159 /// shared data will be added.
162 /// Another DataExtractor object to copy.
165 /// A const reference to this object.
166 //------------------------------------------------------------------
167 const DataExtractor &operator=(const DataExtractor &rhs);
169 //------------------------------------------------------------------
172 /// If this object contains a valid shared data reference, the
173 /// reference count on the data will be decremented, and if zero,
174 /// the data will be freed.
175 //------------------------------------------------------------------
176 virtual ~DataExtractor();
178 uint32_t getTargetByteSize() const { return m_target_byte_size; }
180 //------------------------------------------------------------------
181 /// Clears the object state.
183 /// Clears the object contents back to a default invalid state, and
184 /// release any references to shared data that this object may
186 //------------------------------------------------------------------
189 //------------------------------------------------------------------
190 /// Dumps the binary data as \a type objects to stream \a s (or to
191 /// Log() if \a s is nullptr) starting \a offset bytes into the data
192 /// and stopping after dumping \a length bytes. The offset into the
193 /// data is displayed at the beginning of each line and can be
194 /// offset by base address \a base_addr. \a num_per_line objects
195 /// will be displayed on each line.
198 /// The stream to dump the output to. If nullptr the output will
199 /// be dumped to Log().
201 /// @param[in] offset
202 /// The offset into the data at which to start dumping.
204 /// @param[in] length
205 /// The number of bytes to dump.
207 /// @param[in] base_addr
208 /// The base address that gets added to the offset displayed on
211 /// @param[in] num_per_line
212 /// The number of \a type objects to display on each line.
215 /// The type of objects to use when dumping data from this
216 /// object. See DataExtractor::Type.
218 /// @param[in] type_format
219 /// The optional format to use for the \a type objects. If this
220 /// is nullptr, the default format for the \a type will be used.
223 /// The offset at which dumping ended.
224 //------------------------------------------------------------------
225 lldb::offset_t PutToLog(Log *log, lldb::offset_t offset,
226 lldb::offset_t length, uint64_t base_addr,
227 uint32_t num_per_line, Type type,
228 const char *type_format = nullptr) const;
230 //------------------------------------------------------------------
231 /// Dump a UUID value at \a offset.
233 /// Dump a UUID starting at \a offset bytes into this object's data.
234 /// If the stream \a s is nullptr, the output will be sent to Log().
237 /// The stream to dump the output to. If nullptr the output will
238 /// be dumped to Log().
240 /// @param[in] offset
241 /// The offset into the data at which to extract and dump a
243 //------------------------------------------------------------------
244 void DumpUUID(Stream *s, lldb::offset_t offset) const;
246 //------------------------------------------------------------------
247 /// Extract an arbitrary number of bytes in the specified byte
250 /// Attemps to extract \a length bytes starting at \a offset bytes
251 /// into this data in the requested byte order (\a dst_byte_order)
252 /// and place the results in \a dst. \a dst must be at least \a
253 /// length bytes long.
255 /// @param[in] offset
256 /// The offset in bytes into the contained data at which to
257 /// start extracting.
259 /// @param[in] length
260 /// The number of bytes to extract.
262 /// @param[in] dst_byte_order
263 /// A byte order of the data that we want when the value in
264 /// copied to \a dst.
267 /// The buffer that will receive the extracted value if there
268 /// are enough bytes available in the current data.
271 /// The number of bytes that were extracted which will be \a
272 /// length when the value is successfully extracted, or zero
273 /// if there aren't enough bytes at the specified offset.
274 //------------------------------------------------------------------
275 size_t ExtractBytes(lldb::offset_t offset, lldb::offset_t length,
276 lldb::ByteOrder dst_byte_order, void *dst) const;
278 //------------------------------------------------------------------
279 /// Extract an address from \a *offset_ptr.
281 /// Extract a single address from the data and update the offset
282 /// pointed to by \a offset_ptr. The size of the extracted address
283 /// comes from the \a m_addr_size member variable and should be
284 /// set correctly prior to extracting any address values.
286 /// @param[in,out] offset_ptr
287 /// A pointer to an offset within the data that will be advanced
288 /// by the appropriate number of bytes if the value is extracted
289 /// correctly. If the offset is out of bounds or there are not
290 /// enough bytes to extract this value, the offset will be left
294 /// The extracted address value.
295 //------------------------------------------------------------------
296 uint64_t GetAddress(lldb::offset_t *offset_ptr) const;
298 uint64_t GetAddress_unchecked(lldb::offset_t *offset_ptr) const;
300 //------------------------------------------------------------------
301 /// Get the current address size.
303 /// Return the size in bytes of any address values this object will
307 /// The size in bytes of address values that will be extracted.
308 //------------------------------------------------------------------
309 uint32_t GetAddressByteSize() const { return m_addr_size; }
311 //------------------------------------------------------------------
312 /// Get the number of bytes contained in this object.
315 /// The total number of bytes of data this object refers to.
316 //------------------------------------------------------------------
317 uint64_t GetByteSize() const { return m_end - m_start; }
319 //------------------------------------------------------------------
320 /// Extract a C string from \a *offset_ptr.
322 /// Returns a pointer to a C String from the data at the offset
323 /// pointed to by \a offset_ptr. A variable length NULL terminated C
324 /// string will be extracted and the \a offset_ptr will be
325 /// updated with the offset of the byte that follows the NULL
328 /// @param[in,out] offset_ptr
329 /// A pointer to an offset within the data that will be advanced
330 /// by the appropriate number of bytes if the value is extracted
331 /// correctly. If the offset is out of bounds or there are not
332 /// enough bytes to extract this value, the offset will be left
336 /// A pointer to the C string value in the data. If the offset
337 /// pointed to by \a offset_ptr is out of bounds, or if the
338 /// offset plus the length of the C string is out of bounds,
339 /// nullptr will be returned.
340 //------------------------------------------------------------------
341 const char *GetCStr(lldb::offset_t *offset_ptr) const;
343 //------------------------------------------------------------------
344 /// Extract a C string from \a *offset_ptr with field size \a len.
346 /// Returns a pointer to a C String from the data at the offset
347 /// pointed to by \a offset_ptr, with a field length of \a len.
348 /// A NULL terminated C string will be extracted and the \a offset_ptr
349 /// will be updated with the offset of the byte that follows the fixed
352 /// @param[in,out] offset_ptr
353 /// A pointer to an offset within the data that will be advanced
354 /// by the appropriate number of bytes if the value is extracted
355 /// correctly. If the offset is out of bounds or there are not
356 /// enough bytes to extract this value, the offset will be left
360 /// A pointer to the C string value in the data. If the offset
361 /// pointed to by \a offset_ptr is out of bounds, or if the
362 /// offset plus the length of the field is out of bounds, or if
363 /// the field does not contain a NULL terminator byte, nullptr will
365 const char *GetCStr(lldb::offset_t *offset_ptr, lldb::offset_t len) const;
367 //------------------------------------------------------------------
368 /// Extract \a length bytes from \a *offset_ptr.
370 /// Returns a pointer to a bytes in this object's data at the offset
371 /// pointed to by \a offset_ptr. If \a length is zero or too large,
372 /// then the offset pointed to by \a offset_ptr will not be updated
373 /// and nullptr will be returned.
375 /// @param[in,out] offset_ptr
376 /// A pointer to an offset within the data that will be advanced
377 /// by the appropriate number of bytes if the value is extracted
378 /// correctly. If the offset is out of bounds or there are not
379 /// enough bytes to extract this value, the offset will be left
382 /// @param[in] length
383 /// The optional length of a string to extract. If the value is
384 /// zero, a NULL terminated C string will be extracted.
387 /// A pointer to the bytes in this object's data if the offset
388 /// and length are valid, or nullptr otherwise.
389 //------------------------------------------------------------------
390 const void *GetData(lldb::offset_t *offset_ptr, lldb::offset_t length) const {
391 const uint8_t *ptr = PeekData(*offset_ptr, length);
393 *offset_ptr += length;
397 //------------------------------------------------------------------
398 /// Copy \a length bytes from \a *offset, without swapping bytes.
400 /// @param[in] offset
401 /// The offset into this data from which to start copying
403 /// @param[in] length
404 /// The length of the data to copy from this object
407 /// The buffer to place the output data.
410 /// Returns the number of bytes that were copied, or zero if
411 /// anything goes wrong.
412 //------------------------------------------------------------------
413 lldb::offset_t CopyData(lldb::offset_t offset, lldb::offset_t length,
416 //------------------------------------------------------------------
417 /// Copy \a dst_len bytes from \a *offset_ptr and ensure the copied
418 /// data is treated as a value that can be swapped to match the
419 /// specified byte order.
421 /// For values that are larger than the supported integer sizes,
422 /// this function can be used to extract data in a specified byte
423 /// order. It can also be used to copy a smaller integer value from
424 /// to a larger value. The extra bytes left over will be padded
425 /// correctly according to the byte order of this object and the
426 /// \a dst_byte_order. This can be very handy when say copying a
427 /// partial data value into a register.
429 /// @param[in] src_offset
430 /// The offset into this data from which to start copying an
433 /// @param[in] src_len
434 /// The length of the endian data to copy from this object
435 /// into the \a dst object
438 /// The buffer where to place the endian data. The data might
439 /// need to be byte swapped (and appropriately padded with
440 /// zeroes if \a src_len != \a dst_len) if \a dst_byte_order
441 /// does not match the byte order in this object.
443 /// @param[in] dst_len
444 /// The length number of bytes that the endian value will
445 /// occupy is \a dst.
447 /// @param[in] byte_order
448 /// The byte order that the endian value should be in the \a dst
452 /// Returns the number of bytes that were copied, or zero if
453 /// anything goes wrong.
454 //------------------------------------------------------------------
455 lldb::offset_t CopyByteOrderedData(lldb::offset_t src_offset,
456 lldb::offset_t src_len, void *dst,
457 lldb::offset_t dst_len,
458 lldb::ByteOrder dst_byte_order) const;
460 //------------------------------------------------------------------
461 /// Get the data end pointer.
464 /// Returns a pointer to the next byte contained in this
465 /// object's data, or nullptr of there is no data in this object.
466 //------------------------------------------------------------------
467 const uint8_t *GetDataEnd() const { return m_end; }
469 //------------------------------------------------------------------
470 /// Get the shared data offset.
472 /// Get the offset of the first byte of data in the shared data (if
476 /// If this object contains shared data, this function returns
477 /// the offset in bytes into that shared data, zero otherwise.
478 //------------------------------------------------------------------
479 size_t GetSharedDataOffset() const;
481 //------------------------------------------------------------------
482 /// Get the data start pointer.
485 /// Returns a pointer to the first byte contained in this
486 /// object's data, or nullptr of there is no data in this object.
487 //------------------------------------------------------------------
488 const uint8_t *GetDataStart() const { return m_start; }
490 //------------------------------------------------------------------
491 /// Extract a float from \a *offset_ptr.
493 /// Extract a single float value.
495 /// @param[in,out] offset_ptr
496 /// A pointer to an offset within the data that will be advanced
497 /// by the appropriate number of bytes if the value is extracted
498 /// correctly. If the offset is out of bounds or there are not
499 /// enough bytes to extract this value, the offset will be left
503 /// The floating value that was extracted, or zero on failure.
504 //------------------------------------------------------------------
505 float GetFloat(lldb::offset_t *offset_ptr) const;
507 double GetDouble(lldb::offset_t *offset_ptr) const;
509 long double GetLongDouble(lldb::offset_t *offset_ptr) const;
511 //------------------------------------------------------------------
512 /// Extract an integer of size \a byte_size from \a *offset_ptr.
514 /// Extract a single integer value and update the offset pointed to
515 /// by \a offset_ptr. The size of the extracted integer is specified
516 /// by the \a byte_size argument. \a byte_size should have a value
517 /// >= 1 and <= 4 since the return value is only 32 bits wide. Any
518 /// \a byte_size values less than 1 or greater than 4 will result in
519 /// nothing being extracted, and zero being returned.
521 /// @param[in,out] offset_ptr
522 /// A pointer to an offset within the data that will be advanced
523 /// by the appropriate number of bytes if the value is extracted
524 /// correctly. If the offset is out of bounds or there are not
525 /// enough bytes to extract this value, the offset will be left
528 /// @param[in] byte_size
529 /// The size in byte of the integer to extract.
532 /// The integer value that was extracted, or zero on failure.
533 //------------------------------------------------------------------
534 uint32_t GetMaxU32(lldb::offset_t *offset_ptr, size_t byte_size) const;
536 //------------------------------------------------------------------
537 /// Extract an unsigned integer of size \a byte_size from \a
540 /// Extract a single unsigned integer value and update the offset
541 /// pointed to by \a offset_ptr. The size of the extracted integer
542 /// is specified by the \a byte_size argument. \a byte_size should
543 /// have a value greater than or equal to one and less than or equal
544 /// to eight since the return value is 64 bits wide. Any
545 /// \a byte_size values less than 1 or greater than 8 will result in
546 /// nothing being extracted, and zero being returned.
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
555 /// @param[in] byte_size
556 /// The size in byte of the integer to extract.
559 /// The unsigned integer value that was extracted, or zero on
561 //------------------------------------------------------------------
562 uint64_t GetMaxU64(lldb::offset_t *offset_ptr, size_t byte_size) const;
564 uint64_t GetMaxU64_unchecked(lldb::offset_t *offset_ptr,
565 size_t byte_size) const;
567 //------------------------------------------------------------------
568 /// Extract an signed integer of size \a byte_size from \a *offset_ptr.
570 /// Extract a single signed integer value (sign extending if required)
571 /// and update the offset pointed to by \a offset_ptr. The size of
572 /// the extracted integer is specified by the \a byte_size argument.
573 /// \a byte_size should have a value greater than or equal to one
574 /// and less than or equal to eight since the return value is 64
575 /// bits wide. Any \a byte_size values less than 1 or greater than
576 /// 8 will result in nothing being extracted, and zero being returned.
578 /// @param[in,out] offset_ptr
579 /// A pointer to an offset within the data that will be advanced
580 /// by the appropriate number of bytes if the value is extracted
581 /// correctly. If the offset is out of bounds or there are not
582 /// enough bytes to extract this value, the offset will be left
585 /// @param[in] byte_size
586 /// The size in byte of the integer to extract.
589 /// The sign extended signed integer value that was extracted,
590 /// or zero on failure.
591 //------------------------------------------------------------------
592 int64_t GetMaxS64(lldb::offset_t *offset_ptr, size_t size) const;
594 //------------------------------------------------------------------
595 /// Extract an unsigned integer of size \a byte_size from \a
596 /// *offset_ptr, then extract the bitfield from this value if
597 /// \a bitfield_bit_size is non-zero.
599 /// Extract a single unsigned integer value and update the offset
600 /// pointed to by \a offset_ptr. The size of the extracted integer
601 /// is specified by the \a byte_size argument. \a byte_size should
602 /// have a value greater than or equal to one and less than or equal
603 /// to 8 since the return value is 64 bits wide. Any
604 /// \a byte_size values less than 1 or greater than 8 will result in
605 /// nothing being extracted, and zero being returned.
607 /// @param[in,out] offset_ptr
608 /// A pointer to an offset within the data that will be advanced
609 /// by the appropriate number of bytes if the value is extracted
610 /// correctly. If the offset is out of bounds or there are not
611 /// enough bytes to extract this value, the offset will be left
614 /// @param[in] byte_size
615 /// The size in byte of the integer to extract.
617 /// @param[in] bitfield_bit_size
618 /// The size in bits of the bitfield value to extract, or zero
619 /// to just extract the entire integer value.
621 /// @param[in] bitfield_bit_offset
622 /// The bit offset of the bitfield value in the extracted
623 /// integer. For little-endian data, this is the offset of
624 /// the LSB of the bitfield from the LSB of the integer.
625 /// For big-endian data, this is the offset of the MSB of the
626 /// bitfield from the MSB of the integer.
629 /// The unsigned bitfield integer value that was extracted, or
631 //------------------------------------------------------------------
632 uint64_t GetMaxU64Bitfield(lldb::offset_t *offset_ptr, size_t size,
633 uint32_t bitfield_bit_size,
634 uint32_t bitfield_bit_offset) const;
636 //------------------------------------------------------------------
637 /// Extract an signed integer of size \a byte_size from \a
638 /// *offset_ptr, then extract and signe extend the bitfield from
639 /// this value if \a bitfield_bit_size is non-zero.
641 /// Extract a single signed integer value (sign extending if required)
642 /// and update the offset pointed to by \a offset_ptr. The size of
643 /// the extracted integer is specified by the \a byte_size argument.
644 /// \a byte_size should have a value greater than or equal to one
645 /// and less than or equal to eight since the return value is 64
646 /// bits wide. Any \a byte_size values less than 1 or greater than
647 /// 8 will result in nothing being extracted, and zero being returned.
649 /// @param[in,out] offset_ptr
650 /// A pointer to an offset within the data that will be advanced
651 /// by the appropriate number of bytes if the value is extracted
652 /// correctly. If the offset is out of bounds or there are not
653 /// enough bytes to extract this value, the offset will be left
656 /// @param[in] byte_size
657 /// The size in bytes of the integer to extract.
659 /// @param[in] bitfield_bit_size
660 /// The size in bits of the bitfield value to extract, or zero
661 /// to just extract the entire integer value.
663 /// @param[in] bitfield_bit_offset
664 /// The bit offset of the bitfield value in the extracted
665 /// integer. For little-endian data, this is the offset of
666 /// the LSB of the bitfield from the LSB of the integer.
667 /// For big-endian data, this is the offset of the MSB of the
668 /// bitfield from the MSB of the integer.
671 /// The signed bitfield integer value that was extracted, or
673 //------------------------------------------------------------------
674 int64_t GetMaxS64Bitfield(lldb::offset_t *offset_ptr, size_t size,
675 uint32_t bitfield_bit_size,
676 uint32_t bitfield_bit_offset) const;
678 //------------------------------------------------------------------
679 /// Extract an pointer from \a *offset_ptr.
681 /// Extract a single pointer from the data and update the offset
682 /// pointed to by \a offset_ptr. The size of the extracted pointer
683 /// comes from the \a m_addr_size member variable and should be
684 /// set correctly prior to extracting any pointer values.
686 /// @param[in,out] offset_ptr
687 /// A pointer to an offset within the data that will be advanced
688 /// by the appropriate number of bytes if the value is extracted
689 /// correctly. If the offset is out of bounds or there are not
690 /// enough bytes to extract this value, the offset will be left
694 /// The extracted pointer value as a 64 integer.
695 //------------------------------------------------------------------
696 uint64_t GetPointer(lldb::offset_t *offset_ptr) const;
698 //------------------------------------------------------------------
699 /// Get the current byte order value.
702 /// The current byte order value from this object's internal
704 //------------------------------------------------------------------
705 lldb::ByteOrder GetByteOrder() const { return m_byte_order; }
707 //------------------------------------------------------------------
708 /// Extract a uint8_t value from \a *offset_ptr.
710 /// Extract a single uint8_t from the binary data at the offset
711 /// pointed to by \a offset_ptr, and advance the offset on success.
713 /// @param[in,out] offset_ptr
714 /// A pointer to an offset within the data that will be advanced
715 /// by the appropriate number of bytes if the value is extracted
716 /// correctly. If the offset is out of bounds or there are not
717 /// enough bytes to extract this value, the offset will be left
721 /// The extracted uint8_t value.
722 //------------------------------------------------------------------
723 uint8_t GetU8(lldb::offset_t *offset_ptr) const;
725 uint8_t GetU8_unchecked(lldb::offset_t *offset_ptr) const {
726 uint8_t val = m_start[*offset_ptr];
731 uint16_t GetU16_unchecked(lldb::offset_t *offset_ptr) const;
733 uint32_t GetU32_unchecked(lldb::offset_t *offset_ptr) const;
735 uint64_t GetU64_unchecked(lldb::offset_t *offset_ptr) const;
736 //------------------------------------------------------------------
737 /// Extract \a count uint8_t values from \a *offset_ptr.
739 /// Extract \a count uint8_t values from the binary data at the
740 /// offset pointed to by \a offset_ptr, and advance the offset on
741 /// success. The extracted values are copied into \a dst.
743 /// @param[in,out] offset_ptr
744 /// A pointer to an offset within the data that will be advanced
745 /// by the appropriate number of bytes if the value is extracted
746 /// correctly. If the offset is out of bounds or there are not
747 /// enough bytes to extract this value, the offset will be left
751 /// A buffer to copy \a count uint8_t values into. \a dst must
752 /// be large enough to hold all requested data.
755 /// The number of uint8_t values to extract.
758 /// \a dst if all values were properly extracted and copied,
759 /// nullptr otherwise.
760 //------------------------------------------------------------------
761 void *GetU8(lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
763 //------------------------------------------------------------------
764 /// Extract a uint16_t value from \a *offset_ptr.
766 /// Extract a single uint16_t from the binary data at the offset
767 /// pointed to by \a offset_ptr, and update the offset on success.
769 /// @param[in,out] offset_ptr
770 /// A pointer to an offset within the data that will be advanced
771 /// by the appropriate number of bytes if the value is extracted
772 /// correctly. If the offset is out of bounds or there are not
773 /// enough bytes to extract this value, the offset will be left
777 /// The extracted uint16_t value.
778 //------------------------------------------------------------------
779 uint16_t GetU16(lldb::offset_t *offset_ptr) const;
781 //------------------------------------------------------------------
782 /// Extract \a count uint16_t values from \a *offset_ptr.
784 /// Extract \a count uint16_t values from the binary data at the
785 /// offset pointed to by \a offset_ptr, and advance the offset on
786 /// success. The extracted values are copied into \a dst.
788 /// @param[in,out] offset_ptr
789 /// A pointer to an offset within the data that will be advanced
790 /// by the appropriate number of bytes if the value is extracted
791 /// correctly. If the offset is out of bounds or there are not
792 /// enough bytes to extract this value, the offset will be left
796 /// A buffer to copy \a count uint16_t values into. \a dst must
797 /// be large enough to hold all requested data.
800 /// The number of uint16_t values to extract.
803 /// \a dst if all values were properly extracted and copied,
804 /// nullptr otherwise.
805 //------------------------------------------------------------------
806 void *GetU16(lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
808 //------------------------------------------------------------------
809 /// Extract a uint32_t value from \a *offset_ptr.
811 /// Extract a single uint32_t from the binary data at the offset
812 /// pointed to by \a offset_ptr, and update the offset on success.
814 /// @param[in,out] offset_ptr
815 /// A pointer to an offset within the data that will be advanced
816 /// by the appropriate number of bytes if the value is extracted
817 /// correctly. If the offset is out of bounds or there are not
818 /// enough bytes to extract this value, the offset will be left
822 /// The extracted uint32_t value.
823 //------------------------------------------------------------------
824 uint32_t GetU32(lldb::offset_t *offset_ptr) const;
826 //------------------------------------------------------------------
827 /// Extract \a count uint32_t values from \a *offset_ptr.
829 /// Extract \a count uint32_t values from the binary data at the
830 /// offset pointed to by \a offset_ptr, and advance the offset on
831 /// success. The extracted values are copied into \a dst.
833 /// @param[in,out] offset_ptr
834 /// A pointer to an offset within the data that will be advanced
835 /// by the appropriate number of bytes if the value is extracted
836 /// correctly. If the offset is out of bounds or there are not
837 /// enough bytes to extract this value, the offset will be left
841 /// A buffer to copy \a count uint32_t values into. \a dst must
842 /// be large enough to hold all requested data.
845 /// The number of uint32_t values to extract.
848 /// \a dst if all values were properly extracted and copied,
849 /// nullptr otherwise.
850 //------------------------------------------------------------------
851 void *GetU32(lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
853 //------------------------------------------------------------------
854 /// Extract a uint64_t value from \a *offset_ptr.
856 /// Extract a single uint64_t from the binary data at the offset
857 /// pointed to by \a offset_ptr, and update the offset on success.
859 /// @param[in,out] offset_ptr
860 /// A pointer to an offset within the data that will be advanced
861 /// by the appropriate number of bytes if the value is extracted
862 /// correctly. If the offset is out of bounds or there are not
863 /// enough bytes to extract this value, the offset will be left
867 /// The extracted uint64_t value.
868 //------------------------------------------------------------------
869 uint64_t GetU64(lldb::offset_t *offset_ptr) const;
871 //------------------------------------------------------------------
872 /// Extract \a count uint64_t values from \a *offset_ptr.
874 /// Extract \a count uint64_t values from the binary data at the
875 /// offset pointed to by \a offset_ptr, and advance the offset on
876 /// success. The extracted values are copied into \a dst.
878 /// @param[in,out] offset_ptr
879 /// A pointer to an offset within the data that will be advanced
880 /// by the appropriate number of bytes if the value is extracted
881 /// correctly. If the offset is out of bounds or there are not
882 /// enough bytes to extract this value, the offset will be left
886 /// A buffer to copy \a count uint64_t values into. \a dst must
887 /// be large enough to hold all requested data.
890 /// The number of uint64_t values to extract.
893 /// \a dst if all values were properly extracted and copied,
894 /// nullptr otherwise.
895 //------------------------------------------------------------------
896 void *GetU64(lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
898 //------------------------------------------------------------------
899 /// Extract a signed LEB128 value from \a *offset_ptr.
901 /// Extracts an signed LEB128 number from this object's data
902 /// starting at the offset pointed to by \a offset_ptr. The offset
903 /// pointed to by \a offset_ptr will be updated with the offset of
904 /// the byte following the last extracted byte.
906 /// @param[in,out] offset_ptr
907 /// A pointer to an offset within the data that will be advanced
908 /// by the appropriate number of bytes if the value is extracted
909 /// correctly. If the offset is out of bounds or there are not
910 /// enough bytes to extract this value, the offset will be left
914 /// The extracted signed integer value.
915 //------------------------------------------------------------------
916 int64_t GetSLEB128(lldb::offset_t *offset_ptr) const;
918 //------------------------------------------------------------------
919 /// Extract a unsigned LEB128 value from \a *offset_ptr.
921 /// Extracts an unsigned LEB128 number from this object's data
922 /// starting at the offset pointed to by \a offset_ptr. The offset
923 /// pointed to by \a offset_ptr will be updated with the offset of
924 /// the byte following the last extracted byte.
926 /// @param[in,out] offset_ptr
927 /// A pointer to an offset within the data that will be advanced
928 /// by the appropriate number of bytes if the value is extracted
929 /// correctly. If the offset is out of bounds or there are not
930 /// enough bytes to extract this value, the offset will be left
934 /// The extracted unsigned integer value.
935 //------------------------------------------------------------------
936 uint64_t GetULEB128(lldb::offset_t *offset_ptr) const;
938 lldb::DataBufferSP &GetSharedDataBuffer() { return m_data_sp; }
940 //------------------------------------------------------------------
941 /// Peek at a C string at \a offset.
943 /// Peeks at a string in the contained data. No verification is done
944 /// to make sure the entire string lies within the bounds of this
945 /// object's data, only \a offset is verified to be a valid offset.
947 /// @param[in] offset
948 /// An offset into the data.
951 /// A non-nullptr C string pointer if \a offset is a valid offset,
952 /// nullptr otherwise.
953 //------------------------------------------------------------------
954 const char *PeekCStr(lldb::offset_t offset) const;
956 //------------------------------------------------------------------
957 /// Peek at a bytes at \a offset.
959 /// Returns a pointer to \a length bytes at \a offset as long as
960 /// there are \a length bytes available starting at \a offset.
963 /// A non-nullptr data pointer if \a offset is a valid offset and
964 /// there are \a length bytes available at that offset, nullptr
966 //------------------------------------------------------------------
967 const uint8_t *PeekData(lldb::offset_t offset, lldb::offset_t length) const {
968 if (ValidOffsetForDataOfSize(offset, length))
969 return m_start + offset;
973 //------------------------------------------------------------------
974 /// Set the address byte size.
976 /// Set the size in bytes that will be used when extracting any
977 /// address and pointer values from data contained in this object.
979 /// @param[in] addr_size
980 /// The size in bytes to use when extracting addresses.
981 //------------------------------------------------------------------
982 void SetAddressByteSize(uint32_t addr_size) {
983 #ifdef LLDB_CONFIGURATION_DEBUG
984 assert(addr_size == 4 || addr_size == 8);
986 m_addr_size = addr_size;
989 //------------------------------------------------------------------
990 /// Set data with a buffer that is caller owned.
992 /// Use data that is owned by the caller when extracting values.
993 /// The data must stay around as long as this object, or any object
994 /// that copies a subset of this object's data, is valid. If \a
995 /// bytes is nullptr, or \a length is zero, this object will contain
999 /// A pointer to caller owned data.
1001 /// @param[in] length
1002 /// The length in bytes of \a bytes.
1004 /// @param[in] byte_order
1005 /// A byte order of the data that we are extracting from.
1008 /// The number of bytes that this object now contains.
1009 //------------------------------------------------------------------
1010 lldb::offset_t SetData(const void *bytes, lldb::offset_t length,
1011 lldb::ByteOrder byte_order);
1013 //------------------------------------------------------------------
1014 /// Adopt a subset of \a data.
1016 /// Set this object's data to be a subset of the data bytes in \a
1017 /// data. If \a data contains shared data, then a reference to the
1018 /// shared data will be added to ensure the shared data stays around
1019 /// as long as any objects have references to the shared data. The
1020 /// byte order and the address size settings are copied from \a
1021 /// data. If \a offset is not a valid offset in \a data, then no
1022 /// reference to the shared data will be added. If there are not
1023 /// \a length bytes available in \a data starting at \a offset,
1024 /// the length will be truncated to contains as many bytes as
1028 /// Another DataExtractor object that contains data.
1030 /// @param[in] offset
1031 /// The offset into \a data at which the subset starts.
1033 /// @param[in] length
1034 /// The length in bytes of the subset of \a data.
1037 /// The number of bytes that this object now contains.
1038 //------------------------------------------------------------------
1039 lldb::offset_t SetData(const DataExtractor &data, lldb::offset_t offset,
1040 lldb::offset_t length);
1042 //------------------------------------------------------------------
1043 /// Adopt a subset of shared data in \a data_sp.
1045 /// Copies the data shared pointer which adds a reference to the
1046 /// contained in \a data_sp. The shared data reference is reference
1047 /// counted to ensure the data lives as long as anyone still has a
1048 /// valid shared pointer to the data in \a data_sp. The byte order
1049 /// and address byte size settings remain the same. If
1050 /// \a offset is not a valid offset in \a data_sp, then no reference
1051 /// to the shared data will be added. If there are not \a length
1052 /// bytes available in \a data starting at \a offset, the length
1053 /// will be truncated to contains as many bytes as possible.
1055 /// @param[in] data_sp
1056 /// A shared pointer to data.
1058 /// @param[in] offset
1059 /// The offset into \a data_sp at which the subset starts.
1061 /// @param[in] length
1062 /// The length in bytes of the subset of \a data_sp.
1065 /// The number of bytes that this object now contains.
1066 //------------------------------------------------------------------
1067 lldb::offset_t SetData(const lldb::DataBufferSP &data_sp,
1068 lldb::offset_t offset = 0,
1069 lldb::offset_t length = LLDB_INVALID_OFFSET);
1071 //------------------------------------------------------------------
1072 /// Set the byte_order value.
1074 /// Sets the byte order of the data to extract. Extracted values
1075 /// will be swapped if necessary when decoding.
1077 /// @param[in] byte_order
1078 /// The byte order value to use when extracting data.
1079 //------------------------------------------------------------------
1080 void SetByteOrder(lldb::ByteOrder byte_order) { m_byte_order = byte_order; }
1082 //------------------------------------------------------------------
1083 /// Skip an LEB128 number at \a *offset_ptr.
1085 /// Skips a LEB128 number (signed or unsigned) from this object's
1086 /// data starting at the offset pointed to by \a offset_ptr. The
1087 /// offset pointed to by \a offset_ptr will be updated with the
1088 /// offset of the byte following the last extracted byte.
1090 /// @param[in,out] offset_ptr
1091 /// A pointer to an offset within the data that will be advanced
1092 /// by the appropriate number of bytes if the value is extracted
1093 /// correctly. If the offset is out of bounds or there are not
1094 /// enough bytes to extract this value, the offset will be left
1098 // The number of bytes consumed during the extraction.
1099 //------------------------------------------------------------------
1100 uint32_t Skip_LEB128(lldb::offset_t *offset_ptr) const;
1102 //------------------------------------------------------------------
1103 /// Test the validity of \a offset.
1106 /// \b true if \a offset is a valid offset into the data in this
1107 /// object, \b false otherwise.
1108 //------------------------------------------------------------------
1109 bool ValidOffset(lldb::offset_t offset) const {
1110 return offset < GetByteSize();
1113 //------------------------------------------------------------------
1114 /// Test the availability of \a length bytes of data from \a offset.
1117 /// \b true if \a offset is a valid offset and there are \a
1118 /// length bytes available at that offset, \b false otherwise.
1119 //------------------------------------------------------------------
1120 bool ValidOffsetForDataOfSize(lldb::offset_t offset,
1121 lldb::offset_t length) const {
1122 return length <= BytesLeft(offset);
1125 size_t Copy(DataExtractor &dest_data) const;
1127 bool Append(DataExtractor &rhs);
1129 bool Append(void *bytes, lldb::offset_t length);
1131 lldb::offset_t BytesLeft(lldb::offset_t offset) const {
1132 const lldb::offset_t size = GetByteSize();
1134 return size - offset;
1138 void Checksum(llvm::SmallVectorImpl<uint8_t> &dest, uint64_t max_data = 0);
1141 //------------------------------------------------------------------
1143 //------------------------------------------------------------------
1144 const uint8_t *m_start; ///< A pointer to the first byte of data.
1146 *m_end; ///< A pointer to the byte that is past the end of the data.
1148 m_byte_order; ///< The byte order of the data we are extracting from.
1149 uint32_t m_addr_size; ///< The address size to use when extracting pointers or
1151 mutable lldb::DataBufferSP m_data_sp; ///< The shared pointer to data that can
1152 /// be shared among multiple instances
1153 const uint32_t m_target_byte_size;
1156 } // namespace lldb_private
1158 #endif // liblldb_DataExtractor_h_