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 liblldb_DataExtractor_h_
11 #define liblldb_DataExtractor_h_
12 #if defined (__cplusplus)
15 #include "lldb/lldb-private.h"
20 namespace lldb_private {
22 //----------------------------------------------------------------------
23 /// @class DataExtractor DataExtractor.h "lldb/Core/DataExtractor.h"
24 /// @brief An data extractor class.
26 /// DataExtractor is a class that can extract data (swapping if needed)
27 /// from a data buffer. The data buffer can be caller owned, or can be
28 /// shared data that can be shared between multiple DataExtractor
29 /// instances. Multiple DataExtractor objects can share the same data,
30 /// yet extract values in different address sizes and byte order modes.
31 /// Each object can have a unique position in the shared data and extract
32 /// data from different offsets.
35 //----------------------------------------------------------------------
39 //------------------------------------------------------------------
40 /// @typedef DataExtractor::Type
41 /// @brief Type enumerations used in the dump routines.
42 /// @see DataExtractor::Dump()
43 /// @see DataExtractor::DumpRawHexBytes()
44 //------------------------------------------------------------------
47 TypeUInt8, ///< Format output as unsigned 8 bit integers
48 TypeChar, ///< Format output as characters
49 TypeUInt16, ///< Format output as unsigned 16 bit integers
50 TypeUInt32, ///< Format output as unsigned 32 bit integers
51 TypeUInt64, ///< Format output as unsigned 64 bit integers
52 TypePointer, ///< Format output as pointers
53 TypeULEB128, ///< Format output as ULEB128 numbers
54 TypeSLEB128 ///< Format output as SLEB128 numbers
58 DumpHexBytes (Stream *s,
61 uint32_t bytes_per_line,
62 lldb::addr_t base_addr); // Pass LLDB_INVALID_ADDRESS to not show address at start of line
63 //------------------------------------------------------------------
64 /// Default constructor.
66 /// Initialize all members to a default empty state.
67 //------------------------------------------------------------------
70 //------------------------------------------------------------------
71 /// Construct with a buffer that is owned by the caller.
73 /// This constructor allows us to use data that is owned by the
74 /// caller. The data must stay around as long as this object is
78 /// A pointer to caller owned data.
80 /// @param[in] data_length
81 /// The length in bytes of \a data.
83 /// @param[in] byte_order
84 /// A byte order of the data that we are extracting from.
86 /// @param[in] addr_size
87 /// A new address byte size value.
88 //------------------------------------------------------------------
89 DataExtractor (const void* data, lldb::offset_t data_length, lldb::ByteOrder byte_order, uint32_t addr_size);
91 //------------------------------------------------------------------
92 /// Construct with shared data.
94 /// Copies the data shared pointer which adds a reference to the
95 /// contained in \a data_sp. The shared data reference is reference
96 /// counted to ensure the data lives as long as anyone still has a
97 /// valid shared pointer to the data in \a data_sp.
99 /// @param[in] data_sp
100 /// A shared pointer to data.
102 /// @param[in] byte_order
103 /// A byte order of the data that we are extracting from.
105 /// @param[in] addr_size
106 /// A new address byte size value.
107 //------------------------------------------------------------------
108 DataExtractor (const lldb::DataBufferSP& data_sp, lldb::ByteOrder byte_order, uint32_t addr_size);
110 //------------------------------------------------------------------
111 /// Construct with a subset of \a data.
113 /// Initialize this object with a subset of the data bytes in \a
114 /// data. If \a data contains shared data, then a reference to the
115 /// shared data will be added to ensure the shared data stays around
116 /// as long as any objects have references to the shared data. The
117 /// byte order value and the address size settings are copied from \a
118 /// data. If \a offset is not a valid offset in \a data, then no
119 /// reference to the shared data will be added. If there are not
120 /// \a length bytes available in \a data starting at \a offset,
121 /// the length will be truncated to contain as many bytes as
125 /// Another DataExtractor object that contains data.
127 /// @param[in] offset
128 /// The offset into \a data at which the subset starts.
130 /// @param[in] length
131 /// The length in bytes of the subset of data.
132 //------------------------------------------------------------------
133 DataExtractor (const DataExtractor& data, lldb::offset_t offset, lldb::offset_t length);
135 DataExtractor (const DataExtractor& rhs);
136 //------------------------------------------------------------------
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
141 /// shared data will be added.
144 /// Another DataExtractor object to copy.
147 /// A const reference to this object.
148 //------------------------------------------------------------------
150 operator= (const DataExtractor& rhs);
152 //------------------------------------------------------------------
155 /// If this object contains a valid shared data reference, the
156 /// reference count on the data will be decremented, and if zero,
157 /// the data will be freed.
158 //------------------------------------------------------------------
161 //------------------------------------------------------------------
162 /// Clears the object state.
164 /// Clears the object contents back to a default invalid state, and
165 /// release any references to shared data that this object may
167 //------------------------------------------------------------------
171 //------------------------------------------------------------------
172 /// Dumps the binary data as \a type objects to stream \a s (or to
173 /// Log() if \a s is NULL) starting \a offset bytes into the data
174 /// and stopping after dumping \a length bytes. The offset into the
175 /// data is displayed at the beginning of each line and can be
176 /// offset by base address \a base_addr. \a num_per_line objects
177 /// will be displayed on each line.
180 /// The stream to dump the output to. If NULL the output will
181 /// be dumped to Log().
183 /// @param[in] offset
184 /// The offset into the data at which to start dumping.
186 /// @param[in] length
187 /// The number of bytes to dump.
189 /// @param[in] base_addr
190 /// The base address that gets added to the offset displayed on
193 /// @param[in] num_per_line
194 /// The number of \a type objects to display on each line.
197 /// The type of objects to use when dumping data from this
198 /// object. See DataExtractor::Type.
200 /// @param[in] type_format
201 /// The optional format to use for the \a type objects. If this
202 /// is NULL, the default format for the \a type will be used.
205 /// The offset at which dumping ended.
206 //------------------------------------------------------------------
209 lldb::offset_t offset,
210 lldb::offset_t length,
212 uint32_t num_per_line,
214 const char *type_format = NULL) const;
216 //------------------------------------------------------------------
217 /// Dumps \a item_count objects into the stream \a s.
219 /// Dumps \a item_count objects using \a item_format, each of which
220 /// are \a item_byte_size bytes long starting at offset \a offset
221 /// bytes into the contained data, into the stream \a s. \a
222 /// num_per_line objects will be dumped on each line before a new
223 /// line will be output. If \a base_addr is a valid address, then
224 /// each new line of output will be prededed by the address value
225 /// plus appropriate offset, and a colon and space. Bitfield values
226 /// can be dumped by calling this function multiple times with the
227 /// same start offset, format and size, yet differing \a
228 /// item_bit_size and \a item_bit_offset values.
231 /// The stream to dump the output to. This value can not be NULL.
233 /// @param[in] offset
234 /// The offset into the data at which to start dumping.
236 /// @param[in] item_format
237 /// The format to use when dumping each item.
239 /// @param[in] item_byte_size
240 /// The byte size of each item.
242 /// @param[in] item_count
243 /// The number of items to dump.
245 /// @param[in] num_per_line
246 /// The number of items to display on each line.
248 /// @param[in] base_addr
249 /// The base address that gets added to the offset displayed on
250 /// each line if the value is valid. Is \a base_addr is
251 /// LLDB_INVALID_ADDRESS then no address values will be prepended
254 /// @param[in] item_bit_size
255 /// If the value to display is a bitfield, this value should
256 /// be the number of bits that the bitfield item has within the
257 /// item's byte size value. This function will need to be called
258 /// multiple times with identical \a offset and \a item_byte_size
259 /// values in order to display multiple bitfield values that
260 /// exist within the same integer value. If the items being
261 /// displayed are not bitfields, this value should be zero.
263 /// @param[in] item_bit_offset
264 /// If the value to display is a bitfield, this value should
265 /// be the offset in bits, or shift right amount, that the
266 /// bitfield item occupies within the item's byte size value.
267 /// This function will need to be called multiple times with
268 /// identical \a offset and \a item_byte_size values in order
269 /// to display multiple bitfield values that exist within the
270 /// same integer value. If the items being displayed are not
271 /// bitfields, this value should be zero.
274 /// The offset at which dumping ended.
275 //------------------------------------------------------------------
278 lldb::offset_t offset,
279 lldb::Format item_format,
280 size_t item_byte_size,
284 uint32_t item_bit_size,
285 uint32_t item_bit_offset,
286 ExecutionContextScope *exe_scope = NULL) const;
288 //------------------------------------------------------------------
289 /// Dump a UUID value at \a offset.
291 /// Dump a UUID starting at \a offset bytes into this object's data.
292 /// If the stream \a s is NULL, the output will be sent to Log().
295 /// The stream to dump the output to. If NULL the output will
296 /// be dumped to Log().
298 /// @param[in] offset
299 /// The offset into the data at which to extract and dump a
301 //------------------------------------------------------------------
303 DumpUUID (Stream *s, lldb::offset_t offset) const;
305 //------------------------------------------------------------------
306 /// Extract an arbitrary number of bytes in the specified byte
309 /// Attemps to extract \a length bytes starting at \a offset bytes
310 /// into this data in the requested byte order (\a dst_byte_order)
311 /// and place the results in \a dst. \a dst must be at least \a
312 /// length bytes long.
314 /// @param[in] offset
315 /// The offset in bytes into the contained data at which to
316 /// start extracting.
318 /// @param[in] length
319 /// The number of bytes to extract.
321 /// @param[in] dst_byte_order
322 /// A byte order of the data that we want when the value in
323 /// copied to \a dst.
326 /// The buffer that will receive the extracted value if there
327 /// are enough bytes available in the current data.
330 /// The number of bytes that were extracted which will be \a
331 /// length when the value is successfully extracted, or zero
332 /// if there aren't enough bytes at the specified offset.
333 //------------------------------------------------------------------
335 ExtractBytes (lldb::offset_t offset, lldb::offset_t length, lldb::ByteOrder dst_byte_order, void *dst) const;
337 //------------------------------------------------------------------
338 /// Extract an address from \a *offset_ptr.
340 /// Extract a single address from the data and update the offset
341 /// pointed to by \a offset_ptr. The size of the extracted address
342 /// comes from the \a m_addr_size member variable and should be
343 /// set correctly prior to extracting any address values.
345 /// @param[in,out] offset_ptr
346 /// A pointer to an offset within the data that will be advanced
347 /// by the appropriate number of bytes if the value is extracted
348 /// correctly. If the offset is out of bounds or there are not
349 /// enough bytes to extract this value, the offset will be left
353 /// The extracted address value.
354 //------------------------------------------------------------------
356 GetAddress (lldb::offset_t *offset_ptr) const;
359 GetAddress_unchecked (lldb::offset_t *offset_ptr) const;
361 //------------------------------------------------------------------
362 /// Get the current address size.
364 /// Return the size in bytes of any address values this object will
368 /// The size in bytes of address values that will be extracted.
369 //------------------------------------------------------------------
371 GetAddressByteSize () const
376 //------------------------------------------------------------------
377 /// Get the number of bytes contained in this object.
380 /// The total number of bytes of data this object refers to.
381 //------------------------------------------------------------------
385 return m_end - m_start;
388 //------------------------------------------------------------------
389 /// Extract a C string from \a *offset_ptr.
391 /// Returns a pointer to a C String from the data at the offset
392 /// pointed to by \a offset_ptr. A variable length NULL terminated C
393 /// string will be extracted and the \a offset_ptr will be
394 /// updated with the offset of the byte that follows the NULL
397 /// @param[in,out] offset_ptr
398 /// A pointer to an offset within the data that will be advanced
399 /// by the appropriate number of bytes if the value is extracted
400 /// correctly. If the offset is out of bounds or there are not
401 /// enough bytes to extract this value, the offset will be left
405 /// A pointer to the C string value in the data. If the offset
406 /// pointed to by \a offset_ptr is out of bounds, or if the
407 /// offset plus the length of the C string is out of bounds,
408 /// NULL will be returned.
409 //------------------------------------------------------------------
411 GetCStr (lldb::offset_t *offset_ptr) const;
413 //------------------------------------------------------------------
414 /// Extract a C string from \a *offset_ptr with field size \a len.
416 /// Returns a pointer to a C String from the data at the offset
417 /// pointed to by \a offset_ptr, with a field length of \a len.
418 /// A NULL terminated C string will be extracted and the \a offset_ptr
419 /// will be updated with the offset of the byte that follows the fixed
422 /// @param[in,out] offset_ptr
423 /// A pointer to an offset within the data that will be advanced
424 /// by the appropriate number of bytes if the value is extracted
425 /// correctly. If the offset is out of bounds or there are not
426 /// enough bytes to extract this value, the offset will be left
430 /// A pointer to the C string value in the data. If the offset
431 /// pointed to by \a offset_ptr is out of bounds, or if the
432 /// offset plus the length of the field is out of bounds, or if
433 /// the field does not contain a NULL terminator byte, NULL will
436 GetCStr (lldb::offset_t *offset_ptr, lldb::offset_t len) const;
438 //------------------------------------------------------------------
439 /// Extract \a length bytes from \a *offset_ptr.
441 /// Returns a pointer to a bytes in this object's data at the offset
442 /// pointed to by \a offset_ptr. If \a length is zero or too large,
443 /// then the offset pointed to by \a offset_ptr will not be updated
444 /// and NULL will be returned.
446 /// @param[in,out] offset_ptr
447 /// A pointer to an offset within the data that will be advanced
448 /// by the appropriate number of bytes if the value is extracted
449 /// correctly. If the offset is out of bounds or there are not
450 /// enough bytes to extract this value, the offset will be left
453 /// @param[in] length
454 /// The optional length of a string to extract. If the value is
455 /// zero, a NULL terminated C string will be extracted.
458 /// A pointer to the bytes in this object's data if the offset
459 /// and length are valid, or NULL otherwise.
460 //------------------------------------------------------------------
462 GetData (lldb::offset_t *offset_ptr, lldb::offset_t length) const
464 const uint8_t *ptr = PeekData (*offset_ptr, length);
466 *offset_ptr += length;
470 //------------------------------------------------------------------
471 /// Copy \a length bytes from \a *offset, without swapping bytes.
473 /// @param[in] offset
474 /// The offset into this data from which to start copying
476 /// @param[in] length
477 /// The length of the data to copy from this object
480 /// The buffer to place the output data.
483 /// Returns the number of bytes that were copied, or zero if
484 /// anything goes wrong.
485 //------------------------------------------------------------------
487 CopyData (lldb::offset_t offset,
488 lldb::offset_t length,
491 //------------------------------------------------------------------
492 /// Copy \a dst_len bytes from \a *offset_ptr and ensure the copied
493 /// data is treated as a value that can be swapped to match the
494 /// specified byte order.
496 /// For values that are larger than the supported integer sizes,
497 /// this function can be used to extract data in a specified byte
498 /// order. It can also be used to copy a smaller integer value from
499 /// to a larger value. The extra bytes left over will be padded
500 /// correctly according to the byte order of this object and the
501 /// \a dst_byte_order. This can be very handy when say copying a
502 /// partial data value into a register.
504 /// @param[in] src_offset
505 /// The offset into this data from which to start copying an
508 /// @param[in] src_len
509 /// The length of the endian data to copy from this object
510 /// into the \a dst object
513 /// The buffer where to place the endian data. The data might
514 /// need to be byte swapped (and appropriately padded with
515 /// zeroes if \a src_len != \a dst_len) if \a dst_byte_order
516 /// does not match the byte order in this object.
518 /// @param[in] dst_len
519 /// The length number of bytes that the endian value will
520 /// occupy is \a dst.
522 /// @param[in] byte_order
523 /// The byte order that the endian value should be in the \a dst
527 /// Returns the number of bytes that were copied, or zero if
528 /// anything goes wrong.
529 //------------------------------------------------------------------
531 CopyByteOrderedData (lldb::offset_t src_offset,
532 lldb::offset_t src_len,
534 lldb::offset_t dst_len,
535 lldb::ByteOrder dst_byte_order) const;
537 //------------------------------------------------------------------
538 /// Get the data end pointer.
541 /// Returns a pointer to the next byte contained in this
542 /// object's data, or NULL of there is no data in this object.
543 //------------------------------------------------------------------
550 //------------------------------------------------------------------
551 /// Get the shared data offset.
553 /// Get the offset of the first byte of data in the shared data (if
557 /// If this object contains shared data, this function returns
558 /// the offset in bytes into that shared data, zero otherwise.
559 //------------------------------------------------------------------
561 GetSharedDataOffset () const;
563 //------------------------------------------------------------------
564 /// Get a the data start pointer.
567 /// Returns a pointer to the first byte contained in this
568 /// object's data, or NULL of there is no data in this object.
569 //------------------------------------------------------------------
571 GetDataStart () const
577 //------------------------------------------------------------------
578 /// Extract a float from \a *offset_ptr.
580 /// Extract a single float value.
582 /// @param[in,out] offset_ptr
583 /// A pointer to an offset within the data that will be advanced
584 /// by the appropriate number of bytes if the value is extracted
585 /// correctly. If the offset is out of bounds or there are not
586 /// enough bytes to extract this value, the offset will be left
590 /// The floating value that was extracted, or zero on failure.
591 //------------------------------------------------------------------
593 GetFloat (lldb::offset_t *offset_ptr) const;
596 GetDouble (lldb::offset_t *offset_ptr) const;
599 GetLongDouble (lldb::offset_t *offset_ptr) const;
601 //------------------------------------------------------------------
602 /// Extract a GNU encoded pointer value from \a *offset_ptr.
604 /// @param[in,out] offset_ptr
605 /// A pointer to an offset within the data that will be advanced
606 /// by the appropriate number of bytes if the value is extracted
607 /// correctly. If the offset is out of bounds or there are not
608 /// enough bytes to extract this value, the offset will be left
611 /// @param[in] eh_ptr_enc
612 /// The GNU pointer encoding type.
614 /// @param[in] pc_rel_addr
615 /// The PC relative address to use when the encoding is
616 /// \c DW_GNU_EH_PE_pcrel.
618 /// @param[in] text_addr
619 /// The text (code) relative address to use when the encoding is
620 /// \c DW_GNU_EH_PE_textrel.
622 /// @param[in] data_addr
623 /// The data relative address to use when the encoding is
624 /// \c DW_GNU_EH_PE_datarel.
627 /// The extracted GNU encoded pointer value.
628 //------------------------------------------------------------------
630 GetGNUEHPointer (lldb::offset_t *offset_ptr,
632 lldb::addr_t pc_rel_addr,
633 lldb::addr_t text_addr,
634 lldb::addr_t data_addr);
636 //------------------------------------------------------------------
637 /// Extract an integer of size \a byte_size from \a *offset_ptr.
639 /// Extract a single integer value and update the offset pointed to
640 /// by \a offset_ptr. The size of the extracted integer is specified
641 /// by the \a byte_size argument. \a byte_size should have a value
642 /// >= 1 and <= 4 since the return value is only 32 bits wide. Any
643 /// \a byte_size values less than 1 or greater than 4 will result in
644 /// nothing being extracted, and zero being returned.
646 /// @param[in,out] offset_ptr
647 /// A pointer to an offset within the data that will be advanced
648 /// by the appropriate number of bytes if the value is extracted
649 /// correctly. If the offset is out of bounds or there are not
650 /// enough bytes to extract this value, the offset will be left
653 /// @param[in] byte_size
654 /// The size in byte of the integer to extract.
657 /// The integer value that was extracted, or zero on failure.
658 //------------------------------------------------------------------
660 GetMaxU32 (lldb::offset_t *offset_ptr, size_t byte_size) const;
662 //------------------------------------------------------------------
663 /// Extract an unsigned integer of size \a byte_size from \a
666 /// Extract a single unsigned integer value and update the offset
667 /// pointed to by \a offset_ptr. The size of the extracted integer
668 /// is specified by the \a byte_size argument. \a byte_size should
669 /// have a value greater than or equal to one and less than or equal
670 /// to eight since the return value is 64 bits wide. Any
671 /// \a byte_size values less than 1 or greater than 8 will result in
672 /// nothing being extracted, and zero being returned.
674 /// @param[in,out] offset_ptr
675 /// A pointer to an offset within the data that will be advanced
676 /// by the appropriate number of bytes if the value is extracted
677 /// correctly. If the offset is out of bounds or there are not
678 /// enough bytes to extract this value, the offset will be left
681 /// @param[in] byte_size
682 /// The size in byte of the integer to extract.
685 /// The unsigned integer value that was extracted, or zero on
687 //------------------------------------------------------------------
689 GetMaxU64 (lldb::offset_t *offset_ptr, size_t byte_size) const;
692 GetMaxU64_unchecked (lldb::offset_t *offset_ptr, size_t byte_size) const;
694 //------------------------------------------------------------------
695 /// Extract an signed integer of size \a byte_size from \a *offset_ptr.
697 /// Extract a single signed integer value (sign extending if required)
698 /// and update the offset pointed to by \a offset_ptr. The size of
699 /// the extracted integer is specified by the \a byte_size argument.
700 /// \a byte_size should have a value greater than or equal to one
701 /// and less than or equal to eight since the return value is 64
702 /// bits wide. Any \a byte_size values less than 1 or greater than
703 /// 8 will result in nothing being extracted, and zero being returned.
705 /// @param[in,out] offset_ptr
706 /// A pointer to an offset within the data that will be advanced
707 /// by the appropriate number of bytes if the value is extracted
708 /// correctly. If the offset is out of bounds or there are not
709 /// enough bytes to extract this value, the offset will be left
712 /// @param[in] byte_size
713 /// The size in byte of the integer to extract.
716 /// The sign extended signed integer value that was extracted,
717 /// or zero on failure.
718 //------------------------------------------------------------------
720 GetMaxS64 (lldb::offset_t *offset_ptr, size_t size) const;
722 //------------------------------------------------------------------
723 /// Extract an unsigned integer of size \a byte_size from \a
724 /// *offset_ptr, then extract the bitfield from this value if
725 /// \a bitfield_bit_size is non-zero.
727 /// Extract a single unsigned integer value and update the offset
728 /// pointed to by \a offset_ptr. The size of the extracted integer
729 /// is specified by the \a byte_size argument. \a byte_size should
730 /// have a value greater than or equal to one and less than or equal
731 /// to 8 since the return value is 64 bits wide. Any
732 /// \a byte_size values less than 1 or greater than 8 will result in
733 /// nothing being extracted, and zero being returned.
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
742 /// @param[in] byte_size
743 /// The size in byte of the integer to extract.
745 /// @param[in] bitfield_bit_size
746 /// The size in bits of the bitfield value to extract, or zero
747 /// to just extract the entire integer value.
749 /// @param[in] bitfield_bit_offset
750 /// The bit offset of the bitfield value in the extracted
751 /// integer (the number of bits to shift the integer to the
755 /// The unsigned bitfield integer value that was extracted, or
757 //------------------------------------------------------------------
759 GetMaxU64Bitfield (lldb::offset_t *offset_ptr,
761 uint32_t bitfield_bit_size,
762 uint32_t bitfield_bit_offset) const;
764 //------------------------------------------------------------------
765 /// Extract an signed integer of size \a byte_size from \a
766 /// *offset_ptr, then extract and signe extend the bitfield from
767 /// this value if \a bitfield_bit_size is non-zero.
769 /// Extract a single signed integer value (sign extending if required)
770 /// and update the offset pointed to by \a offset_ptr. The size of
771 /// the extracted integer is specified by the \a byte_size argument.
772 /// \a byte_size should have a value greater than or equal to one
773 /// and less than or equal to eight since the return value is 64
774 /// bits wide. Any \a byte_size values less than 1 or greater than
775 /// 8 will result in nothing being extracted, and zero being returned.
777 /// @param[in,out] offset_ptr
778 /// A pointer to an offset within the data that will be advanced
779 /// by the appropriate number of bytes if the value is extracted
780 /// correctly. If the offset is out of bounds or there are not
781 /// enough bytes to extract this value, the offset will be left
784 /// @param[in] byte_size
785 /// The size in bytes of the integer to extract.
787 /// @param[in] bitfield_bit_size
788 /// The size in bits of the bitfield value to extract, or zero
789 /// to just extract the entire integer value.
791 /// @param[in] bitfield_bit_offset
792 /// The bit offset of the bitfield value in the extracted
793 /// integer (the number of bits to shift the integer to the
797 /// The signed bitfield integer value that was extracted, or
799 //------------------------------------------------------------------
801 GetMaxS64Bitfield (lldb::offset_t *offset_ptr,
803 uint32_t bitfield_bit_size,
804 uint32_t bitfield_bit_offset) const;
806 //------------------------------------------------------------------
807 /// Extract an pointer from \a *offset_ptr.
809 /// Extract a single pointer from the data and update the offset
810 /// pointed to by \a offset_ptr. The size of the extracted pointer
811 /// comes from the \a m_addr_size member variable and should be
812 /// set correctly prior to extracting any pointer values.
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 pointer value as a 64 integer.
823 //------------------------------------------------------------------
825 GetPointer (lldb::offset_t *offset_ptr) const;
827 //------------------------------------------------------------------
828 /// Get the current byte order value.
831 /// The current byte order value from this object's internal
833 //------------------------------------------------------------------
840 //------------------------------------------------------------------
841 /// Extract a uint8_t value from \a *offset_ptr.
843 /// Extract a single uint8_t from the binary data at the offset
844 /// pointed to by \a offset_ptr, and advance the offset on success.
846 /// @param[in,out] offset_ptr
847 /// A pointer to an offset within the data that will be advanced
848 /// by the appropriate number of bytes if the value is extracted
849 /// correctly. If the offset is out of bounds or there are not
850 /// enough bytes to extract this value, the offset will be left
854 /// The extracted uint8_t value.
855 //------------------------------------------------------------------
857 GetU8 ( lldb::offset_t *offset_ptr) const;
860 GetU8_unchecked (lldb::offset_t *offset_ptr) const
862 uint8_t val = m_start[*offset_ptr];
868 GetU16_unchecked (lldb::offset_t *offset_ptr) const;
871 GetU32_unchecked (lldb::offset_t *offset_ptr) const;
874 GetU64_unchecked (lldb::offset_t *offset_ptr) const;
875 //------------------------------------------------------------------
876 /// Extract \a count uint8_t values from \a *offset_ptr.
878 /// Extract \a count uint8_t values from the binary data at the
879 /// offset pointed to by \a offset_ptr, and advance the offset on
880 /// success. The extracted values are copied into \a dst.
882 /// @param[in,out] offset_ptr
883 /// A pointer to an offset within the data that will be advanced
884 /// by the appropriate number of bytes if the value is extracted
885 /// correctly. If the offset is out of bounds or there are not
886 /// enough bytes to extract this value, the offset will be left
890 /// A buffer to copy \a count uint8_t values into. \a dst must
891 /// be large enough to hold all requested data.
894 /// The number of uint8_t values to extract.
897 /// \a dst if all values were properly extracted and copied,
899 //------------------------------------------------------------------
901 GetU8 (lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
903 //------------------------------------------------------------------
904 /// Extract a uint16_t value from \a *offset_ptr.
906 /// Extract a single uint16_t from the binary data at the offset
907 /// pointed to by \a offset_ptr, and update the offset on success.
909 /// @param[in,out] offset_ptr
910 /// A pointer to an offset within the data that will be advanced
911 /// by the appropriate number of bytes if the value is extracted
912 /// correctly. If the offset is out of bounds or there are not
913 /// enough bytes to extract this value, the offset will be left
917 /// The extracted uint16_t value.
918 //------------------------------------------------------------------
920 GetU16 (lldb::offset_t *offset_ptr) const;
922 //------------------------------------------------------------------
923 /// Extract \a count uint16_t values from \a *offset_ptr.
925 /// Extract \a count uint16_t values from the binary data at the
926 /// offset pointed to by \a offset_ptr, and advance the offset on
927 /// success. The extracted values are copied into \a dst.
929 /// @param[in,out] offset_ptr
930 /// A pointer to an offset within the data that will be advanced
931 /// by the appropriate number of bytes if the value is extracted
932 /// correctly. If the offset is out of bounds or there are not
933 /// enough bytes to extract this value, the offset will be left
937 /// A buffer to copy \a count uint16_t values into. \a dst must
938 /// be large enough to hold all requested data.
941 /// The number of uint16_t values to extract.
944 /// \a dst if all values were properly extracted and copied,
946 //------------------------------------------------------------------
948 GetU16 (lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
950 //------------------------------------------------------------------
951 /// Extract a uint32_t value from \a *offset_ptr.
953 /// Extract a single uint32_t from the binary data at the offset
954 /// pointed to by \a offset_ptr, and update the offset on success.
956 /// @param[in,out] offset_ptr
957 /// A pointer to an offset within the data that will be advanced
958 /// by the appropriate number of bytes if the value is extracted
959 /// correctly. If the offset is out of bounds or there are not
960 /// enough bytes to extract this value, the offset will be left
964 /// The extracted uint32_t value.
965 //------------------------------------------------------------------
967 GetU32 (lldb::offset_t *offset_ptr) const;
969 //------------------------------------------------------------------
970 /// Extract \a count uint32_t values from \a *offset_ptr.
972 /// Extract \a count uint32_t values from the binary data at the
973 /// offset pointed to by \a offset_ptr, and advance the offset on
974 /// success. The extracted values are copied into \a dst.
976 /// @param[in,out] offset_ptr
977 /// A pointer to an offset within the data that will be advanced
978 /// by the appropriate number of bytes if the value is extracted
979 /// correctly. If the offset is out of bounds or there are not
980 /// enough bytes to extract this value, the offset will be left
984 /// A buffer to copy \a count uint32_t values into. \a dst must
985 /// be large enough to hold all requested data.
988 /// The number of uint32_t values to extract.
991 /// \a dst if all values were properly extracted and copied,
993 //------------------------------------------------------------------
995 GetU32 (lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
997 //------------------------------------------------------------------
998 /// Extract a uint64_t value from \a *offset_ptr.
1000 /// Extract a single uint64_t from the binary data at the offset
1001 /// pointed to by \a offset_ptr, and update the offset on success.
1003 /// @param[in,out] offset_ptr
1004 /// A pointer to an offset within the data that will be advanced
1005 /// by the appropriate number of bytes if the value is extracted
1006 /// correctly. If the offset is out of bounds or there are not
1007 /// enough bytes to extract this value, the offset will be left
1011 /// The extracted uint64_t value.
1012 //------------------------------------------------------------------
1014 GetU64 (lldb::offset_t *offset_ptr) const;
1016 //------------------------------------------------------------------
1017 /// Extract \a count uint64_t values from \a *offset_ptr.
1019 /// Extract \a count uint64_t values from the binary data at the
1020 /// offset pointed to by \a offset_ptr, and advance the offset on
1021 /// success. The extracted values are copied into \a dst.
1023 /// @param[in,out] offset_ptr
1024 /// A pointer to an offset within the data that will be advanced
1025 /// by the appropriate number of bytes if the value is extracted
1026 /// correctly. If the offset is out of bounds or there are not
1027 /// enough bytes to extract this value, the offset will be left
1031 /// A buffer to copy \a count uint64_t values into. \a dst must
1032 /// be large enough to hold all requested data.
1034 /// @param[in] count
1035 /// The number of uint64_t values to extract.
1038 /// \a dst if all values were properly extracted and copied,
1040 //------------------------------------------------------------------
1042 GetU64 ( lldb::offset_t *offset_ptr, void *dst, uint32_t count) const;
1044 //------------------------------------------------------------------
1045 /// Extract a signed LEB128 value from \a *offset_ptr.
1047 /// Extracts an signed LEB128 number from this object's data
1048 /// starting at the offset pointed to by \a offset_ptr. The offset
1049 /// pointed to by \a offset_ptr will be updated with the offset of
1050 /// the byte following the last extracted byte.
1052 /// @param[in,out] offset_ptr
1053 /// A pointer to an offset within the data that will be advanced
1054 /// by the appropriate number of bytes if the value is extracted
1055 /// correctly. If the offset is out of bounds or there are not
1056 /// enough bytes to extract this value, the offset will be left
1060 /// The extracted signed integer value.
1061 //------------------------------------------------------------------
1063 GetSLEB128 (lldb::offset_t *offset_ptr) const;
1065 //------------------------------------------------------------------
1066 /// Extract a unsigned LEB128 value from \a *offset_ptr.
1068 /// Extracts an unsigned LEB128 number from this object's data
1069 /// starting at the offset pointed to by \a offset_ptr. The offset
1070 /// pointed to by \a offset_ptr will be updated with the offset of
1071 /// the byte following the last extracted byte.
1073 /// @param[in,out] offset_ptr
1074 /// A pointer to an offset within the data that will be advanced
1075 /// by the appropriate number of bytes if the value is extracted
1076 /// correctly. If the offset is out of bounds or there are not
1077 /// enough bytes to extract this value, the offset will be left
1081 /// The extracted unsigned integer value.
1082 //------------------------------------------------------------------
1084 GetULEB128 (lldb::offset_t *offset_ptr) const;
1086 lldb::DataBufferSP &
1087 GetSharedDataBuffer ()
1092 //------------------------------------------------------------------
1093 /// Peek at a C string at \a offset.
1095 /// Peeks at a string in the contained data. No verification is done
1096 /// to make sure the entire string lies within the bounds of this
1097 /// object's data, only \a offset is verified to be a valid offset.
1099 /// @param[in] offset
1100 /// An offset into the data.
1103 /// A non-NULL C string pointer if \a offset is a valid offset,
1105 //------------------------------------------------------------------
1107 PeekCStr (lldb::offset_t offset) const;
1109 //------------------------------------------------------------------
1110 /// Peek at a bytes at \a offset.
1112 /// Returns a pointer to \a length bytes at \a offset as long as
1113 /// there are \a length bytes available starting at \a offset.
1116 /// A non-NULL data pointer if \a offset is a valid offset and
1117 /// there are \a length bytes available at that offset, NULL
1119 //------------------------------------------------------------------
1121 PeekData (lldb::offset_t offset, lldb::offset_t length) const
1123 if (length > 0 && ValidOffsetForDataOfSize(offset, length))
1124 return m_start + offset;
1128 //------------------------------------------------------------------
1129 /// Set the address byte size.
1131 /// Set the size in bytes that will be used when extracting any
1132 /// address and pointer values from data contained in this object.
1134 /// @param[in] addr_size
1135 /// The size in bytes to use when extracting addresses.
1136 //------------------------------------------------------------------
1138 SetAddressByteSize (uint32_t addr_size)
1140 m_addr_size = addr_size;
1143 //------------------------------------------------------------------
1144 /// Set data with a buffer that is caller owned.
1146 /// Use data that is owned by the caller when extracting values.
1147 /// The data must stay around as long as this object, or any object
1148 /// that copies a subset of this object's data, is valid. If \a
1149 /// bytes is NULL, or \a length is zero, this object will contain
1152 /// @param[in] bytes
1153 /// A pointer to caller owned data.
1155 /// @param[in] length
1156 /// The length in bytes of \a bytes.
1158 /// @param[in] byte_order
1159 /// A byte order of the data that we are extracting from.
1162 /// The number of bytes that this object now contains.
1163 //------------------------------------------------------------------
1165 SetData (const void *bytes, lldb::offset_t length, lldb::ByteOrder byte_order);
1167 //------------------------------------------------------------------
1168 /// Adopt a subset of \a data.
1170 /// Set this object's data to be a subset of the data bytes in \a
1171 /// data. If \a data contains shared data, then a reference to the
1172 /// shared data will be added to ensure the shared data stays around
1173 /// as long as any objects have references to the shared data. The
1174 /// byte order and the address size settings are copied from \a
1175 /// data. If \a offset is not a valid offset in \a data, then no
1176 /// reference to the shared data will be added. If there are not
1177 /// \a length bytes available in \a data starting at \a offset,
1178 /// the length will be truncated to contains as many bytes as
1182 /// Another DataExtractor object that contains data.
1184 /// @param[in] offset
1185 /// The offset into \a data at which the subset starts.
1187 /// @param[in] length
1188 /// The length in bytes of the subset of \a data.
1191 /// The number of bytes that this object now contains.
1192 //------------------------------------------------------------------
1194 SetData (const DataExtractor& data, lldb::offset_t offset, lldb::offset_t length);
1196 //------------------------------------------------------------------
1197 /// Adopt a subset of shared data in \a data_sp.
1199 /// Copies the data shared pointer which adds a reference to the
1200 /// contained in \a data_sp. The shared data reference is reference
1201 /// counted to ensure the data lives as long as anyone still has a
1202 /// valid shared pointer to the data in \a data_sp. The byte order
1203 /// and address byte size settings remain the same. If
1204 /// \a offset is not a valid offset in \a data_sp, then no reference
1205 /// to the shared data will be added. If there are not \a length
1206 /// bytes available in \a data starting at \a offset, the length
1207 /// will be truncated to contains as many bytes as possible.
1209 /// @param[in] data_sp
1210 /// A shared pointer to data.
1212 /// @param[in] offset
1213 /// The offset into \a data_sp at which the subset starts.
1215 /// @param[in] length
1216 /// The length in bytes of the subset of \a data_sp.
1219 /// The number of bytes that this object now contains.
1220 //------------------------------------------------------------------
1222 SetData (const lldb::DataBufferSP& data_sp, lldb::offset_t offset = 0, lldb::offset_t length = LLDB_INVALID_OFFSET);
1224 //------------------------------------------------------------------
1225 /// Set the byte_order value.
1227 /// Sets the byte order of the data to extract. Extracted values
1228 /// will be swapped if necessary when decoding.
1230 /// @param[in] byte_order
1231 /// The byte order value to use when extracting data.
1232 //------------------------------------------------------------------
1234 SetByteOrder (lldb::ByteOrder byte_order)
1236 m_byte_order = byte_order;
1239 //------------------------------------------------------------------
1240 /// Skip an LEB128 number at \a *offset_ptr.
1242 /// Skips a LEB128 number (signed or unsigned) from this object's
1243 /// data starting at the offset pointed to by \a offset_ptr. The
1244 /// offset pointed to by \a offset_ptr will be updated with the
1245 /// offset of the byte following the last extracted byte.
1247 /// @param[in,out] offset_ptr
1248 /// A pointer to an offset within the data that will be advanced
1249 /// by the appropriate number of bytes if the value is extracted
1250 /// correctly. If the offset is out of bounds or there are not
1251 /// enough bytes to extract this value, the offset will be left
1255 // The number of bytes consumed during the extraction.
1256 //------------------------------------------------------------------
1258 Skip_LEB128 (lldb::offset_t *offset_ptr) const;
1260 //------------------------------------------------------------------
1261 /// Test the validity of \a offset.
1264 /// \b true if \a offset is a valid offset into the data in this
1265 /// object, \b false otherwise.
1266 //------------------------------------------------------------------
1268 ValidOffset (lldb::offset_t offset) const
1270 return offset < GetByteSize();
1273 //------------------------------------------------------------------
1274 /// Test the availability of \a length bytes of data from \a offset.
1277 /// \b true if \a offset is a valid offset and there are \a
1278 /// length bytes available at that offset, \b false otherwise.
1279 //------------------------------------------------------------------
1281 ValidOffsetForDataOfSize (lldb::offset_t offset, lldb::offset_t length) const
1283 return length <= BytesLeft (offset);
1287 Copy (DataExtractor& dest_data) const;
1290 Append (DataExtractor& rhs);
1293 Append (void* bytes, lldb::offset_t length);
1296 BytesLeft (lldb::offset_t offset) const
1298 const lldb::offset_t size = GetByteSize();
1300 return size - offset;
1306 //------------------------------------------------------------------
1308 //------------------------------------------------------------------
1309 const uint8_t * m_start; ///< A pointer to the first byte of data.
1310 const uint8_t * m_end; ///< A pointer to the byte that is past the end of the data.
1311 lldb::ByteOrder m_byte_order; ///< The byte order of the data we are extracting from.
1312 uint32_t m_addr_size; ///< The address size to use when extracting pointers or addresses
1313 mutable lldb::DataBufferSP m_data_sp; ///< The shared pointer to data that can be shared among multilple instances
1316 } // namespace lldb_private
1318 #endif // #if defined (__cplusplus)
1319 #endif // #ifndef liblldb_DataExtractor_h_