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

source code of lldb/include/lldb/Utility/DataExtractor.h