Debian Codegraph @

gcc/jit/docs/topics/expressions.rst

raw
1 .. Copyright (C) 2014-2025 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <[email protected]>
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 Expressions
21 ===========
22
23 Rvalues
24 -------
25 .. type:: gcc_jit_rvalue
26
27 A :c:type:`gcc_jit_rvalue` is an expression that can be computed.
28
29 It can be simple, e.g.:
30
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).
34
35 or compound e.g.:
36
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)`
40 * etc.
41
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).
44
45 .. function:: gcc_jit_type *gcc_jit_rvalue_get_type (gcc_jit_rvalue *rvalue)
46
47 Get the type of this rvalue.
48
49 .. function:: gcc_jit_object *gcc_jit_rvalue_as_object (gcc_jit_rvalue *rvalue)
50
51 Upcast the given rvalue to be an object.
52
53
54 Simple expressions
55 ******************
56
57 .. function:: gcc_jit_rvalue *\
58 gcc_jit_context_new_rvalue_from_int (gcc_jit_context *ctxt, \
59 gcc_jit_type *numeric_type, \
60 int value)
61
62 Given a numeric type (integer or floating point), build an rvalue for
63 the given constant :expr:`int` value.
64
65 .. function:: gcc_jit_rvalue *\
66 gcc_jit_context_new_rvalue_from_long (gcc_jit_context *ctxt, \
67 gcc_jit_type *numeric_type, \
68 long value)
69
70 Given a numeric type (integer or floating point), build an rvalue for
71 the given constant :expr:`long` value.
72
73 .. function:: gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context *ctxt, \
74 gcc_jit_type *numeric_type)
75
76 Given a numeric type (integer or floating point), get the rvalue for
77 zero. Essentially this is just a shortcut for:
78
79 .. code-block:: c
80
81 gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 0)
82
83 .. function:: gcc_jit_rvalue *gcc_jit_context_one (gcc_jit_context *ctxt, \
84 gcc_jit_type *numeric_type)
85
86 Given a numeric type (integer or floating point), get the rvalue for
87 one. Essentially this is just a shortcut for:
88
89 .. code-block:: c
90
91 gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 1)
92
93 .. function:: gcc_jit_rvalue *\
94 gcc_jit_context_new_rvalue_from_double (gcc_jit_context *ctxt, \
95 gcc_jit_type *numeric_type, \
96 double value)
97
98 Given a numeric type (integer or floating point), build an rvalue for
99 the given constant :expr:`double` value.
100
101 .. function:: gcc_jit_rvalue *\
102 gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt, \
103 gcc_jit_type *pointer_type, \
104 void *value)
105
106 Given a pointer type, build an rvalue for the given address.
107
108 .. function:: gcc_jit_rvalue *gcc_jit_context_null (gcc_jit_context *ctxt, \
109 gcc_jit_type *pointer_type)
110
111 Given a pointer type, build an rvalue for ``NULL``. Essentially this
112 is just a shortcut for:
113
114 .. code-block:: c
115
116 gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL)
117
118 .. function:: gcc_jit_rvalue *\
119 gcc_jit_context_new_string_literal (gcc_jit_context *ctxt, \
120 const char *value)
121
122 Generate an rvalue for the given NIL-terminated string, of type
123 :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`.
124
125 The parameter ``value`` must be non-NULL. The call takes a copy of the
126 underlying string, so it is valid to pass in a pointer to an on-stack
127 buffer.
128
129 .. function:: gcc_jit_rvalue *\
130 gcc_jit_context_new_sizeof (gcc_jit_context *ctxt, \
131 gcc_jit_type *type)
132
133 Generate an rvalue that is equal to the size of ``type``.
134
135 The parameter ``type`` must be non-NULL.
136
137 This is equivalent to this C code:
138
139 .. code-block:: c
140
141 sizeof (type)
142
143 .. function:: gcc_jit_rvalue *\
144 gcc_jit_context_new_alignof (gcc_jit_context *ctxt, \
145 gcc_jit_type *type)
146
147 Generate an rvalue that is equal to the alignment of ``type``.
148
149 The parameter ``type`` must be non-NULL.
150
151 This is equivalent to this C code:
152
153 .. code-block:: c
154
155 _Alignof (type)
156
157 Constructor expressions
158 ***********************
159
160 The following functions make constructors for array, struct and union
161 types.
162
163 The constructor rvalue can be used for assignment to locals.
164 It can be used to initialize global variables with
165 :func:`gcc_jit_global_set_initializer_rvalue`. It can also be used as a
166 temporary value for function calls and return values, but its address
167 can't be taken.
168
169 Note that arrays in libgccjit do not collapse to pointers like in
170 C. I.e. if an array constructor is used as e.g. a return value, the whole
171 array would be returned by value - array constructors can be assigned to
172 array variables.
173
174 The constructor can contain nested constructors.
175
176 Note that a string literal rvalue can't be used to construct a char array;
177 the latter needs one rvalue for each char.
178
179 These entrypoints were added in :ref:`LIBGCCJIT_ABI_19`; you can test for
180 their presence using:
181
182 .. code-block:: c
183
184 #ifdef LIBGCCJIT_HAVE_CTORS
185
186 .. function:: gcc_jit_rvalue *\
187 gcc_jit_context_new_array_constructor (gcc_jit_context *ctxt,\
188 gcc_jit_location *loc,\
189 gcc_jit_type *type,\
190 size_t num_values,\
191 gcc_jit_rvalue **values)
192
193 Create a constructor for an array as an rvalue.
194
195 Returns NULL on error. ``values`` are copied and
196 do not have to outlive the context.
197
198 ``type`` specifies what the constructor will build and has to be
199 an array.
200
201 ``num_values`` specifies the number of elements in ``values`` and
202 it can't have more elements than the array type.
203
204 Each value in ``values`` sets the corresponding value in the array.
205 If the array type itself has more elements than ``values``, the
206 left-over elements will be zeroed.
207
208 Each value in ``values`` need to be the same unqualified type as the
209 array type's element type.
210
211 If ``num_values`` is 0, the ``values`` parameter will be
212 ignored and zero initialization will be used.
213
214 This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its
215 presence using:
216
217 .. code-block:: c
218
219 #ifdef LIBGCCJIT_HAVE_CTORS
220
221 .. function:: gcc_jit_rvalue *\
222 gcc_jit_context_new_struct_constructor (gcc_jit_context *ctxt,\
223 gcc_jit_location *loc,\
224 gcc_jit_type *type,\
225 size_t num_values,\
226 gcc_jit_field **fields,\
227 gcc_jit_rvalue **values)
228
229
230 Create a constructor for a struct as an rvalue.
231
232 Returns NULL on error. The two parameter arrays are copied and
233 do not have to outlive the context.
234
235 ``type`` specifies what the constructor will build and has to be
236 a struct.
237
238 ``num_values`` specifies the number of elements in ``values``.
239
240 ``fields`` need to have the same length as ``values``, or be NULL.
241
242 If ``fields`` is null, the values are applied in definition order.
243
244 Otherwise, each field in ``fields`` specifies which field in the struct to
245 set to the corresponding value in ``values``. ``fields`` and ``values``
246 are paired by index.
247
248 The fields in ``fields`` have to be in definition order, but there
249 can be gaps. Any field in the struct that is not specified in
250 ``fields`` will be zeroed.
251
252 The fields in ``fields`` need to be the same objects that were used
253 to create the struct.
254
255 Each value has to have the same unqualified type as the field
256 it is applied to.
257
258 A NULL value element in ``values`` is a shorthand for zero initialization
259 of the corresponding field.
260
261 If ``num_values`` is 0, the array parameters will be
262 ignored and zero initialization will be used.
263
264 This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its
265 presence using:
266
267 .. code-block:: c
268
269 #ifdef LIBGCCJIT_HAVE_CTORS
270
271 .. function:: gcc_jit_rvalue *\
272 gcc_jit_context_new_union_constructor (gcc_jit_context *ctxt,\
273 gcc_jit_location *loc,\
274 gcc_jit_type *type,\
275 gcc_jit_field *field,\
276 gcc_jit_rvalue *value)
277
278 Create a constructor for a union as an rvalue.
279
280 Returns NULL on error.
281
282 ``type`` specifies what the constructor will build and has to be
283 an union.
284
285 ``field`` specifies which field to set. If it is NULL, the first
286 field in the union will be set.``field`` need to be the same object
287 that were used to create the union.
288
289 ``value`` specifies what value to set the corresponding field to.
290 If ``value`` is NULL, zero initialization will be used.
291
292 Each value has to have have the same unqualified type as the field
293 it is applied to.
294
295 This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its
296 presence using:
297
298 .. code-block:: c
299
300 #ifdef LIBGCCJIT_HAVE_CTORS
301
302 Vector expressions
303 ******************
304
305 .. function:: gcc_jit_rvalue * \
306 gcc_jit_context_new_rvalue_from_vector (gcc_jit_context *ctxt, \
307 gcc_jit_location *loc, \
308 gcc_jit_type *vec_type, \
309 size_t num_elements, \
310 gcc_jit_rvalue **elements)
311
312 Build a vector rvalue from an array of elements.
313
314 "vec_type" should be a vector type, created using
315 :func:`gcc_jit_type_get_vector`.
316
317 "num_elements" should match that of the vector type.
318
319 This entrypoint was added in :ref:`LIBGCCJIT_ABI_10`; you can test for
320 its presence using
321
322 .. code-block:: c
323
324 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector
325
326 .. function:: gcc_jit_rvalue * \
327 gcc_jit_context_new_rvalue_vector_perm (gcc_jit_context *ctxt, \
328 gcc_jit_location *loc, \
329 gcc_jit_rvalue *elements1, \
330 gcc_jit_rvalue *elements2, \
331 gcc_jit_rvalue *mask);
332
333 Build a permutation of two vectors.
334
335 "elements1" and "elements2" should have the same type.
336 The length of "mask" and "elements1" should be the same.
337 The element type of "mask" should be integral.
338 The size of the element type of "mask" and "elements1" should be the same.
339
340 This entrypoint was added in :ref:`LIBGCCJIT_ABI_31`; you can test for
341 its presence using
342
343 .. code-block:: c
344
345 #ifdef LIBGCCJIT_HAVE_VECTOR_OPERATIONS
346
347 Analogous to:
348
349 .. code-block:: c
350
351 __builtin_shuffle (elements1, elements2, mask)
352
353 in C.
354
355 Unary Operations
356 ****************
357
358 .. function:: gcc_jit_rvalue * \
359 gcc_jit_context_new_unary_op (gcc_jit_context *ctxt, \
360 gcc_jit_location *loc, \
361 enum gcc_jit_unary_op op, \
362 gcc_jit_type *result_type, \
363 gcc_jit_rvalue *rvalue)
364
365 Build a unary operation out of an input rvalue.
366
367 The parameter ``result_type`` must be a numeric type.
368
369 .. enum:: gcc_jit_unary_op
370
371 The available unary operations are:
372
373 .. list-table::
374 :header-rows: 1
375
376 * - Unary Operation
377 - C equivalent
378
379 * - :c:macro:`GCC_JIT_UNARY_OP_MINUS`
380 - `-(EXPR)`
381 * - :c:macro:`GCC_JIT_UNARY_OP_BITWISE_NEGATE`
382 - `~(EXPR)`
383 * - :c:macro:`GCC_JIT_UNARY_OP_LOGICAL_NEGATE`
384 - `!(EXPR)`
385 * - :c:macro:`GCC_JIT_UNARY_OP_ABS`
386 - `abs (EXPR)`
387
388 .. c:macro:: GCC_JIT_UNARY_OP_MINUS
389
390 Negate an arithmetic value; analogous to:
391
392 .. code-block:: c
393
394 -(EXPR)
395
396 in C.
397
398 .. c:macro:: GCC_JIT_UNARY_OP_BITWISE_NEGATE
399
400 Bitwise negation of an integer value (one's complement); analogous
401 to:
402
403 .. code-block:: c
404
405 ~(EXPR)
406
407 in C.
408
409 .. c:macro:: GCC_JIT_UNARY_OP_LOGICAL_NEGATE
410
411 Logical negation of an arithmetic or pointer value; analogous to:
412
413 .. code-block:: c
414
415 !(EXPR)
416
417 in C.
418
419 .. c:macro:: GCC_JIT_UNARY_OP_ABS
420
421 Absolute value of an arithmetic expression; analogous to:
422
423 .. code-block:: c
424
425 abs (EXPR)
426
427 in C.
428
429 Binary Operations
430 *****************
431
432 .. function:: gcc_jit_rvalue *gcc_jit_context_new_binary_op (gcc_jit_context *ctxt, \
433 gcc_jit_location *loc, \
434 enum gcc_jit_binary_op op, \
435 gcc_jit_type *result_type, \
436 gcc_jit_rvalue *a, gcc_jit_rvalue *b)
437
438 Build a binary operation out of two constituent rvalues.
439
440 The parameter ``result_type`` must be a numeric type.
441
442 .. enum:: gcc_jit_binary_op
443
444 The available binary operations are:
445
446 .. list-table::
447 :header-rows: 1
448
449 * - Binary Operation
450 - C equivalent
451
452 * - :c:macro:`GCC_JIT_BINARY_OP_PLUS`
453 - `x + y`
454 * - :c:macro:`GCC_JIT_BINARY_OP_MINUS`
455 - `x - y`
456 * - :c:macro:`GCC_JIT_BINARY_OP_MULT`
457 - `x * y`
458 * - :c:macro:`GCC_JIT_BINARY_OP_DIVIDE`
459 - `x / y`
460 * - :c:macro:`GCC_JIT_BINARY_OP_MODULO`
461 - `x % y`
462 * - :c:macro:`GCC_JIT_BINARY_OP_BITWISE_AND`
463 - `x & y`
464 * - :c:macro:`GCC_JIT_BINARY_OP_BITWISE_XOR`
465 - `x ^ y`
466 * - :c:macro:`GCC_JIT_BINARY_OP_BITWISE_OR`
467 - `x | y`
468 * - :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_AND`
469 - `x && y`
470 * - :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_OR`
471 - `x || y`
472 * - :c:macro:`GCC_JIT_BINARY_OP_LSHIFT`
473 - `x << y`
474 * - :c:macro:`GCC_JIT_BINARY_OP_RSHIFT`
475 - `x >> y`
476
477 .. c:macro:: GCC_JIT_BINARY_OP_PLUS
478
479 Addition of arithmetic values; analogous to:
480
481 .. code-block:: c
482
483 (EXPR_A) + (EXPR_B)
484
485 in C.
486
487 For pointer addition, use :c:func:`gcc_jit_context_new_array_access`.
488
489 .. c:macro:: GCC_JIT_BINARY_OP_MINUS
490
491 Subtraction of arithmetic values; analogous to:
492
493 .. code-block:: c
494
495 (EXPR_A) - (EXPR_B)
496
497 in C.
498
499 .. c:macro:: GCC_JIT_BINARY_OP_MULT
500
501 Multiplication of a pair of arithmetic values; analogous to:
502
503 .. code-block:: c
504
505 (EXPR_A) * (EXPR_B)
506
507 in C.
508
509 .. c:macro:: GCC_JIT_BINARY_OP_DIVIDE
510
511 Quotient of division of arithmetic values; analogous to:
512
513 .. code-block:: c
514
515 (EXPR_A) / (EXPR_B)
516
517 in C.
518
519 The result type affects the kind of division: if the result type is
520 integer-based, then the result is truncated towards zero, whereas
521 a floating-point result type indicates floating-point division.
522
523 .. c:macro:: GCC_JIT_BINARY_OP_MODULO
524
525 Remainder of division of arithmetic values; analogous to:
526
527 .. code-block:: c
528
529 (EXPR_A) % (EXPR_B)
530
531 in C.
532
533 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_AND
534
535 Bitwise AND; analogous to:
536
537 .. code-block:: c
538
539 (EXPR_A) & (EXPR_B)
540
541 in C.
542
543 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_XOR
544
545 Bitwise exclusive OR; analogous to:
546
547 .. code-block:: c
548
549 (EXPR_A) ^ (EXPR_B)
550
551 in C.
552
553 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_OR
554
555 Bitwise inclusive OR; analogous to:
556
557 .. code-block:: c
558
559 (EXPR_A) | (EXPR_B)
560
561 in C.
562
563 .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_AND
564
565 Logical AND; analogous to:
566
567 .. code-block:: c
568
569 (EXPR_A) && (EXPR_B)
570
571 in C.
572
573 .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_OR
574
575 Logical OR; analogous to:
576
577 .. code-block:: c
578
579 (EXPR_A) || (EXPR_B)
580
581 in C.
582
583 .. c:macro:: GCC_JIT_BINARY_OP_LSHIFT
584
585 Left shift; analogous to:
586
587 .. code-block:: c
588
589 (EXPR_A) << (EXPR_B)
590
591 in C.
592
593 .. c:macro:: GCC_JIT_BINARY_OP_RSHIFT
594
595 Right shift; analogous to:
596
597 .. code-block:: c
598
599 (EXPR_A) >> (EXPR_B)
600
601 in C.
602
603 Comparisons
604 ***********
605
606 .. function:: gcc_jit_rvalue *\
607 gcc_jit_context_new_comparison (gcc_jit_context *ctxt,\
608 gcc_jit_location *loc,\
609 enum gcc_jit_comparison op,\
610 gcc_jit_rvalue *a, gcc_jit_rvalue *b)
611
612 Build a boolean rvalue out of the comparison of two other rvalues.
613
614 .. enum:: gcc_jit_comparison
615
616 .. list-table::
617 :header-rows: 1
618
619 * - Comparison
620 - C equivalent
621
622 * - :c:macro:`GCC_JIT_COMPARISON_EQ`
623 - `x == y`
624 * - :c:macro:`GCC_JIT_COMPARISON_NE`
625 - `x != y`
626 * - :c:macro:`GCC_JIT_COMPARISON_LT`
627 - `x < y`
628 * - :c:macro:`GCC_JIT_COMPARISON_LE`
629 - `x <= y`
630 * - :c:macro:`GCC_JIT_COMPARISON_GT`
631 - `x > y`
632 * - :c:macro:`GCC_JIT_COMPARISON_GE`
633 - `x >= y`
634
635 Function calls
636 **************
637 .. function:: gcc_jit_rvalue *\
638 gcc_jit_context_new_call (gcc_jit_context *ctxt,\
639 gcc_jit_location *loc,\
640 gcc_jit_function *func,\
641 int numargs , gcc_jit_rvalue **args)
642
643 Given a function and the given table of argument rvalues, construct a
644 call to the function, with the result as an rvalue.
645
646 .. note::
647
648 :c:func:`gcc_jit_context_new_call` merely builds a
649 :c:type:`gcc_jit_rvalue` i.e. an expression that can be evaluated,
650 perhaps as part of a more complicated expression.
651 The call *won't* happen unless you add a statement to a function
652 that evaluates the expression.
653
654 For example, if you want to call a function and discard the result
655 (or to call a function with ``void`` return type), use
656 :c:func:`gcc_jit_block_add_eval`:
657
658 .. code-block:: c
659
660 /* Add "(void)printf (arg0, arg1);". */
661 gcc_jit_block_add_eval (
662 block, NULL,
663 gcc_jit_context_new_call (
664 ctxt,
665 NULL,
666 printf_func,
667 2, args));
668
669 .. function:: gcc_jit_rvalue *\
670 gcc_jit_context_new_call_through_ptr (gcc_jit_context *ctxt,\
671 gcc_jit_location *loc,\
672 gcc_jit_rvalue *fn_ptr,\
673 int numargs, \
674 gcc_jit_rvalue **args)
675
676 Given an rvalue of function pointer type (e.g. from
677 :c:func:`gcc_jit_context_new_function_ptr_type`), and the given table of
678 argument rvalues, construct a call to the function pointer, with the
679 result as an rvalue.
680
681 .. note::
682
683 The same caveat as for :c:func:`gcc_jit_context_new_call` applies.
684
685 .. function:: void\
686 gcc_jit_rvalue_set_bool_require_tail_call (gcc_jit_rvalue *call,\
687 int require_tail_call)
688
689 Given an :c:type:`gcc_jit_rvalue` for a call created through
690 :c:func:`gcc_jit_context_new_call` or
691 :c:func:`gcc_jit_context_new_call_through_ptr`, mark/clear the
692 call as needing tail-call optimization. The optimizer will
693 attempt to optimize the call into a jump instruction; if it is
694 unable to do do, an error will be emitted.
695
696 This may be useful when implementing functions that use the
697 continuation-passing style (e.g. for functional programming
698 languages), in which every function "returns" by calling a
699 "continuation" function pointer. This call must be
700 guaranteed to be implemented as a jump, otherwise the program
701 could consume an arbitrary amount of stack space as it executed.
702
703 This entrypoint was added in :ref:`LIBGCCJIT_ABI_6`; you can test for
704 its presence using
705
706 .. code-block:: c
707
708 #ifdef LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call
709
710 Function pointers
711 *****************
712
713 Function pointers can be obtained:
714
715 * from a :c:type:`gcc_jit_function` using
716 :c:func:`gcc_jit_function_get_address`, or
717
718 * from an existing function using
719 :c:func:`gcc_jit_context_new_rvalue_from_ptr`,
720 using a function pointer type obtained using
721 :c:func:`gcc_jit_context_new_function_ptr_type`.
722
723 Type-coercion
724 *************
725
726 .. function:: gcc_jit_rvalue *\
727 gcc_jit_context_new_cast (gcc_jit_context *ctxt,\
728 gcc_jit_location *loc,\
729 gcc_jit_rvalue *rvalue,\
730 gcc_jit_type *type)
731
732 Given an rvalue of T, construct another rvalue of another type.
733
734 Currently only a limited set of conversions are possible:
735
736 * int <-> float
737 * int <-> bool
738 * P* <-> Q*, for pointer types P and Q
739
740 .. function:: gcc_jit_rvalue *\
741 gcc_jit_context_new_bitcast (gcc_jit_context *ctxt,\
742 gcc_jit_location *loc,\
743 gcc_jit_rvalue *rvalue,\
744 gcc_jit_type *type)
745
746 Given an rvalue of T, bitcast it to another type, meaning that this will
747 generate a new rvalue by interpreting the bits of ``rvalue`` to the layout
748 of ``type``.
749
750 The type of rvalue must be the same size as the size of ``type``.
751
752 This entrypoint was added in :ref:`LIBGCCJIT_ABI_21`; you can test for
753 its presence using
754
755 .. code-block:: c
756
757 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitcast
758
759 .. function:: gcc_jit_rvalue *
760 gcc_jit_context_convert_vector (gcc_jit_context *ctxt, \
761 gcc_jit_location *loc, \
762 gcc_jit_rvalue *vector, \
763 gcc_jit_type *type)
764
765 Given a vector rvalue, cast it to the type ``type``, doing an element-wise
766 conversion.
767
768 The number of elements in ``vector`` and ``type`` must match.
769 The ``type`` must be a vector type.
770
771 This entrypoint was added in :ref:`LIBGCCJIT_ABI_30`; you can test for
772 its presence using
773
774 .. code-block:: c
775
776 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_convert_vector
777
778 Lvalues
779 -------
780
781 .. type:: gcc_jit_lvalue
782
783 An lvalue is something that can of the *left*-hand side of an assignment:
784 a storage area (such as a variable). It is also usable as an rvalue,
785 where the rvalue is computed by reading from the storage area.
786
787 .. function:: gcc_jit_object *\
788 gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue)
789
790 Upcast an lvalue to be an object.
791
792 .. function:: gcc_jit_rvalue *\
793 gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue)
794
795 Upcast an lvalue to be an rvalue.
796
797 .. function:: gcc_jit_rvalue *\
798 gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue,\
799 gcc_jit_location *loc)
800
801 Take the address of an lvalue; analogous to:
802
803 .. code-block:: c
804
805 &(EXPR)
806
807 in C.
808
809 .. function:: void\
810 gcc_jit_lvalue_set_tls_model (gcc_jit_lvalue *lvalue,\
811 enum gcc_jit_tls_model model)
812
813 Make a variable a thread-local variable.
814
815 The "model" parameter determines the thread-local storage model of the "lvalue":
816
817 .. enum:: gcc_jit_tls_model
818
819 .. c:macro:: GCC_JIT_TLS_MODEL_NONE
820
821 Don't set the TLS model.
822
823 .. c:macro:: GCC_JIT_TLS_MODEL_GLOBAL_DYNAMIC
824
825 .. c:macro:: GCC_JIT_TLS_MODEL_LOCAL_DYNAMIC
826
827 .. c:macro:: GCC_JIT_TLS_MODEL_INITIAL_EXEC
828
829 .. c:macro:: GCC_JIT_TLS_MODEL_LOCAL_EXEC
830
831 This is analogous to:
832
833 .. code-block:: c
834
835 _Thread_local int foo __attribute__ ((tls_model("MODEL")));
836
837 in C.
838
839 This entrypoint was added in :ref:`LIBGCCJIT_ABI_17`; you can test for
840 its presence using
841
842 .. code-block:: c
843
844 #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_tls_model
845
846 .. function:: void\
847 gcc_jit_lvalue_set_link_section (gcc_jit_lvalue *lvalue,\
848 const char *section_name)
849
850 Set the link section of a variable.
851 The parameter ``section_name`` must be non-NULL and must contain the
852 leading dot. Analogous to:
853
854 .. code-block:: c
855
856 int variable __attribute__((section(".section")));
857
858 in C.
859
860 This entrypoint was added in :ref:`LIBGCCJIT_ABI_18`; you can test for
861 its presence using
862
863 .. code-block:: c
864
865 #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_link_section
866
867 .. function:: void\
868 gcc_jit_lvalue_set_register_name (gcc_jit_lvalue *lvalue,\
869 const char *reg_name);
870
871 Set the register name of a variable.
872 The parameter ``reg_name`` must be non-NULL. Analogous to:
873
874 .. code-block:: c
875
876 register int variable asm ("r12");
877
878 in C.
879
880 This entrypoint was added in :ref:`LIBGCCJIT_ABI_22`; you can test for
881 its presence using
882
883 .. code-block:: c
884
885 #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_register_name
886
887 .. function:: void\
888 gcc_jit_lvalue_set_alignment (gcc_jit_lvalue *lvalue,\
889 unsigned bytes)
890
891 Set the alignment of a variable, in bytes.
892 Analogous to:
893
894 .. code-block:: c
895
896 int variable __attribute__((aligned (16)));
897
898 in C.
899
900 This entrypoint was added in :ref:`LIBGCCJIT_ABI_24`; you can test for
901 its presence using
902
903 .. code-block:: c
904
905 #ifdef LIBGCCJIT_HAVE_ALIGNMENT
906
907 .. function:: unsigned\
908 gcc_jit_lvalue_get_alignment (gcc_jit_lvalue *lvalue)
909
910 Return the alignment of a variable set by ``gcc_jit_lvalue_set_alignment``.
911 Return 0 if the alignment was not set. Analogous to:
912
913 .. code-block:: c
914
915 _Alignof (variable)
916
917 in C.
918
919 This entrypoint was added in :ref:`LIBGCCJIT_ABI_24`; you can test for
920 its presence using
921
922 .. code-block:: c
923
924 #ifdef LIBGCCJIT_HAVE_ALIGNMENT
925
926 Global variables
927 ****************
928
929 .. function:: gcc_jit_lvalue *\
930 gcc_jit_context_new_global (gcc_jit_context *ctxt,\
931 gcc_jit_location *loc,\
932 enum gcc_jit_global_kind kind,\
933 gcc_jit_type *type,\
934 const char *name)
935
936 Add a new global variable of the given type and name to the context.
937
938 The parameter ``type`` must be non-`void`.
939
940 The parameter ``name`` must be non-NULL. The call takes a copy of the
941 underlying string, so it is valid to pass in a pointer to an on-stack
942 buffer.
943
944 The "kind" parameter determines the visibility of the "global" outside
945 of the :c:type:`gcc_jit_result`:
946
947 .. enum:: gcc_jit_global_kind
948
949 .. c:macro:: GCC_JIT_GLOBAL_EXPORTED
950
951 Global is defined by the client code and is visible
952 by name outside of this JIT context via
953 :c:func:`gcc_jit_result_get_global` (and this value is required for
954 the global to be accessible via that entrypoint).
955
956 .. c:macro:: GCC_JIT_GLOBAL_INTERNAL
957
958 Global is defined by the client code, but is invisible
959 outside of it. Analogous to a "static" global within a .c file.
960 Specifically, the variable will only be visible within this
961 context and within child contexts.
962
963 .. c:macro:: GCC_JIT_GLOBAL_IMPORTED
964
965 Global is not defined by the client code; we're merely
966 referring to it. Analogous to using an "extern" global from a
967 header file.
968
969 .. function:: gcc_jit_lvalue *\
970 gcc_jit_global_set_initializer (gcc_jit_lvalue *global,\
971 const void *blob,\
972 size_t num_bytes)
973
974 Set an initializer for ``global`` using the memory content pointed
975 by ``blob`` for ``num_bytes``. ``global`` must be an array of an
976 integral type. Return the global itself.
977
978 The parameter ``blob`` must be non-NULL. The call copies the memory
979 pointed by ``blob`` for ``num_bytes`` bytes, so it is valid to pass
980 in a pointer to an on-stack buffer. The content will be stored in
981 the compilation unit and used as initialization value of the array.
982
983 This entrypoint was added in :ref:`LIBGCCJIT_ABI_14`; you can test for
984 its presence using
985
986 .. code-block:: c
987
988 #ifdef LIBGCCJIT_HAVE_gcc_jit_global_set_initializer
989
990 .. function:: gcc_jit_lvalue *\
991 gcc_jit_global_set_initializer_rvalue (gcc_jit_lvalue *global,\
992 gcc_jit_rvalue *init_value)
993
994 Set the initial value of a global with an rvalue.
995
996 The rvalue needs to be a constant expression, e.g. no function calls.
997
998 The global can't have the ``kind`` :c:macro:`GCC_JIT_GLOBAL_IMPORTED`.
999
1000 As a non-comprehensive example it is OK to do the equivalent of:
1001
1002 .. code-block:: c
1003
1004 int foo = 3 * 2; /* rvalue from gcc_jit_context_new_binary_op. */
1005 int arr[] = {1,2,3,4}; /* rvalue from gcc_jit_context_new_constructor. */
1006 int *bar = &arr[2] + 1; /* rvalue from nested "get address" of "array access". */
1007 const int baz = 3; /* rvalue from gcc_jit_context_rvalue_from_int. */
1008 int boz = baz; /* rvalue from gcc_jit_lvalue_as_rvalue. */
1009
1010 Use together with :c:func:`gcc_jit_context_new_struct_constructor`,
1011 :c:func:`gcc_jit_context_new_union_constructor`, :c:func:`gcc_jit_context_new_array_constructor`
1012 to initialize structs, unions and arrays.
1013
1014 On success, returns the ``global`` parameter unchanged. Otherwise, ``NULL``.
1015
1016 This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its
1017 presence using:
1018
1019 .. code-block:: c
1020
1021 #ifdef LIBGCCJIT_HAVE_CTORS
1022
1023 Variables
1024 *********
1025
1026 .. function:: void\
1027 gcc_jit_lvalue_add_string_attribute (gcc_jit_lvalue *variable,
1028 enum gcc_jit_variable_attribute attribute,
1029 const char *value)
1030
1031 Add an attribute ``attribute`` with value ``value`` to a variable ``variable``.
1032
1033 This entrypoint was added in :ref:`LIBGCCJIT_ABI_26`; you can test for
1034 its presence using
1035
1036 .. code-block:: c
1037
1038 #ifdef LIBGCCJIT_HAVE_ATTRIBUTES
1039
1040 .. function:: void\
1041 gcc_jit_global_set_readonly (gcc_jit_lvalue *global)
1042
1043 Set the global variable as read-only, meaning you cannot assign to this variable.
1044
1045 This entrypoint was added in :ref:`LIBGCCJIT_ABI_29`; you can test for its
1046 presence using:
1047
1048 .. code-block:: c
1049
1050 #ifdef LIBGCCJIT_HAVE_gcc_jit_global_set_readonly
1051
1052 Working with pointers, structs and unions
1053 -----------------------------------------
1054
1055 .. function:: gcc_jit_lvalue *\
1056 gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue,\
1057 gcc_jit_location *loc)
1058
1059 Given an rvalue of pointer type ``T *``, dereferencing the pointer,
1060 getting an lvalue of type ``T``. Analogous to:
1061
1062 .. code-block:: c
1063
1064 *(EXPR)
1065
1066 in C.
1067
1068 Field access is provided separately for both lvalues and rvalues.
1069
1070 .. function:: gcc_jit_lvalue *\
1071 gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_,\
1072 gcc_jit_location *loc,\
1073 gcc_jit_field *field)
1074
1075 Given an lvalue of struct or union type, access the given field,
1076 getting an lvalue of the field's type. Analogous to:
1077
1078 .. code-block:: c
1079
1080 (EXPR).field = ...;
1081
1082 in C.
1083
1084 .. function:: gcc_jit_rvalue *\
1085 gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_,\
1086 gcc_jit_location *loc,\
1087 gcc_jit_field *field)
1088
1089 Given an rvalue of struct or union type, access the given field
1090 as an rvalue. Analogous to:
1091
1092 .. code-block:: c
1093
1094 (EXPR).field
1095
1096 in C.
1097
1098 .. function:: gcc_jit_lvalue *\
1099 gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr,\
1100 gcc_jit_location *loc,\
1101 gcc_jit_field *field)
1102
1103 Given an rvalue of pointer type ``T *`` where T is of struct or union
1104 type, access the given field as an lvalue. Analogous to:
1105
1106 .. code-block:: c
1107
1108 (EXPR)->field
1109
1110 in C, itself equivalent to ``(*EXPR).FIELD``.
1111
1112 .. function:: gcc_jit_lvalue *\
1113 gcc_jit_context_new_array_access (gcc_jit_context *ctxt,\
1114 gcc_jit_location *loc,\
1115 gcc_jit_rvalue *ptr,\
1116 gcc_jit_rvalue *index)
1117
1118 Given an rvalue of pointer type ``T *``, get at the element `T` at
1119 the given index, using standard C array indexing rules i.e. each
1120 increment of ``index`` corresponds to ``sizeof(T)`` bytes.
1121 Analogous to:
1122
1123 .. code-block:: c
1124
1125 PTR[INDEX]
1126
1127 in C (or, indeed, to ``PTR + INDEX``).
1128
1129 .. function:: gcc_jit_lvalue *\
1130 gcc_jit_context_new_vector_access (gcc_jit_context *ctxt,\
1131 gcc_jit_location *loc,\
1132 gcc_jit_rvalue *vector,\
1133 gcc_jit_rvalue *index)
1134
1135 Given an rvalue of vector type ``T __attribute__ ((__vector_size__ (SIZE)))``,
1136 get the element `T` at the given index.
1137
1138 This entrypoint was added in :ref:`LIBGCCJIT_ABI_31`; you can test for
1139 its presence using
1140
1141 .. code-block:: c
1142
1143 #ifdef LIBGCCJIT_HAVE_VECTOR_OPERATIONS
1144
1145 Analogous to:
1146
1147 .. code-block:: c
1148
1149 VECTOR[INDEX]
1150
1151 in C.