| .. Copyright (C) 2014-2022 Free Software Foundation, Inc. |
| Originally contributed by David Malcolm <dmalcolm@redhat.com> |
| |
| This is free software: you can redistribute it and/or modify it |
| under the terms of the GNU General Public License as published by |
| the Free Software Foundation, either version 3 of the License, or |
| (at your option) any later version. |
| |
| This program is distributed in the hope that it will be useful, but |
| WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| General Public License for more details. |
| |
| You should have received a copy of the GNU General Public License |
| along with this program. If not, see |
| <https://www.gnu.org/licenses/>. |
| |
| .. default-domain:: c |
| |
| Expressions |
| =========== |
| |
| Rvalues |
| ------- |
| .. type:: gcc_jit_rvalue |
| |
| A :c:type:`gcc_jit_rvalue` is an expression that can be computed. |
| |
| It can be simple, e.g.: |
| |
| * an integer value e.g. `0` or `42` |
| * a string literal e.g. `"Hello world"` |
| * a variable e.g. `i`. These are also lvalues (see below). |
| |
| or compound e.g.: |
| |
| * a unary expression e.g. `!cond` |
| * a binary expression e.g. `(a + b)` |
| * a function call e.g. `get_distance (&player_ship, &target)` |
| * etc. |
| |
| Every rvalue has an associated type, and the API will check to ensure |
| that types match up correctly (otherwise the context will emit an error). |
| |
| .. function:: gcc_jit_type *gcc_jit_rvalue_get_type (gcc_jit_rvalue *rvalue) |
| |
| Get the type of this rvalue. |
| |
| .. function:: gcc_jit_object *gcc_jit_rvalue_as_object (gcc_jit_rvalue *rvalue) |
| |
| Upcast the given rvalue to be an object. |
| |
| |
| Simple expressions |
| ****************** |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_rvalue_from_int (gcc_jit_context *ctxt, \ |
| gcc_jit_type *numeric_type, \ |
| int value) |
| |
| Given a numeric type (integer or floating point), build an rvalue for |
| the given constant :expr:`int` value. |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_rvalue_from_long (gcc_jit_context *ctxt, \ |
| gcc_jit_type *numeric_type, \ |
| long value) |
| |
| Given a numeric type (integer or floating point), build an rvalue for |
| the given constant :expr:`long` value. |
| |
| .. function:: gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context *ctxt, \ |
| gcc_jit_type *numeric_type) |
| |
| Given a numeric type (integer or floating point), get the rvalue for |
| zero. Essentially this is just a shortcut for: |
| |
| .. code-block:: c |
| |
| gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 0) |
| |
| .. function:: gcc_jit_rvalue *gcc_jit_context_one (gcc_jit_context *ctxt, \ |
| gcc_jit_type *numeric_type) |
| |
| Given a numeric type (integer or floating point), get the rvalue for |
| one. Essentially this is just a shortcut for: |
| |
| .. code-block:: c |
| |
| gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 1) |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_rvalue_from_double (gcc_jit_context *ctxt, \ |
| gcc_jit_type *numeric_type, \ |
| double value) |
| |
| Given a numeric type (integer or floating point), build an rvalue for |
| the given constant :expr:`double` value. |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt, \ |
| gcc_jit_type *pointer_type, \ |
| void *value) |
| |
| Given a pointer type, build an rvalue for the given address. |
| |
| .. function:: gcc_jit_rvalue *gcc_jit_context_null (gcc_jit_context *ctxt, \ |
| gcc_jit_type *pointer_type) |
| |
| Given a pointer type, build an rvalue for ``NULL``. Essentially this |
| is just a shortcut for: |
| |
| .. code-block:: c |
| |
| gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL) |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_string_literal (gcc_jit_context *ctxt, \ |
| const char *value) |
| |
| Generate an rvalue for the given NIL-terminated string, of type |
| :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`. |
| |
| The parameter ``value`` must be non-NULL. The call takes a copy of the |
| underlying string, so it is valid to pass in a pointer to an on-stack |
| buffer. |
| |
| Constructor expressions |
| *********************** |
| |
| The following functions make constructors for array, struct and union |
| types. |
| |
| The constructor rvalue can be used for assignment to locals. |
| It can be used to initialize global variables with |
| :func:`gcc_jit_global_set_initializer_rvalue`. It can also be used as a |
| temporary value for function calls and return values, but its address |
| can't be taken. |
| |
| Note that arrays in libgccjit do not collapse to pointers like in |
| C. I.e. if an array constructor is used as e.g. a return value, the whole |
| array would be returned by value - array constructors can be assigned to |
| array variables. |
| |
| The constructor can contain nested constructors. |
| |
| Note that a string literal rvalue can't be used to construct a char array; |
| the latter needs one rvalue for each char. |
| |
| These entrypoints were added in :ref:`LIBGCCJIT_ABI_19`; you can test for |
| their presence using: |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_CTORS |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_array_constructor (gcc_jit_context *ctxt,\ |
| gcc_jit_location *loc,\ |
| gcc_jit_type *type,\ |
| size_t num_values,\ |
| gcc_jit_rvalue **values) |
| |
| Create a constructor for an array as an rvalue. |
| |
| Returns NULL on error. ``values`` are copied and |
| do not have to outlive the context. |
| |
| ``type`` specifies what the constructor will build and has to be |
| an array. |
| |
| ``num_values`` specifies the number of elements in ``values`` and |
| it can't have more elements than the array type. |
| |
| Each value in ``values`` sets the corresponding value in the array. |
| If the array type itself has more elements than ``values``, the |
| left-over elements will be zeroed. |
| |
| Each value in ``values`` need to be the same unqualified type as the |
| array type's element type. |
| |
| If ``num_values`` is 0, the ``values`` parameter will be |
| ignored and zero initialization will be used. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its |
| presence using: |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_CTORS |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_struct_constructor (gcc_jit_context *ctxt,\ |
| gcc_jit_location *loc,\ |
| gcc_jit_type *type,\ |
| size_t num_values,\ |
| gcc_jit_field **fields,\ |
| gcc_jit_rvalue **values) |
| |
| |
| Create a constructor for a struct as an rvalue. |
| |
| Returns NULL on error. The two parameter arrays are copied and |
| do not have to outlive the context. |
| |
| ``type`` specifies what the constructor will build and has to be |
| a struct. |
| |
| ``num_values`` specifies the number of elements in ``values``. |
| |
| ``fields`` need to have the same length as ``values``, or be NULL. |
| |
| If ``fields`` is null, the values are applied in definition order. |
| |
| Otherwise, each field in ``fields`` specifies which field in the struct to |
| set to the corresponding value in ``values``. ``fields`` and ``values`` |
| are paired by index. |
| |
| The fields in ``fields`` have to be in definition order, but there |
| can be gaps. Any field in the struct that is not specified in |
| ``fields`` will be zeroed. |
| |
| The fields in ``fields`` need to be the same objects that were used |
| to create the struct. |
| |
| Each value has to have have the same unqualified type as the field |
| it is applied to. |
| |
| A NULL value element in ``values`` is a shorthand for zero initialization |
| of the corresponding field. |
| |
| If ``num_values`` is 0, the array parameters will be |
| ignored and zero initialization will be used. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its |
| presence using: |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_CTORS |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_union_constructor (gcc_jit_context *ctxt,\ |
| gcc_jit_location *loc,\ |
| gcc_jit_type *type,\ |
| gcc_jit_field *field,\ |
| gcc_jit_rvalue *value) |
| |
| Create a constructor for a union as an rvalue. |
| |
| Returns NULL on error. |
| |
| ``type`` specifies what the constructor will build and has to be |
| an union. |
| |
| ``field`` specifies which field to set. If it is NULL, the first |
| field in the union will be set.``field`` need to be the same object |
| that were used to create the union. |
| |
| ``value`` specifies what value to set the corresponding field to. |
| If ``value`` is NULL, zero initialization will be used. |
| |
| Each value has to have have the same unqualified type as the field |
| it is applied to. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its |
| presence using: |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_CTORS |
| |
| Vector expressions |
| ****************** |
| |
| .. function:: gcc_jit_rvalue * \ |
| gcc_jit_context_new_rvalue_from_vector (gcc_jit_context *ctxt, \ |
| gcc_jit_location *loc, \ |
| gcc_jit_type *vec_type, \ |
| size_t num_elements, \ |
| gcc_jit_rvalue **elements) |
| |
| Build a vector rvalue from an array of elements. |
| |
| "vec_type" should be a vector type, created using |
| :func:`gcc_jit_type_get_vector`. |
| |
| "num_elements" should match that of the vector type. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_10`; you can test for |
| its presence using |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector |
| |
| Unary Operations |
| **************** |
| |
| .. function:: gcc_jit_rvalue * \ |
| gcc_jit_context_new_unary_op (gcc_jit_context *ctxt, \ |
| gcc_jit_location *loc, \ |
| enum gcc_jit_unary_op op, \ |
| gcc_jit_type *result_type, \ |
| gcc_jit_rvalue *rvalue) |
| |
| Build a unary operation out of an input rvalue. |
| |
| The parameter ``result_type`` must be a numeric type. |
| |
| .. enum:: gcc_jit_unary_op |
| |
| The available unary operations are: |
| |
| .. list-table:: |
| :header-rows: 1 |
| |
| * - Unary Operation |
| - C equivalent |
| |
| * - :c:macro:`GCC_JIT_UNARY_OP_MINUS` |
| - `-(EXPR)` |
| * - :c:macro:`GCC_JIT_UNARY_OP_BITWISE_NEGATE` |
| - `~(EXPR)` |
| * - :c:macro:`GCC_JIT_UNARY_OP_LOGICAL_NEGATE` |
| - `!(EXPR)` |
| * - :c:macro:`GCC_JIT_UNARY_OP_ABS` |
| - `abs (EXPR)` |
| |
| .. c:macro:: GCC_JIT_UNARY_OP_MINUS |
| |
| Negate an arithmetic value; analogous to: |
| |
| .. code-block:: c |
| |
| -(EXPR) |
| |
| in C. |
| |
| .. c:macro:: GCC_JIT_UNARY_OP_BITWISE_NEGATE |
| |
| Bitwise negation of an integer value (one's complement); analogous |
| to: |
| |
| .. code-block:: c |
| |
| ~(EXPR) |
| |
| in C. |
| |
| .. c:macro:: GCC_JIT_UNARY_OP_LOGICAL_NEGATE |
| |
| Logical negation of an arithmetic or pointer value; analogous to: |
| |
| .. code-block:: c |
| |
| !(EXPR) |
| |
| in C. |
| |
| .. c:macro:: GCC_JIT_UNARY_OP_ABS |
| |
| Absolute value of an arithmetic expression; analogous to: |
| |
| .. code-block:: c |
| |
| abs (EXPR) |
| |
| in C. |
| |
| Binary Operations |
| ***************** |
| |
| .. function:: gcc_jit_rvalue *gcc_jit_context_new_binary_op (gcc_jit_context *ctxt, \ |
| gcc_jit_location *loc, \ |
| enum gcc_jit_binary_op op, \ |
| gcc_jit_type *result_type, \ |
| gcc_jit_rvalue *a, gcc_jit_rvalue *b) |
| |
| Build a binary operation out of two constituent rvalues. |
| |
| The parameter ``result_type`` must be a numeric type. |
| |
| .. enum:: gcc_jit_binary_op |
| |
| The available binary operations are: |
| |
| .. list-table:: |
| :header-rows: 1 |
| |
| * - Binary Operation |
| - C equivalent |
| |
| * - :c:macro:`GCC_JIT_BINARY_OP_PLUS` |
| - `x + y` |
| * - :c:macro:`GCC_JIT_BINARY_OP_MINUS` |
| - `x - y` |
| * - :c:macro:`GCC_JIT_BINARY_OP_MULT` |
| - `x * y` |
| * - :c:macro:`GCC_JIT_BINARY_OP_DIVIDE` |
| - `x / y` |
| * - :c:macro:`GCC_JIT_BINARY_OP_MODULO` |
| - `x % y` |
| * - :c:macro:`GCC_JIT_BINARY_OP_BITWISE_AND` |
| - `x & y` |
| * - :c:macro:`GCC_JIT_BINARY_OP_BITWISE_XOR` |
| - `x ^ y` |
| * - :c:macro:`GCC_JIT_BINARY_OP_BITWISE_OR` |
| - `x | y` |
| * - :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_AND` |
| - `x && y` |
| * - :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_OR` |
| - `x || y` |
| * - :c:macro:`GCC_JIT_BINARY_OP_LSHIFT` |
| - `x << y` |
| * - :c:macro:`GCC_JIT_BINARY_OP_RSHIFT` |
| - `x >> y` |
| |
| .. c:macro:: GCC_JIT_BINARY_OP_PLUS |
| |
| Addition of arithmetic values; analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR_A) + (EXPR_B) |
| |
| in C. |
| |
| For pointer addition, use :c:func:`gcc_jit_context_new_array_access`. |
| |
| .. c:macro:: GCC_JIT_BINARY_OP_MINUS |
| |
| Subtraction of arithmetic values; analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR_A) - (EXPR_B) |
| |
| in C. |
| |
| .. c:macro:: GCC_JIT_BINARY_OP_MULT |
| |
| Multiplication of a pair of arithmetic values; analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR_A) * (EXPR_B) |
| |
| in C. |
| |
| .. c:macro:: GCC_JIT_BINARY_OP_DIVIDE |
| |
| Quotient of division of arithmetic values; analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR_A) / (EXPR_B) |
| |
| in C. |
| |
| The result type affects the kind of division: if the result type is |
| integer-based, then the result is truncated towards zero, whereas |
| a floating-point result type indicates floating-point division. |
| |
| .. c:macro:: GCC_JIT_BINARY_OP_MODULO |
| |
| Remainder of division of arithmetic values; analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR_A) % (EXPR_B) |
| |
| in C. |
| |
| .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_AND |
| |
| Bitwise AND; analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR_A) & (EXPR_B) |
| |
| in C. |
| |
| .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_XOR |
| |
| Bitwise exclusive OR; analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR_A) ^ (EXPR_B) |
| |
| in C. |
| |
| .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_OR |
| |
| Bitwise inclusive OR; analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR_A) | (EXPR_B) |
| |
| in C. |
| |
| .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_AND |
| |
| Logical AND; analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR_A) && (EXPR_B) |
| |
| in C. |
| |
| .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_OR |
| |
| Logical OR; analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR_A) || (EXPR_B) |
| |
| in C. |
| |
| .. c:macro:: GCC_JIT_BINARY_OP_LSHIFT |
| |
| Left shift; analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR_A) << (EXPR_B) |
| |
| in C. |
| |
| .. c:macro:: GCC_JIT_BINARY_OP_RSHIFT |
| |
| Right shift; analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR_A) >> (EXPR_B) |
| |
| in C. |
| |
| Comparisons |
| *********** |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_comparison (gcc_jit_context *ctxt,\ |
| gcc_jit_location *loc,\ |
| enum gcc_jit_comparison op,\ |
| gcc_jit_rvalue *a, gcc_jit_rvalue *b) |
| |
| Build a boolean rvalue out of the comparison of two other rvalues. |
| |
| .. enum:: gcc_jit_comparison |
| |
| .. list-table:: |
| :header-rows: 1 |
| |
| * - Comparison |
| - C equivalent |
| |
| * - :c:macro:`GCC_JIT_COMPARISON_EQ` |
| - `x == y` |
| * - :c:macro:`GCC_JIT_COMPARISON_NE` |
| - `x != y` |
| * - :c:macro:`GCC_JIT_COMPARISON_LT` |
| - `x < y` |
| * - :c:macro:`GCC_JIT_COMPARISON_LE` |
| - `x <= y` |
| * - :c:macro:`GCC_JIT_COMPARISON_GT` |
| - `x > y` |
| * - :c:macro:`GCC_JIT_COMPARISON_GE` |
| - `x >= y` |
| |
| Function calls |
| ************** |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_call (gcc_jit_context *ctxt,\ |
| gcc_jit_location *loc,\ |
| gcc_jit_function *func,\ |
| int numargs , gcc_jit_rvalue **args) |
| |
| Given a function and the given table of argument rvalues, construct a |
| call to the function, with the result as an rvalue. |
| |
| .. note:: |
| |
| :c:func:`gcc_jit_context_new_call` merely builds a |
| :c:type:`gcc_jit_rvalue` i.e. an expression that can be evaluated, |
| perhaps as part of a more complicated expression. |
| The call *won't* happen unless you add a statement to a function |
| that evaluates the expression. |
| |
| For example, if you want to call a function and discard the result |
| (or to call a function with ``void`` return type), use |
| :c:func:`gcc_jit_block_add_eval`: |
| |
| .. code-block:: c |
| |
| /* Add "(void)printf (arg0, arg1);". */ |
| gcc_jit_block_add_eval ( |
| block, NULL, |
| gcc_jit_context_new_call ( |
| ctxt, |
| NULL, |
| printf_func, |
| 2, args)); |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_call_through_ptr (gcc_jit_context *ctxt,\ |
| gcc_jit_location *loc,\ |
| gcc_jit_rvalue *fn_ptr,\ |
| int numargs, \ |
| gcc_jit_rvalue **args) |
| |
| Given an rvalue of function pointer type (e.g. from |
| :c:func:`gcc_jit_context_new_function_ptr_type`), and the given table of |
| argument rvalues, construct a call to the function pointer, with the |
| result as an rvalue. |
| |
| .. note:: |
| |
| The same caveat as for :c:func:`gcc_jit_context_new_call` applies. |
| |
| .. function:: void\ |
| gcc_jit_rvalue_set_bool_require_tail_call (gcc_jit_rvalue *call,\ |
| int require_tail_call) |
| |
| Given an :c:type:`gcc_jit_rvalue` for a call created through |
| :c:func:`gcc_jit_context_new_call` or |
| :c:func:`gcc_jit_context_new_call_through_ptr`, mark/clear the |
| call as needing tail-call optimization. The optimizer will |
| attempt to optimize the call into a jump instruction; if it is |
| unable to do do, an error will be emitted. |
| |
| This may be useful when implementing functions that use the |
| continuation-passing style (e.g. for functional programming |
| languages), in which every function "returns" by calling a |
| "continuation" function pointer. This call must be |
| guaranteed to be implemented as a jump, otherwise the program |
| could consume an arbitrary amount of stack space as it executed. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_6`; you can test for |
| its presence using |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call |
| |
| Function pointers |
| ***************** |
| |
| Function pointers can be obtained: |
| |
| * from a :c:type:`gcc_jit_function` using |
| :c:func:`gcc_jit_function_get_address`, or |
| |
| * from an existing function using |
| :c:func:`gcc_jit_context_new_rvalue_from_ptr`, |
| using a function pointer type obtained using |
| :c:func:`gcc_jit_context_new_function_ptr_type`. |
| |
| Type-coercion |
| ************* |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_cast (gcc_jit_context *ctxt,\ |
| gcc_jit_location *loc,\ |
| gcc_jit_rvalue *rvalue,\ |
| gcc_jit_type *type) |
| |
| Given an rvalue of T, construct another rvalue of another type. |
| |
| Currently only a limited set of conversions are possible: |
| |
| * int <-> float |
| * int <-> bool |
| * P* <-> Q*, for pointer types P and Q |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_context_new_bitcast (gcc_jit_context *ctxt,\ |
| gcc_jit_location *loc,\ |
| gcc_jit_rvalue *rvalue,\ |
| gcc_jit_type *type) |
| |
| Given an rvalue of T, bitcast it to another type, meaning that this will |
| generate a new rvalue by interpreting the bits of ``rvalue`` to the layout |
| of ``type``. |
| |
| The type of rvalue must be the same size as the size of ``type``. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_21`; you can test for |
| its presence using |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitcast |
| |
| Lvalues |
| ------- |
| |
| .. type:: gcc_jit_lvalue |
| |
| An lvalue is something that can of the *left*-hand side of an assignment: |
| a storage area (such as a variable). It is also usable as an rvalue, |
| where the rvalue is computed by reading from the storage area. |
| |
| .. function:: gcc_jit_object *\ |
| gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue) |
| |
| Upcast an lvalue to be an object. |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue) |
| |
| Upcast an lvalue to be an rvalue. |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue,\ |
| gcc_jit_location *loc) |
| |
| Take the address of an lvalue; analogous to: |
| |
| .. code-block:: c |
| |
| &(EXPR) |
| |
| in C. |
| |
| .. function:: void\ |
| gcc_jit_lvalue_set_tls_model (gcc_jit_lvalue *lvalue,\ |
| enum gcc_jit_tls_model model) |
| |
| Make a variable a thread-local variable. |
| |
| The "model" parameter determines the thread-local storage model of the "lvalue": |
| |
| .. enum:: gcc_jit_tls_model |
| |
| .. c:macro:: GCC_JIT_TLS_MODEL_NONE |
| |
| Don't set the TLS model. |
| |
| .. c:macro:: GCC_JIT_TLS_MODEL_GLOBAL_DYNAMIC |
| |
| .. c:macro:: GCC_JIT_TLS_MODEL_LOCAL_DYNAMIC |
| |
| .. c:macro:: GCC_JIT_TLS_MODEL_INITIAL_EXEC |
| |
| .. c:macro:: GCC_JIT_TLS_MODEL_LOCAL_EXEC |
| |
| This is analogous to: |
| |
| .. code-block:: c |
| |
| _Thread_local int foo __attribute__ ((tls_model("MODEL"))); |
| |
| in C. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_17`; you can test for |
| its presence using |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_tls_model |
| |
| .. function:: void\ |
| gcc_jit_lvalue_set_link_section (gcc_jit_lvalue *lvalue,\ |
| const char *section_name) |
| |
| Set the link section of a variable. |
| The parameter ``section_name`` must be non-NULL and must contain the |
| leading dot. Analogous to: |
| |
| .. code-block:: c |
| |
| int variable __attribute__((section(".section"))); |
| |
| in C. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_18`; you can test for |
| its presence using |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_link_section |
| |
| .. function:: void\ |
| gcc_jit_lvalue_set_register_name (gcc_jit_lvalue *lvalue,\ |
| const char *reg_name); |
| |
| Set the register name of a variable. |
| The parameter ``reg_name`` must be non-NULL. Analogous to: |
| |
| .. code-block:: c |
| |
| register int variable asm ("r12"); |
| |
| in C. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_22`; you can test for |
| its presence using |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_register_name |
| |
| .. function:: void\ |
| gcc_jit_lvalue_set_alignment (gcc_jit_lvalue *lvalue,\ |
| unsigned bytes) |
| |
| Set the alignment of a variable, in bytes. |
| Analogous to: |
| |
| .. code-block:: c |
| |
| int variable __attribute__((aligned (16))); |
| |
| in C. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_24`; you can test for |
| its presence using |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_ALIGNMENT |
| |
| .. function:: unsigned\ |
| gcc_jit_lvalue_get_alignment (gcc_jit_lvalue *lvalue) |
| |
| Return the alignment of a variable set by ``gcc_jit_lvalue_set_alignment``. |
| Return 0 if the alignment was not set. Analogous to: |
| |
| .. code-block:: c |
| |
| _Alignof (variable) |
| |
| in C. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_24`; you can test for |
| its presence using |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_ALIGNMENT |
| |
| Global variables |
| **************** |
| |
| .. function:: gcc_jit_lvalue *\ |
| gcc_jit_context_new_global (gcc_jit_context *ctxt,\ |
| gcc_jit_location *loc,\ |
| enum gcc_jit_global_kind kind,\ |
| gcc_jit_type *type,\ |
| const char *name) |
| |
| Add a new global variable of the given type and name to the context. |
| |
| The parameter ``type`` must be non-`void`. |
| |
| The parameter ``name`` must be non-NULL. The call takes a copy of the |
| underlying string, so it is valid to pass in a pointer to an on-stack |
| buffer. |
| |
| The "kind" parameter determines the visibility of the "global" outside |
| of the :c:type:`gcc_jit_result`: |
| |
| .. enum:: gcc_jit_global_kind |
| |
| .. c:macro:: GCC_JIT_GLOBAL_EXPORTED |
| |
| Global is defined by the client code and is visible |
| by name outside of this JIT context via |
| :c:func:`gcc_jit_result_get_global` (and this value is required for |
| the global to be accessible via that entrypoint). |
| |
| .. c:macro:: GCC_JIT_GLOBAL_INTERNAL |
| |
| Global is defined by the client code, but is invisible |
| outside of it. Analogous to a "static" global within a .c file. |
| Specifically, the variable will only be visible within this |
| context and within child contexts. |
| |
| .. c:macro:: GCC_JIT_GLOBAL_IMPORTED |
| |
| Global is not defined by the client code; we're merely |
| referring to it. Analogous to using an "extern" global from a |
| header file. |
| |
| .. function:: gcc_jit_lvalue *\ |
| gcc_jit_global_set_initializer (gcc_jit_lvalue *global,\ |
| const void *blob,\ |
| size_t num_bytes) |
| |
| Set an initializer for ``global`` using the memory content pointed |
| by ``blob`` for ``num_bytes``. ``global`` must be an array of an |
| integral type. Return the global itself. |
| |
| The parameter ``blob`` must be non-NULL. The call copies the memory |
| pointed by ``blob`` for ``num_bytes`` bytes, so it is valid to pass |
| in a pointer to an on-stack buffer. The content will be stored in |
| the compilation unit and used as initialization value of the array. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_14`; you can test for |
| its presence using |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_gcc_jit_global_set_initializer |
| |
| .. function:: gcc_jit_lvalue *\ |
| gcc_jit_global_set_initializer_rvalue (gcc_jit_lvalue *global,\ |
| gcc_jit_rvalue *init_value) |
| |
| Set the initial value of a global with an rvalue. |
| |
| The rvalue needs to be a constant expression, e.g. no function calls. |
| |
| The global can't have the ``kind`` :c:macro:`GCC_JIT_GLOBAL_IMPORTED`. |
| |
| As a non-comprehensive example it is OK to do the equivalent of: |
| |
| .. code-block:: c |
| |
| int foo = 3 * 2; /* rvalue from gcc_jit_context_new_binary_op. */ |
| int arr[] = {1,2,3,4}; /* rvalue from gcc_jit_context_new_constructor. */ |
| int *bar = &arr[2] + 1; /* rvalue from nested "get address" of "array access". */ |
| const int baz = 3; /* rvalue from gcc_jit_context_rvalue_from_int. */ |
| int boz = baz; /* rvalue from gcc_jit_lvalue_as_rvalue. */ |
| |
| Use together with :c:func:`gcc_jit_context_new_struct_constructor`, |
| :c:func:`gcc_jit_context_new_union_constructor`, :c:func:`gcc_jit_context_new_array_constructor` |
| to initialize structs, unions and arrays. |
| |
| On success, returns the ``global`` parameter unchanged. Otherwise, ``NULL``. |
| |
| This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its |
| presence using: |
| |
| .. code-block:: c |
| |
| #ifdef LIBGCCJIT_HAVE_CTORS |
| |
| Working with pointers, structs and unions |
| ----------------------------------------- |
| |
| .. function:: gcc_jit_lvalue *\ |
| gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue,\ |
| gcc_jit_location *loc) |
| |
| Given an rvalue of pointer type ``T *``, dereferencing the pointer, |
| getting an lvalue of type ``T``. Analogous to: |
| |
| .. code-block:: c |
| |
| *(EXPR) |
| |
| in C. |
| |
| Field access is provided separately for both lvalues and rvalues. |
| |
| .. function:: gcc_jit_lvalue *\ |
| gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_,\ |
| gcc_jit_location *loc,\ |
| gcc_jit_field *field) |
| |
| Given an lvalue of struct or union type, access the given field, |
| getting an lvalue of the field's type. Analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR).field = ...; |
| |
| in C. |
| |
| .. function:: gcc_jit_rvalue *\ |
| gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_,\ |
| gcc_jit_location *loc,\ |
| gcc_jit_field *field) |
| |
| Given an rvalue of struct or union type, access the given field |
| as an rvalue. Analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR).field |
| |
| in C. |
| |
| .. function:: gcc_jit_lvalue *\ |
| gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr,\ |
| gcc_jit_location *loc,\ |
| gcc_jit_field *field) |
| |
| Given an rvalue of pointer type ``T *`` where T is of struct or union |
| type, access the given field as an lvalue. Analogous to: |
| |
| .. code-block:: c |
| |
| (EXPR)->field |
| |
| in C, itself equivalent to ``(*EXPR).FIELD``. |
| |
| .. function:: gcc_jit_lvalue *\ |
| gcc_jit_context_new_array_access (gcc_jit_context *ctxt,\ |
| gcc_jit_location *loc,\ |
| gcc_jit_rvalue *ptr,\ |
| gcc_jit_rvalue *index) |
| |
| Given an rvalue of pointer type ``T *``, get at the element `T` at |
| the given index, using standard C array indexing rules i.e. each |
| increment of ``index`` corresponds to ``sizeof(T)`` bytes. |
| Analogous to: |
| |
| .. code-block:: c |
| |
| PTR[INDEX] |
| |
| in C (or, indeed, to ``PTR + INDEX``). |
