Debian Codegraph @

libdrgn/binary_buffer.h

raw
1 // Copyright (c) Meta Platforms, Inc. and affiliates.
2 // SPDX-License-Identifier: LGPL-2.1-or-later
3
4 /**
5 * @file
6 *
7 * Binary format parsing.
8 *
9 * See @ref BinaryBuffer.
10 */
11
12 #ifndef DRGN_BINARY_BUFFER_H
13 #define DRGN_BINARY_BUFFER_H
14
15 #include <assert.h>
16 #include <byteswap.h>
17 #include <inttypes.h>
18 #include <stdbool.h>
19 #include <stddef.h>
20 #include <string.h>
21
22 #include "util.h"
23
24 /**
25 * @ingroup Internals
26 *
27 * @defgroup BinaryBuffer Binary buffer
28 *
29 * Binary format parsing.
30 *
31 * A @ref binary_buffer is a buffer for parsing binary data safely. It has a
32 * position (@ref binary_buffer::pos) and various functions to read from the
33 * current position and advance it.
34 *
35 * The `binary_buffer_next*` functions read a value from the buffer and advance
36 * the position past the read value. They return an error if the desired value
37 * is out of bounds of the buffer. They also save the previous position for
38 * error reporting (@ref binary_buffer::prev). On error, they do not advance the
39 * position or change the previous position.
40 *
41 * The `binary_buffer_skip*` functions are similar, except that they skip past
42 * unneeded data in the buffer and don't change the previous position.
43 *
44 * Errors are formatted through a callback (@ref binary_buffer_error_fn) which
45 * can provide information about, e.g., what file contained the bad data. The
46 * @ref binary_buffer can be embedded in a structure containing additional
47 * context.
48 *
49 * @{
50 */
51
52 struct binary_buffer;
53
54 /**
55 * Binary buffer error formatting function.
56 *
57 * @param[in] bb Buffer.
58 * @param[in] pos Position in the buffer where the error occurred.
59 * @param[in] message Error message.
60 */
61 typedef struct drgn_error *(*binary_buffer_error_fn)(struct binary_buffer *bb,
62 const char *pos,
63 const char *message);
64
65 /**
66 * Buffer of binary data to parse.
67 *
68 * In addition to the functions defined here, `pos`, `prev`, and `end` may be
69 * modified directly so long as `pos <= end && prev <= end` remains true.
70 */
71 struct binary_buffer {
72 /**
73 * Current position in the buffer.
74 *
75 * This is advanced by the `binary_buffer_next*` functions.
76 */
77 const char *pos;
78 /** Pointer to one byte after the last valid byte in the buffer. */
79 const char *end;
80 /**
81 * Position of the last accessed value.
82 *
83 * On success, the `binary_buffer_next*` functions set this to the
84 * position of the returned value (i.e., the position on entry). This is
85 * useful for reporting errors after validating a value that was just
86 * read.
87 *
88 * This is not updated by the `binary_buffer_skip*` functions.
89 */
90 const char *prev;
91 /** Whether the data is in the opposite byte order from the host. */
92 bool bswap;
93 /** Error formatting callback. */
94 binary_buffer_error_fn error_fn;
95 };
96
97 /**
98 * Initialize a @ref binary_buffer.
99 *
100 * @param[in] buf Pointer to data.
101 * @param[in] len Length of data in bytes.
102 * @param[in] little_endian Whether the data is little endian.
103 * @param[in] error_fn Error formatting callback.
104 */
105 static inline void binary_buffer_init(struct binary_buffer *bb, const void *buf,
106 size_t len, bool little_endian,
107 binary_buffer_error_fn error_fn)
108 {
109 bb->pos = buf;
110 bb->end = (const char *)buf + len;
111 bb->prev = NULL;
112 bb->bswap = little_endian != HOST_LITTLE_ENDIAN;
113 bb->error_fn = error_fn;
114 }
115
116 /**
117 * Report an error at the previous buffer position (@ref binary_buffer::prev).
118 */
119 struct drgn_error *binary_buffer_error(struct binary_buffer *bb,
120 const char *format, ...)
121 __attribute__((__returns_nonnull__, __format__(__printf__, 2, 3)));
122
123 /** Report an error at a given position in the buffer. */
124 struct drgn_error *binary_buffer_error_at(struct binary_buffer *bb,
125 const char *pos, const char *format,
126 ...)
127 __attribute__((__returns_nonnull__, __format__(__printf__, 3, 4)));
128
129 /**
130 * Return whether there are any bytes in the buffer after the current position.
131 *
132 * @return @c true if there bytes remaining, @c false if the position is at the
133 * end of the buffer.
134 */
135 static inline bool binary_buffer_has_next(struct binary_buffer *bb)
136 {
137 return bb->pos < bb->end;
138 }
139
140 static inline struct drgn_error *
141 binary_buffer_check_bounds(struct binary_buffer *bb, uint64_t n)
142 {
143 if (unlikely(bb->end - bb->pos < n)) {
144 return binary_buffer_error_at(bb, bb->pos,
145 "expected at least %" PRIu64 " byte%s, have %td",
146 n, n == 1 ? "" : "s",
147 bb->end - bb->pos);
148 }
149 return NULL;
150 }
151
152 /** Advance the current buffer position by @p n bytes. */
153 static inline struct drgn_error *binary_buffer_skip(struct binary_buffer *bb,
154 uint64_t n)
155 {
156 struct drgn_error *err;
157 if ((err = binary_buffer_check_bounds(bb, n)))
158 return err;
159 bb->pos += n;
160 return NULL;
161 }
162
163 #ifdef DOXYGEN
164 /**
165 * Get an unsigned N-bit integer at the current buffer position and advance the
166 * position.
167 *
168 * This is defined for N of 16, 32, and 64.
169 *
170 * The byte order is determined by the @p little_endian parameter that was
171 * passed to @ref binary_buffer_init().
172 *
173 * @param[out] ret Returned value.
174 */
175 struct drgn_error *binary_buffer_next_uN(struct binary_buffer *bb,
176 uintN_t *ret);
177
178 /** Like @ref binary_buffer_next_uN(), but return the value as a @c uint64_t. */
179 struct drgn_error *binary_buffer_next_uN_into_u64(struct binary_buffer *bb,
180 uint64_t *ret);
181
182 /**
183 * Get a signed N-bit integer at the current buffer position and advance the
184 * position.
185 *
186 * This is defined for N of 16, 32, and 64.
187 *
188 * The byte order is determined by the @p little_endian parameter that was
189 * passed to @ref binary_buffer_init().
190 *
191 * @param[out] ret Returned value.
192 */
193 struct drgn_error *binary_buffer_next_sN(struct binary_buffer *bb,
194 intN_t *ret);
195
196 /** Like @ref binary_buffer_next_sN(), but return the value as an @c int64_t. */
197 struct drgn_error *binary_buffer_next_sN_into_s64(struct binary_buffer *bb,
198 int64_t *ret);
199
200 /**
201 * Like @ref binary_buffer_next_sN(), but return the value as a @c uint64_t.
202 * Negative values are sign extended.
203 */
204 struct drgn_error *binary_buffer_next_sN_into_u64(struct binary_buffer *bb,
205 unt64_t *ret);
206 #endif
207
208 #define DEFINE_NEXT_INT(bits) \
209 static inline struct drgn_error * \
210 binary_buffer_next_u##bits(struct binary_buffer *bb, uint##bits##_t *ret) \
211 { \
212 struct drgn_error *err; \
213 uint##bits##_t tmp; \
214 if ((err = binary_buffer_check_bounds(bb, sizeof(tmp)))) \
215 return err; \
216 bb->prev = bb->pos; \
217 memcpy(&tmp, bb->pos, sizeof(tmp)); \
218 bb->pos += sizeof(tmp); \
219 *ret = bb->bswap ? bswap_##bits(tmp) : tmp; \
220 return NULL; \
221 } \
222 \
223 static inline struct drgn_error * \
224 binary_buffer_next_u##bits##_into_u64(struct binary_buffer *bb, uint64_t *ret) \
225 { \
226 struct drgn_error *err; \
227 uint##bits##_t tmp; \
228 if ((err = binary_buffer_next_u##bits(bb, &tmp))) \
229 return err; \
230 *ret = tmp; \
231 return NULL; \
232 } \
233 \
234 static inline struct drgn_error * \
235 binary_buffer_next_s##bits(struct binary_buffer *bb, int##bits##_t *ret) \
236 { \
237 struct drgn_error *err; \
238 uint##bits##_t tmp; \
239 if ((err = binary_buffer_next_u##bits(bb, &tmp))) \
240 return err; \
241 *ret = tmp; \
242 return NULL; \
243 } \
244 \
245 static inline struct drgn_error * \
246 binary_buffer_next_s##bits##_into_s64(struct binary_buffer *bb, int64_t *ret) \
247 { \
248 struct drgn_error *err; \
249 int##bits##_t tmp; \
250 if ((err = binary_buffer_next_s##bits(bb, &tmp))) \
251 return err; \
252 *ret = tmp; \
253 return NULL; \
254 } \
255 \
256 static inline struct drgn_error * \
257 binary_buffer_next_s##bits##_into_u64(struct binary_buffer *bb, uint64_t *ret) \
258 { \
259 struct drgn_error *err; \
260 int##bits##_t tmp; \
261 if ((err = binary_buffer_next_s##bits(bb, &tmp))) \
262 return err; \
263 *ret = tmp; \
264 return NULL; \
265 }
266
267 #define bswap_8(x) (x)
268 DEFINE_NEXT_INT(8)
269 #undef bswap_8
270 DEFINE_NEXT_INT(16)
271 DEFINE_NEXT_INT(32)
272 DEFINE_NEXT_INT(64)
273
274 #undef DEFINE_NEXT_INT
275
276 /**
277 * Get an unsigned integer of the given size at the current buffer position and
278 * advance the position.
279 *
280 * The byte order is determined by the @p little_endian parameter that was
281 * passed to @ref binary_buffer_init().
282 *
283 * @param[in] size Size in bytes. Must be no larger than 8.
284 * @param[out] ret Returned value.
285 */
286 static inline struct drgn_error *
287 binary_buffer_next_uint(struct binary_buffer *bb, size_t size, uint64_t *ret)
288 {
289 assert(size <= 8);
290 struct drgn_error *err;
291 if ((err = binary_buffer_check_bounds(bb, size)))
292 return err;
293 *ret = 0;
294 if (HOST_LITTLE_ENDIAN) {
295 if (bb->bswap) {
296 for (size_t i = 0; i < size; i++)
297 ((char *)ret)[i] = bb->pos[size - 1 - i];
298 } else {
299 memcpy(ret, bb->pos, size);
300 }
301 } else {
302 if (bb->bswap) {
303 for (size_t i = 0; i < size; i++)
304 ((char *)(ret + 1))[-i - 1] = bb->pos[i];
305 } else {
306 memcpy((char *)(ret + 1) - size, bb->pos, size);
307 }
308 }
309 bb->prev = bb->pos;
310 bb->pos += size;
311 return NULL;
312 }
313
314 /**
315 * Get a signed integer of the given size at the current buffer position and
316 * advance the position.
317 *
318 * The byte order is determined by the @p little_endian parameter that was
319 * passed to @ref binary_buffer_init().
320 *
321 * @param[in] size Size in bytes. Must be no larger than 8.
322 * @param[out] ret Returned value.
323 */
324 static inline struct drgn_error *
325 binary_buffer_next_sint(struct binary_buffer *bb, size_t size, int64_t *ret)
326 {
327 struct drgn_error *err;
328 uint64_t tmp;
329 err = binary_buffer_next_uint(bb, size, &tmp);
330 if (err)
331 return err;
332 if (size > 0)
333 *ret = (int64_t)(tmp << (64 - 8 * size)) >> (64 - 8 * size);
334 else
335 *ret = tmp;
336 return NULL;
337 }
338
339 /**
340 * Decode an Unsigned Little-Endian Base 128 (ULEB128) number at the current
341 * buffer position and advance the position.
342 *
343 * If the number does not fit in a @c uint64_t, an error is returned.
344 *
345 * @param[out] ret Returned value.
346 */
347 static inline struct drgn_error *
348 binary_buffer_next_uleb128(struct binary_buffer *bb, uint64_t *ret)
349 {
350 uint64_t value = 0;
351 const char *pos = bb->pos;
352 uint8_t byte;
353 /* No overflow possible for the first 9 bytes. */
354 for (int shift = 0; shift < 63; shift += 7) {
355 if (unlikely(pos >= bb->end)) {
356 oob:
357 return binary_buffer_error_at(bb, bb->pos,
358 "expected ULEB128 number");
359 }
360 byte = *(uint8_t *)(pos++);
361 value |= (uint64_t)(byte & 0x7f) << shift;
362 if (!(byte & 0x80)) {
363 done:
364 bb->prev = bb->pos;
365 bb->pos = pos;
366 *ret = value;
367 return NULL;
368 }
369 }
370 /* The 10th byte must be 0 or 1. */
371 if (unlikely(pos >= bb->end))
372 goto oob;
373 byte = *(uint8_t *)(pos++);
374 if (byte & 0x7e) {
375 overflow:
376 return binary_buffer_error_at(bb, bb->pos,
377 "ULEB128 number overflows unsigned 64-bit integer");
378 }
379 value |= (uint64_t)byte << 63;
380 /* Any remaining bytes must be 0. */
381 while (byte & 0x80) {
382 if (unlikely(pos >= bb->end))
383 goto oob;
384 byte = *(uint8_t *)(pos++);
385 if (byte & 0x7f)
386 goto overflow;
387 }
388 goto done;
389 }
390
391 /**
392 * Decode a Signed Little-Endian Base 128 (SLEB128) number at the current buffer
393 * position and advance the position.
394 *
395 * If the number does not fit in an @c int64_t, an error is returned.
396 *
397 * @param[out] ret Returned value.
398 */
399 static inline struct drgn_error *
400 binary_buffer_next_sleb128(struct binary_buffer *bb, int64_t *ret)
401 {
402 uint64_t value = 0;
403 const char *pos = bb->pos;
404 uint8_t byte;
405 /* No overflow possible for the first 9 bytes. */
406 for (int shift = 0; shift < 63; shift += 7) {
407 if (unlikely(pos >= bb->end)) {
408 oob:
409 return binary_buffer_error_at(bb, bb->pos,
410 "expected SLEB128 number");
411 }
412 byte = *(uint8_t *)(pos++);
413 value |= (uint64_t)(byte & 0x7f) << shift;
414 if (!(byte & 0x80)) {
415 if (byte & 0x40)
416 value |= ~(UINT64_C(1) << (shift + 7)) + 1;
417 done:
418 bb->prev = bb->pos;
419 bb->pos = pos;
420 *ret = value;
421 return NULL;
422 }
423 }
424 /*
425 * The least significant bit of the 10th byte must be the sign bit, and
426 * any other bits must match it (sign extension).
427 */
428 if (unlikely(pos >= bb->end))
429 goto oob;
430 byte = *(uint8_t *)(pos++);
431 uint8_t sign = byte & 0x7f;
432 if (sign != 0 && sign != 0x7f) {
433 overflow:
434 return binary_buffer_error_at(bb, bb->pos,
435 "SLEB128 number overflows signed 64-bit integer");
436 }
437 value |= (uint64_t)byte << 63;
438 while (byte & 0x80) {
439 if (unlikely(pos >= bb->end))
440 goto oob;
441 byte = *(uint8_t *)(pos++);
442 if ((byte & 0x7f) != sign)
443 goto overflow;
444 }
445 goto done;
446 }
447
448 /**
449 * Like @ref binary_buffer_next_sleb128(), but return the value as a @c
450 * uint64_t. Negative values are sign extended.
451 */
452 static inline struct drgn_error *
453 binary_buffer_next_sleb128_into_u64(struct binary_buffer *bb, uint64_t *ret)
454 {
455 struct drgn_error *err;
456 int64_t tmp;
457 if ((err = binary_buffer_next_sleb128(bb, &tmp)))
458 return err;
459 *ret = tmp;
460 return NULL;
461 }
462
463 /** Skip past a LEB128 number at the current buffer position. */
464 static inline struct drgn_error *
465 binary_buffer_skip_leb128(struct binary_buffer *bb)
466 {
467 const char *pos = bb->pos;
468 while (likely(pos < bb->end)) {
469 if (!(*(uint8_t *)(pos++) & 0x80)) {
470 bb->pos = pos;
471 return NULL;
472 }
473 }
474 return binary_buffer_error_at(bb, bb->pos, "expected LEB128 number");
475 }
476
477 /**
478 * Get a null-terminated string at the current buffer position and advance the
479 * position.
480 *
481 * @param[out] str_ret Returned string (i.e., the buffer position on entry).
482 * @param[out] len_ret Returned string length not including the null byte.
483 */
484 static inline struct drgn_error *
485 binary_buffer_next_string(struct binary_buffer *bb, const char **str_ret,
486 size_t *len_ret)
487 {
488 size_t len = strnlen(bb->pos, bb->end - bb->pos);
489 if (unlikely(len == bb->end - bb->pos)) {
490 return binary_buffer_error_at(bb, bb->pos,
491 "expected null-terminated string");
492 }
493 *str_ret = bb->prev = bb->pos;
494 *len_ret = len;
495 bb->pos += len + 1;
496 return NULL;
497 }
498
499 /** Skip past a null-terminated string at the current buffer position. */
500 static inline struct drgn_error *
501 binary_buffer_skip_string(struct binary_buffer *bb)
502 {
503 size_t len = strnlen(bb->pos, bb->end - bb->pos);
504 if (unlikely(len == bb->end - bb->pos)) {
505 return binary_buffer_error_at(bb, bb->pos,
506 "expected null-terminated string");
507 }
508 bb->pos += len + 1;
509 return NULL;
510 }
511
512 /** @} */
513
514 #endif /* DRGN_BINARY_BUFFER_H */