Debian Codegraph @

libdrgn/language.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 * Language support.
8 *
9 * See @ref Languages.
10 */
11
12 #ifndef DRGN_LANGUAGE_H
13 #define DRGN_LANGUAGE_H
14
15 #include "drgn_internal.h"
16
17 /**
18 * @ingroup Internals
19 *
20 * @defgroup LanguageInternals Languages
21 *
22 * Language support.
23 *
24 * This defines the interface which support for a language must implement,
25 * including operators and parsing.
26 *
27 * To add a new language:
28 * - Add a @ref drgn_language_number for it.
29 * - Define a @ref drgn_language for it, and set @ref drgn_language::number to
30 * the corresponding @ref drgn_language_number.
31 * - Add it to drgn.h.
32 * - Add it to @ref drgn_languages.
33 * - Add it to add_languages() in the Python bindings.
34 * - Add it to _drgn.pyi.
35 * @{
36 */
37
38 /**
39 * Language numbers.
40 *
41 * These can be used as indices for storing language-specific data in an array.
42 */
43 enum drgn_language_number {
44 DRGN_LANGUAGE_C,
45 DRGN_LANGUAGE_CPP,
46 DRGN_NUM_LANGUAGES,
47 };
48
49 typedef struct drgn_error *drgn_format_type_fn(struct drgn_qualified_type,
50 char **);
51 typedef struct drgn_error *
52 drgn_format_variable_declaration_fn(struct drgn_qualified_type, const char *,
53 char **);
54 typedef struct drgn_error *
55 drgn_format_object_fn(const struct drgn_object *,
56 const struct drgn_format_object_options *,
57 char **);
58 typedef struct drgn_error *drgn_find_type_fn(const struct drgn_language *lang,
59 struct drgn_program *prog,
60 const char *name,
61 const char *filename,
62 struct drgn_qualified_type *ret);
63 typedef struct drgn_error *
64 drgn_type_subobject_fn(struct drgn_type *type, const char *designator,
65 bool expect_member,
66 struct drgn_qualified_type *type_ret,
67 uint64_t *bit_offset_ret, uint64_t *bit_field_size_ret);
68 typedef struct drgn_error *drgn_integer_literal_fn(struct drgn_object *res,
69 uint64_t uvalue);
70 typedef struct drgn_error *drgn_bool_literal_fn(struct drgn_object *res,
71 bool bvalue);
72 typedef struct drgn_error *drgn_float_literal_fn(struct drgn_object *res,
73 double fvalue);
74 typedef struct drgn_error *
75 drgn_cast_op(struct drgn_object *res, struct drgn_qualified_type qualified_type,
76 const struct drgn_object *obj);
77 typedef struct drgn_error *
78 drgn_implicit_convert_op(struct drgn_object *res,
79 struct drgn_qualified_type qualified_type,
80 uint64_t bit_field_size,
81 const struct drgn_object *obj);
82 typedef struct drgn_error *drgn_bool_op(const struct drgn_object *obj, bool *ret);
83 typedef struct drgn_error *drgn_cmp_op(const struct drgn_object *lhs,
84 const struct drgn_object *rhs, int *ret);
85
86 /**
87 * Language implementation.
88 *
89 * This mainly provides callbacks used to implement the higher-level libdrgn
90 * helpers. These callbacks handle the language-specific parts of the helpers.
91 *
92 * In particular, the operator callbacks should do appropriate type checking for
93 * the language and call the implementation in @ref ObjectInternals.
94 */
95 struct drgn_language {
96 /** Name of this programming language. */
97 const char *name;
98 /** Number of this programming language. */
99 enum drgn_language_number number;
100 /** Whether this language has namespaces. */
101 bool has_namespaces;
102 /** Implement @ref drgn_format_type_name(). */
103 drgn_format_type_fn *format_type_name;
104 /** Implement @ref drgn_format_type(). */
105 drgn_format_type_fn *format_type;
106 /** Implement @ref drgn_format_variable_declaration(). */
107 drgn_format_variable_declaration_fn *format_variable_declaration;
108 /** Implement @ref drgn_format_object(). */
109 drgn_format_object_fn *format_object;
110 /**
111 * Implement @ref drgn_program_find_type().
112 *
113 * This should parse @p name and call @ref
114 * drgn_program_find_type_impl().
115 */
116 drgn_find_type_fn *find_type;
117 /**
118 * Get the type, offset, and bit field size of a subobject of a type.
119 *
120 * @param[in] type Starting type.
121 * @param[in] designator One or more member references or array
122 * subscripts.
123 * @param[in] expect_member Require a member reference first.
124 * @param[out] type_ret If not @c NULL, returned subobject type.
125 * @param[out] bit_offset_ret If not @c NULL, returned offset in bits of
126 * subobject from the beginning of @p type.
127 * @param[out] bit_field_size_ret If not @c NULL, returned bit field
128 * size of subobject.
129 */
130 drgn_type_subobject_fn *type_subobject;
131 /**
132 * Set an object to an integer literal.
133 *
134 * This should set @p res to the given value and appropriate type for an
135 * integer literal in the language.
136 */
137 drgn_integer_literal_fn *integer_literal;
138 /**
139 * Set an object to a boolean literal.
140 *
141 * This should set @p res to the given value and the boolean type in the
142 * language.
143 */
144 drgn_bool_literal_fn *bool_literal;
145 /**
146 * Set an object to a floating-point literal.
147 *
148 * This should set @p res to the given value and appropriate type for a
149 * floating-point literal in the language.
150 */
151 drgn_float_literal_fn *float_literal;
152 drgn_cast_op *op_cast;
153 drgn_implicit_convert_op *op_implicit_convert;
154 drgn_bool_op *op_bool;
155 drgn_cmp_op *op_cmp;
156 drgn_binary_op *op_add;
157 drgn_binary_op *op_sub;
158 drgn_binary_op *op_mul;
159 drgn_binary_op *op_div;
160 drgn_binary_op *op_mod;
161 drgn_binary_op *op_lshift;
162 drgn_binary_op *op_rshift;
163 drgn_binary_op *op_and;
164 drgn_binary_op *op_or;
165 drgn_binary_op *op_xor;
166 drgn_unary_op *op_pos;
167 drgn_unary_op *op_neg;
168 drgn_unary_op *op_not;
169 };
170
171 /** Mapping from @ref drgn_language_number to @ref drgn_language. */
172 extern const struct drgn_language * const drgn_languages[];
173
174 /** Language to be used when actual language is unknown. */
175 #define drgn_default_language drgn_language_c
176
177 /**
178 * Return flags that should be passed through when formatting an object
179 * recursively.
180 */
181 static inline enum drgn_format_object_flags
182 drgn_passthrough_format_object_flags(enum drgn_format_object_flags flags)
183 {
184 return (flags & (DRGN_FORMAT_OBJECT_SYMBOLIZE |
185 DRGN_FORMAT_OBJECT_STRING |
186 DRGN_FORMAT_OBJECT_CHAR |
187 DRGN_FORMAT_OBJECT_MEMBER_TYPE_NAMES |
188 DRGN_FORMAT_OBJECT_ELEMENT_TYPE_NAMES |
189 DRGN_FORMAT_OBJECT_MEMBERS_SAME_LINE |
190 DRGN_FORMAT_OBJECT_ELEMENTS_SAME_LINE |
191 DRGN_FORMAT_OBJECT_MEMBER_NAMES |
192 DRGN_FORMAT_OBJECT_ELEMENT_INDICES |
193 DRGN_FORMAT_OBJECT_IMPLICIT_MEMBERS |
194 DRGN_FORMAT_OBJECT_IMPLICIT_ELEMENTS));
195 }
196
197 /** Return flags that should be passed when formatting object members. */
198 static inline enum drgn_format_object_flags
199 drgn_member_format_object_flags(enum drgn_format_object_flags flags)
200 {
201 return (drgn_passthrough_format_object_flags(flags) |
202 (flags & DRGN_FORMAT_OBJECT_MEMBER_TYPE_NAMES) >> 1);
203 }
204
205 /** Return flags that should be passed when formatting object elements. */
206 static inline enum drgn_format_object_flags
207 drgn_element_format_object_flags(enum drgn_format_object_flags flags)
208 {
209 return (drgn_passthrough_format_object_flags(flags) |
210 (flags & DRGN_FORMAT_OBJECT_ELEMENT_TYPE_NAMES) >> 2);
211 }
212
213 /** @} */
214
215 #endif /* DRGN_LANGUAGE_H */