1/* A pure C API to enable client code to embed GCC as a JIT-compiler. 2 Copyright (C) 2013-2022 Free Software Foundation, Inc. 3 4This file is part of GCC. 5 6GCC is free software; you can redistribute it and/or modify it 7under the terms of the GNU General Public License as published by 8the Free Software Foundation; either version 3, or (at your option) 9any later version. 10 11GCC is distributed in the hope that it will be useful, but 12WITHOUT ANY WARRANTY; without even the implied warranty of 13MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14General Public License for more details. 15 16You should have received a copy of the GNU General Public License 17along with GCC; see the file COPYING3. If not see 18<http://www.gnu.org/licenses/>. */ 19 20#ifndef LIBGCCJIT_H 21#define LIBGCCJIT_H 22 23#include <stdio.h> 24 25#ifdef __cplusplus 26extern "C" { 27#endif /* __cplusplus */ 28 29/********************************************************************** 30 Data structures. 31 **********************************************************************/ 32/* All structs within the API are opaque. */ 33 34/* A gcc_jit_context encapsulates the state of a compilation. 35 You can set up options on it, and add types, functions and code, using 36 the API below. 37 38 Invoking gcc_jit_context_compile on it gives you a gcc_jit_result * 39 (or NULL), representing in-memory machine code. 40 41 You can call gcc_jit_context_compile repeatedly on one context, giving 42 multiple independent results. 43 44 Similarly, you can call gcc_jit_context_compile_to_file on a context 45 to compile to disk. 46 47 Eventually you can call gcc_jit_context_release to clean up the 48 context; any in-memory results created from it are still usable, and 49 should be cleaned up via gcc_jit_result_release. */ 50typedef struct gcc_jit_context gcc_jit_context; 51 52/* A gcc_jit_result encapsulates the result of an in-memory compilation. */ 53typedef struct gcc_jit_result gcc_jit_result; 54 55/* An object created within a context. Such objects are automatically 56 cleaned up when the context is released. 57 58 The class hierarchy looks like this: 59 60 +- gcc_jit_object 61 +- gcc_jit_location 62 +- gcc_jit_type 63 +- gcc_jit_struct 64 +- gcc_jit_function_type 65 +- gcc_jit_vector_type 66 +- gcc_jit_field 67 +- gcc_jit_function 68 +- gcc_jit_block 69 +- gcc_jit_rvalue 70 +- gcc_jit_lvalue 71 +- gcc_jit_param 72 +- gcc_jit_case 73 +- gcc_jit_extended_asm 74*/ 75typedef struct gcc_jit_object gcc_jit_object; 76 77/* A gcc_jit_location encapsulates a source code location, so that 78 you can (optionally) associate locations in your language with 79 statements in the JIT-compiled code, allowing the debugger to 80 single-step through your language. 81 82 Note that to do so, you also need to enable 83 GCC_JIT_BOOL_OPTION_DEBUGINFO 84 on the gcc_jit_context. 85 86 gcc_jit_location instances are optional; you can always pass 87 NULL. */ 88typedef struct gcc_jit_location gcc_jit_location; 89 90/* A gcc_jit_type encapsulates a type e.g. "int" or a "struct foo*". */ 91typedef struct gcc_jit_type gcc_jit_type; 92 93/* A gcc_jit_field encapsulates a field within a struct; it is used 94 when creating a struct type (using gcc_jit_context_new_struct_type). 95 Fields cannot be shared between structs. */ 96typedef struct gcc_jit_field gcc_jit_field; 97 98/* A gcc_jit_struct encapsulates a struct type, either one that we have 99 the layout for, or an opaque type. */ 100typedef struct gcc_jit_struct gcc_jit_struct; 101 102/* A gcc_jit_function_type encapsulates a function type. */ 103typedef struct gcc_jit_function_type gcc_jit_function_type; 104 105/* A gcc_jit_vector_type encapsulates a vector type. */ 106typedef struct gcc_jit_vector_type gcc_jit_vector_type; 107 108/* A gcc_jit_function encapsulates a function: either one that you're 109 creating yourself, or a reference to one that you're dynamically 110 linking to within the rest of the process. */ 111typedef struct gcc_jit_function gcc_jit_function; 112 113/* A gcc_jit_block encapsulates a "basic block" of statements within a 114 function (i.e. with one entry point and one exit point). 115 116 Every block within a function must be terminated with a conditional, 117 a branch, or a return. 118 119 The blocks within a function form a directed graph. 120 121 The entrypoint to the function is the first block created within 122 it. 123 124 All of the blocks in a function must be reachable via some path from 125 the first block. 126 127 It's OK to have more than one "return" from a function (i.e. multiple 128 blocks that terminate by returning). */ 129typedef struct gcc_jit_block gcc_jit_block; 130 131/* A gcc_jit_rvalue is an expression within your code, with some type. */ 132typedef struct gcc_jit_rvalue gcc_jit_rvalue; 133 134/* A gcc_jit_lvalue is a storage location within your code (e.g. a 135 variable, a parameter, etc). It is also a gcc_jit_rvalue; use 136 gcc_jit_lvalue_as_rvalue to cast. */ 137typedef struct gcc_jit_lvalue gcc_jit_lvalue; 138 139/* A gcc_jit_param is a function parameter, used when creating a 140 gcc_jit_function. It is also a gcc_jit_lvalue (and thus also an 141 rvalue); use gcc_jit_param_as_lvalue to convert. */ 142typedef struct gcc_jit_param gcc_jit_param; 143 144/* A gcc_jit_case is for use when building multiway branches via 145 gcc_jit_block_end_with_switch and represents a range of integer 146 values (or an individual integer value) together with an associated 147 destination block. */ 148typedef struct gcc_jit_case gcc_jit_case; 149 150/* A gcc_jit_extended_asm represents an assembly language statement, 151 analogous to an extended "asm" statement in GCC's C front-end: a series 152 of low-level instructions inside a function that convert inputs to 153 outputs. */ 154typedef struct gcc_jit_extended_asm gcc_jit_extended_asm; 155 156/* Acquire a JIT-compilation context. */ 157extern gcc_jit_context * 158gcc_jit_context_acquire (void); 159 160/* Release the context. After this call, it's no longer valid to use 161 the ctxt. */ 162extern void 163gcc_jit_context_release (gcc_jit_context *ctxt); 164 165/* Options present in the initial release of libgccjit. 166 These were handled using enums. */ 167 168/* Options taking string values. */ 169enum gcc_jit_str_option 170{ 171 /* The name of the program, for use as a prefix when printing error 172 messages to stderr. If NULL, or default, "libgccjit.so" is used. */ 173 GCC_JIT_STR_OPTION_PROGNAME, 174 175 GCC_JIT_NUM_STR_OPTIONS 176}; 177 178/* Options taking int values. */ 179enum gcc_jit_int_option 180{ 181 /* How much to optimize the code. 182 Valid values are 0-3, corresponding to GCC's command-line options 183 -O0 through -O3. 184 185 The default value is 0 (unoptimized). */ 186 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 187 188 GCC_JIT_NUM_INT_OPTIONS 189}; 190 191/* Options taking boolean values. 192 These all default to "false". */ 193enum gcc_jit_bool_option 194{ 195 /* If true, gcc_jit_context_compile will attempt to do the right 196 thing so that if you attach a debugger to the process, it will 197 be able to inspect variables and step through your code. 198 199 Note that you can't step through code unless you set up source 200 location information for the code (by creating and passing in 201 gcc_jit_location instances). */ 202 GCC_JIT_BOOL_OPTION_DEBUGINFO, 203 204 /* If true, gcc_jit_context_compile will dump its initial "tree" 205 representation of your code to stderr (before any 206 optimizations). */ 207 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE, 208 209 /* If true, gcc_jit_context_compile will dump the "gimple" 210 representation of your code to stderr, before any optimizations 211 are performed. The dump resembles C code. */ 212 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 213 214 /* If true, gcc_jit_context_compile will dump the final 215 generated code to stderr, in the form of assembly language. */ 216 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 217 218 /* If true, gcc_jit_context_compile will print information to stderr 219 on the actions it is performing, followed by a profile showing 220 the time taken and memory usage of each phase. 221 */ 222 GCC_JIT_BOOL_OPTION_DUMP_SUMMARY, 223 224 /* If true, gcc_jit_context_compile will dump copious 225 amount of information on what it's doing to various 226 files within a temporary directory. Use 227 GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES (see below) to 228 see the results. The files are intended to be human-readable, 229 but the exact files and their formats are subject to change. 230 */ 231 GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING, 232 233 /* If true, libgccjit will aggressively run its garbage collector, to 234 shake out bugs (greatly slowing down the compile). This is likely 235 to only be of interest to developers *of* the library. It is 236 used when running the selftest suite. */ 237 GCC_JIT_BOOL_OPTION_SELFCHECK_GC, 238 239 /* If true, gcc_jit_context_release will not clean up 240 intermediate files written to the filesystem, and will display 241 their location on stderr. */ 242 GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES, 243 244 GCC_JIT_NUM_BOOL_OPTIONS 245}; 246 247/* Set a string option on the given context. 248 249 The context takes a copy of the string, so the 250 (const char *) buffer is not needed anymore after the call 251 returns. */ 252extern void 253gcc_jit_context_set_str_option (gcc_jit_context *ctxt, 254 enum gcc_jit_str_option opt, 255 const char *value); 256 257/* Set an int option on the given context. */ 258extern void 259gcc_jit_context_set_int_option (gcc_jit_context *ctxt, 260 enum gcc_jit_int_option opt, 261 int value); 262 263/* Set a boolean option on the given context. 264 265 Zero is "false" (the default), non-zero is "true". */ 266extern void 267gcc_jit_context_set_bool_option (gcc_jit_context *ctxt, 268 enum gcc_jit_bool_option opt, 269 int value); 270 271/* Options added after the initial release of libgccjit. 272 These are handled by providing an entrypoint per option, 273 rather than by extending the enum gcc_jit_*_option, 274 so that client code that use these new options can be identified 275 from binary metadata. */ 276 277/* By default, libgccjit will issue an error about unreachable blocks 278 within a function. 279 280 This option can be used to disable that error. 281 282 This entrypoint was added in LIBGCCJIT_ABI_2; you can test for 283 its presence using 284 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks 285*/ 286 287extern void 288gcc_jit_context_set_bool_allow_unreachable_blocks (gcc_jit_context *ctxt, 289 int bool_value); 290 291/* Pre-canned feature macro to indicate the presence of 292 gcc_jit_context_set_bool_allow_unreachable_blocks. This can be 293 tested for with #ifdef. */ 294#define LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks 295 296/* By default, libgccjit will print errors to stderr. 297 298 This option can be used to disable the printing. 299 300 This entrypoint was added in LIBGCCJIT_ABI_23; you can test for 301 its presence using 302 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_print_errors_to_stderr 303*/ 304 305extern void 306gcc_jit_context_set_bool_print_errors_to_stderr (gcc_jit_context *ctxt, 307 int enabled); 308 309/* Pre-canned feature macro to indicate the presence of 310 gcc_jit_context_set_bool_print_errors_to_stderr. This can be 311 tested for with #ifdef. */ 312#define LIBGCCJIT_HAVE_gcc_jit_context_set_bool_print_errors_to_stderr 313 314/* Implementation detail: 315 libgccjit internally generates assembler, and uses "driver" code 316 for converting it to other formats (e.g. shared libraries). 317 318 By default, libgccjit will use an embedded copy of the driver 319 code. 320 321 This option can be used to instead invoke an external driver executable 322 as a subprocess. 323 324 This entrypoint was added in LIBGCCJIT_ABI_5; you can test for 325 its presence using 326 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver 327*/ 328 329extern void 330gcc_jit_context_set_bool_use_external_driver (gcc_jit_context *ctxt, 331 int bool_value); 332 333/* Pre-canned feature macro to indicate the presence of 334 gcc_jit_context_set_bool_use_external_driver. This can be 335 tested for with #ifdef. */ 336#define LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver 337 338/* Add an arbitrary gcc command-line option to the context. 339 The context takes a copy of the string, so the 340 (const char *) optname is not needed anymore after the call 341 returns. 342 343 Note that only some options are likely to be meaningful; there is no 344 "frontend" within libgccjit, so typically only those affecting 345 optimization and code-generation are likely to be useful. 346 347 This entrypoint was added in LIBGCCJIT_ABI_1; you can test for 348 its presence using 349 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option 350*/ 351 352extern void 353gcc_jit_context_add_command_line_option (gcc_jit_context *ctxt, 354 const char *optname); 355 356/* Pre-canned feature-test macro for detecting the presence of 357 gcc_jit_context_add_command_line_option within libgccjit.h. */ 358 359#define LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option 360 361/* Add an arbitrary gcc driver option to the context. 362 The context takes a copy of the string, so the 363 (const char *) optname is not needed anymore after the call 364 returns. 365 366 Note that only some options are likely to be meaningful; there is no 367 "frontend" within libgccjit, so typically only those affecting 368 assembler and linker are likely to be useful. 369 370 This entrypoint was added in LIBGCCJIT_ABI_11; you can test for 371 its presence using 372 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_driver_option 373*/ 374extern void 375gcc_jit_context_add_driver_option (gcc_jit_context *ctxt, 376 const char *optname); 377 378/* Pre-canned feature-test macro for detecting the presence of 379 gcc_jit_context_add_driver_option within libgccjit.h. */ 380 381#define LIBGCCJIT_HAVE_gcc_jit_context_add_driver_option 382 383/* Compile the context to in-memory machine code. 384 385 This can be called more that once on a given context, 386 although any errors that occur will block further compilation. */ 387 388extern gcc_jit_result * 389gcc_jit_context_compile (gcc_jit_context *ctxt); 390 391/* Kinds of ahead-of-time compilation, for use with 392 gcc_jit_context_compile_to_file. */ 393 394enum gcc_jit_output_kind 395{ 396 /* Compile the context to an assembler file. */ 397 GCC_JIT_OUTPUT_KIND_ASSEMBLER, 398 399 /* Compile the context to an object file. */ 400 GCC_JIT_OUTPUT_KIND_OBJECT_FILE, 401 402 /* Compile the context to a dynamic library. */ 403 GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY, 404 405 /* Compile the context to an executable. */ 406 GCC_JIT_OUTPUT_KIND_EXECUTABLE 407}; 408 409/* Compile the context to a file of the given kind. 410 411 This can be called more that once on a given context, 412 although any errors that occur will block further compilation. */ 413 414extern void 415gcc_jit_context_compile_to_file (gcc_jit_context *ctxt, 416 enum gcc_jit_output_kind output_kind, 417 const char *output_path); 418 419/* To help with debugging: dump a C-like representation to the given path, 420 describing what's been set up on the context. 421 422 If "update_locations" is true, then also set up gcc_jit_location 423 information throughout the context, pointing at the dump file as if it 424 were a source file. This may be of use in conjunction with 425 GCC_JIT_BOOL_OPTION_DEBUGINFO to allow stepping through the code in a 426 debugger. */ 427extern void 428gcc_jit_context_dump_to_file (gcc_jit_context *ctxt, 429 const char *path, 430 int update_locations); 431 432/* To help with debugging; enable ongoing logging of the context's 433 activity to the given FILE *. 434 435 The caller remains responsible for closing "logfile". 436 437 Params "flags" and "verbosity" are reserved for future use, and 438 must both be 0 for now. */ 439extern void 440gcc_jit_context_set_logfile (gcc_jit_context *ctxt, 441 FILE *logfile, 442 int flags, 443 int verbosity); 444 445/* To be called after any API call, this gives the first error message 446 that occurred on the context. 447 448 The returned string is valid for the rest of the lifetime of the 449 context. 450 451 If no errors occurred, this will be NULL. */ 452extern const char * 453gcc_jit_context_get_first_error (gcc_jit_context *ctxt); 454 455/* To be called after any API call, this gives the last error message 456 that occurred on the context. 457 458 If no errors occurred, this will be NULL. 459 460 If non-NULL, the returned string is only guaranteed to be valid until 461 the next call to libgccjit relating to this context. */ 462extern const char * 463gcc_jit_context_get_last_error (gcc_jit_context *ctxt); 464 465/* Locate a given function within the built machine code. 466 This will need to be cast to a function pointer of the 467 correct type before it can be called. */ 468extern void * 469gcc_jit_result_get_code (gcc_jit_result *result, 470 const char *funcname); 471 472/* Locate a given global within the built machine code. 473 It must have been created using GCC_JIT_GLOBAL_EXPORTED. 474 This is a ptr to the global, so e.g. for an int this is an int *. */ 475extern void * 476gcc_jit_result_get_global (gcc_jit_result *result, 477 const char *name); 478 479/* Once we're done with the code, this unloads the built .so file. 480 This cleans up the result; after calling this, it's no longer 481 valid to use the result. */ 482extern void 483gcc_jit_result_release (gcc_jit_result *result); 484 485 486/********************************************************************** 487 Functions for creating "contextual" objects. 488 489 All objects created by these functions share the lifetime of the context 490 they are created within, and are automatically cleaned up for you when 491 you call gcc_jit_context_release on the context. 492 493 Note that this means you can't use references to them after you've 494 released their context. 495 496 All (const char *) string arguments passed to these functions are 497 copied, so you don't need to keep them around. 498 499 You create code by adding a sequence of statements to blocks. 500**********************************************************************/ 501 502/********************************************************************** 503 The base class of "contextual" object. 504 **********************************************************************/ 505/* Which context is "obj" within? */ 506extern gcc_jit_context * 507gcc_jit_object_get_context (gcc_jit_object *obj); 508 509/* Get a human-readable description of this object. 510 The string buffer is created the first time this is called on a given 511 object, and persists until the object's context is released. */ 512extern const char * 513gcc_jit_object_get_debug_string (gcc_jit_object *obj); 514 515/********************************************************************** 516 Debugging information. 517 **********************************************************************/ 518 519/* Creating source code locations for use by the debugger. 520 Line and column numbers are 1-based. */ 521extern gcc_jit_location * 522gcc_jit_context_new_location (gcc_jit_context *ctxt, 523 const char *filename, 524 int line, 525 int column); 526 527/* Upcasting from location to object. */ 528extern gcc_jit_object * 529gcc_jit_location_as_object (gcc_jit_location *loc); 530 531 532/********************************************************************** 533 Types. 534 **********************************************************************/ 535 536/* Upcasting from type to object. */ 537extern gcc_jit_object * 538gcc_jit_type_as_object (gcc_jit_type *type); 539 540/* Access to specific types. */ 541enum gcc_jit_types 542{ 543 /* C's "void" type. */ 544 GCC_JIT_TYPE_VOID, 545 546 /* "void *". */ 547 GCC_JIT_TYPE_VOID_PTR, 548 549 /* C++'s bool type; also C99's "_Bool" type, aka "bool" if using 550 stdbool.h. */ 551 GCC_JIT_TYPE_BOOL, 552 553 /* Various integer types. */ 554 555 /* C's "char" (of some signedness) and the variants where the 556 signedness is specified. */ 557 GCC_JIT_TYPE_CHAR, 558 GCC_JIT_TYPE_SIGNED_CHAR, 559 GCC_JIT_TYPE_UNSIGNED_CHAR, 560 561 /* C's "short" and "unsigned short". */ 562 GCC_JIT_TYPE_SHORT, /* signed */ 563 GCC_JIT_TYPE_UNSIGNED_SHORT, 564 565 /* C's "int" and "unsigned int". */ 566 GCC_JIT_TYPE_INT, /* signed */ 567 GCC_JIT_TYPE_UNSIGNED_INT, 568 569 /* C's "long" and "unsigned long". */ 570 GCC_JIT_TYPE_LONG, /* signed */ 571 GCC_JIT_TYPE_UNSIGNED_LONG, 572 573 /* C99's "long long" and "unsigned long long". */ 574 GCC_JIT_TYPE_LONG_LONG, /* signed */ 575 GCC_JIT_TYPE_UNSIGNED_LONG_LONG, 576 577 /* Floating-point types */ 578 579 GCC_JIT_TYPE_FLOAT, 580 GCC_JIT_TYPE_DOUBLE, 581 GCC_JIT_TYPE_LONG_DOUBLE, 582 583 /* C type: (const char *). */ 584 GCC_JIT_TYPE_CONST_CHAR_PTR, 585 586 /* The C "size_t" type. */ 587 GCC_JIT_TYPE_SIZE_T, 588 589 /* C type: (FILE *) */ 590 GCC_JIT_TYPE_FILE_PTR, 591 592 /* Complex numbers. */ 593 GCC_JIT_TYPE_COMPLEX_FLOAT, 594 GCC_JIT_TYPE_COMPLEX_DOUBLE, 595 GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE, 596 597 /* Sized integer types. */ 598 GCC_JIT_TYPE_UINT8_T, 599 GCC_JIT_TYPE_UINT16_T, 600 GCC_JIT_TYPE_UINT32_T, 601 GCC_JIT_TYPE_UINT64_T, 602 GCC_JIT_TYPE_UINT128_T, 603 GCC_JIT_TYPE_INT8_T, 604 GCC_JIT_TYPE_INT16_T, 605 GCC_JIT_TYPE_INT32_T, 606 GCC_JIT_TYPE_INT64_T, 607 GCC_JIT_TYPE_INT128_T 608}; 609 610extern gcc_jit_type * 611gcc_jit_context_get_type (gcc_jit_context *ctxt, 612 enum gcc_jit_types type_); 613 614/* Get the integer type of the given size and signedness. */ 615extern gcc_jit_type * 616gcc_jit_context_get_int_type (gcc_jit_context *ctxt, 617 int num_bytes, int is_signed); 618 619/* Constructing new types. */ 620 621/* Given type "T", get type "T*". */ 622extern gcc_jit_type * 623gcc_jit_type_get_pointer (gcc_jit_type *type); 624 625/* Given type "T", get type "const T". */ 626extern gcc_jit_type * 627gcc_jit_type_get_const (gcc_jit_type *type); 628 629/* Given type "T", get type "volatile T". */ 630extern gcc_jit_type * 631gcc_jit_type_get_volatile (gcc_jit_type *type); 632 633#define LIBGCCJIT_HAVE_SIZED_INTEGERS 634 635/* Given types LTYPE and RTYPE, return non-zero if they are compatible. 636 This API entrypoint was added in LIBGCCJIT_ABI_20; you can test for its 637 presence using 638 #ifdef LIBGCCJIT_HAVE_SIZED_INTEGERS */ 639extern int 640gcc_jit_compatible_types (gcc_jit_type *ltype, 641 gcc_jit_type *rtype); 642 643/* Given type "T", get its size. 644 This API entrypoint was added in LIBGCCJIT_ABI_20; you can test for its 645 presence using 646 #ifdef LIBGCCJIT_HAVE_SIZED_INTEGERS */ 647extern ssize_t 648gcc_jit_type_get_size (gcc_jit_type *type); 649 650/* Given type "T", get type "T[N]" (for a constant N). */ 651extern gcc_jit_type * 652gcc_jit_context_new_array_type (gcc_jit_context *ctxt, 653 gcc_jit_location *loc, 654 gcc_jit_type *element_type, 655 int num_elements); 656 657/* Struct-handling. */ 658 659/* Create a field, for use within a struct or union. */ 660extern gcc_jit_field * 661gcc_jit_context_new_field (gcc_jit_context *ctxt, 662 gcc_jit_location *loc, 663 gcc_jit_type *type, 664 const char *name); 665 666#define LIBGCCJIT_HAVE_gcc_jit_context_new_bitfield 667 668/* Create a bit field, for use within a struct or union. 669 670 This API entrypoint was added in LIBGCCJIT_ABI_12; you can test for its 671 presence using 672 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitfield 673*/ 674extern gcc_jit_field * 675gcc_jit_context_new_bitfield (gcc_jit_context *ctxt, 676 gcc_jit_location *loc, 677 gcc_jit_type *type, 678 int width, 679 const char *name); 680 681/* Upcasting from field to object. */ 682extern gcc_jit_object * 683gcc_jit_field_as_object (gcc_jit_field *field); 684 685/* Create a struct type from an array of fields. */ 686extern gcc_jit_struct * 687gcc_jit_context_new_struct_type (gcc_jit_context *ctxt, 688 gcc_jit_location *loc, 689 const char *name, 690 int num_fields, 691 gcc_jit_field **fields); 692 693/* Create an opaque struct type. */ 694extern gcc_jit_struct * 695gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt, 696 gcc_jit_location *loc, 697 const char *name); 698 699/* Upcast a struct to a type. */ 700extern gcc_jit_type * 701gcc_jit_struct_as_type (gcc_jit_struct *struct_type); 702 703/* Populating the fields of a formerly-opaque struct type. 704 This can only be called once on a given struct type. */ 705extern void 706gcc_jit_struct_set_fields (gcc_jit_struct *struct_type, 707 gcc_jit_location *loc, 708 int num_fields, 709 gcc_jit_field **fields); 710 711/* Get a field by index. */ 712extern gcc_jit_field * 713gcc_jit_struct_get_field (gcc_jit_struct *struct_type, 714 size_t index); 715 716/* Get the number of fields. */ 717extern size_t 718gcc_jit_struct_get_field_count (gcc_jit_struct *struct_type); 719 720/* Unions work similarly to structs. */ 721extern gcc_jit_type * 722gcc_jit_context_new_union_type (gcc_jit_context *ctxt, 723 gcc_jit_location *loc, 724 const char *name, 725 int num_fields, 726 gcc_jit_field **fields); 727 728/* Function pointers. */ 729 730extern gcc_jit_type * 731gcc_jit_context_new_function_ptr_type (gcc_jit_context *ctxt, 732 gcc_jit_location *loc, 733 gcc_jit_type *return_type, 734 int num_params, 735 gcc_jit_type **param_types, 736 int is_variadic); 737 738/********************************************************************** 739 Constructing functions. 740 **********************************************************************/ 741/* Create a function param. */ 742extern gcc_jit_param * 743gcc_jit_context_new_param (gcc_jit_context *ctxt, 744 gcc_jit_location *loc, 745 gcc_jit_type *type, 746 const char *name); 747 748/* Upcasting from param to object. */ 749extern gcc_jit_object * 750gcc_jit_param_as_object (gcc_jit_param *param); 751 752/* Upcasting from param to lvalue. */ 753extern gcc_jit_lvalue * 754gcc_jit_param_as_lvalue (gcc_jit_param *param); 755 756/* Upcasting from param to rvalue. */ 757extern gcc_jit_rvalue * 758gcc_jit_param_as_rvalue (gcc_jit_param *param); 759 760/* Kinds of function. */ 761enum gcc_jit_function_kind 762{ 763 /* Function is defined by the client code and visible 764 by name outside of the JIT. */ 765 GCC_JIT_FUNCTION_EXPORTED, 766 767 /* Function is defined by the client code, but is invisible 768 outside of the JIT. Analogous to a "static" function. */ 769 GCC_JIT_FUNCTION_INTERNAL, 770 771 /* Function is not defined by the client code; we're merely 772 referring to it. Analogous to using an "extern" function from a 773 header file. */ 774 GCC_JIT_FUNCTION_IMPORTED, 775 776 /* Function is only ever inlined into other functions, and is 777 invisible outside of the JIT. 778 779 Analogous to prefixing with "inline" and adding 780 __attribute__((always_inline)). 781 782 Inlining will only occur when the optimization level is 783 above 0; when optimization is off, this is essentially the 784 same as GCC_JIT_FUNCTION_INTERNAL. */ 785 GCC_JIT_FUNCTION_ALWAYS_INLINE 786}; 787 788/* Thread local storage model. */ 789enum gcc_jit_tls_model 790{ 791 GCC_JIT_TLS_MODEL_NONE, 792 GCC_JIT_TLS_MODEL_GLOBAL_DYNAMIC, 793 GCC_JIT_TLS_MODEL_LOCAL_DYNAMIC, 794 GCC_JIT_TLS_MODEL_INITIAL_EXEC, 795 GCC_JIT_TLS_MODEL_LOCAL_EXEC, 796}; 797 798/* Create a function. */ 799extern gcc_jit_function * 800gcc_jit_context_new_function (gcc_jit_context *ctxt, 801 gcc_jit_location *loc, 802 enum gcc_jit_function_kind kind, 803 gcc_jit_type *return_type, 804 const char *name, 805 int num_params, 806 gcc_jit_param **params, 807 int is_variadic); 808 809/* Create a reference to a builtin function (sometimes called 810 intrinsic functions). */ 811extern gcc_jit_function * 812gcc_jit_context_get_builtin_function (gcc_jit_context *ctxt, 813 const char *name); 814 815/* Upcasting from function to object. */ 816extern gcc_jit_object * 817gcc_jit_function_as_object (gcc_jit_function *func); 818 819/* Get a specific param of a function by index. */ 820extern gcc_jit_param * 821gcc_jit_function_get_param (gcc_jit_function *func, int index); 822 823/* Emit the function in graphviz format. */ 824extern void 825gcc_jit_function_dump_to_dot (gcc_jit_function *func, 826 const char *path); 827 828/* Create a block. 829 830 The name can be NULL, or you can give it a meaningful name, which 831 may show up in dumps of the internal representation, and in error 832 messages. */ 833extern gcc_jit_block * 834gcc_jit_function_new_block (gcc_jit_function *func, 835 const char *name); 836 837/* Upcasting from block to object. */ 838extern gcc_jit_object * 839gcc_jit_block_as_object (gcc_jit_block *block); 840 841/* Which function is this block within? */ 842extern gcc_jit_function * 843gcc_jit_block_get_function (gcc_jit_block *block); 844 845/********************************************************************** 846 lvalues, rvalues and expressions. 847 **********************************************************************/ 848enum gcc_jit_global_kind 849{ 850 /* Global is defined by the client code and visible 851 by name outside of this JIT context via gcc_jit_result_get_global. */ 852 GCC_JIT_GLOBAL_EXPORTED, 853 854 /* Global is defined by the client code, but is invisible 855 outside of this JIT context. Analogous to a "static" global. */ 856 GCC_JIT_GLOBAL_INTERNAL, 857 858 /* Global is not defined by the client code; we're merely 859 referring to it. Analogous to using an "extern" global from a 860 header file. */ 861 GCC_JIT_GLOBAL_IMPORTED 862}; 863 864extern gcc_jit_lvalue * 865gcc_jit_context_new_global (gcc_jit_context *ctxt, 866 gcc_jit_location *loc, 867 enum gcc_jit_global_kind kind, 868 gcc_jit_type *type, 869 const char *name); 870 871#define LIBGCCJIT_HAVE_CTORS 872 873/* Create a constructor for a struct as an rvalue. 874 875 Returns NULL on error. The two parameter arrays are copied and 876 do not have to outlive the context. 877 878 `type` specifies what the constructor will build and has to be 879 a struct. 880 881 `num_values` specifies the number of elements in `values`. 882 883 `fields` need to have the same length as `values`, or be NULL. 884 885 If `fields` is null, the values are applied in definition order. 886 887 Otherwise, each field in `fields` specifies which field in the struct to 888 set to the corresponding value in `values`. `fields` and `values` 889 are paired by index. 890 891 Each value has to have the same unqualified type as the field 892 it is applied to. 893 894 A NULL value element in `values` is a shorthand for zero initialization 895 of the corresponding field. 896 897 The fields in `fields` have to be in definition order, but there 898 can be gaps. Any field in the struct that is not specified in 899 `fields` will be zeroed. 900 901 The fields in `fields` need to be the same objects that were used 902 to create the struct. 903 904 If `num_values` is 0, the array parameters will be 905 ignored and zero initialization will be used. 906 907 The constructor rvalue can be used for assignment to locals. 908 It can be used to initialize global variables with 909 gcc_jit_global_set_initializer_rvalue. It can also be used as a 910 temporary value for function calls and return values. 911 912 The constructor can contain nested constructors. 913 914 This entrypoint was added in LIBGCCJIT_ABI_19; you can test for its 915 presence using: 916 #ifdef LIBGCCJIT_HAVE_CTORS 917*/ 918 919extern gcc_jit_rvalue * 920gcc_jit_context_new_struct_constructor (gcc_jit_context *ctxt, 921 gcc_jit_location *loc, 922 gcc_jit_type *type, 923 size_t num_values, 924 gcc_jit_field **fields, 925 gcc_jit_rvalue **values); 926 927/* Create a constructor for a union as an rvalue. 928 929 Returns NULL on error. 930 931 `type` specifies what the constructor will build and has to be 932 an union. 933 934 `field` specifies which field to set. If it is NULL, the first 935 field in the union will be set. `field` need to be the same 936 object that were used to create the union. 937 938 `value` specifies what value to set the corresponding field to. 939 If `value` is NULL, zero initialization will be used. 940 941 Each value has to have the same unqualified type as the field 942 it is applied to. 943 944 `field` need to be the same objects that were used 945 to create the union. 946 947 The constructor rvalue can be used for assignment to locals. 948 It can be used to initialize global variables with 949 gcc_jit_global_set_initializer_rvalue. It can also be used as a 950 temporary value for function calls and return values. 951 952 The constructor can contain nested constructors. 953 954 This entrypoint was added in LIBGCCJIT_ABI_19; you can test for its 955 presence using: 956 #ifdef LIBGCCJIT_HAVE_CTORS 957*/ 958 959extern gcc_jit_rvalue * 960gcc_jit_context_new_union_constructor (gcc_jit_context *ctxt, 961 gcc_jit_location *loc, 962 gcc_jit_type *type, 963 gcc_jit_field *field, 964 gcc_jit_rvalue *value); 965 966/* Create a constructor for an array as an rvalue. 967 968 Returns NULL on error. `values` are copied and 969 do not have to outlive the context. 970 971 `type` specifies what the constructor will build and has to be 972 an array. 973 974 `num_values` specifies the number of elements in `values` and 975 it can't have more elements than the array type. 976 977 Each value in `values` sets the corresponding value in the array. 978 If the array type itself has more elements than `values`, the 979 left-over elements will be zeroed. 980 981 Each value in `values` need to be the same unqualified type as the 982 array type's element type. 983 984 If `num_values` is 0, the `values` parameter will be 985 ignored and zero initialization will be used. 986 987 Note that a string literal rvalue can't be used to construct a char 988 array. It needs one rvalue for each char. 989 990 This entrypoint was added in LIBGCCJIT_ABI_19; you can test for its 991 presence using: 992 #ifdef LIBGCCJIT_HAVE_CTORS 993*/ 994 995extern gcc_jit_rvalue * 996gcc_jit_context_new_array_constructor (gcc_jit_context *ctxt, 997 gcc_jit_location *loc, 998 gcc_jit_type *type, 999 size_t num_values, 1000 gcc_jit_rvalue **values); 1001 1002/* Set the initial value of a global of any type with an rvalue. 1003 1004 The rvalue needs to be a constant expression, e.g. no function calls. 1005 1006 The global can't have the 'kind' GCC_JIT_GLOBAL_IMPORTED. 1007 1008 Use together with gcc_jit_context_new_constructor () to 1009 initialize structs, unions and arrays. 1010 1011 On success, returns the 'global' parameter unchanged. Otherwise, NULL. 1012 1013 'values' is copied and does not have to outlive the context. 1014 1015 This entrypoint was added in LIBGCCJIT_ABI_19; you can test for its 1016 presence using: 1017 #ifdef LIBGCCJIT_HAVE_CTORS 1018*/ 1019 1020extern gcc_jit_lvalue * 1021gcc_jit_global_set_initializer_rvalue (gcc_jit_lvalue *global, 1022 gcc_jit_rvalue *init_value); 1023 1024#define LIBGCCJIT_HAVE_gcc_jit_global_set_initializer 1025 1026/* Set an initial value for a global, which must be an array of 1027 integral type. Return the global itself. 1028 1029 This API entrypoint was added in LIBGCCJIT_ABI_14; you can test for its 1030 presence using 1031 #ifdef LIBGCCJIT_HAVE_gcc_jit_global_set_initializer 1032*/ 1033 1034extern gcc_jit_lvalue * 1035gcc_jit_global_set_initializer (gcc_jit_lvalue *global, 1036 const void *blob, 1037 size_t num_bytes); 1038 1039/* Upcasting. */ 1040extern gcc_jit_object * 1041gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue); 1042 1043extern gcc_jit_rvalue * 1044gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue); 1045 1046extern gcc_jit_object * 1047gcc_jit_rvalue_as_object (gcc_jit_rvalue *rvalue); 1048 1049extern gcc_jit_type * 1050gcc_jit_rvalue_get_type (gcc_jit_rvalue *rvalue); 1051 1052/* Integer constants. */ 1053extern gcc_jit_rvalue * 1054gcc_jit_context_new_rvalue_from_int (gcc_jit_context *ctxt, 1055 gcc_jit_type *numeric_type, 1056 int value); 1057 1058extern gcc_jit_rvalue * 1059gcc_jit_context_new_rvalue_from_long (gcc_jit_context *ctxt, 1060 gcc_jit_type *numeric_type, 1061 long value); 1062 1063extern gcc_jit_rvalue * 1064gcc_jit_context_zero (gcc_jit_context *ctxt, 1065 gcc_jit_type *numeric_type); 1066 1067extern gcc_jit_rvalue * 1068gcc_jit_context_one (gcc_jit_context *ctxt, 1069 gcc_jit_type *numeric_type); 1070 1071/* Floating-point constants. */ 1072extern gcc_jit_rvalue * 1073gcc_jit_context_new_rvalue_from_double (gcc_jit_context *ctxt, 1074 gcc_jit_type *numeric_type, 1075 double value); 1076 1077/* Pointers. */ 1078extern gcc_jit_rvalue * 1079gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt, 1080 gcc_jit_type *pointer_type, 1081 void *value); 1082 1083extern gcc_jit_rvalue * 1084gcc_jit_context_null (gcc_jit_context *ctxt, 1085 gcc_jit_type *pointer_type); 1086 1087/* String literals. */ 1088extern gcc_jit_rvalue * 1089gcc_jit_context_new_string_literal (gcc_jit_context *ctxt, 1090 const char *value); 1091 1092enum gcc_jit_unary_op 1093{ 1094 /* Negate an arithmetic value; analogous to: 1095 -(EXPR) 1096 in C. */ 1097 GCC_JIT_UNARY_OP_MINUS, 1098 1099 /* Bitwise negation of an integer value (one's complement); analogous 1100 to: 1101 ~(EXPR) 1102 in C. */ 1103 GCC_JIT_UNARY_OP_BITWISE_NEGATE, 1104 1105 /* Logical negation of an arithmetic or pointer value; analogous to: 1106 !(EXPR) 1107 in C. */ 1108 GCC_JIT_UNARY_OP_LOGICAL_NEGATE, 1109 1110 /* Absolute value of an arithmetic expression; analogous to: 1111 abs (EXPR) 1112 in C. */ 1113 GCC_JIT_UNARY_OP_ABS 1114 1115}; 1116 1117extern gcc_jit_rvalue * 1118gcc_jit_context_new_unary_op (gcc_jit_context *ctxt, 1119 gcc_jit_location *loc, 1120 enum gcc_jit_unary_op op, 1121 gcc_jit_type *result_type, 1122 gcc_jit_rvalue *rvalue); 1123 1124enum gcc_jit_binary_op 1125{ 1126 /* Addition of arithmetic values; analogous to: 1127 (EXPR_A) + (EXPR_B) 1128 in C. 1129 For pointer addition, use gcc_jit_context_new_array_access. */ 1130 GCC_JIT_BINARY_OP_PLUS, 1131 1132 /* Subtraction of arithmetic values; analogous to: 1133 (EXPR_A) - (EXPR_B) 1134 in C. */ 1135 GCC_JIT_BINARY_OP_MINUS, 1136 1137 /* Multiplication of a pair of arithmetic values; analogous to: 1138 (EXPR_A) * (EXPR_B) 1139 in C. */ 1140 GCC_JIT_BINARY_OP_MULT, 1141 1142 /* Quotient of division of arithmetic values; analogous to: 1143 (EXPR_A) / (EXPR_B) 1144 in C. 1145 The result type affects the kind of division: if the result type is 1146 integer-based, then the result is truncated towards zero, whereas 1147 a floating-point result type indicates floating-point division. */ 1148 GCC_JIT_BINARY_OP_DIVIDE, 1149 1150 /* Remainder of division of arithmetic values; analogous to: 1151 (EXPR_A) % (EXPR_B) 1152 in C. */ 1153 GCC_JIT_BINARY_OP_MODULO, 1154 1155 /* Bitwise AND; analogous to: 1156 (EXPR_A) & (EXPR_B) 1157 in C. */ 1158 GCC_JIT_BINARY_OP_BITWISE_AND, 1159 1160 /* Bitwise exclusive OR; analogous to: 1161 (EXPR_A) ^ (EXPR_B) 1162 in C. */ 1163 GCC_JIT_BINARY_OP_BITWISE_XOR, 1164 1165 /* Bitwise inclusive OR; analogous to: 1166 (EXPR_A) | (EXPR_B) 1167 in C. */ 1168 GCC_JIT_BINARY_OP_BITWISE_OR, 1169 1170 /* Logical AND; analogous to: 1171 (EXPR_A) && (EXPR_B) 1172 in C. */ 1173 GCC_JIT_BINARY_OP_LOGICAL_AND, 1174 1175 /* Logical OR; analogous to: 1176 (EXPR_A) || (EXPR_B) 1177 in C. */ 1178 GCC_JIT_BINARY_OP_LOGICAL_OR, 1179 1180 /* Left shift; analogous to: 1181 (EXPR_A) << (EXPR_B) 1182 in C. */ 1183 GCC_JIT_BINARY_OP_LSHIFT, 1184 1185 /* Right shift; analogous to: 1186 (EXPR_A) >> (EXPR_B) 1187 in C. */ 1188 GCC_JIT_BINARY_OP_RSHIFT 1189}; 1190 1191extern gcc_jit_rvalue * 1192gcc_jit_context_new_binary_op (gcc_jit_context *ctxt, 1193 gcc_jit_location *loc, 1194 enum gcc_jit_binary_op op, 1195 gcc_jit_type *result_type, 1196 gcc_jit_rvalue *a, gcc_jit_rvalue *b); 1197 1198/* (Comparisons are treated as separate from "binary_op" to save 1199 you having to specify the result_type). */ 1200 1201enum gcc_jit_comparison 1202{ 1203 /* (EXPR_A) == (EXPR_B). */ 1204 GCC_JIT_COMPARISON_EQ, 1205 1206 /* (EXPR_A) != (EXPR_B). */ 1207 GCC_JIT_COMPARISON_NE, 1208 1209 /* (EXPR_A) < (EXPR_B). */ 1210 GCC_JIT_COMPARISON_LT, 1211 1212 /* (EXPR_A) <=(EXPR_B). */ 1213 GCC_JIT_COMPARISON_LE, 1214 1215 /* (EXPR_A) > (EXPR_B). */ 1216 GCC_JIT_COMPARISON_GT, 1217 1218 /* (EXPR_A) >= (EXPR_B). */ 1219 GCC_JIT_COMPARISON_GE 1220}; 1221 1222extern gcc_jit_rvalue * 1223gcc_jit_context_new_comparison (gcc_jit_context *ctxt, 1224 gcc_jit_location *loc, 1225 enum gcc_jit_comparison op, 1226 gcc_jit_rvalue *a, gcc_jit_rvalue *b); 1227 1228/* Function calls. */ 1229 1230/* Call of a specific function. */ 1231extern gcc_jit_rvalue * 1232gcc_jit_context_new_call (gcc_jit_context *ctxt, 1233 gcc_jit_location *loc, 1234 gcc_jit_function *func, 1235 int numargs , gcc_jit_rvalue **args); 1236 1237/* Call through a function pointer. */ 1238extern gcc_jit_rvalue * 1239gcc_jit_context_new_call_through_ptr (gcc_jit_context *ctxt, 1240 gcc_jit_location *loc, 1241 gcc_jit_rvalue *fn_ptr, 1242 int numargs, gcc_jit_rvalue **args); 1243 1244/* Type-coercion. 1245 1246 Currently only a limited set of conversions are possible: 1247 int <-> float 1248 int <-> bool */ 1249extern gcc_jit_rvalue * 1250gcc_jit_context_new_cast (gcc_jit_context *ctxt, 1251 gcc_jit_location *loc, 1252 gcc_jit_rvalue *rvalue, 1253 gcc_jit_type *type); 1254 1255#define LIBGCCJIT_HAVE_gcc_jit_context_new_bitcast 1256 1257/* Reinterpret a value as another type. 1258 1259 The types must be of the same size. 1260 1261 This API entrypoint was added in LIBGCCJIT_ABI_21; you can test for its 1262 presence using 1263 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitcast */ 1264extern gcc_jit_rvalue * 1265gcc_jit_context_new_bitcast (gcc_jit_context *ctxt, 1266 gcc_jit_location *loc, 1267 gcc_jit_rvalue *rvalue, 1268 gcc_jit_type *type); 1269 1270#define LIBGCCJIT_HAVE_ALIGNMENT 1271 1272/* Set the alignment of a variable. 1273 1274 This API entrypoint was added in LIBGCCJIT_ABI_24; you can test for its 1275 presence using 1276 #ifdef LIBGCCJIT_HAVE_ALIGNMENT */ 1277extern void 1278gcc_jit_lvalue_set_alignment (gcc_jit_lvalue *lvalue, 1279 unsigned bytes); 1280 1281/* Get the alignment of a variable. 1282 1283 This API entrypoint was added in LIBGCCJIT_ABI_24; you can test for its 1284 presence using 1285 #ifdef LIBGCCJIT_HAVE_ALIGNMENT */ 1286extern unsigned 1287gcc_jit_lvalue_get_alignment (gcc_jit_lvalue *lvalue); 1288 1289extern gcc_jit_lvalue * 1290gcc_jit_context_new_array_access (gcc_jit_context *ctxt, 1291 gcc_jit_location *loc, 1292 gcc_jit_rvalue *ptr, 1293 gcc_jit_rvalue *index); 1294 1295/* Field access is provided separately for both lvalues and rvalues. */ 1296 1297/* Accessing a field of an lvalue of struct type, analogous to: 1298 (EXPR).field = ...; 1299 in C. */ 1300extern gcc_jit_lvalue * 1301gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_or_union, 1302 gcc_jit_location *loc, 1303 gcc_jit_field *field); 1304 1305/* Accessing a field of an rvalue of struct type, analogous to: 1306 (EXPR).field 1307 in C. */ 1308extern gcc_jit_rvalue * 1309gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_or_union, 1310 gcc_jit_location *loc, 1311 gcc_jit_field *field); 1312 1313/* Accessing a field of an rvalue of pointer type, analogous to: 1314 (EXPR)->field 1315 in C, itself equivalent to (*EXPR).FIELD */ 1316extern gcc_jit_lvalue * 1317gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr, 1318 gcc_jit_location *loc, 1319 gcc_jit_field *field); 1320 1321/* Dereferencing a pointer; analogous to: 1322 *(EXPR) 1323*/ 1324extern gcc_jit_lvalue * 1325gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue, 1326 gcc_jit_location *loc); 1327 1328/* Taking the address of an lvalue; analogous to: 1329 &(EXPR) 1330 in C. */ 1331extern gcc_jit_rvalue * 1332gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue, 1333 gcc_jit_location *loc); 1334 1335#define LIBGCCJIT_HAVE_gcc_jit_lvalue_set_tls_model 1336 1337/* Set the thread-local storage model of a global variable 1338 1339 This API entrypoint was added in LIBGCCJIT_ABI_17; you can test for its 1340 presence using 1341 #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_tls_model */ 1342extern void 1343gcc_jit_lvalue_set_tls_model (gcc_jit_lvalue *lvalue, 1344 enum gcc_jit_tls_model model); 1345 1346#define LIBGCCJIT_HAVE_gcc_jit_lvalue_set_link_section 1347 1348/* Set the link section of a global variable; analogous to: 1349 __attribute__((section(".section_name"))) 1350 in C. 1351 1352 This API entrypoint was added in LIBGCCJIT_ABI_18; you can test for its 1353 presence using 1354 #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_link_section 1355*/ 1356extern void 1357gcc_jit_lvalue_set_link_section (gcc_jit_lvalue *lvalue, 1358 const char *section_name); 1359 1360#define LIBGCCJIT_HAVE_gcc_jit_lvalue_set_register_name 1361 1362/* Make this variable a register variable and set its register name. 1363 1364 This API entrypoint was added in LIBGCCJIT_ABI_22; you can test for its 1365 presence using 1366 #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_register_name 1367*/ 1368void 1369gcc_jit_lvalue_set_register_name (gcc_jit_lvalue *lvalue, 1370 const char *reg_name); 1371 1372extern gcc_jit_lvalue * 1373gcc_jit_function_new_local (gcc_jit_function *func, 1374 gcc_jit_location *loc, 1375 gcc_jit_type *type, 1376 const char *name); 1377 1378/********************************************************************** 1379 Statement-creation. 1380 **********************************************************************/ 1381 1382/* Add evaluation of an rvalue, discarding the result 1383 (e.g. a function call that "returns" void). 1384 1385 This is equivalent to this C code: 1386 1387 (void)expression; 1388*/ 1389extern void 1390gcc_jit_block_add_eval (gcc_jit_block *block, 1391 gcc_jit_location *loc, 1392 gcc_jit_rvalue *rvalue); 1393 1394/* Add evaluation of an rvalue, assigning the result to the given 1395 lvalue. 1396 1397 This is roughly equivalent to this C code: 1398 1399 lvalue = rvalue; 1400*/ 1401extern void 1402gcc_jit_block_add_assignment (gcc_jit_block *block, 1403 gcc_jit_location *loc, 1404 gcc_jit_lvalue *lvalue, 1405 gcc_jit_rvalue *rvalue); 1406 1407/* Add evaluation of an rvalue, using the result to modify an 1408 lvalue. 1409 1410 This is analogous to "+=" and friends: 1411 1412 lvalue += rvalue; 1413 lvalue *= rvalue; 1414 lvalue /= rvalue; 1415 etc */ 1416extern void 1417gcc_jit_block_add_assignment_op (gcc_jit_block *block, 1418 gcc_jit_location *loc, 1419 gcc_jit_lvalue *lvalue, 1420 enum gcc_jit_binary_op op, 1421 gcc_jit_rvalue *rvalue); 1422 1423/* Add a no-op textual comment to the internal representation of the 1424 code. It will be optimized away, but will be visible in the dumps 1425 seen via 1426 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE 1427 and 1428 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1429 and thus may be of use when debugging how your project's internal 1430 representation gets converted to the libgccjit IR. */ 1431extern void 1432gcc_jit_block_add_comment (gcc_jit_block *block, 1433 gcc_jit_location *loc, 1434 const char *text); 1435 1436/* Terminate a block by adding evaluation of an rvalue, branching on the 1437 result to the appropriate successor block. 1438 1439 This is roughly equivalent to this C code: 1440 1441 if (boolval) 1442 goto on_true; 1443 else 1444 goto on_false; 1445 1446 block, boolval, on_true, and on_false must be non-NULL. */ 1447extern void 1448gcc_jit_block_end_with_conditional (gcc_jit_block *block, 1449 gcc_jit_location *loc, 1450 gcc_jit_rvalue *boolval, 1451 gcc_jit_block *on_true, 1452 gcc_jit_block *on_false); 1453 1454/* Terminate a block by adding a jump to the given target block. 1455 1456 This is roughly equivalent to this C code: 1457 1458 goto target; 1459*/ 1460extern void 1461gcc_jit_block_end_with_jump (gcc_jit_block *block, 1462 gcc_jit_location *loc, 1463 gcc_jit_block *target); 1464 1465/* Terminate a block by adding evaluation of an rvalue, returning the value. 1466 1467 This is roughly equivalent to this C code: 1468 1469 return expression; 1470*/ 1471extern void 1472gcc_jit_block_end_with_return (gcc_jit_block *block, 1473 gcc_jit_location *loc, 1474 gcc_jit_rvalue *rvalue); 1475 1476/* Terminate a block by adding a valueless return, for use within a function 1477 with "void" return type. 1478 1479 This is equivalent to this C code: 1480 1481 return; 1482*/ 1483extern void 1484gcc_jit_block_end_with_void_return (gcc_jit_block *block, 1485 gcc_jit_location *loc); 1486 1487/* Create a new gcc_jit_case instance for use in a switch statement. 1488 min_value and max_value must be constants of integer type. 1489 1490 This API entrypoint was added in LIBGCCJIT_ABI_3; you can test for its 1491 presence using 1492 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS 1493*/ 1494extern gcc_jit_case * 1495gcc_jit_context_new_case (gcc_jit_context *ctxt, 1496 gcc_jit_rvalue *min_value, 1497 gcc_jit_rvalue *max_value, 1498 gcc_jit_block *dest_block); 1499 1500/* Upcasting from case to object. 1501 1502 This API entrypoint was added in LIBGCCJIT_ABI_3; you can test for its 1503 presence using 1504 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS 1505*/ 1506 1507extern gcc_jit_object * 1508gcc_jit_case_as_object (gcc_jit_case *case_); 1509 1510/* Terminate a block by adding evalation of an rvalue, then performing 1511 a multiway branch. 1512 1513 This is roughly equivalent to this C code: 1514 1515 switch (expr) 1516 { 1517 default: 1518 goto default_block; 1519 1520 case C0.min_value ... C0.max_value: 1521 goto C0.dest_block; 1522 1523 case C1.min_value ... C1.max_value: 1524 goto C1.dest_block; 1525 1526 ...etc... 1527 1528 case C[N - 1].min_value ... C[N - 1].max_value: 1529 goto C[N - 1].dest_block; 1530 } 1531 1532 block, expr, default_block and cases must all be non-NULL. 1533 1534 expr must be of the same integer type as all of the min_value 1535 and max_value within the cases. 1536 1537 num_cases must be >= 0. 1538 1539 The ranges of the cases must not overlap (or have duplicate 1540 values). 1541 1542 This API entrypoint was added in LIBGCCJIT_ABI_3; you can test for its 1543 presence using 1544 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS 1545*/ 1546 1547extern void 1548gcc_jit_block_end_with_switch (gcc_jit_block *block, 1549 gcc_jit_location *loc, 1550 gcc_jit_rvalue *expr, 1551 gcc_jit_block *default_block, 1552 int num_cases, 1553 gcc_jit_case **cases); 1554 1555/* Pre-canned feature macro to indicate the presence of 1556 gcc_jit_block_end_with_switch, gcc_jit_case_as_object, and 1557 gcc_jit_context_new_case. 1558 1559 This can be tested for with #ifdef. */ 1560#define LIBGCCJIT_HAVE_SWITCH_STATEMENTS 1561 1562/********************************************************************** 1563 Nested contexts. 1564 **********************************************************************/ 1565 1566/* Given an existing JIT context, create a child context. 1567 1568 The child inherits a copy of all option-settings from the parent. 1569 1570 The child can reference objects created within the parent, but not 1571 vice-versa. 1572 1573 The lifetime of the child context must be bounded by that of the 1574 parent: you should release a child context before releasing the parent 1575 context. 1576 1577 If you use a function from a parent context within a child context, 1578 you have to compile the parent context before you can compile the 1579 child context, and the gcc_jit_result of the parent context must 1580 outlive the gcc_jit_result of the child context. 1581 1582 This allows caching of shared initializations. For example, you could 1583 create types and declarations of global functions in a parent context 1584 once within a process, and then create child contexts whenever a 1585 function or loop becomes hot. Each such child context can be used for 1586 JIT-compiling just one function or loop, but can reference types 1587 and helper functions created within the parent context. 1588 1589 Contexts can be arbitrarily nested, provided the above rules are 1590 followed, but it's probably not worth going above 2 or 3 levels, and 1591 there will likely be a performance hit for such nesting. */ 1592 1593extern gcc_jit_context * 1594gcc_jit_context_new_child_context (gcc_jit_context *parent_ctxt); 1595 1596/********************************************************************** 1597 Implementation support. 1598 **********************************************************************/ 1599 1600/* Write C source code into "path" that can be compiled into a 1601 self-contained executable (i.e. with libgccjit as the only dependency). 1602 The generated code will attempt to replay the API calls that have been 1603 made into the given context. 1604 1605 This may be useful when debugging the library or client code, for 1606 reducing a complicated recipe for reproducing a bug into a simpler 1607 form. 1608 1609 Typically you need to supply the option "-Wno-unused-variable" when 1610 compiling the generated file (since the result of each API call is 1611 assigned to a unique variable within the generated C source, and not 1612 all are necessarily then used). */ 1613 1614extern void 1615gcc_jit_context_dump_reproducer_to_file (gcc_jit_context *ctxt, 1616 const char *path); 1617 1618/* Enable the dumping of a specific set of internal state from the 1619 compilation, capturing the result in-memory as a buffer. 1620 1621 Parameter "dumpname" corresponds to the equivalent gcc command-line 1622 option, without the "-fdump-" prefix. 1623 For example, to get the equivalent of "-fdump-tree-vrp1", supply 1624 "tree-vrp1". 1625 The context directly stores the dumpname as a (const char *), so the 1626 passed string must outlive the context. 1627 1628 gcc_jit_context_compile and gcc_jit_context_to_file 1629 will capture the dump as a dynamically-allocated buffer, writing 1630 it to ``*out_ptr``. 1631 1632 The caller becomes responsible for calling 1633 free (*out_ptr) 1634 each time that gcc_jit_context_compile or gcc_jit_context_to_file 1635 are called. *out_ptr will be written to, either with the address of a 1636 buffer, or with NULL if an error occurred. 1637 1638 This API entrypoint is likely to be less stable than the others. 1639 In particular, both the precise dumpnames, and the format and content 1640 of the dumps are subject to change. 1641 1642 It exists primarily for writing the library's own test suite. */ 1643 1644extern void 1645gcc_jit_context_enable_dump (gcc_jit_context *ctxt, 1646 const char *dumpname, 1647 char **out_ptr); 1648 1649/********************************************************************** 1650 Timing support. 1651 **********************************************************************/ 1652 1653/* The timing API was added in LIBGCCJIT_ABI_4; you can test for its 1654 presence using 1655 #ifdef LIBGCCJIT_HAVE_TIMING_API 1656*/ 1657#define LIBGCCJIT_HAVE_TIMING_API 1658 1659typedef struct gcc_jit_timer gcc_jit_timer; 1660 1661/* Create a gcc_jit_timer instance, and start timing. 1662 1663 This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its 1664 presence using 1665 #ifdef LIBGCCJIT_HAVE_TIMING_API 1666*/ 1667extern gcc_jit_timer * 1668gcc_jit_timer_new (void); 1669 1670/* Release a gcc_jit_timer instance. 1671 1672 This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its 1673 presence using 1674 #ifdef LIBGCCJIT_HAVE_TIMING_API 1675*/ 1676extern void 1677gcc_jit_timer_release (gcc_jit_timer *timer); 1678 1679/* Associate a gcc_jit_timer instance with a context. 1680 1681 This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its 1682 presence using 1683 #ifdef LIBGCCJIT_HAVE_TIMING_API 1684*/ 1685extern void 1686gcc_jit_context_set_timer (gcc_jit_context *ctxt, 1687 gcc_jit_timer *timer); 1688 1689/* Get the timer associated with a context (if any). 1690 1691 This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its 1692 presence using 1693 #ifdef LIBGCCJIT_HAVE_TIMING_API 1694*/ 1695 1696extern gcc_jit_timer * 1697gcc_jit_context_get_timer (gcc_jit_context *ctxt); 1698 1699/* Push the given item onto the timing stack. 1700 1701 This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its 1702 presence using 1703 #ifdef LIBGCCJIT_HAVE_TIMING_API 1704*/ 1705 1706extern void 1707gcc_jit_timer_push (gcc_jit_timer *timer, 1708 const char *item_name); 1709 1710/* Pop the top item from the timing stack. 1711 1712 This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its 1713 presence using 1714 #ifdef LIBGCCJIT_HAVE_TIMING_API 1715*/ 1716 1717extern void 1718gcc_jit_timer_pop (gcc_jit_timer *timer, 1719 const char *item_name); 1720 1721/* Print timing information to the given stream about activity since 1722 the timer was started. 1723 1724 This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its 1725 presence using 1726 #ifdef LIBGCCJIT_HAVE_TIMING_API 1727*/ 1728 1729extern void 1730gcc_jit_timer_print (gcc_jit_timer *timer, 1731 FILE *f_out); 1732 1733 1734#define LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call 1735 1736/* Mark/clear a call as needing tail-call optimization. 1737 1738 This API entrypoint was added in LIBGCCJIT_ABI_6; you can test for its 1739 presence using 1740 #ifdef LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call 1741*/ 1742extern void 1743gcc_jit_rvalue_set_bool_require_tail_call (gcc_jit_rvalue *call, 1744 int require_tail_call); 1745 1746#define LIBGCCJIT_HAVE_gcc_jit_type_get_aligned 1747 1748/* Given type "T", get type: 1749 1750 T __attribute__ ((aligned (ALIGNMENT_IN_BYTES))) 1751 1752 The alignment must be a power of two. 1753 1754 This API entrypoint was added in LIBGCCJIT_ABI_7; you can test for its 1755 presence using 1756 #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_aligned 1757*/ 1758extern gcc_jit_type * 1759gcc_jit_type_get_aligned (gcc_jit_type *type, 1760 size_t alignment_in_bytes); 1761 1762#define LIBGCCJIT_HAVE_gcc_jit_type_get_vector 1763 1764/* Given type "T", get type: 1765 1766 T __attribute__ ((vector_size (sizeof(T) * num_units)) 1767 1768 T must be integral/floating point; num_units must be a power of two. 1769 1770 This API entrypoint was added in LIBGCCJIT_ABI_8; you can test for its 1771 presence using 1772 #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_vector 1773*/ 1774extern gcc_jit_type * 1775gcc_jit_type_get_vector (gcc_jit_type *type, size_t num_units); 1776 1777 1778#define LIBGCCJIT_HAVE_gcc_jit_function_get_address 1779 1780/* Get the address of a function as an rvalue, of function pointer 1781 type. 1782 1783 This API entrypoint was added in LIBGCCJIT_ABI_9; you can test for its 1784 presence using 1785 #ifdef LIBGCCJIT_HAVE_gcc_jit_function_get_address 1786*/ 1787extern gcc_jit_rvalue * 1788gcc_jit_function_get_address (gcc_jit_function *fn, 1789 gcc_jit_location *loc); 1790 1791 1792#define LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector 1793 1794/* Build a vector rvalue from an array of elements. 1795 1796 "vec_type" should be a vector type, created using gcc_jit_type_get_vector. 1797 1798 This API entrypoint was added in LIBGCCJIT_ABI_10; you can test for its 1799 presence using 1800 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector 1801*/ 1802extern gcc_jit_rvalue * 1803gcc_jit_context_new_rvalue_from_vector (gcc_jit_context *ctxt, 1804 gcc_jit_location *loc, 1805 gcc_jit_type *vec_type, 1806 size_t num_elements, 1807 gcc_jit_rvalue **elements); 1808 1809#define LIBGCCJIT_HAVE_gcc_jit_version 1810 1811/* Functions to retrieve libgccjit version. 1812 Analogous to __GNUC__, __GNUC_MINOR__, __GNUC_PATCHLEVEL__ in C code. 1813 1814 These API entrypoints were added in LIBGCCJIT_ABI_13; you can test for their 1815 presence using 1816 #ifdef LIBGCCJIT_HAVE_gcc_jit_version 1817 */ 1818extern int 1819gcc_jit_version_major (void); 1820extern int 1821gcc_jit_version_minor (void); 1822extern int 1823gcc_jit_version_patchlevel (void); 1824 1825/********************************************************************** 1826 Asm support. 1827 **********************************************************************/ 1828 1829/* Functions for adding inline assembler code, analogous to GCC's 1830 "extended asm" syntax. 1831 1832 See https://gcc.gnu.org/onlinedocs/gcc/Using-Assembly-Language-with-C.html 1833 1834 These API entrypoints were added in LIBGCCJIT_ABI_15; you can test for their 1835 presence using 1836 #ifdef LIBGCCJIT_HAVE_ASM_STATEMENTS 1837*/ 1838 1839#define LIBGCCJIT_HAVE_ASM_STATEMENTS 1840 1841/* Create a gcc_jit_extended_asm for an extended asm statement 1842 with no control flow (i.e. without the goto qualifier). 1843 1844 The asm_template parameter corresponds to the AssemblerTemplate 1845 within C's extended asm syntax. It must be non-NULL. */ 1846 1847extern gcc_jit_extended_asm * 1848gcc_jit_block_add_extended_asm (gcc_jit_block *block, 1849 gcc_jit_location *loc, 1850 const char *asm_template); 1851 1852/* Create a gcc_jit_extended_asm for an extended asm statement 1853 that may perform jumps, and use it to terminate the given block. 1854 This is equivalent to the "goto" qualifier in C's extended asm 1855 syntax. */ 1856 1857extern gcc_jit_extended_asm * 1858gcc_jit_block_end_with_extended_asm_goto (gcc_jit_block *block, 1859 gcc_jit_location *loc, 1860 const char *asm_template, 1861 int num_goto_blocks, 1862 gcc_jit_block **goto_blocks, 1863 gcc_jit_block *fallthrough_block); 1864 1865/* Upcasting from extended asm to object. */ 1866 1867extern gcc_jit_object * 1868gcc_jit_extended_asm_as_object (gcc_jit_extended_asm *ext_asm); 1869 1870/* Set whether the gcc_jit_extended_asm has side-effects, equivalent to 1871 the "volatile" qualifier in C's extended asm syntax. */ 1872 1873extern void 1874gcc_jit_extended_asm_set_volatile_flag (gcc_jit_extended_asm *ext_asm, 1875 int flag); 1876 1877/* Set the equivalent of the "inline" qualifier in C's extended asm 1878 syntax. */ 1879 1880extern void 1881gcc_jit_extended_asm_set_inline_flag (gcc_jit_extended_asm *ext_asm, 1882 int flag); 1883 1884/* Add an output operand to the extended asm statement. 1885 "asm_symbolic_name" can be NULL. 1886 "constraint" and "dest" must be non-NULL. 1887 This function can't be called on an "asm goto" as such instructions 1888 can't have outputs */ 1889 1890extern void 1891gcc_jit_extended_asm_add_output_operand (gcc_jit_extended_asm *ext_asm, 1892 const char *asm_symbolic_name, 1893 const char *constraint, 1894 gcc_jit_lvalue *dest); 1895 1896/* Add an input operand to the extended asm statement. 1897 "asm_symbolic_name" can be NULL. 1898 "constraint" and "src" must be non-NULL. */ 1899 1900extern void 1901gcc_jit_extended_asm_add_input_operand (gcc_jit_extended_asm *ext_asm, 1902 const char *asm_symbolic_name, 1903 const char *constraint, 1904 gcc_jit_rvalue *src); 1905 1906/* Add "victim" to the list of registers clobbered by the extended 1907 asm statement. It must be non-NULL. */ 1908 1909extern void 1910gcc_jit_extended_asm_add_clobber (gcc_jit_extended_asm *ext_asm, 1911 const char *victim); 1912 1913/* Add "asm_stmts", a set of top-level asm statements, analogous to 1914 those created by GCC's "basic" asm syntax in C at file scope. */ 1915 1916extern void 1917gcc_jit_context_add_top_level_asm (gcc_jit_context *ctxt, 1918 gcc_jit_location *loc, 1919 const char *asm_stmts); 1920 1921#define LIBGCCJIT_HAVE_REFLECTION 1922 1923/* Reflection functions to get the number of parameters, return type of 1924 a function and whether a type is a bool from the C API. 1925 1926 This API entrypoint was added in LIBGCCJIT_ABI_16; you can test for its 1927 presence using 1928 #ifdef LIBGCCJIT_HAVE_REFLECTION 1929*/ 1930/* Get the return type of a function. */ 1931extern gcc_jit_type * 1932gcc_jit_function_get_return_type (gcc_jit_function *func); 1933 1934/* Get the number of params of a function. */ 1935extern size_t 1936gcc_jit_function_get_param_count (gcc_jit_function *func); 1937 1938/* Get the element type of an array type or NULL if it's not an array. */ 1939extern gcc_jit_type * 1940gcc_jit_type_dyncast_array (gcc_jit_type *type); 1941 1942/* Return non-zero if the type is a bool. */ 1943extern int 1944gcc_jit_type_is_bool (gcc_jit_type *type); 1945 1946/* Return the function type if it is one or NULL. */ 1947extern gcc_jit_function_type * 1948gcc_jit_type_dyncast_function_ptr_type (gcc_jit_type *type); 1949 1950/* Given a function type, return its return type. */ 1951extern gcc_jit_type * 1952gcc_jit_function_type_get_return_type (gcc_jit_function_type *function_type); 1953 1954/* Given a function type, return its number of parameters. */ 1955extern size_t 1956gcc_jit_function_type_get_param_count (gcc_jit_function_type *function_type); 1957 1958/* Given a function type, return the type of the specified parameter. */ 1959extern gcc_jit_type * 1960gcc_jit_function_type_get_param_type (gcc_jit_function_type *function_type, 1961 size_t index); 1962 1963/* Return non-zero if the type is an integral. */ 1964extern int 1965gcc_jit_type_is_integral (gcc_jit_type *type); 1966 1967/* Return the type pointed by the pointer type or NULL if it's not a 1968 * pointer. */ 1969extern gcc_jit_type * 1970gcc_jit_type_is_pointer (gcc_jit_type *type); 1971 1972/* Given a type, return a dynamic cast to a vector type or NULL. */ 1973extern gcc_jit_vector_type * 1974gcc_jit_type_dyncast_vector (gcc_jit_type *type); 1975 1976/* Given a type, return a dynamic cast to a struct type or NULL. */ 1977extern gcc_jit_struct * 1978gcc_jit_type_is_struct (gcc_jit_type *type); 1979 1980/* Given a vector type, return the number of units it contains. */ 1981extern size_t 1982gcc_jit_vector_type_get_num_units (gcc_jit_vector_type *vector_type); 1983 1984/* Given a vector type, return the type of its elements. */ 1985extern gcc_jit_type * 1986gcc_jit_vector_type_get_element_type (gcc_jit_vector_type *vector_type); 1987 1988/* Given a type, return the unqualified type, removing "const", "volatile" 1989 * and alignment qualifiers. */ 1990extern gcc_jit_type * 1991gcc_jit_type_unqualified (gcc_jit_type *type); 1992 1993#ifdef __cplusplus 1994} 1995#endif /* __cplusplus */ 1996 1997#endif /* LIBGCCJIT_H */ 1998