Mercurial > hg > CbC > CbC_gcc

comparison gcc/jit/docs/topics/expressions.rst @ 111:04ced10e8804

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
gcc 7
author kono
date Fri, 27 Oct 2017 22:46:09 +0900
parents
children 84e7813d76e9
comparison
equal deleted inserted replaced
68:561a7518be6b 111:04ced10e8804
1 .. Copyright (C) 2014-2017 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <dmalcolm@redhat.com>
3
4 This is free software: you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by
6 the Free Software Foundation, either version 3 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful, but
10 WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see
16 <http://www.gnu.org/licenses/>.
17
18 .. default-domain:: c
19
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 :c:type:`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 :c:type:`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 :c:type:`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 Vector expressions
130 ******************
131
132 .. function:: gcc_jit_rvalue * \
133 gcc_jit_context_new_rvalue_from_vector (gcc_jit_context *ctxt, \
134 gcc_jit_location *loc, \
135 gcc_jit_type *vec_type, \
136 size_t num_elements, \
137 gcc_jit_rvalue **elements)
138
139 Build a vector rvalue from an array of elements.
140
141 "vec_type" should be a vector type, created using
142 :func:`gcc_jit_type_get_vector`.
143
144 "num_elements" should match that of the vector type.
145
146 This entrypoint was added in :ref:`LIBGCCJIT_ABI_10`; you can test for
147 its presence using
148
149 .. code-block:: c
150
151 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector
152
153 Unary Operations
154 ****************
155
156 .. function:: gcc_jit_rvalue * \
157 gcc_jit_context_new_unary_op (gcc_jit_context *ctxt, \
158 gcc_jit_location *loc, \
159 enum gcc_jit_unary_op op, \
160 gcc_jit_type *result_type, \
161 gcc_jit_rvalue *rvalue)
162
163 Build a unary operation out of an input rvalue.
164
165 .. type:: enum gcc_jit_unary_op
166
167 The available unary operations are:
168
169 ========================================== ============
170 Unary Operation C equivalent
171 ========================================== ============
172 :c:macro:`GCC_JIT_UNARY_OP_MINUS` `-(EXPR)`
173 :c:macro:`GCC_JIT_UNARY_OP_BITWISE_NEGATE` `~(EXPR)`
174 :c:macro:`GCC_JIT_UNARY_OP_LOGICAL_NEGATE` `!(EXPR)`
175 :c:macro:`GCC_JIT_UNARY_OP_ABS` `abs (EXPR)`
176 ========================================== ============
177
178 .. c:macro:: GCC_JIT_UNARY_OP_MINUS
179
180 Negate an arithmetic value; analogous to:
181
182 .. code-block:: c
183
184 -(EXPR)
185
186 in C.
187
188 .. c:macro:: GCC_JIT_UNARY_OP_BITWISE_NEGATE
189
190 Bitwise negation of an integer value (one's complement); analogous
191 to:
192
193 .. code-block:: c
194
195 ~(EXPR)
196
197 in C.
198
199 .. c:macro:: GCC_JIT_UNARY_OP_LOGICAL_NEGATE
200
201 Logical negation of an arithmetic or pointer value; analogous to:
202
203 .. code-block:: c
204
205 !(EXPR)
206
207 in C.
208
209 .. c:macro:: GCC_JIT_UNARY_OP_ABS
210
211 Absolute value of an arithmetic expression; analogous to:
212
213 .. code-block:: c
214
215 abs (EXPR)
216
217 in C.
218
219 Binary Operations
220 *****************
221
222 .. function:: gcc_jit_rvalue *gcc_jit_context_new_binary_op (gcc_jit_context *ctxt, \
223 gcc_jit_location *loc, \
224 enum gcc_jit_binary_op op, \
225 gcc_jit_type *result_type, \
226 gcc_jit_rvalue *a, gcc_jit_rvalue *b)
227
228 Build a binary operation out of two constituent rvalues.
229
230 .. type:: enum gcc_jit_binary_op
231
232 The available binary operations are:
233
234 ======================================== ============
235 Binary Operation C equivalent
236 ======================================== ============
237 :c:macro:`GCC_JIT_BINARY_OP_PLUS` `x + y`
238 :c:macro:`GCC_JIT_BINARY_OP_MINUS` `x - y`
239 :c:macro:`GCC_JIT_BINARY_OP_MULT` `x * y`
240 :c:macro:`GCC_JIT_BINARY_OP_DIVIDE` `x / y`
241 :c:macro:`GCC_JIT_BINARY_OP_MODULO` `x % y`
242 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_AND` `x & y`
243 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_XOR` `x ^ y`
244 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_OR` `x | y`
245 :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_AND` `x && y`
246 :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_OR` `x || y`
247 :c:macro:`GCC_JIT_BINARY_OP_LSHIFT` `x << y`
248 :c:macro:`GCC_JIT_BINARY_OP_RSHIFT` `x >> y`
249 ======================================== ============
250
251 .. c:macro:: GCC_JIT_BINARY_OP_PLUS
252
253 Addition of arithmetic values; analogous to:
254
255 .. code-block:: c
256
257 (EXPR_A) + (EXPR_B)
258
259 in C.
260
261 For pointer addition, use :c:func:`gcc_jit_context_new_array_access`.
262
263 .. c:macro:: GCC_JIT_BINARY_OP_MINUS
264
265 Subtraction of arithmetic values; analogous to:
266
267 .. code-block:: c
268
269 (EXPR_A) - (EXPR_B)
270
271 in C.
272
273 .. c:macro:: GCC_JIT_BINARY_OP_MULT
274
275 Multiplication of a pair of arithmetic values; analogous to:
276
277 .. code-block:: c
278
279 (EXPR_A) * (EXPR_B)
280
281 in C.
282
283 .. c:macro:: GCC_JIT_BINARY_OP_DIVIDE
284
285 Quotient of division of arithmetic values; analogous to:
286
287 .. code-block:: c
288
289 (EXPR_A) / (EXPR_B)
290
291 in C.
292
293 The result type affects the kind of division: if the result type is
294 integer-based, then the result is truncated towards zero, whereas
295 a floating-point result type indicates floating-point division.
296
297 .. c:macro:: GCC_JIT_BINARY_OP_MODULO
298
299 Remainder of division of arithmetic values; analogous to:
300
301 .. code-block:: c
302
303 (EXPR_A) % (EXPR_B)
304
305 in C.
306
307 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_AND
308
309 Bitwise AND; analogous to:
310
311 .. code-block:: c
312
313 (EXPR_A) & (EXPR_B)
314
315 in C.
316
317 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_XOR
318
319 Bitwise exclusive OR; analogous to:
320
321 .. code-block:: c
322
323 (EXPR_A) ^ (EXPR_B)
324
325 in C.
326
327 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_OR
328
329 Bitwise inclusive OR; analogous to:
330
331 .. code-block:: c
332
333 (EXPR_A) | (EXPR_B)
334
335 in C.
336
337 .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_AND
338
339 Logical AND; analogous to:
340
341 .. code-block:: c
342
343 (EXPR_A) && (EXPR_B)
344
345 in C.
346
347 .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_OR
348
349 Logical OR; analogous to:
350
351 .. code-block:: c
352
353 (EXPR_A) || (EXPR_B)
354
355 in C.
356
357 .. c:macro:: GCC_JIT_BINARY_OP_LSHIFT
358
359 Left shift; analogous to:
360
361 .. code-block:: c
362
363 (EXPR_A) << (EXPR_B)
364
365 in C.
366
367 .. c:macro:: GCC_JIT_BINARY_OP_RSHIFT
368
369 Right shift; analogous to:
370
371 .. code-block:: c
372
373 (EXPR_A) >> (EXPR_B)
374
375 in C.
376
377 Comparisons
378 ***********
379
380 .. function:: gcc_jit_rvalue *\
381 gcc_jit_context_new_comparison (gcc_jit_context *ctxt,\
382 gcc_jit_location *loc,\
383 enum gcc_jit_comparison op,\
384 gcc_jit_rvalue *a, gcc_jit_rvalue *b)
385
386 Build a boolean rvalue out of the comparison of two other rvalues.
387
388 .. type:: enum gcc_jit_comparison
389
390 ======================================= ============
391 Comparison C equivalent
392 ======================================= ============
393 :c:macro:`GCC_JIT_COMPARISON_EQ` `x == y`
394 :c:macro:`GCC_JIT_COMPARISON_NE` `x != y`
395 :c:macro:`GCC_JIT_COMPARISON_LT` `x < y`
396 :c:macro:`GCC_JIT_COMPARISON_LE` `x <= y`
397 :c:macro:`GCC_JIT_COMPARISON_GT` `x > y`
398 :c:macro:`GCC_JIT_COMPARISON_GE` `x >= y`
399 ======================================= ============
400
401
402 Function calls
403 **************
404 .. function:: gcc_jit_rvalue *\
405 gcc_jit_context_new_call (gcc_jit_context *ctxt,\
406 gcc_jit_location *loc,\
407 gcc_jit_function *func,\
408 int numargs , gcc_jit_rvalue **args)
409
410 Given a function and the given table of argument rvalues, construct a
411 call to the function, with the result as an rvalue.
412
413 .. note::
414
415 :c:func:`gcc_jit_context_new_call` merely builds a
416 :c:type:`gcc_jit_rvalue` i.e. an expression that can be evaluated,
417 perhaps as part of a more complicated expression.
418 The call *won't* happen unless you add a statement to a function
419 that evaluates the expression.
420
421 For example, if you want to call a function and discard the result
422 (or to call a function with ``void`` return type), use
423 :c:func:`gcc_jit_block_add_eval`:
424
425 .. code-block:: c
426
427 /* Add "(void)printf (arg0, arg1);". */
428 gcc_jit_block_add_eval (
429 block, NULL,
430 gcc_jit_context_new_call (
431 ctxt,
432 NULL,
433 printf_func,
434 2, args));
435
436 .. function:: gcc_jit_rvalue *\
437 gcc_jit_context_new_call_through_ptr (gcc_jit_context *ctxt,\
438 gcc_jit_location *loc,\
439 gcc_jit_rvalue *fn_ptr,\
440 int numargs, \
441 gcc_jit_rvalue **args)
442
443 Given an rvalue of function pointer type (e.g. from
444 :c:func:`gcc_jit_context_new_function_ptr_type`), and the given table of
445 argument rvalues, construct a call to the function pointer, with the
446 result as an rvalue.
447
448 .. note::
449
450 The same caveat as for :c:func:`gcc_jit_context_new_call` applies.
451
452 .. function:: void\
453 gcc_jit_rvalue_set_bool_require_tail_call (gcc_jit_rvalue *call,\
454 int require_tail_call)
455
456 Given an :c:type:`gcc_jit_rvalue *` for a call created through
457 :c:func:`gcc_jit_context_new_call` or
458 :c:func:`gcc_jit_context_new_call_through_ptr`, mark/clear the
459 call as needing tail-call optimization. The optimizer will
460 attempt to optimize the call into a jump instruction; if it is
461 unable to do do, an error will be emitted.
462
463 This may be useful when implementing functions that use the
464 continuation-passing style (e.g. for functional programming
465 languages), in which every function "returns" by calling a
466 "continuation" function pointer. This call must be
467 guaranteed to be implemented as a jump, otherwise the program
468 could consume an arbitrary amount of stack space as it executed.
469
470 This entrypoint was added in :ref:`LIBGCCJIT_ABI_6`; you can test for
471 its presence using
472
473 .. code-block:: c
474
475 #ifdef LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call
476
477 Function pointers
478 *****************
479
480 Function pointers can be obtained:
481
482 * from a :c:type:`gcc_jit_function` using
483 :c:func:`gcc_jit_function_get_address`, or
484
485 * from an existing function using
486 :c:func:`gcc_jit_context_new_rvalue_from_ptr`,
487 using a function pointer type obtained using
488 :c:func:`gcc_jit_context_new_function_ptr_type`.
489
490 Type-coercion
491 *************
492
493 .. function:: gcc_jit_rvalue *\
494 gcc_jit_context_new_cast (gcc_jit_context *ctxt,\
495 gcc_jit_location *loc,\
496 gcc_jit_rvalue *rvalue,\
497 gcc_jit_type *type)
498
499 Given an rvalue of T, construct another rvalue of another type.
500
501 Currently only a limited set of conversions are possible:
502
503 * int <-> float
504 * int <-> bool
505 * P* <-> Q*, for pointer types P and Q
506
507 Lvalues
508 -------
509
510 .. type:: gcc_jit_lvalue
511
512 An lvalue is something that can of the *left*-hand side of an assignment:
513 a storage area (such as a variable). It is also usable as an rvalue,
514 where the rvalue is computed by reading from the storage area.
515
516 .. function:: gcc_jit_object *\
517 gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue)
518
519 Upcast an lvalue to be an object.
520
521 .. function:: gcc_jit_rvalue *\
522 gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue)
523
524 Upcast an lvalue to be an rvalue.
525
526 .. function:: gcc_jit_rvalue *\
527 gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue,\
528 gcc_jit_location *loc)
529
530 Take the address of an lvalue; analogous to:
531
532 .. code-block:: c
533
534 &(EXPR)
535
536 in C.
537
538 Global variables
539 ****************
540
541 .. function:: gcc_jit_lvalue *\
542 gcc_jit_context_new_global (gcc_jit_context *ctxt,\
543 gcc_jit_location *loc,\
544 enum gcc_jit_global_kind kind,\
545 gcc_jit_type *type,\
546 const char *name)
547
548 Add a new global variable of the given type and name to the context.
549
550 The parameter ``name`` must be non-NULL. The call takes a copy of the
551 underlying string, so it is valid to pass in a pointer to an on-stack
552 buffer.
553
554 The "kind" parameter determines the visibility of the "global" outside
555 of the :c:type:`gcc_jit_result`:
556
557 .. type:: enum gcc_jit_global_kind
558
559 .. c:macro:: GCC_JIT_GLOBAL_EXPORTED
560
561 Global is defined by the client code and is visible
562 by name outside of this JIT context via
563 :c:func:`gcc_jit_result_get_global` (and this value is required for
564 the global to be accessible via that entrypoint).
565
566 .. c:macro:: GCC_JIT_GLOBAL_INTERNAL
567
568 Global is defined by the client code, but is invisible
569 outside of it. Analogous to a "static" global within a .c file.
570 Specifically, the variable will only be visible within this
571 context and within child contexts.
572
573 .. c:macro:: GCC_JIT_GLOBAL_IMPORTED
574
575 Global is not defined by the client code; we're merely
576 referring to it. Analogous to using an "extern" global from a
577 header file.
578
579 Working with pointers, structs and unions
580 -----------------------------------------
581
582 .. function:: gcc_jit_lvalue *\
583 gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue,\
584 gcc_jit_location *loc)
585
586 Given an rvalue of pointer type ``T *``, dereferencing the pointer,
587 getting an lvalue of type ``T``. Analogous to:
588
589 .. code-block:: c
590
591 *(EXPR)
592
593 in C.
594
595 Field access is provided separately for both lvalues and rvalues.
596
597 .. function:: gcc_jit_lvalue *\
598 gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_,\
599 gcc_jit_location *loc,\
600 gcc_jit_field *field)
601
602 Given an lvalue of struct or union type, access the given field,
603 getting an lvalue of the field's type. Analogous to:
604
605 .. code-block:: c
606
607 (EXPR).field = ...;
608
609 in C.
610
611 .. function:: gcc_jit_rvalue *\
612 gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_,\
613 gcc_jit_location *loc,\
614 gcc_jit_field *field)
615
616 Given an rvalue of struct or union type, access the given field
617 as an rvalue. Analogous to:
618
619 .. code-block:: c
620
621 (EXPR).field
622
623 in C.
624
625 .. function:: gcc_jit_lvalue *\
626 gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr,\
627 gcc_jit_location *loc,\
628 gcc_jit_field *field)
629
630 Given an rvalue of pointer type ``T *`` where T is of struct or union
631 type, access the given field as an lvalue. Analogous to:
632
633 .. code-block:: c
634
635 (EXPR)->field
636
637 in C, itself equivalent to ``(*EXPR).FIELD``.
638
639 .. function:: gcc_jit_lvalue *\
640 gcc_jit_context_new_array_access (gcc_jit_context *ctxt,\
641 gcc_jit_location *loc,\
642 gcc_jit_rvalue *ptr,\
643 gcc_jit_rvalue *index)
644
645 Given an rvalue of pointer type ``T *``, get at the element `T` at
646 the given index, using standard C array indexing rules i.e. each
647 increment of ``index`` corresponds to ``sizeof(T)`` bytes.
648 Analogous to:
649
650 .. code-block:: c
651
652 PTR[INDEX]
653
654 in C (or, indeed, to ``PTR + INDEX``).