Debian Codegraph @

gcc/jit/docs/topics/types.rst

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