1.. Copyright (C) 2014-2020 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 20Expressions 21=========== 22 23Rvalues 24------- 25.. type:: gcc_jit_rvalue 26 27A :c:type:`gcc_jit_rvalue *` is an expression that can be computed. 28 29It 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 35or 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 42Every rvalue has an associated type, and the API will check to ensure 43that 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 54Simple 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 129Vector 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 153Unary 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 167The available unary operations are: 168 169========================================== ============ 170Unary 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 219Binary 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 232The available binary operations are: 233 234======================================== ============ 235Binary 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 377Comparisons 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======================================= ============ 391Comparison 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 402Function 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 477Function pointers 478***************** 479 480Function 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 490Type-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 507Lvalues 508------- 509 510.. type:: gcc_jit_lvalue 511 512An lvalue is something that can of the *left*-hand side of an assignment: 513a storage area (such as a variable). It is also usable as an rvalue, 514where 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 538Global 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 579Working 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 595Field 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``). 655