1 .. Copyright (C) 2014-2019 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <dmalcolm@redhat.com>
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.
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.
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/>.
23 .. c:type:: gcc_jit_type
25 gcc_jit_type represents a type within the library.
27 .. function:: gcc_jit_object *gcc_jit_type_as_object (gcc_jit_type *type)
29 Upcast a type to an object.
31 Types can be created in several ways:
33 * fundamental types can be accessed using
34 :func:`gcc_jit_context_get_type`:
38 gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
40 See :func:`gcc_jit_context_get_type` for the available types.
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`:
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));
50 * by creating structures (see below).
55 .. function:: gcc_jit_type *gcc_jit_context_get_type (gcc_jit_context *ctxt, \
56 enum gcc_jit_types type_)
58 Access a specific type. The available types are:
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
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_FLOAT`
80 :c:data:`GCC_JIT_TYPE_DOUBLE`
81 :c:data:`GCC_JIT_TYPE_LONG_DOUBLE`
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 ========================================== ================================
90 .. function:: gcc_jit_type *\
91 gcc_jit_context_get_int_type (gcc_jit_context *ctxt, \
92 int num_bytes, int is_signed)
94 Access the integer type of the given size.
97 Pointers, `const`, and `volatile`
98 ---------------------------------
100 .. function:: gcc_jit_type *gcc_jit_type_get_pointer (gcc_jit_type *type)
102 Given type "T", get type "T*".
104 .. function:: gcc_jit_type *gcc_jit_type_get_const (gcc_jit_type *type)
106 Given type "T", get type "const T".
108 .. function:: gcc_jit_type *gcc_jit_type_get_volatile (gcc_jit_type *type)
110 Given type "T", get type "volatile T".
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, \
118 Given type "T", get type "T[N]" (for a constant N).
120 .. function:: gcc_jit_type *\
121 gcc_jit_type_get_aligned (gcc_jit_type *type, \
122 size_t alignment_in_bytes)
124 Given type "T", get type:
128 T __attribute__ ((aligned (ALIGNMENT_IN_BYTES)))
130 The alignment must be a power of two.
132 This entrypoint was added in :ref:`LIBGCCJIT_ABI_7`; you can test for
137 #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_aligned
142 .. function:: gcc_jit_type *\
143 gcc_jit_type_get_vector (gcc_jit_type *type, \
146 Given type "T", get type:
150 T __attribute__ ((vector_size (sizeof(T) * num_units))
152 T must be integral or floating point; num_units must be a power of two.
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
159 For example, assuming 4-byte ``ints``, then:
163 typedef int v4si __attribute__ ((vector_size (16)));
165 can be obtained using:
169 gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt,
171 gcc_jit_type *v4si_type = gcc_jit_type_get_vector (int_type, 4);
173 This API entrypoint was added in :ref:`LIBGCCJIT_ABI_8`; you can test
174 for its presence using
178 #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_vector
180 Vector rvalues can be generated using
181 :func:`gcc_jit_context_new_rvalue_from_vector`.
184 Structures and unions
185 ---------------------
187 .. c:type:: gcc_jit_struct
189 A compound type analagous to a C `struct`.
191 .. c:type:: gcc_jit_field
193 A field within a :c:type:`gcc_jit_struct`.
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:
198 * by creating the fields, then the structure. For example, to model:
202 struct coord {double x; double y; };
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);
216 * by creating the structure, then populating it with fields, typically
217 to allow modelling self-referential structs such as:
221 struct node { int m_hash; struct node *m_next; };
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);
238 .. function:: gcc_jit_field *\
239 gcc_jit_context_new_field (gcc_jit_context *ctxt,\
240 gcc_jit_location *loc,\
244 Construct a new field, with the given type and name.
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
250 .. function:: gcc_jit_object *\
251 gcc_jit_field_as_object (gcc_jit_field *field)
253 Upcast from field to object.
255 .. function:: gcc_jit_struct *\
256 gcc_jit_context_new_struct_type (gcc_jit_context *ctxt,\
257 gcc_jit_location *loc,\
260 gcc_jit_field **fields)
262 Construct a new struct type, with the given name and fields.
264 The parameter ``name`` must be non-NULL. The call takes a copy of
265 the underlying string, so it is valid to pass in a pointer to an
268 .. function:: gcc_jit_struct *\
269 gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt,\
270 gcc_jit_location *loc,\
273 Construct a new struct type, with the given name, but without
274 specifying the fields. The fields can be omitted (in which case the
275 size of the struct is not known), or later specified using
276 :c:func:`gcc_jit_struct_set_fields`.
278 The parameter ``name`` must be non-NULL. The call takes a copy of
279 the underlying string, so it is valid to pass in a pointer to an
282 .. function:: gcc_jit_type *\
283 gcc_jit_struct_as_type (gcc_jit_struct *struct_type)
285 Upcast from struct to type.
288 gcc_jit_struct_set_fields (gcc_jit_struct *struct_type,\
289 gcc_jit_location *loc,\
291 gcc_jit_field **fields)
293 Populate the fields of a formerly-opaque struct type.
295 This can only be called once on a given struct type.
297 .. function:: gcc_jit_type *\
298 gcc_jit_context_new_union_type (gcc_jit_context *ctxt,\
299 gcc_jit_location *loc,\
302 gcc_jit_field **fields)
304 Construct a new union type, with the given name and fields.
306 The parameter ``name`` must be non-NULL. It is copied, so the input
307 buffer does not need to outlive the call.
311 .. literalinclude:: ../../../testsuite/jit.dg/test-accessing-union.c
312 :start-after: /* Quote from here in docs/topics/types.rst. */
313 :end-before: /* Quote up to here in docs/topics/types.rst. */
316 Function pointer types
317 ----------------------
319 Function pointer types can be created using
320 :c:func:`gcc_jit_context_new_function_ptr_type`.