Debian Codegraph @

libdrgn/object.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 * Object internals.
8 *
9 * See @ref ObjectInternals.
10 */
11
12 #ifndef DRGN_OBJECT_H
13 #define DRGN_OBJECT_H
14
15 #include <stdlib.h>
16 #include <string.h>
17
18 #include "drgn_internal.h"
19 #include "handler.h"
20 #include "type.h"
21
22 /**
23 * @ingroup Internals
24 *
25 * @defgroup ObjectInternals Objects
26 *
27 * Object internals.
28 *
29 * This provides the language-agnostic part of operator implementations. The
30 * operators have defined behavior for various cases where C is undefined or
31 * implementation-defined (e.g., signed arithmetic is modular, signed bitwise
32 * operators operate on the two's complement representation, right shifts are
33 * arithmetic).
34 *
35 * @{
36 */
37
38 struct drgn_object_finder {
39 struct drgn_handler handler;
40 struct drgn_object_finder_ops ops;
41 void *arg;
42 };
43
44 /** Allocate a zero-initialized @ref drgn_value. */
45 static inline bool drgn_value_zalloc(uint64_t size, union drgn_value *value_ret,
46 char **buf_ret)
47 {
48 if (size <= sizeof(value_ret->ibuf)) {
49 memset(value_ret->ibuf, 0, sizeof(value_ret->ibuf));
50 *buf_ret = value_ret->ibuf;
51 } else {
52 if (size > SIZE_MAX)
53 return false;
54 char *buf = calloc(1, size);
55 if (!buf)
56 return false;
57 value_ret->bufp = *buf_ret = buf;
58 }
59 return true;
60 }
61
62 /**
63 * Get whether an object is zero.
64 *
65 * For scalars, this is true iff its value is zero. For structures, unions, and
66 * classes, this is true iff all of its members are zero. For arrays, this is
67 * true iff all of its elements are zero. Note that this ignores padding.
68 */
69 struct drgn_error *drgn_object_is_zero(const struct drgn_object *obj,
70 bool *ret);
71
72 /** Type-related fields from @ref drgn_object. */
73 struct drgn_object_type {
74 struct drgn_type *type;
75 /* Cached underlying type of @c type. */
76 struct drgn_type *underlying_type;
77 uint64_t bit_size;
78 enum drgn_qualifiers qualifiers;
79 enum drgn_object_encoding encoding;
80 bool is_bit_field;
81 bool little_endian;
82 };
83
84 /** Convert a @ref drgn_object_type to a @ref drgn_qualified_type. */
85 static inline struct drgn_qualified_type
86 drgn_object_type_qualified(const struct drgn_object_type *type)
87 {
88 return (struct drgn_qualified_type){
89 .type = type->type,
90 .qualifiers = type->qualifiers,
91 };
92 }
93
94 /**
95 * Type of an operand or operator result.
96 *
97 * This is basically @ref drgn_qualified_type plus a bit field size and cached
98 * underlying type.
99 */
100 struct drgn_operand_type {
101 struct drgn_type *type;
102 enum drgn_qualifiers qualifiers;
103 struct drgn_type *underlying_type;
104 uint64_t bit_field_size;
105 };
106
107 /** Convert a @ref drgn_operand_type to a @ref drgn_qualified_type. */
108 static inline struct drgn_qualified_type
109 drgn_operand_type_qualified(const struct drgn_operand_type *type)
110 {
111 return (struct drgn_qualified_type){
112 .type = type->type,
113 .qualifiers = type->qualifiers,
114 };
115 }
116
117 /** Get the @ref drgn_operand_type of a @ref drgn_object. */
118 static inline struct drgn_operand_type
119 drgn_object_operand_type(const struct drgn_object *obj)
120 {
121 return (struct drgn_operand_type){
122 .type = obj->type,
123 .qualifiers = obj->qualifiers,
124 .underlying_type = drgn_underlying_type(obj->type),
125 .bit_field_size = obj->is_bit_field ? obj->bit_size : 0,
126 };
127 }
128
129 /**
130 * Deinitialize the value of a @ref drgn_object and reinitialize the kind and
131 * type fields.
132 */
133 static inline void drgn_object_reinit(struct drgn_object *obj,
134 const struct drgn_object_type *type,
135 enum drgn_object_kind kind)
136 {
137 drgn_object_deinit(obj);
138 obj->type = type->type;
139 obj->qualifiers = type->qualifiers;
140 obj->bit_size = type->bit_size;
141 obj->encoding = type->encoding;
142 obj->is_bit_field = type->is_bit_field;
143 obj->little_endian = type->little_endian;
144 obj->kind = kind;
145 }
146
147 /**
148 * Compute the type-related fields of a @ref drgn_object from a @ref
149 * drgn_qualified_type and a bit field size.
150 */
151 struct drgn_error *
152 drgn_object_type(struct drgn_qualified_type qualified_type,
153 uint64_t bit_field_size, struct drgn_object_type *ret);
154
155 /**
156 * Like @ref drgn_object_set_signed() but @ref drgn_object_type() was already
157 * called and the type is already known to be a signed integer type.
158 */
159 struct drgn_error *
160 drgn_object_set_signed_internal(struct drgn_object *res,
161 const struct drgn_object_type *type,
162 int64_t svalue);
163
164 /**
165 * Like @ref drgn_object_set_unsigned() but @ref drgn_object_type() was already
166 * called and the type is already known to be an unsigned integer type.
167 */
168 struct drgn_error *
169 drgn_object_set_unsigned_internal(struct drgn_object *res,
170 const struct drgn_object_type *type,
171 uint64_t uvalue);
172
173 /**
174 * Like @ref drgn_object_set_float() but @ref drgn_object_type() was already
175 * called and the type is already known to be a floating-point type.
176 */
177 struct drgn_error *
178 drgn_object_set_float_internal(struct drgn_object *res,
179 const struct drgn_object_type *type,
180 double fvalue);
181
182 /**
183 * Like @ref drgn_object_set_from_buffer() but @ref drgn_object_type() was
184 * already called and the bounds of the buffer have already been checked.
185 */
186 struct drgn_error *
187 drgn_object_set_from_buffer_internal(struct drgn_object *res,
188 const struct drgn_object_type *type,
189 const void *buf, uint64_t bit_offset);
190
191 /**
192 * Like @ref drgn_object_set_reference() but @ref drgn_object_type() was already
193 * called.
194 */
195 struct drgn_error *
196 drgn_object_set_reference_internal(struct drgn_object *res,
197 const struct drgn_object_type *type,
198 uint64_t address, uint64_t bit_offset);
199
200 /**
201 * Like @ref drgn_object_set_absent() but @ref drgn_object_type() was already
202 * called.
203 */
204 static inline void
205 drgn_object_set_absent_internal(struct drgn_object *res,
206 const struct drgn_object_type *type,
207 enum drgn_absence_reason reason)
208 {
209 drgn_object_reinit(res, type, DRGN_OBJECT_ABSENT);
210 res->absence_reason = reason;
211 }
212
213 struct drgn_error *
214 drgn_object_fragment_internal(struct drgn_object *res,
215 const struct drgn_object *obj,
216 const struct drgn_object_type *type,
217 int64_t bit_offset, uint64_t bit_field_size);
218
219 /**
220 * Binary operator implementation.
221 *
222 * Operator implementations with this type convert @p lhs and @p rhs to @p
223 * op_type, apply the operator, and store the result in @p res.
224 *
225 * @param[out] res Operator result. May be the same as @p lhs and/or @p rhs.
226 * @param[in] op_type Result type.
227 * @param[in] lhs Operator left hand side.
228 * @param[in] rhs Operator right hand side.
229 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
230 * error.
231 */
232 typedef struct drgn_error *
233 drgn_binary_op_impl(struct drgn_object *res,
234 const struct drgn_operand_type *op_type,
235 const struct drgn_object *lhs,
236 const struct drgn_object *rhs);
237 /**
238 * Shift operator implementation.
239 *
240 * Operator implementations with this type convert @p lhs to @p lhs_type and @p
241 * rhs to @p rhs_type and store the result in @p res.
242 *
243 * @param[out] res Operator result. May be the same as @p lhs and/or @p rhs.
244 * @param[in] lhs Operator left hand side.
245 * @param[in] lhs_type Type of left hand side and result.
246 * @param[in] rhs Operator right hand side.
247 * @param[in] rhs_type Type of right hand side.
248 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
249 * error.
250 */
251 typedef struct drgn_error *
252 drgn_shift_op_impl(struct drgn_object *res,
253 const struct drgn_object *lhs,
254 const struct drgn_operand_type *lhs_type,
255 const struct drgn_object *rhs,
256 const struct drgn_operand_type *rhs_type);
257
258 /**
259 * Unary operator implementation.
260 *
261 * Operator implementations with this type convert @p obj to @p op_type and
262 * store the result in @p res.
263 *
264 * @param[out] res Operator result. May be the same as @p obj.
265 * @param[in] op_type Result type.
266 * @param[in] obj Operand.
267 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
268 * error.
269 */
270 typedef struct drgn_error *
271 drgn_unary_op_impl(struct drgn_object *res,
272 const struct drgn_operand_type *op_type,
273 const struct drgn_object *obj);
274
275 /**
276 * Implement addition for signed, unsigned, and floating-point objects.
277 *
278 * Integer results are reduced modulo 2^width.
279 */
280 drgn_binary_op_impl drgn_op_add_impl;
281 /**
282 * Implement subtraction for signed, unsigned, and floating-point objects.
283 *
284 * Integer results are reduced modulo 2^width.
285 */
286 drgn_binary_op_impl drgn_op_sub_impl;
287 /**
288 * Implement multiplication for signed, unsigned, and floating-point objects.
289 *
290 * Integer results are reduced modulo 2^width.
291 */
292 drgn_binary_op_impl drgn_op_mul_impl;
293 /**
294 * Implement division for signed, unsigned, and floating-point objects.
295 *
296 * Integer results are truncated towards zero. A @ref DRGN_ERROR_ZERO_DIVISION
297 * error is returned if @p rhs is zero.
298 */
299 drgn_binary_op_impl drgn_op_div_impl;
300 /**
301 * Implement modulo for signed and unsigned objects.
302 *
303 * The result has the sign of the dividend. A @ref DRGN_ERROR_ZERO_DIVISION
304 * error is returned if @p rhs is zero.
305 */
306 drgn_binary_op_impl drgn_op_mod_impl;
307 /**
308 * Implement left shift for signed and unsigned objects.
309 *
310 * For signed integers, this acts on the two's complement representation. The
311 * result is reduced modulo 2^width. In particular, if @p rhs is greater than
312 * the width of the result, then the result is zero. An error is returned if @p
313 * rhs is negative.
314 */
315 drgn_shift_op_impl drgn_op_lshift_impl;
316 /**
317 * Implement right shift for signed and unsigned objects.
318 *
319 * For signed integers, this is an arithmetic shift. For unsigned integers, it
320 * is logical. The result is reduced modulo 2^width. In particular, if @p rhs is
321 * greater than the width of the result, then the result is zero. An error is
322 * returned if @p rhs is negative.
323 */
324 drgn_shift_op_impl drgn_op_rshift_impl;
325 /**
326 * Implement bitwise and for signed and unsigned objects.
327 *
328 * For signed integers, this acts on the two's complement representation.
329 */
330 drgn_binary_op_impl drgn_op_and_impl;
331 /**
332 * Implement bitwise or for signed and unsigned objects.
333 *
334 * For signed integers, this acts on the two's complement representation.
335 */
336 drgn_binary_op_impl drgn_op_or_impl;
337 /**
338 * Implement bitwise xor for signed and unsigned objects.
339 *
340 * For signed integers, this acts on the two's complement representation.
341 */
342 drgn_binary_op_impl drgn_op_xor_impl;
343 /**
344 * Implement the unary plus operator for signed, unsigned, and floating-point
345 * objects.
346 *
347 * This converts @p obj without otherwise changing the value.
348 */
349 drgn_unary_op_impl drgn_op_pos_impl;
350 /**
351 * Implement negation for signed, unsigned, and floating-point objects.
352 *
353 * Integer results are reduced modulo 2^width.
354 */
355 drgn_unary_op_impl drgn_op_neg_impl;
356 /**
357 * Implement bitwise negation for signed and unsigned objects.
358 *
359 * For signed integers, this acts on the two's complement representation.
360 */
361 drgn_unary_op_impl drgn_op_not_impl;
362
363 /**
364 * Implement object type casting.
365 *
366 * If @p obj_type is a pointer type and @c obj is a buffer, then the reference
367 * address of @p obj is used.
368 */
369 struct drgn_error *drgn_op_cast(struct drgn_object *res,
370 const struct drgn_object_type *type,
371 const struct drgn_object *obj,
372 const struct drgn_operand_type *obj_type);
373
374 /**
375 * Implement object comparison for signed, unsigned, and floating-point objects.
376 *
377 * This converts @p lhs and @p rhs to @p type before comparing.
378 */
379 struct drgn_error *drgn_op_cmp_impl(const struct drgn_object *lhs,
380 const struct drgn_object *rhs,
381 const struct drgn_operand_type *op_type,
382 int *ret);
383
384 /**
385 * Implement object comparison for pointers and reference buffer objects.
386 *
387 * When comparing reference buffer objects, their address is used.
388 */
389 struct drgn_error *drgn_op_cmp_pointers(const struct drgn_object *lhs,
390 const struct drgn_object *rhs,
391 int *ret);
392
393 /**
394 * Implement pointer arithmetic.
395 *
396 * This converts @p ptr to @p op_type, adds or subtracts
397 * <tt>index * referenced_size</tt>, and stores the result in @p res.
398 *
399 * @param[out] res Operator result. May be the same as @p ptr or @p index.
400 * @param[in] op_type Result type.
401 * @param[in] referenced_size Size of the object pointed to by @p ptr.
402 * @param[in] negate Subtract @p index instead of adding.
403 * @param[in] ptr Pointer.
404 * @param[in] index Value to add to/subtract from pointer.
405 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
406 * error.
407 */
408 struct drgn_error *
409 drgn_op_add_to_pointer(struct drgn_object *res,
410 const struct drgn_operand_type *op_type,
411 uint64_t referenced_size, bool negate,
412 const struct drgn_object *ptr,
413 const struct drgn_object *index);
414
415 /**
416 * Implement pointer subtraction.
417 *
418 * This stores <tt>(lhs - rhs) / referenced_size</tt> in @p res.
419 *
420 * @param[out] res Operator result. May be the same as @p lhs and/or @p rhs.
421 * @param[in] referenced_size Size of the object pointed to by @p lhs and @p
422 * rhs.
423 * @param[in] op_type Result type. Must be a signed integer type.
424 * @param[in] lhs Operator left hand side.
425 * @param[in] rhs Operator right hand side.
426 * @return @c NULL on success, non-@c NULL on error. @p res is not modified on
427 * error.
428 */
429 struct drgn_error *drgn_op_sub_pointers(struct drgn_object *res,
430 const struct drgn_operand_type *op_type,
431 uint64_t referenced_size,
432 const struct drgn_object *lhs,
433 const struct drgn_object *rhs);
434
435 /** @} */
436
437 #endif /* DRGN_OBJECT_H */