1 /* A pure C API to enable client code to embed GCC as a JIT-compiler. 2 Copyright (C) 2013-2015 Free Software Foundation, Inc. 3 4 This file is part of GCC. 5 6 GCC is free software; you can redistribute it and/or modify it 7 under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 3, or (at your option) 9 any later version. 10 11 GCC is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along 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 26 extern "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. */ 50 typedef struct gcc_jit_context gcc_jit_context; 51 52 /* A gcc_jit_result encapsulates the result of an in-memory compilation. */ 53 typedef 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_field 65 +- gcc_jit_function 66 +- gcc_jit_block 67 +- gcc_jit_rvalue 68 +- gcc_jit_lvalue 69 +- gcc_jit_param 70 +- gcc_jit_case 71 */ 72 typedef struct gcc_jit_object gcc_jit_object; 73 74 /* A gcc_jit_location encapsulates a source code location, so that 75 you can (optionally) associate locations in your language with 76 statements in the JIT-compiled code, allowing the debugger to 77 single-step through your language. 78 79 Note that to do so, you also need to enable 80 GCC_JIT_BOOL_OPTION_DEBUGINFO 81 on the gcc_jit_context. 82 83 gcc_jit_location instances are optional; you can always pass 84 NULL. */ 85 typedef struct gcc_jit_location gcc_jit_location; 86 87 /* A gcc_jit_type encapsulates a type e.g. "int" or a "struct foo*". */ 88 typedef struct gcc_jit_type gcc_jit_type; 89 90 /* A gcc_jit_field encapsulates a field within a struct; it is used 91 when creating a struct type (using gcc_jit_context_new_struct_type). 92 Fields cannot be shared between structs. */ 93 typedef struct gcc_jit_field gcc_jit_field; 94 95 /* A gcc_jit_struct encapsulates a struct type, either one that we have 96 the layout for, or an opaque type. */ 97 typedef struct gcc_jit_struct gcc_jit_struct; 98 99 /* A gcc_jit_function encapsulates a function: either one that you're 100 creating yourself, or a reference to one that you're dynamically 101 linking to within the rest of the process. */ 102 typedef struct gcc_jit_function gcc_jit_function; 103 104 /* A gcc_jit_block encapsulates a "basic block" of statements within a 105 function (i.e. with one entry point and one exit point). 106 107 Every block within a function must be terminated with a conditional, 108 a branch, or a return. 109 110 The blocks within a function form a directed graph. 111 112 The entrypoint to the function is the first block created within 113 it. 114 115 All of the blocks in a function must be reachable via some path from 116 the first block. 117 118 It's OK to have more than one "return" from a function (i.e. multiple 119 blocks that terminate by returning). */ 120 typedef struct gcc_jit_block gcc_jit_block; 121 122 /* A gcc_jit_rvalue is an expression within your code, with some type. */ 123 typedef struct gcc_jit_rvalue gcc_jit_rvalue; 124 125 /* A gcc_jit_lvalue is a storage location within your code (e.g. a 126 variable, a parameter, etc). It is also a gcc_jit_rvalue; use 127 gcc_jit_lvalue_as_rvalue to cast. */ 128 typedef struct gcc_jit_lvalue gcc_jit_lvalue; 129 130 /* A gcc_jit_param is a function parameter, used when creating a 131 gcc_jit_function. It is also a gcc_jit_lvalue (and thus also an 132 rvalue); use gcc_jit_param_as_lvalue to convert. */ 133 typedef struct gcc_jit_param gcc_jit_param; 134 135 /* A gcc_jit_case is for use when building multiway branches via 136 gcc_jit_block_end_with_switch and represents a range of integer 137 values (or an individual integer value) together with an associated 138 destination block. */ 139 typedef struct gcc_jit_case gcc_jit_case; 140 141 /* Acquire a JIT-compilation context. */ 142 extern gcc_jit_context * 143 gcc_jit_context_acquire (void); 144 145 /* Release the context. After this call, it's no longer valid to use 146 the ctxt. */ 147 extern void 148 gcc_jit_context_release (gcc_jit_context *ctxt); 149 150 /* Options present in the initial release of libgccjit. 151 These were handled using enums. */ 152 153 /* Options taking string values. */ 154 enum gcc_jit_str_option 155 { 156 /* The name of the program, for use as a prefix when printing error 157 messages to stderr. If NULL, or default, "libgccjit.so" is used. */ 158 GCC_JIT_STR_OPTION_PROGNAME, 159 160 GCC_JIT_NUM_STR_OPTIONS 161 }; 162 163 /* Options taking int values. */ 164 enum gcc_jit_int_option 165 { 166 /* How much to optimize the code. 167 Valid values are 0-3, corresponding to GCC's command-line options 168 -O0 through -O3. 169 170 The default value is 0 (unoptimized). */ 171 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 172 173 GCC_JIT_NUM_INT_OPTIONS 174 }; 175 176 /* Options taking boolean values. 177 These all default to "false". */ 178 enum gcc_jit_bool_option 179 { 180 /* If true, gcc_jit_context_compile will attempt to do the right 181 thing so that if you attach a debugger to the process, it will 182 be able to inspect variables and step through your code. 183 184 Note that you can't step through code unless you set up source 185 location information for the code (by creating and passing in 186 gcc_jit_location instances). */ 187 GCC_JIT_BOOL_OPTION_DEBUGINFO, 188 189 /* If true, gcc_jit_context_compile will dump its initial "tree" 190 representation of your code to stderr (before any 191 optimizations). */ 192 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE, 193 194 /* If true, gcc_jit_context_compile will dump the "gimple" 195 representation of your code to stderr, before any optimizations 196 are performed. The dump resembles C code. */ 197 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 198 199 /* If true, gcc_jit_context_compile will dump the final 200 generated code to stderr, in the form of assembly language. */ 201 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 202 203 /* If true, gcc_jit_context_compile will print information to stderr 204 on the actions it is performing, followed by a profile showing 205 the time taken and memory usage of each phase. 206 */ 207 GCC_JIT_BOOL_OPTION_DUMP_SUMMARY, 208 209 /* If true, gcc_jit_context_compile will dump copious 210 amount of information on what it's doing to various 211 files within a temporary directory. Use 212 GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES (see below) to 213 see the results. The files are intended to be human-readable, 214 but the exact files and their formats are subject to change. 215 */ 216 GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING, 217 218 /* If true, libgccjit will aggressively run its garbage collector, to 219 shake out bugs (greatly slowing down the compile). This is likely 220 to only be of interest to developers *of* the library. It is 221 used when running the selftest suite. */ 222 GCC_JIT_BOOL_OPTION_SELFCHECK_GC, 223 224 /* If true, gcc_jit_context_release will not clean up 225 intermediate files written to the filesystem, and will display 226 their location on stderr. */ 227 GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES, 228 229 GCC_JIT_NUM_BOOL_OPTIONS 230 }; 231 232 /* Set a string option on the given context. 233 234 The context takes a copy of the string, so the 235 (const char *) buffer is not needed anymore after the call 236 returns. */ 237 extern void 238 gcc_jit_context_set_str_option (gcc_jit_context *ctxt, 239 enum gcc_jit_str_option opt, 240 const char *value); 241 242 /* Set an int option on the given context. */ 243 extern void 244 gcc_jit_context_set_int_option (gcc_jit_context *ctxt, 245 enum gcc_jit_int_option opt, 246 int value); 247 248 /* Set a boolean option on the given context. 249 250 Zero is "false" (the default), non-zero is "true". */ 251 extern void 252 gcc_jit_context_set_bool_option (gcc_jit_context *ctxt, 253 enum gcc_jit_bool_option opt, 254 int value); 255 256 /* Options added after the initial release of libgccjit. 257 These are handled by providing an entrypoint per option, 258 rather than by extending the enum gcc_jit_*_option, 259 so that client code that use these new options can be identified 260 from binary metadata. */ 261 262 /* By default, libgccjit will issue an error about unreachable blocks 263 within a function. 264 265 This option can be used to disable that error. 266 267 This entrypoint was added in LIBGCCJIT_ABI_2; you can test for 268 its presence using 269 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks 270 */ 271 272 extern void 273 gcc_jit_context_set_bool_allow_unreachable_blocks (gcc_jit_context *ctxt, 274 int bool_value); 275 276 /* Pre-canned feature macro to indicate the presence of 277 gcc_jit_context_set_bool_allow_unreachable_blocks. This can be 278 tested for with #ifdef. */ 279 #define LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks 280 281 /* Add an arbitrary gcc command-line option to the context. 282 The context takes a copy of the string, so the 283 (const char *) optname is not needed anymore after the call 284 returns. 285 286 Note that only some options are likely to be meaningful; there is no 287 "frontend" within libgccjit, so typically only those affecting 288 optimization and code-generation are likely to be useful. 289 290 This entrypoint was added in LIBGCCJIT_ABI_1; you can test for 291 its presence using 292 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option 293 */ 294 295 extern void 296 gcc_jit_context_add_command_line_option (gcc_jit_context *ctxt, 297 const char *optname); 298 299 /* Pre-canned feature-test macro for detecting the presence of 300 gcc_jit_context_add_command_line_option within libgccjit.h. */ 301 302 #define LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option 303 304 /* Compile the context to in-memory machine code. 305 306 This can be called more that once on a given context, 307 although any errors that occur will block further compilation. */ 308 309 extern gcc_jit_result * 310 gcc_jit_context_compile (gcc_jit_context *ctxt); 311 312 /* Kinds of ahead-of-time compilation, for use with 313 gcc_jit_context_compile_to_file. */ 314 315 enum gcc_jit_output_kind 316 { 317 /* Compile the context to an assembler file. */ 318 GCC_JIT_OUTPUT_KIND_ASSEMBLER, 319 320 /* Compile the context to an object file. */ 321 GCC_JIT_OUTPUT_KIND_OBJECT_FILE, 322 323 /* Compile the context to a dynamic library. */ 324 GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY, 325 326 /* Compile the context to an executable. */ 327 GCC_JIT_OUTPUT_KIND_EXECUTABLE 328 }; 329 330 /* Compile the context to a file of the given kind. 331 332 This can be called more that once on a given context, 333 although any errors that occur will block further compilation. */ 334 335 extern void 336 gcc_jit_context_compile_to_file (gcc_jit_context *ctxt, 337 enum gcc_jit_output_kind output_kind, 338 const char *output_path); 339 340 /* To help with debugging: dump a C-like representation to the given path, 341 describing what's been set up on the context. 342 343 If "update_locations" is true, then also set up gcc_jit_location 344 information throughout the context, pointing at the dump file as if it 345 were a source file. This may be of use in conjunction with 346 GCC_JIT_BOOL_OPTION_DEBUGINFO to allow stepping through the code in a 347 debugger. */ 348 extern void 349 gcc_jit_context_dump_to_file (gcc_jit_context *ctxt, 350 const char *path, 351 int update_locations); 352 353 /* To help with debugging; enable ongoing logging of the context's 354 activity to the given FILE *. 355 356 The caller remains responsible for closing "logfile". 357 358 Params "flags" and "verbosity" are reserved for future use, and 359 must both be 0 for now. */ 360 extern void 361 gcc_jit_context_set_logfile (gcc_jit_context *ctxt, 362 FILE *logfile, 363 int flags, 364 int verbosity); 365 366 /* To be called after any API call, this gives the first error message 367 that occurred on the context. 368 369 The returned string is valid for the rest of the lifetime of the 370 context. 371 372 If no errors occurred, this will be NULL. */ 373 extern const char * 374 gcc_jit_context_get_first_error (gcc_jit_context *ctxt); 375 376 /* To be called after any API call, this gives the last error message 377 that occurred on the context. 378 379 If no errors occurred, this will be NULL. 380 381 If non-NULL, the returned string is only guaranteed to be valid until 382 the next call to libgccjit relating to this context. */ 383 extern const char * 384 gcc_jit_context_get_last_error (gcc_jit_context *ctxt); 385 386 /* Locate a given function within the built machine code. 387 This will need to be cast to a function pointer of the 388 correct type before it can be called. */ 389 extern void * 390 gcc_jit_result_get_code (gcc_jit_result *result, 391 const char *funcname); 392 393 /* Locate a given global within the built machine code. 394 It must have been created using GCC_JIT_GLOBAL_EXPORTED. 395 This is a ptr to the global, so e.g. for an int this is an int *. */ 396 extern void * 397 gcc_jit_result_get_global (gcc_jit_result *result, 398 const char *name); 399 400 /* Once we're done with the code, this unloads the built .so file. 401 This cleans up the result; after calling this, it's no longer 402 valid to use the result. */ 403 extern void 404 gcc_jit_result_release (gcc_jit_result *result); 405 406 407 /********************************************************************** 408 Functions for creating "contextual" objects. 409 410 All objects created by these functions share the lifetime of the context 411 they are created within, and are automatically cleaned up for you when 412 you call gcc_jit_context_release on the context. 413 414 Note that this means you can't use references to them after you've 415 released their context. 416 417 All (const char *) string arguments passed to these functions are 418 copied, so you don't need to keep them around. 419 420 You create code by adding a sequence of statements to blocks. 421 **********************************************************************/ 422 423 /********************************************************************** 424 The base class of "contextual" object. 425 **********************************************************************/ 426 /* Which context is "obj" within? */ 427 extern gcc_jit_context * 428 gcc_jit_object_get_context (gcc_jit_object *obj); 429 430 /* Get a human-readable description of this object. 431 The string buffer is created the first time this is called on a given 432 object, and persists until the object's context is released. */ 433 extern const char * 434 gcc_jit_object_get_debug_string (gcc_jit_object *obj); 435 436 /********************************************************************** 437 Debugging information. 438 **********************************************************************/ 439 440 /* Creating source code locations for use by the debugger. 441 Line and column numbers are 1-based. */ 442 extern gcc_jit_location * 443 gcc_jit_context_new_location (gcc_jit_context *ctxt, 444 const char *filename, 445 int line, 446 int column); 447 448 /* Upcasting from location to object. */ 449 extern gcc_jit_object * 450 gcc_jit_location_as_object (gcc_jit_location *loc); 451 452 453 /********************************************************************** 454 Types. 455 **********************************************************************/ 456 457 /* Upcasting from type to object. */ 458 extern gcc_jit_object * 459 gcc_jit_type_as_object (gcc_jit_type *type); 460 461 /* Access to specific types. */ 462 enum gcc_jit_types 463 { 464 /* C's "void" type. */ 465 GCC_JIT_TYPE_VOID, 466 467 /* "void *". */ 468 GCC_JIT_TYPE_VOID_PTR, 469 470 /* C++'s bool type; also C99's "_Bool" type, aka "bool" if using 471 stdbool.h. */ 472 GCC_JIT_TYPE_BOOL, 473 474 /* Various integer types. */ 475 476 /* C's "char" (of some signedness) and the variants where the 477 signedness is specified. */ 478 GCC_JIT_TYPE_CHAR, 479 GCC_JIT_TYPE_SIGNED_CHAR, 480 GCC_JIT_TYPE_UNSIGNED_CHAR, 481 482 /* C's "short" and "unsigned short". */ 483 GCC_JIT_TYPE_SHORT, /* signed */ 484 GCC_JIT_TYPE_UNSIGNED_SHORT, 485 486 /* C's "int" and "unsigned int". */ 487 GCC_JIT_TYPE_INT, /* signed */ 488 GCC_JIT_TYPE_UNSIGNED_INT, 489 490 /* C's "long" and "unsigned long". */ 491 GCC_JIT_TYPE_LONG, /* signed */ 492 GCC_JIT_TYPE_UNSIGNED_LONG, 493 494 /* C99's "long long" and "unsigned long long". */ 495 GCC_JIT_TYPE_LONG_LONG, /* signed */ 496 GCC_JIT_TYPE_UNSIGNED_LONG_LONG, 497 498 /* Floating-point types */ 499 500 GCC_JIT_TYPE_FLOAT, 501 GCC_JIT_TYPE_DOUBLE, 502 GCC_JIT_TYPE_LONG_DOUBLE, 503 504 /* C type: (const char *). */ 505 GCC_JIT_TYPE_CONST_CHAR_PTR, 506 507 /* The C "size_t" type. */ 508 GCC_JIT_TYPE_SIZE_T, 509 510 /* C type: (FILE *) */ 511 GCC_JIT_TYPE_FILE_PTR, 512 513 /* Complex numbers. */ 514 GCC_JIT_TYPE_COMPLEX_FLOAT, 515 GCC_JIT_TYPE_COMPLEX_DOUBLE, 516 GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE 517 518 }; 519 520 extern gcc_jit_type * 521 gcc_jit_context_get_type (gcc_jit_context *ctxt, 522 enum gcc_jit_types type_); 523 524 /* Get the integer type of the given size and signedness. */ 525 extern gcc_jit_type * 526 gcc_jit_context_get_int_type (gcc_jit_context *ctxt, 527 int num_bytes, int is_signed); 528 529 /* Constructing new types. */ 530 531 /* Given type "T", get type "T*". */ 532 extern gcc_jit_type * 533 gcc_jit_type_get_pointer (gcc_jit_type *type); 534 535 /* Given type "T", get type "const T". */ 536 extern gcc_jit_type * 537 gcc_jit_type_get_const (gcc_jit_type *type); 538 539 /* Given type "T", get type "volatile T". */ 540 extern gcc_jit_type * 541 gcc_jit_type_get_volatile (gcc_jit_type *type); 542 543 /* Given type "T", get type "T[N]" (for a constant N). */ 544 extern gcc_jit_type * 545 gcc_jit_context_new_array_type (gcc_jit_context *ctxt, 546 gcc_jit_location *loc, 547 gcc_jit_type *element_type, 548 int num_elements); 549 550 /* Struct-handling. */ 551 552 /* Create a field, for use within a struct or union. */ 553 extern gcc_jit_field * 554 gcc_jit_context_new_field (gcc_jit_context *ctxt, 555 gcc_jit_location *loc, 556 gcc_jit_type *type, 557 const char *name); 558 559 /* Upcasting from field to object. */ 560 extern gcc_jit_object * 561 gcc_jit_field_as_object (gcc_jit_field *field); 562 563 /* Create a struct type from an array of fields. */ 564 extern gcc_jit_struct * 565 gcc_jit_context_new_struct_type (gcc_jit_context *ctxt, 566 gcc_jit_location *loc, 567 const char *name, 568 int num_fields, 569 gcc_jit_field **fields); 570 571 /* Create an opaque struct type. */ 572 extern gcc_jit_struct * 573 gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt, 574 gcc_jit_location *loc, 575 const char *name); 576 577 /* Upcast a struct to a type. */ 578 extern gcc_jit_type * 579 gcc_jit_struct_as_type (gcc_jit_struct *struct_type); 580 581 /* Populating the fields of a formerly-opaque struct type. 582 This can only be called once on a given struct type. */ 583 extern void 584 gcc_jit_struct_set_fields (gcc_jit_struct *struct_type, 585 gcc_jit_location *loc, 586 int num_fields, 587 gcc_jit_field **fields); 588 589 /* Unions work similarly to structs. */ 590 extern gcc_jit_type * 591 gcc_jit_context_new_union_type (gcc_jit_context *ctxt, 592 gcc_jit_location *loc, 593 const char *name, 594 int num_fields, 595 gcc_jit_field **fields); 596 597 /* Function pointers. */ 598 599 extern gcc_jit_type * 600 gcc_jit_context_new_function_ptr_type (gcc_jit_context *ctxt, 601 gcc_jit_location *loc, 602 gcc_jit_type *return_type, 603 int num_params, 604 gcc_jit_type **param_types, 605 int is_variadic); 606 607 /********************************************************************** 608 Constructing functions. 609 **********************************************************************/ 610 /* Create a function param. */ 611 extern gcc_jit_param * 612 gcc_jit_context_new_param (gcc_jit_context *ctxt, 613 gcc_jit_location *loc, 614 gcc_jit_type *type, 615 const char *name); 616 617 /* Upcasting from param to object. */ 618 extern gcc_jit_object * 619 gcc_jit_param_as_object (gcc_jit_param *param); 620 621 /* Upcasting from param to lvalue. */ 622 extern gcc_jit_lvalue * 623 gcc_jit_param_as_lvalue (gcc_jit_param *param); 624 625 /* Upcasting from param to rvalue. */ 626 extern gcc_jit_rvalue * 627 gcc_jit_param_as_rvalue (gcc_jit_param *param); 628 629 /* Kinds of function. */ 630 enum gcc_jit_function_kind 631 { 632 /* Function is defined by the client code and visible 633 by name outside of the JIT. */ 634 GCC_JIT_FUNCTION_EXPORTED, 635 636 /* Function is defined by the client code, but is invisible 637 outside of the JIT. Analogous to a "static" function. */ 638 GCC_JIT_FUNCTION_INTERNAL, 639 640 /* Function is not defined by the client code; we're merely 641 referring to it. Analogous to using an "extern" function from a 642 header file. */ 643 GCC_JIT_FUNCTION_IMPORTED, 644 645 /* Function is only ever inlined into other functions, and is 646 invisible outside of the JIT. 647 648 Analogous to prefixing with "inline" and adding 649 __attribute__((always_inline)). 650 651 Inlining will only occur when the optimization level is 652 above 0; when optimization is off, this is essentially the 653 same as GCC_JIT_FUNCTION_INTERNAL. */ 654 GCC_JIT_FUNCTION_ALWAYS_INLINE 655 }; 656 657 /* Create a function. */ 658 extern gcc_jit_function * 659 gcc_jit_context_new_function (gcc_jit_context *ctxt, 660 gcc_jit_location *loc, 661 enum gcc_jit_function_kind kind, 662 gcc_jit_type *return_type, 663 const char *name, 664 int num_params, 665 gcc_jit_param **params, 666 int is_variadic); 667 668 /* Create a reference to a builtin function (sometimes called 669 intrinsic functions). */ 670 extern gcc_jit_function * 671 gcc_jit_context_get_builtin_function (gcc_jit_context *ctxt, 672 const char *name); 673 674 /* Upcasting from function to object. */ 675 extern gcc_jit_object * 676 gcc_jit_function_as_object (gcc_jit_function *func); 677 678 /* Get a specific param of a function by index. */ 679 extern gcc_jit_param * 680 gcc_jit_function_get_param (gcc_jit_function *func, int index); 681 682 /* Emit the function in graphviz format. */ 683 extern void 684 gcc_jit_function_dump_to_dot (gcc_jit_function *func, 685 const char *path); 686 687 /* Create a block. 688 689 The name can be NULL, or you can give it a meaningful name, which 690 may show up in dumps of the internal representation, and in error 691 messages. */ 692 extern gcc_jit_block * 693 gcc_jit_function_new_block (gcc_jit_function *func, 694 const char *name); 695 696 /* Upcasting from block to object. */ 697 extern gcc_jit_object * 698 gcc_jit_block_as_object (gcc_jit_block *block); 699 700 /* Which function is this block within? */ 701 extern gcc_jit_function * 702 gcc_jit_block_get_function (gcc_jit_block *block); 703 704 /********************************************************************** 705 lvalues, rvalues and expressions. 706 **********************************************************************/ 707 enum gcc_jit_global_kind 708 { 709 /* Global is defined by the client code and visible 710 by name outside of this JIT context via gcc_jit_result_get_global. */ 711 GCC_JIT_GLOBAL_EXPORTED, 712 713 /* Global is defined by the client code, but is invisible 714 outside of this JIT context. Analogous to a "static" global. */ 715 GCC_JIT_GLOBAL_INTERNAL, 716 717 /* Global is not defined by the client code; we're merely 718 referring to it. Analogous to using an "extern" global from a 719 header file. */ 720 GCC_JIT_GLOBAL_IMPORTED 721 }; 722 723 extern gcc_jit_lvalue * 724 gcc_jit_context_new_global (gcc_jit_context *ctxt, 725 gcc_jit_location *loc, 726 enum gcc_jit_global_kind kind, 727 gcc_jit_type *type, 728 const char *name); 729 730 /* Upcasting. */ 731 extern gcc_jit_object * 732 gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue); 733 734 extern gcc_jit_rvalue * 735 gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue); 736 737 extern gcc_jit_object * 738 gcc_jit_rvalue_as_object (gcc_jit_rvalue *rvalue); 739 740 extern gcc_jit_type * 741 gcc_jit_rvalue_get_type (gcc_jit_rvalue *rvalue); 742 743 /* Integer constants. */ 744 extern gcc_jit_rvalue * 745 gcc_jit_context_new_rvalue_from_int (gcc_jit_context *ctxt, 746 gcc_jit_type *numeric_type, 747 int value); 748 749 extern gcc_jit_rvalue * 750 gcc_jit_context_new_rvalue_from_long (gcc_jit_context *ctxt, 751 gcc_jit_type *numeric_type, 752 long value); 753 754 extern gcc_jit_rvalue * 755 gcc_jit_context_zero (gcc_jit_context *ctxt, 756 gcc_jit_type *numeric_type); 757 758 extern gcc_jit_rvalue * 759 gcc_jit_context_one (gcc_jit_context *ctxt, 760 gcc_jit_type *numeric_type); 761 762 /* Floating-point constants. */ 763 extern gcc_jit_rvalue * 764 gcc_jit_context_new_rvalue_from_double (gcc_jit_context *ctxt, 765 gcc_jit_type *numeric_type, 766 double value); 767 768 /* Pointers. */ 769 extern gcc_jit_rvalue * 770 gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt, 771 gcc_jit_type *pointer_type, 772 void *value); 773 774 extern gcc_jit_rvalue * 775 gcc_jit_context_null (gcc_jit_context *ctxt, 776 gcc_jit_type *pointer_type); 777 778 /* String literals. */ 779 extern gcc_jit_rvalue * 780 gcc_jit_context_new_string_literal (gcc_jit_context *ctxt, 781 const char *value); 782 783 enum gcc_jit_unary_op 784 { 785 /* Negate an arithmetic value; analogous to: 786 -(EXPR) 787 in C. */ 788 GCC_JIT_UNARY_OP_MINUS, 789 790 /* Bitwise negation of an integer value (one's complement); analogous 791 to: 792 ~(EXPR) 793 in C. */ 794 GCC_JIT_UNARY_OP_BITWISE_NEGATE, 795 796 /* Logical negation of an arithmetic or pointer value; analogous to: 797 !(EXPR) 798 in C. */ 799 GCC_JIT_UNARY_OP_LOGICAL_NEGATE, 800 801 /* Absolute value of an arithmetic expression; analogous to: 802 abs (EXPR) 803 in C. */ 804 GCC_JIT_UNARY_OP_ABS 805 806 }; 807 808 extern gcc_jit_rvalue * 809 gcc_jit_context_new_unary_op (gcc_jit_context *ctxt, 810 gcc_jit_location *loc, 811 enum gcc_jit_unary_op op, 812 gcc_jit_type *result_type, 813 gcc_jit_rvalue *rvalue); 814 815 enum gcc_jit_binary_op 816 { 817 /* Addition of arithmetic values; analogous to: 818 (EXPR_A) + (EXPR_B) 819 in C. 820 For pointer addition, use gcc_jit_context_new_array_access. */ 821 GCC_JIT_BINARY_OP_PLUS, 822 823 /* Subtraction of arithmetic values; analogous to: 824 (EXPR_A) - (EXPR_B) 825 in C. */ 826 GCC_JIT_BINARY_OP_MINUS, 827 828 /* Multiplication of a pair of arithmetic values; analogous to: 829 (EXPR_A) * (EXPR_B) 830 in C. */ 831 GCC_JIT_BINARY_OP_MULT, 832 833 /* Quotient of division of arithmetic values; analogous to: 834 (EXPR_A) / (EXPR_B) 835 in C. 836 The result type affects the kind of division: if the result type is 837 integer-based, then the result is truncated towards zero, whereas 838 a floating-point result type indicates floating-point division. */ 839 GCC_JIT_BINARY_OP_DIVIDE, 840 841 /* Remainder of division of arithmetic values; analogous to: 842 (EXPR_A) % (EXPR_B) 843 in C. */ 844 GCC_JIT_BINARY_OP_MODULO, 845 846 /* Bitwise AND; analogous to: 847 (EXPR_A) & (EXPR_B) 848 in C. */ 849 GCC_JIT_BINARY_OP_BITWISE_AND, 850 851 /* Bitwise exclusive OR; analogous to: 852 (EXPR_A) ^ (EXPR_B) 853 in C. */ 854 GCC_JIT_BINARY_OP_BITWISE_XOR, 855 856 /* Bitwise inclusive OR; analogous to: 857 (EXPR_A) | (EXPR_B) 858 in C. */ 859 GCC_JIT_BINARY_OP_BITWISE_OR, 860 861 /* Logical AND; analogous to: 862 (EXPR_A) && (EXPR_B) 863 in C. */ 864 GCC_JIT_BINARY_OP_LOGICAL_AND, 865 866 /* Logical OR; analogous to: 867 (EXPR_A) || (EXPR_B) 868 in C. */ 869 GCC_JIT_BINARY_OP_LOGICAL_OR, 870 871 /* Left shift; analogous to: 872 (EXPR_A) << (EXPR_B) 873 in C. */ 874 GCC_JIT_BINARY_OP_LSHIFT, 875 876 /* Right shift; analogous to: 877 (EXPR_A) >> (EXPR_B) 878 in C. */ 879 GCC_JIT_BINARY_OP_RSHIFT 880 }; 881 882 extern gcc_jit_rvalue * 883 gcc_jit_context_new_binary_op (gcc_jit_context *ctxt, 884 gcc_jit_location *loc, 885 enum gcc_jit_binary_op op, 886 gcc_jit_type *result_type, 887 gcc_jit_rvalue *a, gcc_jit_rvalue *b); 888 889 /* (Comparisons are treated as separate from "binary_op" to save 890 you having to specify the result_type). */ 891 892 enum gcc_jit_comparison 893 { 894 /* (EXPR_A) == (EXPR_B). */ 895 GCC_JIT_COMPARISON_EQ, 896 897 /* (EXPR_A) != (EXPR_B). */ 898 GCC_JIT_COMPARISON_NE, 899 900 /* (EXPR_A) < (EXPR_B). */ 901 GCC_JIT_COMPARISON_LT, 902 903 /* (EXPR_A) <=(EXPR_B). */ 904 GCC_JIT_COMPARISON_LE, 905 906 /* (EXPR_A) > (EXPR_B). */ 907 GCC_JIT_COMPARISON_GT, 908 909 /* (EXPR_A) >= (EXPR_B). */ 910 GCC_JIT_COMPARISON_GE 911 }; 912 913 extern gcc_jit_rvalue * 914 gcc_jit_context_new_comparison (gcc_jit_context *ctxt, 915 gcc_jit_location *loc, 916 enum gcc_jit_comparison op, 917 gcc_jit_rvalue *a, gcc_jit_rvalue *b); 918 919 /* Function calls. */ 920 921 /* Call of a specific function. */ 922 extern gcc_jit_rvalue * 923 gcc_jit_context_new_call (gcc_jit_context *ctxt, 924 gcc_jit_location *loc, 925 gcc_jit_function *func, 926 int numargs , gcc_jit_rvalue **args); 927 928 /* Call through a function pointer. */ 929 extern gcc_jit_rvalue * 930 gcc_jit_context_new_call_through_ptr (gcc_jit_context *ctxt, 931 gcc_jit_location *loc, 932 gcc_jit_rvalue *fn_ptr, 933 int numargs, gcc_jit_rvalue **args); 934 935 /* Type-coercion. 936 937 Currently only a limited set of conversions are possible: 938 int <-> float 939 int <-> bool */ 940 extern gcc_jit_rvalue * 941 gcc_jit_context_new_cast (gcc_jit_context *ctxt, 942 gcc_jit_location *loc, 943 gcc_jit_rvalue *rvalue, 944 gcc_jit_type *type); 945 946 extern gcc_jit_lvalue * 947 gcc_jit_context_new_array_access (gcc_jit_context *ctxt, 948 gcc_jit_location *loc, 949 gcc_jit_rvalue *ptr, 950 gcc_jit_rvalue *index); 951 952 /* Field access is provided separately for both lvalues and rvalues. */ 953 954 /* Accessing a field of an lvalue of struct type, analogous to: 955 (EXPR).field = ...; 956 in C. */ 957 extern gcc_jit_lvalue * 958 gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_or_union, 959 gcc_jit_location *loc, 960 gcc_jit_field *field); 961 962 /* Accessing a field of an rvalue of struct type, analogous to: 963 (EXPR).field 964 in C. */ 965 extern gcc_jit_rvalue * 966 gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_or_union, 967 gcc_jit_location *loc, 968 gcc_jit_field *field); 969 970 /* Accessing a field of an rvalue of pointer type, analogous to: 971 (EXPR)->field 972 in C, itself equivalent to (*EXPR).FIELD */ 973 extern gcc_jit_lvalue * 974 gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr, 975 gcc_jit_location *loc, 976 gcc_jit_field *field); 977 978 /* Dereferencing a pointer; analogous to: 979 *(EXPR) 980 */ 981 extern gcc_jit_lvalue * 982 gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue, 983 gcc_jit_location *loc); 984 985 /* Taking the address of an lvalue; analogous to: 986 &(EXPR) 987 in C. */ 988 extern gcc_jit_rvalue * 989 gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue, 990 gcc_jit_location *loc); 991 992 extern gcc_jit_lvalue * 993 gcc_jit_function_new_local (gcc_jit_function *func, 994 gcc_jit_location *loc, 995 gcc_jit_type *type, 996 const char *name); 997 998 /********************************************************************** 999 Statement-creation. 1000 **********************************************************************/ 1001 1002 /* Add evaluation of an rvalue, discarding the result 1003 (e.g. a function call that "returns" void). 1004 1005 This is equivalent to this C code: 1006 1007 (void)expression; 1008 */ 1009 extern void 1010 gcc_jit_block_add_eval (gcc_jit_block *block, 1011 gcc_jit_location *loc, 1012 gcc_jit_rvalue *rvalue); 1013 1014 /* Add evaluation of an rvalue, assigning the result to the given 1015 lvalue. 1016 1017 This is roughly equivalent to this C code: 1018 1019 lvalue = rvalue; 1020 */ 1021 extern void 1022 gcc_jit_block_add_assignment (gcc_jit_block *block, 1023 gcc_jit_location *loc, 1024 gcc_jit_lvalue *lvalue, 1025 gcc_jit_rvalue *rvalue); 1026 1027 /* Add evaluation of an rvalue, using the result to modify an 1028 lvalue. 1029 1030 This is analogous to "+=" and friends: 1031 1032 lvalue += rvalue; 1033 lvalue *= rvalue; 1034 lvalue /= rvalue; 1035 etc */ 1036 extern void 1037 gcc_jit_block_add_assignment_op (gcc_jit_block *block, 1038 gcc_jit_location *loc, 1039 gcc_jit_lvalue *lvalue, 1040 enum gcc_jit_binary_op op, 1041 gcc_jit_rvalue *rvalue); 1042 1043 /* Add a no-op textual comment to the internal representation of the 1044 code. It will be optimized away, but will be visible in the dumps 1045 seen via 1046 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE 1047 and 1048 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1049 and thus may be of use when debugging how your project's internal 1050 representation gets converted to the libgccjit IR. */ 1051 extern void 1052 gcc_jit_block_add_comment (gcc_jit_block *block, 1053 gcc_jit_location *loc, 1054 const char *text); 1055 1056 /* Terminate a block by adding evaluation of an rvalue, branching on the 1057 result to the appropriate successor block. 1058 1059 This is roughly equivalent to this C code: 1060 1061 if (boolval) 1062 goto on_true; 1063 else 1064 goto on_false; 1065 1066 block, boolval, on_true, and on_false must be non-NULL. */ 1067 extern void 1068 gcc_jit_block_end_with_conditional (gcc_jit_block *block, 1069 gcc_jit_location *loc, 1070 gcc_jit_rvalue *boolval, 1071 gcc_jit_block *on_true, 1072 gcc_jit_block *on_false); 1073 1074 /* Terminate a block by adding a jump to the given target block. 1075 1076 This is roughly equivalent to this C code: 1077 1078 goto target; 1079 */ 1080 extern void 1081 gcc_jit_block_end_with_jump (gcc_jit_block *block, 1082 gcc_jit_location *loc, 1083 gcc_jit_block *target); 1084 1085 /* Terminate a block by adding evaluation of an rvalue, returning the value. 1086 1087 This is roughly equivalent to this C code: 1088 1089 return expression; 1090 */ 1091 extern void 1092 gcc_jit_block_end_with_return (gcc_jit_block *block, 1093 gcc_jit_location *loc, 1094 gcc_jit_rvalue *rvalue); 1095 1096 /* Terminate a block by adding a valueless return, for use within a function 1097 with "void" return type. 1098 1099 This is equivalent to this C code: 1100 1101 return; 1102 */ 1103 extern void 1104 gcc_jit_block_end_with_void_return (gcc_jit_block *block, 1105 gcc_jit_location *loc); 1106 1107 /* Create a new gcc_jit_case instance for use in a switch statement. 1108 min_value and max_value must be constants of integer type. 1109 1110 This API entrypoint was added in LIBGCCJIT_ABI_3; you can test for its 1111 presence using 1112 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS 1113 */ 1114 extern gcc_jit_case * 1115 gcc_jit_context_new_case (gcc_jit_context *ctxt, 1116 gcc_jit_rvalue *min_value, 1117 gcc_jit_rvalue *max_value, 1118 gcc_jit_block *dest_block); 1119 1120 /* Upcasting from case to object. 1121 1122 This API entrypoint was added in LIBGCCJIT_ABI_3; you can test for its 1123 presence using 1124 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS 1125 */ 1126 1127 extern gcc_jit_object * 1128 gcc_jit_case_as_object (gcc_jit_case *case_); 1129 1130 /* Terminate a block by adding evalation of an rvalue, then performing 1131 a multiway branch. 1132 1133 This is roughly equivalent to this C code: 1134 1135 switch (expr) 1136 { 1137 default: 1138 goto default_block; 1139 1140 case C0.min_value ... C0.max_value: 1141 goto C0.dest_block; 1142 1143 case C1.min_value ... C1.max_value: 1144 goto C1.dest_block; 1145 1146 ...etc... 1147 1148 case C[N - 1].min_value ... C[N - 1].max_value: 1149 goto C[N - 1].dest_block; 1150 } 1151 1152 block, expr, default_block and cases must all be non-NULL. 1153 1154 expr must be of the same integer type as all of the min_value 1155 and max_value within the cases. 1156 1157 num_cases must be >= 0. 1158 1159 The ranges of the cases must not overlap (or have duplicate 1160 values). 1161 1162 This API entrypoint was added in LIBGCCJIT_ABI_3; you can test for its 1163 presence using 1164 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS 1165 */ 1166 1167 extern void 1168 gcc_jit_block_end_with_switch (gcc_jit_block *block, 1169 gcc_jit_location *loc, 1170 gcc_jit_rvalue *expr, 1171 gcc_jit_block *default_block, 1172 int num_cases, 1173 gcc_jit_case **cases); 1174 1175 /* Pre-canned feature macro to indicate the presence of 1176 gcc_jit_block_end_with_switch, gcc_jit_case_as_object, and 1177 gcc_jit_context_new_case. 1178 1179 This can be tested for with #ifdef. */ 1180 #define LIBGCCJIT_HAVE_SWITCH_STATEMENTS 1181 1182 /********************************************************************** 1183 Nested contexts. 1184 **********************************************************************/ 1185 1186 /* Given an existing JIT context, create a child context. 1187 1188 The child inherits a copy of all option-settings from the parent. 1189 1190 The child can reference objects created within the parent, but not 1191 vice-versa. 1192 1193 The lifetime of the child context must be bounded by that of the 1194 parent: you should release a child context before releasing the parent 1195 context. 1196 1197 If you use a function from a parent context within a child context, 1198 you have to compile the parent context before you can compile the 1199 child context, and the gcc_jit_result of the parent context must 1200 outlive the gcc_jit_result of the child context. 1201 1202 This allows caching of shared initializations. For example, you could 1203 create types and declarations of global functions in a parent context 1204 once within a process, and then create child contexts whenever a 1205 function or loop becomes hot. Each such child context can be used for 1206 JIT-compiling just one function or loop, but can reference types 1207 and helper functions created within the parent context. 1208 1209 Contexts can be arbitrarily nested, provided the above rules are 1210 followed, but it's probably not worth going above 2 or 3 levels, and 1211 there will likely be a performance hit for such nesting. */ 1212 1213 extern gcc_jit_context * 1214 gcc_jit_context_new_child_context (gcc_jit_context *parent_ctxt); 1215 1216 /********************************************************************** 1217 Implementation support. 1218 **********************************************************************/ 1219 1220 /* Write C source code into "path" that can be compiled into a 1221 self-contained executable (i.e. with libgccjit as the only dependency). 1222 The generated code will attempt to replay the API calls that have been 1223 made into the given context. 1224 1225 This may be useful when debugging the library or client code, for 1226 reducing a complicated recipe for reproducing a bug into a simpler 1227 form. 1228 1229 Typically you need to supply the option "-Wno-unused-variable" when 1230 compiling the generated file (since the result of each API call is 1231 assigned to a unique variable within the generated C source, and not 1232 all are necessarily then used). */ 1233 1234 extern void 1235 gcc_jit_context_dump_reproducer_to_file (gcc_jit_context *ctxt, 1236 const char *path); 1237 1238 /* Enable the dumping of a specific set of internal state from the 1239 compilation, capturing the result in-memory as a buffer. 1240 1241 Parameter "dumpname" corresponds to the equivalent gcc command-line 1242 option, without the "-fdump-" prefix. 1243 For example, to get the equivalent of "-fdump-tree-vrp1", supply 1244 "tree-vrp1". 1245 The context directly stores the dumpname as a (const char *), so the 1246 passed string must outlive the context. 1247 1248 gcc_jit_context_compile and gcc_jit_context_to_file 1249 will capture the dump as a dynamically-allocated buffer, writing 1250 it to ``*out_ptr``. 1251 1252 The caller becomes responsible for calling 1253 free (*out_ptr) 1254 each time that gcc_jit_context_compile or gcc_jit_context_to_file 1255 are called. *out_ptr will be written to, either with the address of a 1256 buffer, or with NULL if an error occurred. 1257 1258 This API entrypoint is likely to be less stable than the others. 1259 In particular, both the precise dumpnames, and the format and content 1260 of the dumps are subject to change. 1261 1262 It exists primarily for writing the library's own test suite. */ 1263 1264 extern void 1265 gcc_jit_context_enable_dump (gcc_jit_context *ctxt, 1266 const char *dumpname, 1267 char **out_ptr); 1268 1269 #ifdef __cplusplus 1270 } 1271 #endif /* __cplusplus */ 1272 1273 #endif /* LIBGCCJIT_H */ 1274