Debian Codegraph @

libdrgn/serialize.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 * Serialization and deserialization to and from memory.
8 *
9 * See @ref SerializationDeserialization.
10 */
11
12 #ifndef DRGN_SERIALIZE_H
13 #define DRGN_SERIALIZE_H
14
15 #include <byteswap.h>
16 #include <stdbool.h>
17 #include <stdint.h>
18 #include <string.h>
19
20 #include "minmax.h"
21 #include "util.h"
22
23 /**
24 * @ingroup Internals
25 *
26 * @defgroup SerializationDeserialization Serialization/deserialization
27 *
28 * Serialization and deserialization of bits to and from memory.
29 *
30 * @{
31 */
32
33 /** Truncate a signed integer to @p bit_size bits with sign extension. */
34 static inline int64_t truncate_signed(int64_t svalue, uint64_t bit_size)
35 {
36 return (int64_t)((uint64_t)svalue << (64 - bit_size)) >> (64 - bit_size);
37 }
38
39 /** Truncate an unsigned integer to @p bit_size bits. */
40 static inline uint64_t truncate_unsigned(uint64_t uvalue, uint64_t bit_size)
41 {
42 return uvalue << (64 - bit_size) >> (64 - bit_size);
43 }
44
45 static inline int8_t truncate_signed8(int8_t svalue, int bit_size)
46 {
47 return (int8_t)((uint8_t)svalue << (8 - bit_size)) >> (8 - bit_size);
48 }
49
50 static inline uint8_t truncate_unsigned8(uint8_t uvalue, int bit_size)
51 {
52 return (uint8_t)(uvalue << (8 - bit_size)) >> (8 - bit_size);
53 }
54
55 /**
56 * Copy the @p src_size least-significant bytes from @p src to the @p dst_size
57 * least-significant bytes of @p dst.
58 *
59 * If `src_size > dst_size`, the extra bytes are discarded. If `src_size <
60 * dst_size`, the extra bytes are filled with @p fill.
61 */
62 static inline void copy_lsbytes_fill(void *dst, size_t dst_size,
63 bool dst_little_endian, const void *src,
64 size_t src_size, bool src_little_endian,
65 int fill)
66 {
67 char *d = dst;
68 const char *s = src;
69 size_t size = min(dst_size, src_size);
70 if (dst_little_endian) {
71 if (src_little_endian) {
72 memcpy(d, s, size);
73 } else {
74 for (size_t i = 0; i < size; i++)
75 d[i] = s[src_size - 1 - i];
76 }
77 memset(d + size, fill, dst_size - size);
78 } else {
79 memset(d, fill, dst_size - size);
80 if (src_little_endian) {
81 for (size_t i = dst_size - size; i < dst_size; i++)
82 d[i] = s[dst_size - 1 - i];
83 } else {
84 memcpy(d + dst_size - size, s + src_size - size, size);
85 }
86 }
87 }
88
89 /**
90 * Copy the @p src_size least-significant bytes from @p src to the @p dst_size
91 * least-significant bytes of @p dst.
92 *
93 * If `src_size > dst_size`, the extra bytes are discarded. If `src_size <
94 * dst_size`, the extra bytes are zero-filled.
95 */
96 static inline void copy_lsbytes(void *dst, size_t dst_size,
97 bool dst_little_endian, const void *src,
98 size_t src_size, bool src_little_endian)
99 {
100 return copy_lsbytes_fill(dst, dst_size, dst_little_endian, src,
101 src_size, src_little_endian, 0);
102 }
103
104 /**
105 * Return a bit mask with bits `[bit_offset, 7]` set.
106 *
107 * @param[in] lsb0 See @ref copy_bits().
108 */
109 static inline uint8_t copy_bits_first_mask(unsigned int bit_offset, bool lsb0)
110 {
111 return lsb0 ? 0xff << bit_offset : 0xff >> bit_offset;
112 }
113
114 /**
115 * Return a bit mask with bits `[0, last_bit % 8]` set.
116 *
117 * @param[in] lsb0 See @ref copy_bits().
118 */
119 static inline uint8_t copy_bits_last_mask(uint64_t last_bit, bool lsb0)
120 {
121 return lsb0 ? 0xff >> (7 - last_bit % 8) : 0x7f80 >> (last_bit % 8);
122 }
123
124 /**
125 * Copy @p bit_size bits from @p src at bit offset @p src_bit_offset to @p dst
126 * at bit offset @p dst_bit_offset.
127 *
128 * @param[in] dst Destination buffer.
129 * @param[in] dst_bit_offset Offset in bits from the beginning of @p dst to copy
130 * to. Must be < 8.
131 * @param[in] src Source buffer.
132 * @param[in] src_bit_offset Offset in bits from the beginning of @p src to copy
133 * from. Must be < 8.
134 * @param[in] bit_size Number of bits to copy.
135 * @param[in] lsb0 If @c true, bits within a byte are numbered from least
136 * significant (0) to most significant (7); if @c false, they are numbered from
137 * most significant (0) to least significant (7). This determines the
138 * interpretation of @p dst_bit_offset and @p src_bit_offset.
139 */
140 void copy_bits(void *dst, unsigned int dst_bit_offset, const void *src,
141 unsigned int src_bit_offset, uint64_t bit_size, bool lsb0);
142
143 /**
144 * Serialize bits to a memory buffer.
145 *
146 * Note that this does not perform any bounds checking, so the caller must check
147 * that <tt>bit_offset + bit_size</tt> is within the buffer.
148 *
149 * @param[in] buf Memory buffer to write to.
150 * @param[in] bit_offset Offset in bits from the beginning of @p buf to where to
151 * write. This is interpreted differently based on @p little_endian.
152 * @param[in] uvalue Bits to write, in host order.
153 * @param[in] bit_size Number of bits in @p uvalue. This must be greater than
154 * zero and no more than 64. Note that this is not checked or truncated, so if
155 * @p uvalue has more than this many bits, the results will likely be incorrect.
156 * @param[in] little_endian Whether the bits should be written out in
157 * little-endian order.
158 */
159 void serialize_bits(void *buf, uint64_t bit_offset, uint64_t uvalue,
160 uint8_t bit_size, bool little_endian);
161
162 /**
163 * Deserialize bits from a memory buffer.
164 *
165 * Note that this does not perform any bounds checking, so the caller must check
166 * that <tt>bit_offset + bit_size</tt> is within the buffer.
167 *
168 * @param[in] buf Memory buffer to read from.
169 * @param[in] bit_offset Offset in bits from the beginning of @p buf to where to
170 * read from. This is interpreted differently based on @p little_endian.
171 * @param[in] bit_size Number of bits to read. This must be greater than zero
172 * and no more than 64.
173 * @param[in] little_endian Whether the bits should be interpreted in
174 * little-endian order.
175 * @return The read bits in host order.
176 */
177 uint64_t deserialize_bits(const void *buf, uint64_t bit_offset,
178 uint8_t bit_size, bool little_endian);
179
180 #define struct64_assign_member(member) do { \
181 typeof_member(_struct64_src_type, member) _struct64_tmp; \
182 memcpy(&_struct64_tmp, \
183 _struct64_src + offsetof(_struct64_src_type, member), \
184 sizeof(_struct64_tmp)); \
185 _struct64_dst->member = _struct64_tmp; \
186 } while (0)
187
188 #define struct64_bswap_member(member) do { \
189 typeof_member(_struct64_src_type, member) _struct64_swapped; \
190 _Static_assert(sizeof(_struct64_swapped) == 8 || \
191 sizeof(_struct64_swapped) == 4 || \
192 sizeof(_struct64_swapped) == 2 || \
193 sizeof(_struct64_swapped) == 1, \
194 "scalar member has invalid size"); \
195 if (sizeof(_struct64_swapped) == 8) { \
196 uint64_t _struct64_tmp; \
197 memcpy(&_struct64_tmp, \
198 _struct64_src + offsetof(_struct64_src_type, member), \
199 sizeof(_struct64_tmp)); \
200 _struct64_tmp = bswap_64(_struct64_tmp); \
201 memcpy(&_struct64_swapped, &_struct64_tmp, \
202 sizeof(_struct64_tmp)); \
203 } else if (sizeof(_struct64_swapped) == 4) { \
204 uint32_t _struct64_tmp; \
205 memcpy(&_struct64_tmp, \
206 _struct64_src + offsetof(_struct64_src_type, member), \
207 sizeof(_struct64_tmp)); \
208 _struct64_tmp = bswap_32(_struct64_tmp); \
209 memcpy(&_struct64_swapped, &_struct64_tmp, \
210 sizeof(_struct64_tmp)); \
211 } else if (sizeof(_struct64_swapped) == 2) { \
212 uint16_t _struct64_tmp; \
213 memcpy(&_struct64_tmp, \
214 _struct64_src + offsetof(_struct64_src_type, member), \
215 sizeof(_struct64_tmp)); \
216 _struct64_tmp = bswap_16(_struct64_tmp); \
217 memcpy(&_struct64_swapped, &_struct64_tmp, \
218 sizeof(_struct64_tmp)); \
219 } else { \
220 memcpy(&_struct64_swapped, \
221 _struct64_src + offsetof(_struct64_src_type, member), \
222 sizeof(_struct64_swapped)); \
223 } \
224 _struct64_dst->member = _struct64_swapped; \
225 } while (0)
226
227 #define struct64_bswap_member_inplace(member) do { \
228 _Static_assert(sizeof(_struct64_dst->member) == 8 || \
229 sizeof(_struct64_dst->member) == 4 || \
230 sizeof(_struct64_dst->member) == 2 || \
231 sizeof(_struct64_dst->member) == 1, \
232 "scalar member has invalid size"); \
233 if (sizeof(_struct64_dst->member) == 8) { \
234 uint64_t _struct64_tmp; \
235 memcpy(&_struct64_tmp, &_struct64_dst->member, \
236 sizeof(_struct64_tmp)); \
237 _struct64_tmp = bswap_64(_struct64_tmp); \
238 memcpy(&_struct64_dst->member, &_struct64_tmp, \
239 sizeof(_struct64_tmp)); \
240 } else if (sizeof(_struct64_dst->member) == 4) { \
241 uint32_t _struct64_tmp; \
242 memcpy(&_struct64_tmp, &_struct64_dst->member, \
243 sizeof(_struct64_tmp)); \
244 _struct64_tmp = bswap_32(_struct64_tmp); \
245 memcpy(&_struct64_dst->member, &_struct64_tmp, \
246 sizeof(_struct64_tmp)); \
247 } else if (sizeof(_struct64_dst->member) == 2) { \
248 uint16_t _struct64_tmp; \
249 memcpy(&_struct64_tmp, &_struct64_dst->member, \
250 sizeof(_struct64_tmp)); \
251 _struct64_tmp = bswap_16(_struct64_tmp); \
252 memcpy(&_struct64_dst->member, &_struct64_tmp, \
253 sizeof(_struct64_tmp)); \
254 } \
255 } while (0)
256
257 #define struct64_memcpy_member(member) do { \
258 _Static_assert(sizeof(_struct64_dst->member) \
259 == sizeof_member(_struct64_src_type, member), \
260 "64-bit and 32-bit members have different sizes"); \
261 memcpy(&_struct64_dst->member, \
262 _struct64_src + offsetof(_struct64_src_type, member), \
263 sizeof(_struct64_dst->member)); \
264 } while (0)
265
266 #define struct64_ignore_member(member)
267
268 #ifdef DOXYGEN
269 /**
270 * Deserialize a structure from a memory buffer, where the structure has
271 * different 64-bit and 32-bit formats, may have a different byte order, and may
272 * be unaligned.
273 *
274 * @param[out] struct64p Returned 64-bit structure in host byte order.
275 * @param[in] T32 32-bit structure type.
276 * @param[in] visit_members Macro with signature
277 * `visit_members(visit_scalar_member, visit_raw_member)`.
278 * `visit_scalar_member()` is a macro that should be called with the name of
279 * each scalar member of the structure. `visit_raw_member()` is a macro that
280 * should be called with the name of each member that is identical regardless of
281 * 64-/32-bit format or byte order.
282 * @param[in] buf Source buffer. Must not overlap with @p struct64p.
283 * @param[in] is_64_bit Whether the source is in the 64-bit format or the 32-bit
284 * format.
285 * @param[in] bswap Whether the source has a different byte order than the host
286 * system.
287 */
288 void deserialize_struct64(T64 * restrict struct64p, T32, visit_members,
289 const void * restrict buf, bool is_64_bit,
290 bool bswap);
291
292 /**
293 * Like @ref deserialize_struct64(), but the source and destination are the
294 * same.
295 *
296 * @param[in,out] struct64p Initially the source buffer, then the returned
297 * 64-bit structure in host byte order.
298 */
299 void deserialize_struct64_inplace(T64 *struct64p, T32, bool visit_members,
300 bool is_64_bit, bool bswap);
301
302 #else
303 #define deserialize_struct64(struct64p, type32, visit_members, buf, is_64_bit, \
304 bswap) \
305 do { \
306 __auto_type _struct64_dst = (struct64p); \
307 /* \
308 * We want to type check buf like a function parameter, so do two \
309 * implicit conversions instead of an explicit cast. \
310 */ \
311 const void *_struct64_buf = (buf); \
312 const char *_struct64_src = _struct64_buf; \
313 if (is_64_bit) { \
314 if (bswap) { \
315 typedef typeof(*_struct64_dst) _struct64_src_type; \
316 visit_members(struct64_bswap_member, \
317 struct64_memcpy_member); \
318 } else { \
319 memcpy(_struct64_dst, buf, sizeof(*_struct64_dst)); \
320 } \
321 } else { \
322 typedef typeof(type32) _struct64_src_type; \
323 if (bswap) { \
324 visit_members(struct64_bswap_member, \
325 struct64_memcpy_member); \
326 } else { \
327 visit_members(struct64_assign_member, \
328 struct64_memcpy_member); \
329 } \
330 } \
331 } while (0)
332
333 #define deserialize_struct64_inplace(struct64p, type32, visit_members, \
334 is_64_bit, bswap) do { \
335 __auto_type _struct64_dst = (struct64p); \
336 if (!(is_64_bit)) { \
337 typedef typeof(type32) _struct64_src_type; \
338 _Alignas(_struct64_src_type) char \
339 _struct64_src[sizeof(_struct64_src_type)]; \
340 memcpy(_struct64_src, _struct64_dst, sizeof(_struct64_src)); \
341 if (bswap) { \
342 visit_members(struct64_bswap_member, \
343 struct64_memcpy_member); \
344 } else { \
345 visit_members(struct64_assign_member, \
346 struct64_memcpy_member); \
347 } \
348 } else if (bswap) { \
349 visit_members(struct64_bswap_member_inplace, \
350 struct64_ignore_member); \
351 } \
352 } while (0)
353 #endif
354
355 /** @} */
356
357 #endif /* DRGN_SERIALIZE_H */