gcc/jit/docs/topics/types.rst

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