1 .. Copyright (C) 2014 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/>.
25 .. type:: gcc_jit_rvalue
27 A :c:type:`gcc_jit_rvalue *` is an expression that can be computed.
29 It can be simple, e.g.:
31 * an integer value e.g. `0` or `42`
32 * a string literal e.g. `"Hello world"`
33 * a variable e.g. `i`. These are also lvalues (see below).
37 * a unary expression e.g. `!cond`
38 * a binary expression e.g. `(a + b)`
39 * a function call e.g. `get_distance (&player_ship, &target)`
42 Every rvalue has an associated type, and the API will check to ensure
43 that types match up correctly (otherwise the context will emit an error).
45 .. function:: gcc_jit_type *gcc_jit_rvalue_get_type (gcc_jit_rvalue *rvalue)
47 Get the type of this rvalue.
49 .. function:: gcc_jit_object *gcc_jit_rvalue_as_object (gcc_jit_rvalue *rvalue)
51 Upcast the given rvalue to be an object.
57 .. function:: gcc_jit_rvalue *\
58 gcc_jit_context_new_rvalue_from_int (gcc_jit_context *ctxt, \
59 gcc_jit_type *numeric_type, \
62 Given a numeric type (integer or floating point), build an rvalue for
63 the given constant :c:type:`int` value.
65 .. function:: gcc_jit_rvalue *\
66 gcc_jit_context_new_rvalue_from_long (gcc_jit_context *ctxt, \
67 gcc_jit_type *numeric_type, \
70 Given a numeric type (integer or floating point), build an rvalue for
71 the given constant :c:type:`long` value.
73 .. function:: gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context *ctxt, \
74 gcc_jit_type *numeric_type)
76 Given a numeric type (integer or floating point), get the rvalue for
77 zero. Essentially this is just a shortcut for:
81 gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 0)
83 .. function:: gcc_jit_rvalue *gcc_jit_context_one (gcc_jit_context *ctxt, \
84 gcc_jit_type *numeric_type)
86 Given a numeric type (integer or floating point), get the rvalue for
87 zero. Essentially this is just a shortcut for:
91 gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 1)
93 .. function:: gcc_jit_rvalue *\
94 gcc_jit_context_new_rvalue_from_double (gcc_jit_context *ctxt, \
95 gcc_jit_type *numeric_type, \
98 Given a numeric type (integer or floating point), build an rvalue for
99 the given constant :c:type:`double` value.
101 .. function:: gcc_jit_rvalue *\
102 gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt, \
103 gcc_jit_type *pointer_type, \
106 Given a pointer type, build an rvalue for the given address.
108 .. function:: gcc_jit_rvalue *gcc_jit_context_null (gcc_jit_context *ctxt, \
109 gcc_jit_type *pointer_type)
111 Given a pointer type, build an rvalue for ``NULL``. Essentially this
112 is just a shortcut for:
116 gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL)
118 .. function:: gcc_jit_rvalue *\
119 gcc_jit_context_new_string_literal (gcc_jit_context *ctxt, \
122 Generate an rvalue for the given NIL-terminated string, of type
123 :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`.
129 .. function:: gcc_jit_rvalue * \
130 gcc_jit_context_new_unary_op (gcc_jit_context *ctxt, \
131 gcc_jit_location *loc, \
132 enum gcc_jit_unary_op op, \
133 gcc_jit_type *result_type, \
134 gcc_jit_rvalue *rvalue)
136 Build a unary operation out of an input rvalue.
138 .. type:: enum gcc_jit_unary_op
140 The available unary operations are:
142 ========================================== ============
143 Unary Operation C equivalent
144 ========================================== ============
145 :c:macro:`GCC_JIT_UNARY_OP_MINUS` `-(EXPR)`
146 :c:macro:`GCC_JIT_UNARY_OP_BITWISE_NEGATE` `~(EXPR)`
147 :c:macro:`GCC_JIT_UNARY_OP_LOGICAL_NEGATE` `!(EXPR)`
148 :c:macro:`GCC_JIT_UNARY_OP_ABS` `abs (EXPR)`
149 ========================================== ============
151 .. c:macro:: GCC_JIT_UNARY_OP_MINUS
153 Negate an arithmetic value; analogous to:
161 .. c:macro:: GCC_JIT_UNARY_OP_BITWISE_NEGATE
163 Bitwise negation of an integer value (one's complement); analogous
172 .. c:macro:: GCC_JIT_UNARY_OP_LOGICAL_NEGATE
174 Logical negation of an arithmetic or pointer value; analogous to:
182 .. c:macro:: GCC_JIT_UNARY_OP_ABS
184 Absolute value of an arithmetic expression; analogous to:
195 .. function:: gcc_jit_rvalue *gcc_jit_context_new_binary_op (gcc_jit_context *ctxt, \
196 gcc_jit_location *loc, \
197 enum gcc_jit_binary_op op, \
198 gcc_jit_type *result_type, \
199 gcc_jit_rvalue *a, gcc_jit_rvalue *b)
201 Build a binary operation out of two constituent rvalues.
203 .. type:: enum gcc_jit_binary_op
205 The available binary operations are:
207 ======================================== ============
208 Binary Operation C equivalent
209 ======================================== ============
210 :c:macro:`GCC_JIT_BINARY_OP_PLUS` `x + y`
211 :c:macro:`GCC_JIT_BINARY_OP_MINUS` `x - y`
212 :c:macro:`GCC_JIT_BINARY_OP_MULT` `x * y`
213 :c:macro:`GCC_JIT_BINARY_OP_DIVIDE` `x / y`
214 :c:macro:`GCC_JIT_BINARY_OP_MODULO` `x % y`
215 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_AND` `x & y`
216 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_XOR` `x ^ y`
217 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_OR` `x | y`
218 :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_AND` `x && y`
219 :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_OR` `x || y`
220 :c:macro:`GCC_JIT_BINARY_OP_LSHIFT` `x << y`
221 :c:macro:`GCC_JIT_BINARY_OP_RSHIFT` `x >> y`
222 ======================================== ============
224 .. c:macro:: GCC_JIT_BINARY_OP_PLUS
226 Addition of arithmetic values; analogous to:
234 For pointer addition, use :c:func:`gcc_jit_context_new_array_access`.
236 .. c:macro:: GCC_JIT_BINARY_OP_MINUS`
238 Subtraction of arithmetic values; analogous to:
246 .. c:macro:: GCC_JIT_BINARY_OP_MULT
248 Multiplication of a pair of arithmetic values; analogous to:
256 .. c:macro:: GCC_JIT_BINARY_OP_DIVIDE
258 Quotient of division of arithmetic values; analogous to:
266 The result type affects the kind of division: if the result type is
267 integer-based, then the result is truncated towards zero, whereas
268 a floating-point result type indicates floating-point division.
270 .. c:macro:: GCC_JIT_BINARY_OP_MODULO
272 Remainder of division of arithmetic values; analogous to:
280 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_AND
282 Bitwise AND; analogous to:
290 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_XOR
292 Bitwise exclusive OR; analogous to:
300 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_OR
302 Bitwise inclusive OR; analogous to:
310 .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_AND
312 Logical AND; analogous to:
320 .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_OR
322 Logical OR; analogous to:
330 .. c:macro:: GCC_JIT_BINARY_OP_LSHIFT
332 Left shift; analogous to:
340 .. c:macro:: GCC_JIT_BINARY_OP_RSHIFT
342 Right shift; analogous to:
353 .. function:: gcc_jit_rvalue *\
354 gcc_jit_context_new_comparison (gcc_jit_context *ctxt,\
355 gcc_jit_location *loc,\
356 enum gcc_jit_comparison op,\
357 gcc_jit_rvalue *a, gcc_jit_rvalue *b)
359 Build a boolean rvalue out of the comparison of two other rvalues.
361 .. type:: enum gcc_jit_comparison
363 ======================================= ============
364 Comparison C equivalent
365 ======================================= ============
366 :c:macro:`GCC_JIT_COMPARISON_EQ` `x == y`
367 :c:macro:`GCC_JIT_COMPARISON_NE` `x != y`
368 :c:macro:`GCC_JIT_COMPARISON_LT` `x < y`
369 :c:macro:`GCC_JIT_COMPARISON_LE` `x <= y`
370 :c:macro:`GCC_JIT_COMPARISON_GT` `x > y`
371 :c:macro:`GCC_JIT_COMPARISON_GE` `x >= y`
372 ======================================= ============
377 .. function:: gcc_jit_rvalue *\
378 gcc_jit_context_new_call (gcc_jit_context *ctxt,\
379 gcc_jit_location *loc,\
380 gcc_jit_function *func,\
381 int numargs , gcc_jit_rvalue **args)
383 Given a function and the given table of argument rvalues, construct a
384 call to the function, with the result as an rvalue.
388 :c:func:`gcc_jit_context_new_call` merely builds a
389 :c:type:`gcc_jit_rvalue` i.e. an expression that can be evaluated,
390 perhaps as part of a more complicated expression.
391 The call *won't* happen unless you add a statement to a function
392 that evaluates the expression.
394 For example, if you want to call a function and discard the result
395 (or to call a function with ``void`` return type), use
396 :c:func:`gcc_jit_block_add_eval`:
400 /* Add "(void)printf (arg0, arg1);". */
401 gcc_jit_block_add_eval (
403 gcc_jit_context_new_call (
412 .. function:: gcc_jit_rvalue *\
413 gcc_jit_context_new_cast (gcc_jit_context *ctxt,\
414 gcc_jit_location *loc,\
415 gcc_jit_rvalue *rvalue,\
418 Given an rvalue of T, construct another rvalue of another type.
420 Currently only a limited set of conversions are possible:
424 * P* <-> Q*, for pointer types P and Q
429 .. type:: gcc_jit_lvalue
431 An lvalue is something that can of the *left*-hand side of an assignment:
432 a storage area (such as a variable). It is also usable as an rvalue,
433 where the rvalue is computed by reading from the storage area.
435 .. function:: gcc_jit_object *\
436 gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue)
438 Upcast an lvalue to be an object.
440 .. function:: gcc_jit_rvalue *\
441 gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue)
443 Upcast an lvalue to be an rvalue.
445 .. function:: gcc_jit_rvalue *\
446 gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue,\
447 gcc_jit_location *loc)
449 Take the address of an lvalue; analogous to:
460 .. function:: gcc_jit_lvalue *\
461 gcc_jit_context_new_global (gcc_jit_context *ctxt,\
462 gcc_jit_location *loc,\
463 enum gcc_jit_global_kind kind,\
467 Add a new global variable of the given type and name to the context.
469 The "kind" parameter determines the visibility of the "global" outside
470 of the :c:type:`gcc_jit_result`:
472 .. type:: enum gcc_jit_global_kind
474 .. c:macro:: GCC_JIT_GLOBAL_EXPORTED
476 Global is defined by the client code and is visible
477 by name outside of this JIT context via
478 :c:func:`gcc_jit_result_get_global` (and this value is required for
479 the global to be accessible via that entrypoint).
481 .. c:macro:: GCC_JIT_GLOBAL_INTERNAL
483 Global is defined by the client code, but is invisible
484 outside of it. Analogous to a "static" global within a .c file.
485 Specifically, the variable will only be visible within this
486 context and within child contexts.
488 .. c:macro:: GCC_JIT_GLOBAL_IMPORTED
490 Global is not defined by the client code; we're merely
491 referring to it. Analogous to using an "extern" global from a
494 Working with pointers, structs and unions
495 -----------------------------------------
497 .. function:: gcc_jit_lvalue *\
498 gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue,\
499 gcc_jit_location *loc)
501 Given an rvalue of pointer type ``T *``, dereferencing the pointer,
502 getting an lvalue of type ``T``. Analogous to:
510 Field access is provided separately for both lvalues and rvalues.
512 .. function:: gcc_jit_lvalue *\
513 gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_,\
514 gcc_jit_location *loc,\
515 gcc_jit_field *field)
517 Given an lvalue of struct or union type, access the given field,
518 getting an lvalue of the field's type. Analogous to:
526 .. function:: gcc_jit_rvalue *\
527 gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_,\
528 gcc_jit_location *loc,\
529 gcc_jit_field *field)
531 Given an rvalue of struct or union type, access the given field
532 as an rvalue. Analogous to:
540 .. function:: gcc_jit_lvalue *\
541 gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr,\
542 gcc_jit_location *loc,\
543 gcc_jit_field *field)
545 Given an rvalue of pointer type ``T *`` where T is of struct or union
546 type, access the given field as an lvalue. Analogous to:
552 in C, itself equivalent to ``(*EXPR).FIELD``.
554 .. function:: gcc_jit_lvalue *\
555 gcc_jit_context_new_array_access (gcc_jit_context *ctxt,\
556 gcc_jit_location *loc,\
557 gcc_jit_rvalue *ptr,\
558 gcc_jit_rvalue *index)
560 Given an rvalue of pointer type ``T *``, get at the element `T` at
561 the given index, using standard C array indexing rules i.e. each
562 increment of ``index`` corresponds to ``sizeof(T)`` bytes.
569 in C (or, indeed, to ``PTR + INDEX``).