1.. Copyright (C) 2014-2020 Free Software Foundation, Inc. 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 20Types 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 31Types 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 52Standard 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 97Pointers, `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 139Vector 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 184Structures and unions 185--------------------- 186 187.. c:type:: gcc_jit_struct 188 189A compound type analagous to a C `struct`. 190 191.. c:type:: gcc_jit_field 192 193A field within a :c:type:`gcc_jit_struct`. 194 195You 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_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 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 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 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 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 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. 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 339 340Function pointer types 341---------------------- 342 343Function pointer types can be created using 344:c:func:`gcc_jit_context_new_function_ptr_type`. 345