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