gcc/jit/libgccjit.h

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