Debian Codegraph @

libdrgn/type.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 * Type internals.
8 *
9 * See @ref TypeInternals.
10 */
11
12 #ifndef DRGN_TYPE_H
13 #define DRGN_TYPE_H
14
15 #include <assert.h>
16
17 #include "drgn_internal.h"
18 #include "handler.h"
19 #include "hash_table.h"
20 #include "vector.h"
21
22 /**
23 * @ingroup Internals
24 *
25 * @defgroup TypeInternals Types
26 *
27 * Type internals.
28 *
29 * This provides internal helpers for creating and accessing types.
30 * Additionally, standard C types need special handling for C's various operator
31 * conversion rules, so this provides helpers for working with standard C types.
32 *
33 * @{
34 */
35
36 /** Byte-order specification. */
37 enum drgn_byte_order {
38 /** Big-endian. */
39 DRGN_BIG_ENDIAN,
40 /** Little-endian. */
41 DRGN_LITTLE_ENDIAN,
42 /** Endianness of the program. */
43 DRGN_PROGRAM_ENDIAN,
44 };
45
46 static inline enum drgn_byte_order
47 drgn_byte_order_from_little_endian(bool little_endian)
48 {
49 return little_endian ? DRGN_LITTLE_ENDIAN : DRGN_BIG_ENDIAN;
50 }
51
52 /** Registered type finding callback in a @ref drgn_program. */
53 struct drgn_type_finder {
54 struct drgn_handler handler;
55 struct drgn_type_finder_ops ops;
56 void *arg;
57 };
58
59 DEFINE_HASH_SET_TYPE(drgn_dedupe_type_set, struct drgn_type *);
60
61 /** <tt>(type, member name)</tt> pair. */
62 struct drgn_member_key {
63 struct drgn_type *type;
64 const char *name;
65 size_t name_len;
66 };
67
68 /** Type, offset, and bit field size of a type member. */
69 struct drgn_member_value {
70 struct drgn_type_member *member;
71 uint64_t bit_offset;
72 };
73
74 #ifdef DOXYGEN
75 /**
76 * @struct drgn_member_map
77 *
78 * Map of compound type members.
79 *
80 * The key is a @ref drgn_member_key, and the value is a @ref drgn_member_value.
81 *
82 * @struct drgn_type_set
83 *
84 * Set of types compared by address.
85 */
86 #else
87 DEFINE_HASH_MAP_TYPE(drgn_member_map, struct drgn_member_key,
88 struct drgn_member_value);
89 DEFINE_HASH_SET_TYPE(drgn_type_set, struct drgn_type *);
90 #endif
91
92 /**
93 * @defgroup TypeCreation Type creation
94 *
95 * Creating type descriptors.
96 *
97 * These functions create type descriptors. They are valid for the lifetime of
98 * the program that owns them.
99 *
100 * A few kinds of types have variable-length fields: structure, union, and class
101 * types have members, enumerated types have enumerators, and function types
102 * have parameters. These fields are constructed with a @em builder before
103 * creating the type.
104 *
105 * @{
106 */
107
108 /**
109 * Get the void type for the given @ref drgn_language.
110 *
111 * The void type does not have any fields, so a program has a single type
112 * descriptor per language to represent it. This function cannot fail.
113 *
114 * @param[in] prog Program owning type.
115 * @param[in] lang Language of the type or @c NULL for the default language of
116 * @p prog.
117 */
118 struct drgn_type *drgn_void_type(struct drgn_program *prog,
119 const struct drgn_language *lang);
120
121 /**
122 * Create an integer type.
123 *
124 * @param[in] prog Program owning type.
125 * @param[in] name Name of the type. Not copied; must remain valid for the
126 * lifetime of @p prog. Must not be @c NULL.
127 * @param[in] size Size of the type in bytes.
128 * @param[in] is_signed Whether the type is signed.
129 * @param[in] lang Language of the type or @c NULL for the default language of
130 * @p prog.
131 * @param[out] ret Returned type.
132 * @return @c NULL on success, non-@c NULL on error.
133 */
134 struct drgn_error *drgn_int_type_create(struct drgn_program *prog,
135 const char *name, uint64_t size,
136 bool is_signed,
137 enum drgn_byte_order byte_order,
138 const struct drgn_language *lang,
139 struct drgn_type **ret);
140
141 /**
142 * Create a boolean type.
143 *
144 * @param[in] prog Program owning type.
145 * @param[in] name Name of the type. Not copied; must remain valid for the
146 * lifetime of @p prog. Must not be @c NULL.
147 * @param[in] size Size of the type in bytes.
148 * @param[in] lang Language of the type or @c NULL for the default language of
149 * @p prog.
150 * @param[out] ret Returned type.
151 * @return @c NULL on success, non-@c NULL on error.
152 */
153 struct drgn_error *drgn_bool_type_create(struct drgn_program *prog,
154 const char *name, uint64_t size,
155 enum drgn_byte_order byte_order,
156 const struct drgn_language *lang,
157 struct drgn_type **ret);
158
159 /**
160 * Create a floating-point type.
161 *
162 * @param[in] prog Program owning type.
163 * @param[in] name Name of the type. Not copied; must remain valid for the
164 * lifetime of @p prog. Must not be @c NULL.
165 * @param[in] size Size of the type in bytes.
166 * @param[in] lang Language of the type or @c NULL for the default language of
167 * @p prog.
168 * @param[out] ret Returned type.
169 * @return @c NULL on success, non-@c NULL on error.
170 */
171 struct drgn_error *drgn_float_type_create(struct drgn_program *prog,
172 const char *name, uint64_t size,
173 enum drgn_byte_order byte_order,
174 const struct drgn_language *lang,
175 struct drgn_type **ret);
176
177 DEFINE_VECTOR_TYPE(drgn_type_template_parameter_vector,
178 struct drgn_type_template_parameter);
179
180 /**
181 * Common builder shared between compound and function types for template
182 * parameters.
183 */
184 struct drgn_template_parameters_builder {
185 struct drgn_program *prog;
186 struct drgn_type_template_parameter_vector parameters;
187 };
188
189 /**
190 * Add a @ref drgn_type_template_parameter to a @ref
191 * drgn_template_parameters_builder.
192 *
193 * On success, @p builder takes ownership of @p argument.
194 */
195 struct drgn_error *
196 drgn_template_parameters_builder_add(struct drgn_template_parameters_builder *builder,
197 const union drgn_lazy_object *argument,
198 const char *name, bool is_default);
199
200 DEFINE_VECTOR_TYPE(drgn_type_member_vector, struct drgn_type_member);
201
202 /** Builder for members of a structure, union, or class type. */
203 struct drgn_compound_type_builder {
204 struct drgn_template_parameters_builder template_builder;
205 enum drgn_type_kind kind;
206 struct drgn_type_member_vector members;
207 };
208
209 /**
210 * Initialize a @ref drgn_compound_type_builder.
211 *
212 * @param[in] kind One of @ref DRGN_TYPE_STRUCT, @ref DRGN_TYPE_UNION, or @ref
213 * DRGN_TYPE_CLASS.
214 */
215 void drgn_compound_type_builder_init(struct drgn_compound_type_builder *builder,
216 struct drgn_program *prog,
217 enum drgn_type_kind kind);
218
219 /**
220 * Deinitialize a @ref drgn_compound_type_builder.
221 *
222 * Don't call this if @ref drgn_compound_type_create() succeeded.
223 */
224 void
225 drgn_compound_type_builder_deinit(struct drgn_compound_type_builder *builder);
226
227 /**
228 * Add a @ref drgn_type_member to a @ref drgn_compound_type_builder.
229 *
230 * On success, @p builder takes ownership of @p object.
231 */
232 struct drgn_error *
233 drgn_compound_type_builder_add_member(struct drgn_compound_type_builder *builder,
234 const union drgn_lazy_object *object,
235 const char *name, uint64_t bit_offset);
236
237 /**
238 * Create a structure, union, or class type.
239 *
240 * On success, this takes ownership of @p builder.
241 *
242 * @param[in] builder Builder containing members and template parameters. @c
243 * object/@c argument and @c name of each member and template parameter must
244 * remain valid for the lifetime of @c prog. If incomplete, must not contain any
245 * members.
246 * @param[in] tag Name of the type. Not copied; must remain valid for the
247 * lifetime of @c prog. May be @c NULL if the type is anonymous.
248 * @param[in] size Size of the type in bytes. Must be zero if the type is
249 * incomplete.
250 * @param[in] is_complete Whether the type is complete.
251 * @param[in] lang Language of the type or @c NULL for the default language of
252 * @c prog.
253 * @param[out] ret Returned type.
254 * @return @c NULL on success, non-@c NULL on error.
255 */
256 struct drgn_error *
257 drgn_compound_type_create(struct drgn_compound_type_builder *builder,
258 const char *tag, uint64_t size, bool is_complete,
259 const struct drgn_language *lang,
260 struct drgn_type **ret);
261
262 DEFINE_VECTOR_TYPE(drgn_type_enumerator_vector, struct drgn_type_enumerator);
263
264 /** Builder for enumerators of an enumerated type. */
265 struct drgn_enum_type_builder {
266 struct drgn_program *prog;
267 struct drgn_type_enumerator_vector enumerators;
268 };
269
270 /** Initialize a @ref drgn_enum_type_builder. */
271 void drgn_enum_type_builder_init(struct drgn_enum_type_builder *builder,
272 struct drgn_program *prog);
273
274 /**
275 * Deinitialize a @ref drgn_enum_type_builder.
276 *
277 * Don't call this if @ref drgn_enum_type_create() succeeded.
278 */
279 void drgn_enum_type_builder_deinit(struct drgn_enum_type_builder *builder);
280
281 /**
282 * Add a @ref drgn_type_enumerator with a signed value to a @ref
283 * drgn_enum_type_builder.
284 */
285 struct drgn_error *
286 drgn_enum_type_builder_add_signed(struct drgn_enum_type_builder *builder,
287 const char *name, int64_t svalue);
288
289 /**
290 * Add a @ref drgn_type_enumerator with an unsigned value to a @ref
291 * drgn_enum_type_builder.
292 */
293 struct drgn_error *
294 drgn_enum_type_builder_add_unsigned(struct drgn_enum_type_builder *builder,
295 const char *name, uint64_t uvalue);
296
297 /**
298 * Create an enumerated type.
299 *
300 * On success, this takes ownership of @p builder.
301 *
302 * @param[in] builder Builder containing enumerators. @c name of each enumerator
303 * must remain valid for the lifetime of @c builder->prog.
304 * @param[in] tag Name of the type. This string is not copied. It may be @c NULL
305 * if the type is anonymous.
306 * @param[in] compatible_type Type compatible with this enumerated type. Must be
307 * an integer type.
308 * @param[in] lang Language of the type or @c NULL for the default language of
309 * @c builder->prog.
310 * @param[out] ret Returned type.
311 * @return @c NULL on success, non-@c NULL on error.
312 */
313 struct drgn_error *drgn_enum_type_create(struct drgn_enum_type_builder *builder,
314 const char *tag,
315 struct drgn_type *compatible_type,
316 const struct drgn_language *lang,
317 struct drgn_type **ret);
318
319 /**
320 * Create an incomplete enumerated type.
321 *
322 * @c compatible_type is set to @c NULL and @c num_enumerators is set to zero.
323 *
324 * @param[in] prog Program owning type.
325 * @param[in] tag Name of the type. Not copied; must remain valid for the
326 * lifetime of @p prog. May be @c NULL if the type is anonymous.
327 * @param[in] lang Language of the type or @c NULL for the default language of
328 * @p prog.
329 * @param[out] ret Returned type.
330 * @return @c NULL on success, non-@c NULL on error.
331 */
332 struct drgn_error *
333 drgn_incomplete_enum_type_create(struct drgn_program *prog, const char *tag,
334 const struct drgn_language *lang,
335 struct drgn_type **ret);
336
337 /**
338 * Create a typedef type.
339 *
340 * @param[in] prog Program owning type.
341 * @param[in] name Name of the type. Not copied; must remain valid for the
342 * lifetime of @p prog. Must not be @c NULL.
343 * @param[in] aliased_type Type aliased by the typedef.
344 * @param[in] lang Language of the type or @c NULL for the default language of
345 * @p prog.
346 * @param[out] ret Returned type.
347 * @return @c NULL on success, non-@c NULL on error.
348 */
349 struct drgn_error *
350 drgn_typedef_type_create(struct drgn_program *prog, const char *name,
351 struct drgn_qualified_type aliased_type,
352 const struct drgn_language *lang,
353 struct drgn_type **ret);
354
355 /**
356 * Create a pointer type.
357 *
358 * @param[in] prog Program owning type.
359 * @param[in] referenced_type Type referenced by the pointer type.
360 * @param[in] size Size of the type in bytes.
361 * @param[in] lang Language of the type or @c NULL for the default language of
362 * @p prog.
363 * @param[out] ret Returned type.
364 * @return @c NULL on success, non-@c NULL on error.
365 */
366 struct drgn_error *
367 drgn_pointer_type_create(struct drgn_program *prog,
368 struct drgn_qualified_type referenced_type,
369 uint64_t size, enum drgn_byte_order byte_order,
370 const struct drgn_language *lang,
371 struct drgn_type **ret);
372
373 /**
374 * Create an array type.
375 *
376 * @param[in] prog Program owning type.
377 * @param[in] element_type Type of an element in the array type.
378 * @param[in] length Number of elements in the array type.
379 * @param[in] lang Language of the type or @c NULL for the default language of
380 * @p prog.
381 * @param[out] ret Returned type.
382 * @return @c NULL on success, non-@c NULL on error.
383 */
384 struct drgn_error *
385 drgn_array_type_create(struct drgn_program *prog,
386 struct drgn_qualified_type element_type,
387 uint64_t length, const struct drgn_language *lang,
388 struct drgn_type **ret);
389
390 /**
391 * Create an incomplete array type.
392 *
393 * @c length is set to zero.
394 *
395 * @param[in] prog Program owning type.
396 * @param[in] element_type Type of an element in the array type.
397 * @param[in] lang Language of the type or @c NULL for the default language of
398 * @p prog.
399 * @param[out] ret Returned type.
400 * @return @c NULL on success, non-@c NULL on error.
401 */
402 struct drgn_error *
403 drgn_incomplete_array_type_create(struct drgn_program *prog,
404 struct drgn_qualified_type element_type,
405 const struct drgn_language *lang,
406 struct drgn_type **ret);
407
408 DEFINE_VECTOR_TYPE(drgn_type_parameter_vector, struct drgn_type_parameter);
409
410 /** Builder for parameters of a function type. */
411 struct drgn_function_type_builder {
412 struct drgn_template_parameters_builder template_builder;
413 struct drgn_type_parameter_vector parameters;
414 };
415
416 /** Initialize a @ref drgn_function_type_builder. */
417 void drgn_function_type_builder_init(struct drgn_function_type_builder *builder,
418 struct drgn_program *prog);
419
420 /**
421 * Deinitialize a @ref drgn_function_type_builder.
422 *
423 * Don't call this if @ref drgn_function_type_create() succeeded.
424 */
425 void
426 drgn_function_type_builder_deinit(struct drgn_function_type_builder *builder);
427
428 /**
429 * Add a @ref drgn_type_parameter to a @ref drgn_function_type_builder.
430 *
431 * On success, @p builder takes ownership of @p default_argument.
432 */
433 struct drgn_error *
434 drgn_function_type_builder_add_parameter(struct drgn_function_type_builder *builder,
435 const union drgn_lazy_object *default_argument,
436 const char *name);
437
438 /**
439 * Create a function type.
440 *
441 * On success, this takes ownership of @p builder.
442 *
443 * @param[in] builder Builder containing parameters and template parameters. @c
444 * default_argument/@c argument and @c name of each parameter and template
445 * parameter must remain valid for the lifetime of @c prog.
446 * @param[in] return_type Type returned by the function type.
447 * @param[in] is_variadic Whether the function type is variadic.
448 * @param[in] lang Language of the type or @c NULL for the default language of
449 * @c prog.
450 * @param[out] ret Returned type.
451 * @return @c NULL on success, non-@c NULL on error.
452 */
453 struct drgn_error *
454 drgn_function_type_create(struct drgn_function_type_builder *builder,
455 struct drgn_qualified_type return_type,
456 bool is_variadic, const struct drgn_language *lang,
457 struct drgn_type **ret);
458
459 /** @} */
460
461 /** Create a copy of a type with a different byte order. */
462 struct drgn_error *
463 drgn_type_with_byte_order(struct drgn_type **type,
464 struct drgn_type **underlying_type,
465 enum drgn_byte_order byte_order);
466
467 /** Mapping from @ref drgn_type_kind to the spelling of that kind. */
468 extern const char * const drgn_type_kind_spelling[];
469
470 /**
471 * Parse the name of an unqualified primitive C type.
472 *
473 * @return The type, or @ref DRGN_NOT_PRIMITIVE_TYPE if @p s is not the name of
474 * a primitive C type.
475 */
476 enum drgn_primitive_type c_parse_specifier_list(const char *s);
477
478 /**
479 * Get the type of a @ref drgn_type with all typedefs removed.
480 *
481 * I.e., the underlying type is the aliased type of the type if it is a typedef,
482 * recursively.
483 */
484 static inline struct drgn_type *drgn_underlying_type(struct drgn_type *type)
485 {
486 struct drgn_type *underlying_type;
487
488 underlying_type = type;
489 while (drgn_type_kind(underlying_type) == DRGN_TYPE_TYPEDEF)
490 underlying_type = drgn_type_type(underlying_type).type;
491 return underlying_type;
492 }
493
494 /**
495 * Get whether an enumerated type is signed.
496 *
497 * This is true if and only if the compatible integer type is signed.
498 *
499 * @param[in] type Enumerated type. It must be complete.
500 */
501 static inline bool drgn_enum_type_is_signed(struct drgn_type *type)
502 {
503 assert(type->_type);
504 return drgn_type_is_signed(type->_type);
505 }
506
507 /**
508 * Get whether a type is anonymous (i.e., the type has no name).
509 *
510 * This may be @c false for structure, union, class, and enum types. Otherwise,
511 * it is always true.
512 */
513 static inline bool drgn_type_is_anonymous(struct drgn_type *type)
514 {
515 switch (drgn_type_kind(type)) {
516 case DRGN_TYPE_STRUCT:
517 case DRGN_TYPE_UNION:
518 case DRGN_TYPE_CLASS:
519 case DRGN_TYPE_ENUM:
520 return !drgn_type_tag(type);
521 default:
522 return false;
523 }
524 }
525
526 /**
527 * Returned whether a @ref drgn_type is an integer type.
528 *
529 * This is true for integer, boolean, and enumerated types, as well typedefs
530 * with an underlying type of one of those.
531 */
532 bool drgn_type_is_integer(struct drgn_type *type);
533
534 /**
535 * Return whether a @ref drgn_type is an arithmetic type.
536 *
537 * This is true for integer types (see @ref drgn_type_is_integer()) as well as
538 * floating-point types and equivalent typedefs.
539 */
540 bool drgn_type_is_arithmetic(struct drgn_type *type);
541
542 /**
543 * Return whether a @ref drgn_type is a scalar type.
544 *
545 * This is true for arithmetic types (see @ref drgn_type_is_arithmetic()) as
546 * well as pointer types and equivalent typedefs.
547 */
548 bool drgn_type_is_scalar(struct drgn_type *type);
549
550 /**
551 * Get the size of a type in bits.
552 *
553 * This is the same as multplying the result of @ref drgn_type_sizeof() by 8
554 * except that it handles overflow.
555 */
556 struct drgn_error *drgn_type_bit_size(struct drgn_type *type,
557 uint64_t *ret);
558
559 struct drgn_error *drgn_dwarf_type_alignment(struct drgn_type *type,
560 uint64_t *ret);
561
562 /** Initialize type-related fields in a @ref drgn_program. */
563 void drgn_program_init_types(struct drgn_program *prog);
564 /** Deinitialize type-related fields in a @ref drgn_program. */
565 void drgn_program_deinit_types(struct drgn_program *prog);
566
567 /**
568 * Find a parsed type in a @ref drgn_program.
569 *
570 * This should only be called by implementations of @ref
571 * drgn_language::find_type()
572 *
573 * @param[in] kind Kind of type to find. Must be @ref DRGN_TYPE_STRUCT, @ref
574 * DRGN_TYPE_UNION, @ref DRGN_TYPE_CLASS, @ref DRGN_TYPE_ENUM, or @ref
575 * DRGN_TYPE_TYPEDEF.
576 * @param[in] name Name of the type.
577 * @param[in] name_len Length of @p name in bytes.
578 * @param[in] filename See @ref drgn_program_find_type().
579 * @param[out] ret Returned type.
580 * @return @c NULL on success, &@ref drgn_not_found if the type wasn't found,
581 * non-@c NULL on other error.
582 */
583 struct drgn_error *drgn_program_find_type_impl(struct drgn_program *prog,
584 uint64_t kinds, const char *name,
585 size_t name_len,
586 const char *filename,
587 struct drgn_qualified_type *ret);
588
589 /** Find a primitive type in a @ref drgn_program. */
590 struct drgn_error *
591 drgn_program_find_primitive_type(struct drgn_program *prog,
592 enum drgn_primitive_type type,
593 struct drgn_type **ret);
594
595 /** @} */
596
597 #endif /* DRGN_TYPE_H */