|
131
|
1 .. Copyright (C) 2014-2018 Free Software Foundation, Inc.
|
|
111
|
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
|
|
|
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_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 ========================================== ================================
|
|
|
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
|
|
|
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
|
|
|
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
|
|
|
180 Vector rvalues can be generated using
|
|
|
181 :func:`gcc_jit_context_new_rvalue_from_vector`.
|
|
|
182
|
|
|
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
|
|
|
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
|
|
|
250 .. function:: gcc_jit_object *\
|
|
|
251 gcc_jit_field_as_object (gcc_jit_field *field)
|
|
|
252
|
|
|
253 Upcast from field to object.
|
|
|
254
|
|
|
255 .. function:: gcc_jit_struct *\
|
|
|
256 gcc_jit_context_new_struct_type (gcc_jit_context *ctxt,\
|
|
|
257 gcc_jit_location *loc,\
|
|
|
258 const char *name,\
|
|
|
259 int num_fields,\
|
|
|
260 gcc_jit_field **fields)
|
|
|
261
|
|
|
262 Construct a new struct type, with the given name and fields.
|
|
|
263
|
|
|
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
|
|
|
266 on-stack buffer.
|
|
|
267
|
|
|
268 .. function:: gcc_jit_struct *\
|
|
|
269 gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt,\
|
|
|
270 gcc_jit_location *loc,\
|
|
|
271 const char *name)
|
|
|
272
|
|
|
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`.
|
|
|
277
|
|
|
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
|
|
|
280 on-stack buffer.
|
|
|
281
|
|
|
282 .. function:: gcc_jit_type *\
|
|
|
283 gcc_jit_struct_as_type (gcc_jit_struct *struct_type)
|
|
|
284
|
|
|
285 Upcast from struct to type.
|
|
|
286
|
|
|
287 .. function:: void\
|
|
|
288 gcc_jit_struct_set_fields (gcc_jit_struct *struct_type,\
|
|
|
289 gcc_jit_location *loc,\
|
|
|
290 int num_fields,\
|
|
|
291 gcc_jit_field **fields)
|
|
|
292
|
|
|
293 Populate the fields of a formerly-opaque struct type.
|
|
|
294
|
|
|
295 This can only be called once on a given struct type.
|
|
|
296
|
|
|
297 .. function:: gcc_jit_type *\
|
|
|
298 gcc_jit_context_new_union_type (gcc_jit_context *ctxt,\
|
|
|
299 gcc_jit_location *loc,\
|
|
|
300 const char *name,\
|
|
|
301 int num_fields,\
|
|
|
302 gcc_jit_field **fields)
|
|
|
303
|
|
|
304 Construct a new union type, with the given name and fields.
|
|
|
305
|
|
|
306 The parameter ``name`` must be non-NULL. It is copied, so the input
|
|
|
307 buffer does not need to outlive the call.
|
|
|
308
|
|
|
309 Example of use:
|
|
|
310
|
|
|
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. */
|
|
|
314 :language: c
|
|
|
315
|
|
|
316 Function pointer types
|
|
|
317 ----------------------
|
|
|
318
|
|
|
319 Function pointer types can be created using
|
|
|
320 :c:func:`gcc_jit_context_new_function_ptr_type`.
|
