Debian Codegraph @

gcc/jit/docs/topics/types.rst

raw
1 .. Copyright (C) 2014-2023 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <[email protected]>
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 <https://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
38 gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
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
60 .. list-table::
61 :header-rows: 1
62
63 * - `enum gcc_jit_types` value
64 - Meaning
65
66 * - :c:data:`GCC_JIT_TYPE_VOID`
67 - C's ``void`` type.
68 * - :c:data:`GCC_JIT_TYPE_VOID_PTR`
69 - C's ``void *``.
70 * - :c:data:`GCC_JIT_TYPE_BOOL`
71 - C++'s ``bool`` type; also C99's ``_Bool`` type, aka ``bool`` if using stdbool.h.
72 * - :c:data:`GCC_JIT_TYPE_CHAR`
73 - C's ``char`` (of some signedness)
74 * - :c:data:`GCC_JIT_TYPE_SIGNED_CHAR`
75 - C's ``signed char``
76 * - :c:data:`GCC_JIT_TYPE_UNSIGNED_CHAR`
77 - C's ``unsigned char``
78 * - :c:data:`GCC_JIT_TYPE_SHORT`
79 - C's ``short`` (signed)
80 * - :c:data:`GCC_JIT_TYPE_UNSIGNED_SHORT`
81 - C's ``unsigned short``
82 * - :c:data:`GCC_JIT_TYPE_INT`
83 - C's ``int`` (signed)
84 * - :c:data:`GCC_JIT_TYPE_UNSIGNED_INT`
85 - C's ``unsigned int``
86 * - :c:data:`GCC_JIT_TYPE_LONG`
87 - C's ``long`` (signed)
88 * - :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG`
89 - C's ``unsigned long``
90 * - :c:data:`GCC_JIT_TYPE_LONG_LONG`
91 - C99's ``long long`` (signed)
92 * - :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG_LONG`
93 - C99's ``unsigned long long``
94 * - :c:data:`GCC_JIT_TYPE_UINT8_T`
95 - C99's ``uint8_t``
96 * - :c:data:`GCC_JIT_TYPE_UINT16_T`
97 - C99's ``uint16_t``
98 * - :c:data:`GCC_JIT_TYPE_UINT32_T`
99 - C99's ``uint32_t``
100 * - :c:data:`GCC_JIT_TYPE_UINT64_T`
101 - C99's ``uint64_t``
102 * - :c:data:`GCC_JIT_TYPE_UINT128_T`
103 - C99's ``__uint128_t``
104 * - :c:data:`GCC_JIT_TYPE_INT8_T`
105 - C99's ``int8_t``
106 * - :c:data:`GCC_JIT_TYPE_INT16_T`
107 - C99's ``int16_t``
108 * - :c:data:`GCC_JIT_TYPE_INT32_T`
109 - C99's ``int32_t``
110 * - :c:data:`GCC_JIT_TYPE_INT64_T`
111 - C99's ``int64_t``
112 * - :c:data:`GCC_JIT_TYPE_INT128_T`
113 - C99's ``__int128_t``
114 * - :c:data:`GCC_JIT_TYPE_FLOAT`
115 -
116 * - :c:data:`GCC_JIT_TYPE_DOUBLE`
117 -
118 * - :c:data:`GCC_JIT_TYPE_LONG_DOUBLE`
119 -
120 * - :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`
121 - C type: ``(const char *)``
122 * - :c:data:`GCC_JIT_TYPE_SIZE_T`
123 - C's ``size_t`` type
124 * - :c:data:`GCC_JIT_TYPE_FILE_PTR`
125 - C type: ``(FILE *)``
126 * - :c:data:`GCC_JIT_TYPE_COMPLEX_FLOAT`
127 - C99's ``_Complex float``
128 * - :c:data:`GCC_JIT_TYPE_COMPLEX_DOUBLE`
129 - C99's ``_Complex double``
130 * - :c:data:`GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE`
131 - C99's ``_Complex long double``
132
133 .. function:: gcc_jit_type *\
134 gcc_jit_context_get_int_type (gcc_jit_context *ctxt, \
135 int num_bytes, int is_signed)
136
137 Access the integer type of the given size.
138
139
140 Pointers, `const`, and `volatile`
141 ---------------------------------
142
143 .. function:: gcc_jit_type *gcc_jit_type_get_pointer (gcc_jit_type *type)
144
145 Given type "T", get type "T*".
146
147 .. function:: gcc_jit_type *gcc_jit_type_get_const (gcc_jit_type *type)
148
149 Given type "T", get type "const T".
150
151 .. function:: gcc_jit_type *gcc_jit_type_get_volatile (gcc_jit_type *type)
152
153 Given type "T", get type "volatile T".
154
155 .. function:: gcc_jit_type *\
156 gcc_jit_context_new_array_type (gcc_jit_context *ctxt, \
157 gcc_jit_location *loc, \
158 gcc_jit_type *element_type, \
159 int num_elements)
160
161 Given non-`void` type "T", get type "T[N]" (for a constant N).
162
163 .. function:: gcc_jit_type *\
164 gcc_jit_type_get_aligned (gcc_jit_type *type, \
165 size_t alignment_in_bytes)
166
167 Given non-`void` type "T", get type:
168
169 .. code-block:: c
170
171 T __attribute__ ((aligned (ALIGNMENT_IN_BYTES)))
172
173 The alignment must be a power of two.
174
175 This entrypoint was added in :ref:`LIBGCCJIT_ABI_7`; you can test for
176 its presence using
177
178 .. code-block:: c
179
180 #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_aligned
181
182 Vector types
183 ------------
184
185 .. function:: gcc_jit_type *\
186 gcc_jit_type_get_vector (gcc_jit_type *type, \
187 size_t num_units)
188
189 Given type "T", get type:
190
191 .. code-block:: c
192
193 T __attribute__ ((vector_size (sizeof(T) * num_units))
194
195 T must be integral or floating point; num_units must be a power of two.
196
197 This can be used to construct a vector type in which operations
198 are applied element-wise. The compiler will automatically
199 use SIMD instructions where possible. See:
200 https://gcc.gnu.org/onlinedocs/gcc/Vector-Extensions.html
201
202 For example, assuming 4-byte ``ints``, then:
203
204 .. code-block:: c
205
206 typedef int v4si __attribute__ ((vector_size (16)));
207
208 can be obtained using:
209
210 .. code-block:: c
211
212 gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt,
213 GCC_JIT_TYPE_INT);
214 gcc_jit_type *v4si_type = gcc_jit_type_get_vector (int_type, 4);
215
216 This API entrypoint was added in :ref:`LIBGCCJIT_ABI_8`; you can test
217 for its presence using
218
219 .. code-block:: c
220
221 #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_vector
222
223 Vector rvalues can be generated using
224 :func:`gcc_jit_context_new_rvalue_from_vector`.
225
226
227 Structures and unions
228 ---------------------
229
230 .. c:type:: gcc_jit_struct
231
232 A compound type analagous to a C `struct`.
233
234 .. c:type:: gcc_jit_field
235
236 A field within a :c:type:`gcc_jit_struct`.
237
238 You can model C `struct` types by creating :c:type:`gcc_jit_struct` and
239 :c:type:`gcc_jit_field` instances, in either order:
240
241 * by creating the fields, then the structure. For example, to model:
242
243 .. code-block:: c
244
245 struct coord {double x; double y; };
246
247 you could call:
248
249 .. code-block:: c
250
251 gcc_jit_field *field_x =
252 gcc_jit_context_new_field (ctxt, NULL, double_type, "x");
253 gcc_jit_field *field_y =
254 gcc_jit_context_new_field (ctxt, NULL, double_type, "y");
255 gcc_jit_field *fields[2] = {field_x, field_y};
256 gcc_jit_struct *coord =
257 gcc_jit_context_new_struct_type (ctxt, NULL, "coord", 2, fields);
258
259 * by creating the structure, then populating it with fields, typically
260 to allow modelling self-referential structs such as:
261
262 .. code-block:: c
263
264 struct node { int m_hash; struct node *m_next; };
265
266 like this:
267
268 .. code-block:: c
269
270 gcc_jit_type *node =
271 gcc_jit_context_new_opaque_struct (ctxt, NULL, "node");
272 gcc_jit_type *node_ptr =
273 gcc_jit_type_get_pointer (node);
274 gcc_jit_field *field_hash =
275 gcc_jit_context_new_field (ctxt, NULL, int_type, "m_hash");
276 gcc_jit_field *field_next =
277 gcc_jit_context_new_field (ctxt, NULL, node_ptr, "m_next");
278 gcc_jit_field *fields[2] = {field_hash, field_next};
279 gcc_jit_struct_set_fields (node, NULL, 2, fields);
280
281 .. function:: gcc_jit_field *\
282 gcc_jit_context_new_field (gcc_jit_context *ctxt,\
283 gcc_jit_location *loc,\
284 gcc_jit_type *type,\
285 const char *name)
286
287 Construct a new field, with the given type and name.
288
289 The parameter ``type`` must be non-`void`.
290
291 The parameter ``name`` must be non-NULL. The call takes a copy of the
292 underlying string, so it is valid to pass in a pointer to an on-stack
293 buffer.
294
295 .. function:: gcc_jit_field *\
296 gcc_jit_context_new_bitfield (gcc_jit_context *ctxt,\
297 gcc_jit_location *loc,\
298 gcc_jit_type *type,\
299 int width,\
300 const char *name)
301
302 Construct a new bit field, with the given type width and name.
303
304 The parameter ``name`` must be non-NULL. The call takes a copy of the
305 underlying string, so it is valid to pass in a pointer to an on-stack
306 buffer.
307
308 The parameter ``type`` must be an integer type.
309
310 The parameter ``width`` must be a positive integer that does not exceed the
311 size of ``type``.
312
313 This API entrypoint was added in :ref:`LIBGCCJIT_ABI_12`; you can test
314 for its presence using
315
316 .. code-block:: c
317
318 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitfield
319
320 .. function:: gcc_jit_object *\
321 gcc_jit_field_as_object (gcc_jit_field *field)
322
323 Upcast from field to object.
324
325 .. function:: gcc_jit_struct *\
326 gcc_jit_context_new_struct_type (gcc_jit_context *ctxt,\
327 gcc_jit_location *loc,\
328 const char *name,\
329 int num_fields,\
330 gcc_jit_field **fields)
331
332 Construct a new struct type, with the given name and fields.
333
334 The parameter ``name`` must be non-NULL. The call takes a copy of
335 the underlying string, so it is valid to pass in a pointer to an
336 on-stack buffer.
337
338 .. function:: gcc_jit_struct *\
339 gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt,\
340 gcc_jit_location *loc,\
341 const char *name)
342
343 Construct a new struct type, with the given name, but without
344 specifying the fields. The fields can be omitted (in which case the
345 size of the struct is not known), or later specified using
346 :c:func:`gcc_jit_struct_set_fields`.
347
348 The parameter ``name`` must be non-NULL. The call takes a copy of
349 the underlying string, so it is valid to pass in a pointer to an
350 on-stack buffer.
351
352 .. function:: gcc_jit_type *\
353 gcc_jit_struct_as_type (gcc_jit_struct *struct_type)
354
355 Upcast from struct to type.
356
357 .. function:: void\
358 gcc_jit_struct_set_fields (gcc_jit_struct *struct_type,\
359 gcc_jit_location *loc,\
360 int num_fields,\
361 gcc_jit_field **fields)
362
363 Populate the fields of a formerly-opaque struct type.
364
365 This can only be called once on a given struct type.
366
367 .. function:: gcc_jit_type *\
368 gcc_jit_context_new_union_type (gcc_jit_context *ctxt,\
369 gcc_jit_location *loc,\
370 const char *name,\
371 int num_fields,\
372 gcc_jit_field **fields)
373
374 Construct a new union type, with the given name and fields.
375
376 The parameter ``name`` must be non-NULL. It is copied, so the input
377 buffer does not need to outlive the call.
378
379 Example of use:
380
381 .. literalinclude:: ../../../testsuite/jit.dg/test-accessing-union.c
382 :start-after: /* Quote from here in docs/topics/types.rst. */
383 :end-before: /* Quote up to here in docs/topics/types.rst. */
384 :language: c
385
386 Function pointer types
387 ----------------------
388
389 Function pointer types can be created using
390 :c:func:`gcc_jit_context_new_function_ptr_type`.
391
392 Reflection API
393 --------------
394
395 .. function:: gcc_jit_type *\
396 gcc_jit_type_dyncast_array (gcc_jit_type *type)
397
398 Get the element type of an array type or NULL if it's not an array.
399
400 .. function:: int\
401 gcc_jit_type_is_bool (gcc_jit_type *type)
402
403 Return non-zero if the type is a bool.
404
405 .. function:: gcc_jit_function_type *\
406 gcc_jit_type_dyncast_function_ptr_type (gcc_jit_type *type)
407
408 Return the function type if it is one or NULL.
409
410 .. function:: gcc_jit_type *\
411 gcc_jit_function_type_get_return_type (gcc_jit_function_type *function_type)
412
413 Given a function type, return its return type.
414
415 .. function:: size_t\
416 gcc_jit_function_type_get_param_count (gcc_jit_function_type *function_type)
417
418 Given a function type, return its number of parameters.
419
420 .. function:: gcc_jit_type *\
421 gcc_jit_function_type_get_param_type (gcc_jit_function_type *function_type,\
422 size_t index)
423
424 Given a function type, return the type of the specified parameter.
425
426 .. function:: int\
427 gcc_jit_type_is_integral (gcc_jit_type *type)
428
429 Return non-zero if the type is an integral.
430
431 .. function:: gcc_jit_type *\
432 gcc_jit_type_is_pointer (gcc_jit_type *type)
433
434 Return the type pointed by the pointer type or NULL if it's not a pointer.
435
436 .. function:: gcc_jit_vector_type *\
437 gcc_jit_type_dyncast_vector (gcc_jit_type *type)
438
439 Given a type, return a dynamic cast to a vector type or NULL.
440
441 .. function:: gcc_jit_struct *\
442 gcc_jit_type_is_struct (gcc_jit_type *type)
443
444 Given a type, return a dynamic cast to a struct type or NULL.
445
446 .. function:: size_t\
447 gcc_jit_vector_type_get_num_units (gcc_jit_vector_type *vector_type)
448
449 Given a vector type, return the number of units it contains.
450
451 .. function:: gcc_jit_type *\
452 gcc_jit_vector_type_get_element_type (gcc_jit_vector_type * vector_type)
453
454 Given a vector type, return the type of its elements.
455
456 .. function:: gcc_jit_type *\
457 gcc_jit_type_unqualified (gcc_jit_type *type)
458
459 Given a type, return the unqualified type, removing "const", "volatile" and
460 alignment qualifiers.
461
462 .. function:: gcc_jit_field *\
463 gcc_jit_struct_get_field (gcc_jit_struct *struct_type,\
464 size_t index)
465
466 Get a struct field by index.
467
468 .. function:: size_t\
469 gcc_jit_struct_get_field_count (gcc_jit_struct *struct_type)
470
471 Get the number of fields in the struct.
472
473 The API entrypoints related to the reflection API:
474
475 * :c:func:`gcc_jit_function_type_get_return_type`
476
477 * :c:func:`gcc_jit_function_type_get_param_count`
478
479 * :c:func:`gcc_jit_function_type_get_param_type`
480
481 * :c:func:`gcc_jit_type_unqualified`
482
483 * :c:func:`gcc_jit_type_dyncast_array`
484
485 * :c:func:`gcc_jit_type_is_bool`
486
487 * :c:func:`gcc_jit_type_dyncast_function_ptr_type`
488
489 * :c:func:`gcc_jit_type_is_integral`
490
491 * :c:func:`gcc_jit_type_is_pointer`
492
493 * :c:func:`gcc_jit_type_dyncast_vector`
494
495 * :c:func:`gcc_jit_vector_type_get_element_type`
496
497 * :c:func:`gcc_jit_vector_type_get_num_units`
498
499 * :c:func:`gcc_jit_struct_get_field`
500
501 * :c:func:`gcc_jit_type_is_struct`
502
503 * :c:func:`gcc_jit_struct_get_field_count`
504
505 were added in :ref:`LIBGCCJIT_ABI_16`; you can test for their presence
506 using
507
508 .. code-block:: c
509
510 #ifdef LIBGCCJIT_HAVE_REFLECTION
511
512 .. type:: gcc_jit_case
513
514 .. function:: int\
515 gcc_jit_compatible_types (gcc_jit_type *ltype,\
516 gcc_jit_type *rtype)
517
518 Return non-zero if the two types are compatible. For instance,
519 if :c:data:`GCC_JIT_TYPE_UINT64_T` and :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG`
520 are the same size on the target, this will return non-zero.
521 The parameters ``ltype`` and ``rtype`` must be non-NULL.
522 Return 0 on errors.
523
524 This entrypoint was added in :ref:`LIBGCCJIT_ABI_20`; you can test for
525 its presence using
526
527 .. code-block:: c
528
529 #ifdef LIBGCCJIT_HAVE_SIZED_INTEGERS
530
531 .. function:: ssize_t\
532 gcc_jit_type_get_size (gcc_jit_type *type)
533
534 Return the size of a type, in bytes. It only works on integer types for now.
535 The parameter ``type`` must be non-NULL.
536 Return -1 on errors.
537
538 This entrypoint was added in :ref:`LIBGCCJIT_ABI_20`; you can test for
539 its presence using
540
541 .. code-block:: c
542
543 #ifdef LIBGCCJIT_HAVE_SIZED_INTEGERS