1 //===-- DataExtractor.h -----------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef LLVM_SUPPORT_DATAEXTRACTOR_H
11 #define LLVM_SUPPORT_DATAEXTRACTOR_H
13 #include "llvm/ADT/StringRef.h"
14 #include "llvm/Support/DataTypes.h"
19 uint8_t IsLittleEndian;
22 /// Construct with a buffer that is owned by the caller.
24 /// This constructor allows us to use data that is owned by the
25 /// caller. The data must stay around as long as this object is
27 DataExtractor(StringRef Data, bool IsLittleEndian, uint8_t PointerSize)
28 : Data(Data), IsLittleEndian(IsLittleEndian), PointerSize(PointerSize) {}
30 /// getData - Get the data pointed to by this extractor.
31 StringRef getData() const { return Data; }
32 /// isLittleEndian - Get the endianess for this extractor.
33 bool isLittleEndian() const { return IsLittleEndian; }
34 /// getAddressSize - Get the address size for this extractor.
35 uint8_t getAddressSize() const { return PointerSize; }
37 /// Extract a C string from \a *offset_ptr.
39 /// Returns a pointer to a C String from the data at the offset
40 /// pointed to by \a offset_ptr. A variable length NULL terminated C
41 /// string will be extracted and the \a offset_ptr will be
42 /// updated with the offset of the byte that follows the NULL
45 /// @param[in,out] offset_ptr
46 /// A pointer to an offset within the data that will be advanced
47 /// by the appropriate number of bytes if the value is extracted
48 /// correctly. If the offset is out of bounds or there are not
49 /// enough bytes to extract this value, the offset will be left
53 /// A pointer to the C string value in the data. If the offset
54 /// pointed to by \a offset_ptr is out of bounds, or if the
55 /// offset plus the length of the C string is out of bounds,
56 /// NULL will be returned.
57 const char *getCStr(uint32_t *offset_ptr) const;
59 /// Extract an unsigned integer of size \a byte_size from \a
62 /// Extract a single unsigned integer value and update the offset
63 /// pointed to by \a offset_ptr. The size of the extracted integer
64 /// is specified by the \a byte_size argument. \a byte_size should
65 /// have a value greater than or equal to one and less than or equal
66 /// to eight since the return value is 64 bits wide. Any
67 /// \a byte_size values less than 1 or greater than 8 will result in
68 /// nothing being extracted, and zero being returned.
70 /// @param[in,out] offset_ptr
71 /// A pointer to an offset within the data that will be advanced
72 /// by the appropriate number of bytes if the value is extracted
73 /// correctly. If the offset is out of bounds or there are not
74 /// enough bytes to extract this value, the offset will be left
77 /// @param[in] byte_size
78 /// The size in byte of the integer to extract.
81 /// The unsigned integer value that was extracted, or zero on
83 uint64_t getUnsigned(uint32_t *offset_ptr, uint32_t byte_size) const;
85 /// Extract an signed integer of size \a byte_size from \a *offset_ptr.
87 /// Extract a single signed integer value (sign extending if required)
88 /// and update the offset pointed to by \a offset_ptr. The size of
89 /// the extracted integer is specified by the \a byte_size argument.
90 /// \a byte_size should have a value greater than or equal to one
91 /// and less than or equal to eight since the return value is 64
92 /// bits wide. Any \a byte_size values less than 1 or greater than
93 /// 8 will result in nothing being extracted, and zero being returned.
95 /// @param[in,out] offset_ptr
96 /// A pointer to an offset within the data that will be advanced
97 /// by the appropriate number of bytes if the value is extracted
98 /// correctly. If the offset is out of bounds or there are not
99 /// enough bytes to extract this value, the offset will be left
102 /// @param[in] byte_size
103 /// The size in byte of the integer to extract.
106 /// The sign extended signed integer value that was extracted,
107 /// or zero on failure.
108 int64_t getSigned(uint32_t *offset_ptr, uint32_t size) const;
110 //------------------------------------------------------------------
111 /// Extract an pointer from \a *offset_ptr.
113 /// Extract a single pointer from the data and update the offset
114 /// pointed to by \a offset_ptr. The size of the extracted pointer
115 /// comes from the \a m_addr_size member variable and should be
116 /// set correctly prior to extracting any pointer values.
118 /// @param[in,out] offset_ptr
119 /// A pointer to an offset within the data that will be advanced
120 /// by the appropriate number of bytes if the value is extracted
121 /// correctly. If the offset is out of bounds or there are not
122 /// enough bytes to extract this value, the offset will be left
126 /// The extracted pointer value as a 64 integer.
127 uint64_t getAddress(uint32_t *offset_ptr) const {
128 return getUnsigned(offset_ptr, PointerSize);
131 /// Extract a uint8_t value from \a *offset_ptr.
133 /// Extract a single uint8_t from the binary data at the offset
134 /// pointed to by \a offset_ptr, and advance the offset on success.
136 /// @param[in,out] offset_ptr
137 /// A pointer to an offset within the data that will be advanced
138 /// by the appropriate number of bytes if the value is extracted
139 /// correctly. If the offset is out of bounds or there are not
140 /// enough bytes to extract this value, the offset will be left
144 /// The extracted uint8_t value.
145 uint8_t getU8(uint32_t *offset_ptr) const;
147 /// Extract \a count uint8_t values from \a *offset_ptr.
149 /// Extract \a count uint8_t values from the binary data at the
150 /// offset pointed to by \a offset_ptr, and advance the offset on
151 /// success. The extracted values are copied into \a dst.
153 /// @param[in,out] offset_ptr
154 /// A pointer to an offset within the data that will be advanced
155 /// by the appropriate number of bytes if the value is extracted
156 /// correctly. If the offset is out of bounds or there are not
157 /// enough bytes to extract this value, the offset will be left
161 /// A buffer to copy \a count uint8_t values into. \a dst must
162 /// be large enough to hold all requested data.
165 /// The number of uint8_t values to extract.
168 /// \a dst if all values were properly extracted and copied,
170 uint8_t *getU8(uint32_t *offset_ptr, uint8_t *dst, uint32_t count) const;
172 //------------------------------------------------------------------
173 /// Extract a uint16_t value from \a *offset_ptr.
175 /// Extract a single uint16_t from the binary data at the offset
176 /// pointed to by \a offset_ptr, and update the offset on success.
178 /// @param[in,out] offset_ptr
179 /// A pointer to an offset within the data that will be advanced
180 /// by the appropriate number of bytes if the value is extracted
181 /// correctly. If the offset is out of bounds or there are not
182 /// enough bytes to extract this value, the offset will be left
186 /// The extracted uint16_t value.
187 //------------------------------------------------------------------
188 uint16_t getU16(uint32_t *offset_ptr) const;
190 /// Extract \a count uint16_t values from \a *offset_ptr.
192 /// Extract \a count uint16_t values from the binary data at the
193 /// offset pointed to by \a offset_ptr, and advance the offset on
194 /// success. The extracted values are copied into \a dst.
196 /// @param[in,out] offset_ptr
197 /// A pointer to an offset within the data that will be advanced
198 /// by the appropriate number of bytes if the value is extracted
199 /// correctly. If the offset is out of bounds or there are not
200 /// enough bytes to extract this value, the offset will be left
204 /// A buffer to copy \a count uint16_t values into. \a dst must
205 /// be large enough to hold all requested data.
208 /// The number of uint16_t values to extract.
211 /// \a dst if all values were properly extracted and copied,
213 uint16_t *getU16(uint32_t *offset_ptr, uint16_t *dst, uint32_t count) const;
215 /// Extract a uint32_t value from \a *offset_ptr.
217 /// Extract a single uint32_t from the binary data at the offset
218 /// pointed to by \a offset_ptr, and update the offset on success.
220 /// @param[in,out] offset_ptr
221 /// A pointer to an offset within the data that will be advanced
222 /// by the appropriate number of bytes if the value is extracted
223 /// correctly. If the offset is out of bounds or there are not
224 /// enough bytes to extract this value, the offset will be left
228 /// The extracted uint32_t value.
229 uint32_t getU32(uint32_t *offset_ptr) const;
231 /// Extract \a count uint32_t values from \a *offset_ptr.
233 /// Extract \a count uint32_t values from the binary data at the
234 /// offset pointed to by \a offset_ptr, and advance the offset on
235 /// success. The extracted values are copied into \a dst.
237 /// @param[in,out] offset_ptr
238 /// A pointer to an offset within the data that will be advanced
239 /// by the appropriate number of bytes if the value is extracted
240 /// correctly. If the offset is out of bounds or there are not
241 /// enough bytes to extract this value, the offset will be left
245 /// A buffer to copy \a count uint32_t values into. \a dst must
246 /// be large enough to hold all requested data.
249 /// The number of uint32_t values to extract.
252 /// \a dst if all values were properly extracted and copied,
254 uint32_t *getU32(uint32_t *offset_ptr, uint32_t *dst, uint32_t count) const;
256 /// Extract a uint64_t value from \a *offset_ptr.
258 /// Extract a single uint64_t from the binary data at the offset
259 /// pointed to by \a offset_ptr, and update the offset on success.
261 /// @param[in,out] offset_ptr
262 /// A pointer to an offset within the data that will be advanced
263 /// by the appropriate number of bytes if the value is extracted
264 /// correctly. If the offset is out of bounds or there are not
265 /// enough bytes to extract this value, the offset will be left
269 /// The extracted uint64_t value.
270 uint64_t getU64(uint32_t *offset_ptr) const;
272 /// Extract \a count uint64_t values from \a *offset_ptr.
274 /// Extract \a count uint64_t values from the binary data at the
275 /// offset pointed to by \a offset_ptr, and advance the offset on
276 /// success. The extracted values are copied into \a dst.
278 /// @param[in,out] offset_ptr
279 /// A pointer to an offset within the data that will be advanced
280 /// by the appropriate number of bytes if the value is extracted
281 /// correctly. If the offset is out of bounds or there are not
282 /// enough bytes to extract this value, the offset will be left
286 /// A buffer to copy \a count uint64_t values into. \a dst must
287 /// be large enough to hold all requested data.
290 /// The number of uint64_t values to extract.
293 /// \a dst if all values were properly extracted and copied,
295 uint64_t *getU64(uint32_t *offset_ptr, uint64_t *dst, uint32_t count) const;
297 /// Extract a signed LEB128 value from \a *offset_ptr.
299 /// Extracts an signed LEB128 number from this object's data
300 /// starting at the offset pointed to by \a offset_ptr. The offset
301 /// pointed to by \a offset_ptr will be updated with the offset of
302 /// the byte following the last extracted byte.
304 /// @param[in,out] offset_ptr
305 /// A pointer to an offset within the data that will be advanced
306 /// by the appropriate number of bytes if the value is extracted
307 /// correctly. If the offset is out of bounds or there are not
308 /// enough bytes to extract this value, the offset will be left
312 /// The extracted signed integer value.
313 int64_t getSLEB128(uint32_t *offset_ptr) const;
315 /// Extract a unsigned LEB128 value from \a *offset_ptr.
317 /// Extracts an unsigned LEB128 number from this object's data
318 /// starting at the offset pointed to by \a offset_ptr. The offset
319 /// pointed to by \a offset_ptr will be updated with the offset of
320 /// the byte following the last extracted byte.
322 /// @param[in,out] offset_ptr
323 /// A pointer to an offset within the data that will be advanced
324 /// by the appropriate number of bytes if the value is extracted
325 /// correctly. If the offset is out of bounds or there are not
326 /// enough bytes to extract this value, the offset will be left
330 /// The extracted unsigned integer value.
331 uint64_t getULEB128(uint32_t *offset_ptr) const;
333 /// Test the validity of \a offset.
336 /// \b true if \a offset is a valid offset into the data in this
337 /// object, \b false otherwise.
338 bool isValidOffset(uint32_t offset) const { return Data.size() > offset; }
340 /// Test the availability of \a length bytes of data from \a offset.
343 /// \b true if \a offset is a valid offset and there are \a
344 /// length bytes available at that offset, \b false otherwise.
345 bool isValidOffsetForDataOfSize(uint32_t offset, uint32_t length) const {
346 return offset + length >= offset && isValidOffset(offset + length - 1);