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 |
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 | |
25 | namespace lldb_private { |
26 | class Log; |
27 | class Stream; |
28 | } |
29 | namespace llvm { |
30 | template <typename T> class SmallVectorImpl; |
31 | } |
32 | |
33 | |
34 | namespace 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 |
48 | class { |
49 | public: |
50 | /// \typedef DataExtractor::Type |
51 | /// Type enumerations used in the dump routines. |
52 | enum { |
53 | , ///< Format output as unsigned 8 bit integers |
54 | , ///< Format output as characters |
55 | , ///< Format output as unsigned 16 bit integers |
56 | , ///< Format output as unsigned 32 bit integers |
57 | , ///< Format output as unsigned 64 bit integers |
58 | , ///< Format output as pointers |
59 | , ///< Format output as ULEB128 numbers |
60 | ///< Format output as SLEB128 numbers |
61 | }; |
62 | |
63 | /// Default constructor. |
64 | /// |
65 | /// Initialize all members to a default empty state. |
66 | (); |
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 | (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 | (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 | (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 (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 &(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 &&rhs) = default; |
161 | DataExtractor &(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 (); |
169 | |
170 | uint32_t () 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 (); |
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 (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 (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 (lldb::offset_t *offset_ptr) const; |
255 | |
256 | uint64_t (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 () 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 () 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 *(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 *(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 *(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 (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 (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 *() 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 () 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 *() 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 (lldb::offset_t *offset_ptr) const; |
438 | |
439 | double (lldb::offset_t *offset_ptr) const; |
440 | |
441 | long double (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 (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 (lldb::offset_t *offset_ptr, size_t byte_size) const; |
486 | |
487 | uint64_t (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 (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 (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 (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 () 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 (lldb::offset_t *offset_ptr) const; |
611 | |
612 | uint8_t (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 (lldb::offset_t *offset_ptr) const; |
619 | |
620 | uint32_t (lldb::offset_t *offset_ptr) const; |
621 | |
622 | uint64_t (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 *(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 (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 *(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 (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 *(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 (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 *(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 (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 (lldb::offset_t *offset_ptr) const; |
806 | |
807 | lldb::DataBufferSP &() { 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 *(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 *(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 (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 (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 (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 (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 (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 (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 (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 (lldb::offset_t offset, |
964 | lldb::offset_t length) const { |
965 | return length <= BytesLeft(offset); |
966 | } |
967 | |
968 | size_t (DataExtractor &dest_data) const; |
969 | |
970 | bool (DataExtractor &rhs); |
971 | |
972 | bool (void *bytes, lldb::offset_t length); |
973 | |
974 | lldb::offset_t (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 (llvm::SmallVectorImpl<uint8_t> &dest, uint64_t max_data = 0); |
982 | |
983 | llvm::ArrayRef<uint8_t> () const { |
984 | return {GetDataStart(), size_t(GetByteSize())}; |
985 | } |
986 | |
987 | llvm::DataExtractor () const { |
988 | return {GetData(), GetByteOrder() == lldb::eByteOrderLittle, |
989 | uint8_t(GetAddressByteSize())}; |
990 | } |
991 | |
992 | protected: |
993 | template <typename T> T (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 * = nullptr; ///< A pointer to the first byte of data. |
1010 | const uint8_t * = |
1011 | nullptr; ///< A pointer to the byte that is past the end of the data. |
1012 | lldb::ByteOrder |
1013 | ; ///< The byte order of the data we are extracting from. |
1014 | uint32_t ; ///< The address size to use when extracting addresses. |
1015 | /// The shared pointer to data that can be shared among multiple instances |
1016 | lldb::DataBufferSP ; |
1017 | /// Making it const would require implementation of move assignment operator. |
1018 | uint32_t = 1; |
1019 | }; |
1020 | |
1021 | } // namespace lldb_private |
1022 | |
1023 | #endif // LLDB_UTILITY_DATAEXTRACTOR_H |
1024 | |