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