]>
Commit | Line | Data |
---|---|---|
a5544970 | 1 | .. Copyright (C) 2014-2019 Free Software Foundation, Inc. |
35485da9 DM |
2 | Originally contributed by David Malcolm <dmalcolm@redhat.com> |
3 | ||
4 | This is free software: you can redistribute it and/or modify it | |
5 | under the terms of the GNU General Public License as published by | |
6 | the Free Software Foundation, either version 3 of the License, or | |
7 | (at your option) any later version. | |
8 | ||
9 | This program is distributed in the hope that it will be useful, but | |
10 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
12 | General Public License for more details. | |
13 | ||
14 | You should have received a copy of the GNU General Public License | |
15 | along with this program. If not, see | |
16 | <http://www.gnu.org/licenses/>. | |
17 | ||
18 | .. default-domain:: c | |
19 | ||
20 | Types | |
21 | ===== | |
22 | ||
23 | .. c:type:: gcc_jit_type | |
24 | ||
25 | gcc_jit_type represents a type within the library. | |
26 | ||
27 | .. function:: gcc_jit_object *gcc_jit_type_as_object (gcc_jit_type *type) | |
28 | ||
29 | Upcast a type to an object. | |
30 | ||
31 | Types can be created in several ways: | |
32 | ||
33 | * fundamental types can be accessed using | |
34 | :func:`gcc_jit_context_get_type`: | |
35 | ||
36 | .. code-block:: c | |
37 | ||
47ee1b7c | 38 | gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT); |
35485da9 DM |
39 | |
40 | See :func:`gcc_jit_context_get_type` for the available types. | |
41 | ||
42 | * derived types can be accessed by using functions such as | |
43 | :func:`gcc_jit_type_get_pointer` and :func:`gcc_jit_type_get_const`: | |
44 | ||
45 | .. code-block:: c | |
46 | ||
47 | gcc_jit_type *const_int_star = gcc_jit_type_get_pointer (gcc_jit_type_get_const (int_type)); | |
48 | gcc_jit_type *int_const_star = gcc_jit_type_get_const (gcc_jit_type_get_pointer (int_type)); | |
49 | ||
50 | * by creating structures (see below). | |
51 | ||
52 | Standard types | |
53 | -------------- | |
54 | ||
55 | .. function:: gcc_jit_type *gcc_jit_context_get_type (gcc_jit_context *ctxt, \ | |
56 | enum gcc_jit_types type_) | |
57 | ||
58 | Access a specific type. The available types are: | |
59 | ||
eeafb319 DM |
60 | ========================================== ================================ |
61 | `enum gcc_jit_types` value Meaning | |
62 | ========================================== ================================ | |
63 | :c:data:`GCC_JIT_TYPE_VOID` C's ``void`` type. | |
64 | :c:data:`GCC_JIT_TYPE_VOID_PTR` C's ``void *``. | |
65 | :c:data:`GCC_JIT_TYPE_BOOL` C++'s ``bool`` type; also C99's | |
66 | ``_Bool`` type, aka ``bool`` if | |
67 | using stdbool.h. | |
68 | :c:data:`GCC_JIT_TYPE_CHAR` C's ``char`` (of some signedness) | |
69 | :c:data:`GCC_JIT_TYPE_SIGNED_CHAR` C's ``signed char`` | |
70 | :c:data:`GCC_JIT_TYPE_UNSIGNED_CHAR` C's ``unsigned char`` | |
71 | :c:data:`GCC_JIT_TYPE_SHORT` C's ``short`` (signed) | |
72 | :c:data:`GCC_JIT_TYPE_UNSIGNED_SHORT` C's ``unsigned short`` | |
73 | :c:data:`GCC_JIT_TYPE_INT` C's ``int`` (signed) | |
74 | :c:data:`GCC_JIT_TYPE_UNSIGNED_INT` C's ``unsigned int`` | |
75 | :c:data:`GCC_JIT_TYPE_LONG` C's ``long`` (signed) | |
76 | :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG` C's ``unsigned long`` | |
77 | :c:data:`GCC_JIT_TYPE_LONG_LONG` C99's ``long long`` (signed) | |
78 | :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG_LONG` C99's ``unsigned long long`` | |
35485da9 DM |
79 | :c:data:`GCC_JIT_TYPE_FLOAT` |
80 | :c:data:`GCC_JIT_TYPE_DOUBLE` | |
81 | :c:data:`GCC_JIT_TYPE_LONG_DOUBLE` | |
eeafb319 DM |
82 | :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR` C type: ``(const char *)`` |
83 | :c:data:`GCC_JIT_TYPE_SIZE_T` C's ``size_t`` type | |
84 | :c:data:`GCC_JIT_TYPE_FILE_PTR` C type: ``(FILE *)`` | |
85 | :c:data:`GCC_JIT_TYPE_COMPLEX_FLOAT` C99's ``_Complex float`` | |
86 | :c:data:`GCC_JIT_TYPE_COMPLEX_DOUBLE` C99's ``_Complex double`` | |
87 | :c:data:`GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE` C99's ``_Complex long double`` | |
88 | ========================================== ================================ | |
35485da9 DM |
89 | |
90 | .. function:: gcc_jit_type *\ | |
91 | gcc_jit_context_get_int_type (gcc_jit_context *ctxt, \ | |
92 | int num_bytes, int is_signed) | |
93 | ||
94 | Access the integer type of the given size. | |
95 | ||
96 | ||
97 | Pointers, `const`, and `volatile` | |
98 | --------------------------------- | |
99 | ||
100 | .. function:: gcc_jit_type *gcc_jit_type_get_pointer (gcc_jit_type *type) | |
101 | ||
102 | Given type "T", get type "T*". | |
103 | ||
104 | .. function:: gcc_jit_type *gcc_jit_type_get_const (gcc_jit_type *type) | |
105 | ||
106 | Given type "T", get type "const T". | |
107 | ||
108 | .. function:: gcc_jit_type *gcc_jit_type_get_volatile (gcc_jit_type *type) | |
109 | ||
110 | Given type "T", get type "volatile T". | |
111 | ||
112 | .. function:: gcc_jit_type *\ | |
113 | gcc_jit_context_new_array_type (gcc_jit_context *ctxt, \ | |
114 | gcc_jit_location *loc, \ | |
115 | gcc_jit_type *element_type, \ | |
116 | int num_elements) | |
117 | ||
118 | Given type "T", get type "T[N]" (for a constant N). | |
119 | ||
0ebd1f00 DM |
120 | .. function:: gcc_jit_type *\ |
121 | gcc_jit_type_get_aligned (gcc_jit_type *type, \ | |
122 | size_t alignment_in_bytes) | |
123 | ||
124 | Given type "T", get type: | |
125 | ||
126 | .. code-block:: c | |
127 | ||
128 | T __attribute__ ((aligned (ALIGNMENT_IN_BYTES))) | |
129 | ||
130 | The alignment must be a power of two. | |
131 | ||
132 | This entrypoint was added in :ref:`LIBGCCJIT_ABI_7`; you can test for | |
133 | its presence using | |
134 | ||
135 | .. code-block:: c | |
136 | ||
137 | #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_aligned | |
138 | ||
47ee1b7c DM |
139 | Vector types |
140 | ------------ | |
141 | ||
142 | .. function:: gcc_jit_type *\ | |
143 | gcc_jit_type_get_vector (gcc_jit_type *type, \ | |
144 | size_t num_units) | |
145 | ||
146 | Given type "T", get type: | |
147 | ||
148 | .. code-block:: c | |
149 | ||
150 | T __attribute__ ((vector_size (sizeof(T) * num_units)) | |
151 | ||
152 | T must be integral or floating point; num_units must be a power of two. | |
153 | ||
154 | This can be used to construct a vector type in which operations | |
155 | are applied element-wise. The compiler will automatically | |
156 | use SIMD instructions where possible. See: | |
157 | https://gcc.gnu.org/onlinedocs/gcc/Vector-Extensions.html | |
158 | ||
159 | For example, assuming 4-byte ``ints``, then: | |
160 | ||
161 | .. code-block:: c | |
162 | ||
163 | typedef int v4si __attribute__ ((vector_size (16))); | |
164 | ||
165 | can be obtained using: | |
166 | ||
167 | .. code-block:: c | |
168 | ||
169 | gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt, | |
170 | GCC_JIT_TYPE_INT); | |
171 | gcc_jit_type *v4si_type = gcc_jit_type_get_vector (int_type, 4); | |
172 | ||
173 | This API entrypoint was added in :ref:`LIBGCCJIT_ABI_8`; you can test | |
174 | for its presence using | |
175 | ||
176 | .. code-block:: c | |
177 | ||
178 | #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_vector | |
179 | ||
6069fe72 DM |
180 | Vector rvalues can be generated using |
181 | :func:`gcc_jit_context_new_rvalue_from_vector`. | |
182 | ||
35485da9 DM |
183 | |
184 | Structures and unions | |
185 | --------------------- | |
186 | ||
187 | .. c:type:: gcc_jit_struct | |
188 | ||
189 | A compound type analagous to a C `struct`. | |
190 | ||
191 | .. c:type:: gcc_jit_field | |
192 | ||
193 | A field within a :c:type:`gcc_jit_struct`. | |
194 | ||
195 | You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and | |
196 | :c:type:`gcc_jit_field` instances, in either order: | |
197 | ||
198 | * by creating the fields, then the structure. For example, to model: | |
199 | ||
200 | .. code-block:: c | |
201 | ||
202 | struct coord {double x; double y; }; | |
203 | ||
204 | you could call: | |
205 | ||
206 | .. code-block:: c | |
207 | ||
208 | gcc_jit_field *field_x = | |
209 | gcc_jit_context_new_field (ctxt, NULL, double_type, "x"); | |
210 | gcc_jit_field *field_y = | |
211 | gcc_jit_context_new_field (ctxt, NULL, double_type, "y"); | |
212 | gcc_jit_field *fields[2] = {field_x, field_y}; | |
213 | gcc_jit_struct *coord = | |
214 | gcc_jit_context_new_struct_type (ctxt, NULL, "coord", 2, fields); | |
215 | ||
216 | * by creating the structure, then populating it with fields, typically | |
217 | to allow modelling self-referential structs such as: | |
218 | ||
219 | .. code-block:: c | |
220 | ||
221 | struct node { int m_hash; struct node *m_next; }; | |
222 | ||
223 | like this: | |
224 | ||
225 | .. code-block:: c | |
226 | ||
227 | gcc_jit_type *node = | |
228 | gcc_jit_context_new_opaque_struct (ctxt, NULL, "node"); | |
229 | gcc_jit_type *node_ptr = | |
230 | gcc_jit_type_get_pointer (node); | |
231 | gcc_jit_field *field_hash = | |
232 | gcc_jit_context_new_field (ctxt, NULL, int_type, "m_hash"); | |
233 | gcc_jit_field *field_next = | |
234 | gcc_jit_context_new_field (ctxt, NULL, node_ptr, "m_next"); | |
235 | gcc_jit_field *fields[2] = {field_hash, field_next}; | |
236 | gcc_jit_struct_set_fields (node, NULL, 2, fields); | |
237 | ||
238 | .. function:: gcc_jit_field *\ | |
239 | gcc_jit_context_new_field (gcc_jit_context *ctxt,\ | |
240 | gcc_jit_location *loc,\ | |
241 | gcc_jit_type *type,\ | |
242 | const char *name) | |
243 | ||
244 | Construct a new field, with the given type and name. | |
245 | ||
c575221a DM |
246 | The parameter ``name`` must be non-NULL. The call takes a copy of the |
247 | underlying string, so it is valid to pass in a pointer to an on-stack | |
248 | buffer. | |
249 | ||
ee118c14 AC |
250 | .. function:: gcc_jit_field *\ |
251 | gcc_jit_context_new_bitfield (gcc_jit_context *ctxt,\ | |
252 | gcc_jit_location *loc,\ | |
253 | gcc_jit_type *type,\ | |
254 | int width,\ | |
255 | const char *name) | |
256 | ||
257 | Construct a new bit field, with the given type width and name. | |
258 | ||
259 | The parameter ``name`` must be non-NULL. The call takes a copy of the | |
260 | underlying string, so it is valid to pass in a pointer to an on-stack | |
261 | buffer. | |
262 | ||
263 | The parameter ``type`` must be an integer type. | |
264 | ||
265 | The parameter ``width`` must be a positive integer that does not exceed the | |
266 | size of ``type``. | |
267 | ||
268 | This API entrypoint was added in :ref:`LIBGCCJIT_ABI_12`; you can test | |
269 | for its presence using | |
270 | .. code-block:: c | |
271 | ||
272 | #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitfield | |
273 | ||
35485da9 DM |
274 | .. function:: gcc_jit_object *\ |
275 | gcc_jit_field_as_object (gcc_jit_field *field) | |
276 | ||
277 | Upcast from field to object. | |
278 | ||
279 | .. function:: gcc_jit_struct *\ | |
280 | gcc_jit_context_new_struct_type (gcc_jit_context *ctxt,\ | |
281 | gcc_jit_location *loc,\ | |
282 | const char *name,\ | |
283 | int num_fields,\ | |
284 | gcc_jit_field **fields) | |
285 | ||
286 | Construct a new struct type, with the given name and fields. | |
287 | ||
c575221a DM |
288 | The parameter ``name`` must be non-NULL. The call takes a copy of |
289 | the underlying string, so it is valid to pass in a pointer to an | |
290 | on-stack buffer. | |
291 | ||
35485da9 DM |
292 | .. function:: gcc_jit_struct *\ |
293 | gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt,\ | |
294 | gcc_jit_location *loc,\ | |
295 | const char *name) | |
296 | ||
297 | Construct a new struct type, with the given name, but without | |
298 | specifying the fields. The fields can be omitted (in which case the | |
299 | size of the struct is not known), or later specified using | |
300 | :c:func:`gcc_jit_struct_set_fields`. | |
301 | ||
c575221a DM |
302 | The parameter ``name`` must be non-NULL. The call takes a copy of |
303 | the underlying string, so it is valid to pass in a pointer to an | |
304 | on-stack buffer. | |
305 | ||
35485da9 DM |
306 | .. function:: gcc_jit_type *\ |
307 | gcc_jit_struct_as_type (gcc_jit_struct *struct_type) | |
308 | ||
309 | Upcast from struct to type. | |
310 | ||
311 | .. function:: void\ | |
312 | gcc_jit_struct_set_fields (gcc_jit_struct *struct_type,\ | |
313 | gcc_jit_location *loc,\ | |
314 | int num_fields,\ | |
315 | gcc_jit_field **fields) | |
316 | ||
317 | Populate the fields of a formerly-opaque struct type. | |
318 | ||
319 | This can only be called once on a given struct type. | |
e807aeaa DM |
320 | |
321 | .. function:: gcc_jit_type *\ | |
322 | gcc_jit_context_new_union_type (gcc_jit_context *ctxt,\ | |
323 | gcc_jit_location *loc,\ | |
324 | const char *name,\ | |
325 | int num_fields,\ | |
326 | gcc_jit_field **fields) | |
327 | ||
328 | Construct a new union type, with the given name and fields. | |
329 | ||
330 | The parameter ``name`` must be non-NULL. It is copied, so the input | |
331 | buffer does not need to outlive the call. | |
332 | ||
333 | Example of use: | |
334 | ||
335 | .. literalinclude:: ../../../testsuite/jit.dg/test-accessing-union.c | |
336 | :start-after: /* Quote from here in docs/topics/types.rst. */ | |
337 | :end-before: /* Quote up to here in docs/topics/types.rst. */ | |
338 | :language: c | |
ecd5156d DM |
339 | |
340 | Function pointer types | |
341 | ---------------------- | |
342 | ||
343 | Function pointer types can be created using | |
344 | :c:func:`gcc_jit_context_new_function_ptr_type`. |