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