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