gcc/jit/libgccjit.h

   1 /* A pure C API to enable client code to embed GCC as a JIT-compiler.
   2    Copyright (C) 2013-2020 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 /* Implementation detail:
 282    libgccjit internally generates assembler, and uses "driver" code
 283    for converting it to other formats (e.g. shared libraries).
 284
 285    By default, libgccjit will use an embedded copy of the driver
 286    code.
 287
 288    This option can be used to instead invoke an external driver executable
 289    as a subprocess.
 290
 291    This entrypoint was added in LIBGCCJIT_ABI_5; you can test for
 292    its presence using
 293      #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver
 294 */
 295
 296 extern void
 297 gcc_jit_context_set_bool_use_external_driver (gcc_jit_context *ctxt,
 298                                               int bool_value);
 299
 300 /* Pre-canned feature macro to indicate the presence of
 301    gcc_jit_context_set_bool_use_external_driver.  This can be
 302    tested for with #ifdef.  */
 303 #define LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver
 304
 305 /* Add an arbitrary gcc command-line option to the context.
 306    The context takes a copy of the string, so the
 307    (const char *) optname is not needed anymore after the call
 308    returns.
 309
 310    Note that only some options are likely to be meaningful; there is no
 311    "frontend" within libgccjit, so typically only those affecting
 312    optimization and code-generation are likely to be useful.
 313
 314    This entrypoint was added in LIBGCCJIT_ABI_1; you can test for
 315    its presence using
 316    #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option
 317 */
 318
 319 extern void
 320 gcc_jit_context_add_command_line_option (gcc_jit_context *ctxt,
 321                                          const char *optname);
 322
 323 /* Pre-canned feature-test macro for detecting the presence of
 324    gcc_jit_context_add_command_line_option within libgccjit.h.  */
 325
 326 #define LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option
 327
 328 /* Add an arbitrary gcc driver option to the context.
 329    The context takes a copy of the string, so the
 330    (const char *) optname is not needed anymore after the call
 331    returns.
 332
 333    Note that only some options are likely to be meaningful; there is no
 334    "frontend" within libgccjit, so typically only those affecting
 335    assembler and linker are likely to be useful.
 336
 337    This entrypoint was added in LIBGCCJIT_ABI_11; you can test for
 338    its presence using
 339    #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_driver_option
 340 */
 341 extern void
 342 gcc_jit_context_add_driver_option (gcc_jit_context *ctxt,
 343                                    const char *optname);
 344
 345 /* Pre-canned feature-test macro for detecting the presence of
 346    gcc_jit_context_add_driver_option within libgccjit.h.  */
 347
 348 #define LIBGCCJIT_HAVE_gcc_jit_context_add_driver_option
 349
 350 /* Compile the context to in-memory machine code.
 351
 352    This can be called more that once on a given context,
 353    although any errors that occur will block further compilation.  */
 354
 355 extern gcc_jit_result *
 356 gcc_jit_context_compile (gcc_jit_context *ctxt);
 357
 358 /* Kinds of ahead-of-time compilation, for use with
 359    gcc_jit_context_compile_to_file.  */
 360
 361 enum gcc_jit_output_kind
 362 {
 363   /* Compile the context to an assembler file.  */
 364   GCC_JIT_OUTPUT_KIND_ASSEMBLER,
 365
 366   /* Compile the context to an object file.  */
 367   GCC_JIT_OUTPUT_KIND_OBJECT_FILE,
 368
 369   /* Compile the context to a dynamic library.  */
 370   GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY,
 371
 372   /* Compile the context to an executable.  */
 373   GCC_JIT_OUTPUT_KIND_EXECUTABLE
 374 };
 375
 376 /* Compile the context to a file of the given kind.
 377
 378    This can be called more that once on a given context,
 379    although any errors that occur will block further compilation.  */
 380
 381 extern void
 382 gcc_jit_context_compile_to_file (gcc_jit_context *ctxt,
 383                                  enum gcc_jit_output_kind output_kind,
 384                                  const char *output_path);
 385
 386 /* To help with debugging: dump a C-like representation to the given path,
 387    describing what's been set up on the context.
 388
 389    If "update_locations" is true, then also set up gcc_jit_location
 390    information throughout the context, pointing at the dump file as if it
 391    were a source file.  This may be of use in conjunction with
 392    GCC_JIT_BOOL_OPTION_DEBUGINFO to allow stepping through the code in a
 393    debugger.  */
 394 extern void
 395 gcc_jit_context_dump_to_file (gcc_jit_context *ctxt,
 396                               const char *path,
 397                               int update_locations);
 398
 399 /* To help with debugging; enable ongoing logging of the context's
 400    activity to the given FILE *.
 401
 402    The caller remains responsible for closing "logfile".
 403
 404    Params "flags" and "verbosity" are reserved for future use, and
 405    must both be 0 for now.  */
 406 extern void
 407 gcc_jit_context_set_logfile (gcc_jit_context *ctxt,
 408                              FILE *logfile,
 409                              int flags,
 410                              int verbosity);
 411
 412 /* To be called after any API call, this gives the first error message
 413    that occurred on the context.
 414
 415    The returned string is valid for the rest of the lifetime of the
 416    context.
 417
 418    If no errors occurred, this will be NULL.  */
 419 extern const char *
 420 gcc_jit_context_get_first_error (gcc_jit_context *ctxt);
 421
 422 /* To be called after any API call, this gives the last error message
 423    that occurred on the context.
 424
 425    If no errors occurred, this will be NULL.
 426
 427    If non-NULL, the returned string is only guaranteed to be valid until
 428    the next call to libgccjit relating to this context. */
 429 extern const char *
 430 gcc_jit_context_get_last_error (gcc_jit_context *ctxt);
 431
 432 /* Locate a given function within the built machine code.
 433    This will need to be cast to a function pointer of the
 434    correct type before it can be called. */
 435 extern void *
 436 gcc_jit_result_get_code (gcc_jit_result *result,
 437                          const char *funcname);
 438
 439 /* Locate a given global within the built machine code.
 440    It must have been created using GCC_JIT_GLOBAL_EXPORTED.
 441    This is a ptr to the global, so e.g. for an int this is an int *.  */
 442 extern void *
 443 gcc_jit_result_get_global (gcc_jit_result *result,
 444                            const char *name);
 445
 446 /* Once we're done with the code, this unloads the built .so file.
 447    This cleans up the result; after calling this, it's no longer
 448    valid to use the result.  */
 449 extern void
 450 gcc_jit_result_release (gcc_jit_result *result);
 451
 452
 453 /**********************************************************************
 454  Functions for creating "contextual" objects.
 455
 456  All objects created by these functions share the lifetime of the context
 457  they are created within, and are automatically cleaned up for you when
 458  you call gcc_jit_context_release on the context.
 459
 460  Note that this means you can't use references to them after you've
 461  released their context.
 462
 463  All (const char *) string arguments passed to these functions are
 464  copied, so you don't need to keep them around.
 465
 466  You create code by adding a sequence of statements to blocks.
 467 **********************************************************************/
 468
 469 /**********************************************************************
 470  The base class of "contextual" object.
 471  **********************************************************************/
 472 /* Which context is "obj" within?  */
 473 extern gcc_jit_context *
 474 gcc_jit_object_get_context (gcc_jit_object *obj);
 475
 476 /* Get a human-readable description of this object.
 477    The string buffer is created the first time this is called on a given
 478    object, and persists until the object's context is released.  */
 479 extern const char *
 480 gcc_jit_object_get_debug_string (gcc_jit_object *obj);
 481
 482 /**********************************************************************
 483  Debugging information.
 484  **********************************************************************/
 485
 486 /* Creating source code locations for use by the debugger.
 487    Line and column numbers are 1-based.  */
 488 extern gcc_jit_location *
 489 gcc_jit_context_new_location (gcc_jit_context *ctxt,
 490                               const char *filename,
 491                               int line,
 492                               int column);
 493
 494 /* Upcasting from location to object.  */
 495 extern gcc_jit_object *
 496 gcc_jit_location_as_object (gcc_jit_location *loc);
 497
 498
 499 /**********************************************************************
 500  Types.
 501  **********************************************************************/
 502
 503 /* Upcasting from type to object.  */
 504 extern gcc_jit_object *
 505 gcc_jit_type_as_object (gcc_jit_type *type);
 506
 507 /* Access to specific types.  */
 508 enum gcc_jit_types
 509 {
 510   /* C's "void" type.  */
 511   GCC_JIT_TYPE_VOID,
 512
 513   /* "void *".  */
 514   GCC_JIT_TYPE_VOID_PTR,
 515
 516   /* C++'s bool type; also C99's "_Bool" type, aka "bool" if using
 517      stdbool.h.  */
 518   GCC_JIT_TYPE_BOOL,
 519
 520   /* Various integer types.  */
 521
 522   /* C's "char" (of some signedness) and the variants where the
 523      signedness is specified.  */
 524   GCC_JIT_TYPE_CHAR,
 525   GCC_JIT_TYPE_SIGNED_CHAR,
 526   GCC_JIT_TYPE_UNSIGNED_CHAR,
 527
 528   /* C's "short" and "unsigned short".  */
 529   GCC_JIT_TYPE_SHORT, /* signed */
 530   GCC_JIT_TYPE_UNSIGNED_SHORT,
 531
 532   /* C's "int" and "unsigned int".  */
 533   GCC_JIT_TYPE_INT, /* signed */
 534   GCC_JIT_TYPE_UNSIGNED_INT,
 535
 536   /* C's "long" and "unsigned long".  */
 537   GCC_JIT_TYPE_LONG, /* signed */
 538   GCC_JIT_TYPE_UNSIGNED_LONG,
 539
 540   /* C99's "long long" and "unsigned long long".  */
 541   GCC_JIT_TYPE_LONG_LONG, /* signed */
 542   GCC_JIT_TYPE_UNSIGNED_LONG_LONG,
 543
 544   /* Floating-point types  */
 545
 546   GCC_JIT_TYPE_FLOAT,
 547   GCC_JIT_TYPE_DOUBLE,
 548   GCC_JIT_TYPE_LONG_DOUBLE,
 549
 550   /* C type: (const char *).  */
 551   GCC_JIT_TYPE_CONST_CHAR_PTR,
 552
 553  /* The C "size_t" type.  */
 554   GCC_JIT_TYPE_SIZE_T,
 555
 556  /* C type: (FILE *)  */
 557   GCC_JIT_TYPE_FILE_PTR,
 558
 559   /* Complex numbers.  */
 560   GCC_JIT_TYPE_COMPLEX_FLOAT,
 561   GCC_JIT_TYPE_COMPLEX_DOUBLE,
 562   GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE
 563
 564 };
 565
 566 extern gcc_jit_type *
 567 gcc_jit_context_get_type (gcc_jit_context *ctxt,
 568                           enum gcc_jit_types type_);
 569
 570 /* Get the integer type of the given size and signedness.  */
 571 extern gcc_jit_type *
 572 gcc_jit_context_get_int_type (gcc_jit_context *ctxt,
 573                               int num_bytes, int is_signed);
 574
 575 /* Constructing new types. */
 576
 577 /* Given type "T", get type "T*".  */
 578 extern gcc_jit_type *
 579 gcc_jit_type_get_pointer (gcc_jit_type *type);
 580
 581 /* Given type "T", get type "const T".  */
 582 extern gcc_jit_type *
 583 gcc_jit_type_get_const (gcc_jit_type *type);
 584
 585 /* Given type "T", get type "volatile T".  */
 586 extern gcc_jit_type *
 587 gcc_jit_type_get_volatile (gcc_jit_type *type);
 588
 589 /* Given type "T", get type "T[N]" (for a constant N).  */
 590 extern gcc_jit_type *
 591 gcc_jit_context_new_array_type (gcc_jit_context *ctxt,
 592                                 gcc_jit_location *loc,
 593                                 gcc_jit_type *element_type,
 594                                 int num_elements);
 595
 596 /* Struct-handling.  */
 597
 598 /* Create a field, for use within a struct or union.  */
 599 extern gcc_jit_field *
 600 gcc_jit_context_new_field (gcc_jit_context *ctxt,
 601                            gcc_jit_location *loc,
 602                            gcc_jit_type *type,
 603                            const char *name);
 604
 605 #define LIBGCCJIT_HAVE_gcc_jit_context_new_bitfield
 606
 607 /* Create a bit field, for use within a struct or union.
 608
 609    This API entrypoint was added in LIBGCCJIT_ABI_12; you can test for its
 610    presence using
 611      #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitfield
 612 */
 613 extern gcc_jit_field *
 614 gcc_jit_context_new_bitfield (gcc_jit_context *ctxt,
 615                               gcc_jit_location *loc,
 616                               gcc_jit_type *type,
 617                               int width,
 618                               const char *name);
 619
 620 /* Upcasting from field to object.  */
 621 extern gcc_jit_object *
 622 gcc_jit_field_as_object (gcc_jit_field *field);
 623
 624 /* Create a struct type from an array of fields.  */
 625 extern gcc_jit_struct *
 626 gcc_jit_context_new_struct_type (gcc_jit_context *ctxt,
 627                                  gcc_jit_location *loc,
 628                                  const char *name,
 629                                  int num_fields,
 630                                  gcc_jit_field **fields);
 631
 632 /* Create an opaque struct type.  */
 633 extern gcc_jit_struct *
 634 gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt,
 635                                    gcc_jit_location *loc,
 636                                    const char *name);
 637
 638 /* Upcast a struct to a type.  */
 639 extern gcc_jit_type *
 640 gcc_jit_struct_as_type (gcc_jit_struct *struct_type);
 641
 642 /* Populating the fields of a formerly-opaque struct type.
 643    This can only be called once on a given struct type.  */
 644 extern void
 645 gcc_jit_struct_set_fields (gcc_jit_struct *struct_type,
 646                            gcc_jit_location *loc,
 647                            int num_fields,
 648                            gcc_jit_field **fields);
 649
 650 /* Unions work similarly to structs.  */
 651 extern gcc_jit_type *
 652 gcc_jit_context_new_union_type (gcc_jit_context *ctxt,
 653                                 gcc_jit_location *loc,
 654                                 const char *name,
 655                                 int num_fields,
 656                                 gcc_jit_field **fields);
 657
 658 /* Function pointers. */
 659
 660 extern gcc_jit_type *
 661 gcc_jit_context_new_function_ptr_type (gcc_jit_context *ctxt,
 662                                        gcc_jit_location *loc,
 663                                        gcc_jit_type *return_type,
 664                                        int num_params,
 665                                        gcc_jit_type **param_types,
 666                                        int is_variadic);
 667
 668 /**********************************************************************
 669  Constructing functions.
 670  **********************************************************************/
 671 /* Create a function param.  */
 672 extern gcc_jit_param *
 673 gcc_jit_context_new_param (gcc_jit_context *ctxt,
 674                            gcc_jit_location *loc,
 675                            gcc_jit_type *type,
 676                            const char *name);
 677
 678 /* Upcasting from param to object.  */
 679 extern gcc_jit_object *
 680 gcc_jit_param_as_object (gcc_jit_param *param);
 681
 682 /* Upcasting from param to lvalue.  */
 683 extern gcc_jit_lvalue *
 684 gcc_jit_param_as_lvalue (gcc_jit_param *param);
 685
 686 /* Upcasting from param to rvalue.  */
 687 extern gcc_jit_rvalue *
 688 gcc_jit_param_as_rvalue (gcc_jit_param *param);
 689
 690 /* Kinds of function.  */
 691 enum gcc_jit_function_kind
 692 {
 693   /* Function is defined by the client code and visible
 694      by name outside of the JIT.  */
 695   GCC_JIT_FUNCTION_EXPORTED,
 696
 697   /* Function is defined by the client code, but is invisible
 698      outside of the JIT.  Analogous to a "static" function.  */
 699   GCC_JIT_FUNCTION_INTERNAL,
 700
 701   /* Function is not defined by the client code; we're merely
 702      referring to it.  Analogous to using an "extern" function from a
 703      header file.  */
 704   GCC_JIT_FUNCTION_IMPORTED,
 705
 706   /* Function is only ever inlined into other functions, and is
 707      invisible outside of the JIT.
 708
 709      Analogous to prefixing with "inline" and adding
 710      __attribute__((always_inline)).
 711
 712      Inlining will only occur when the optimization level is
 713      above 0; when optimization is off, this is essentially the
 714      same as GCC_JIT_FUNCTION_INTERNAL.  */
 715   GCC_JIT_FUNCTION_ALWAYS_INLINE
 716 };
 717
 718 /* Create a function.  */
 719 extern gcc_jit_function *
 720 gcc_jit_context_new_function (gcc_jit_context *ctxt,
 721                               gcc_jit_location *loc,
 722                               enum gcc_jit_function_kind kind,
 723                               gcc_jit_type *return_type,
 724                               const char *name,
 725                               int num_params,
 726                               gcc_jit_param **params,
 727                               int is_variadic);
 728
 729 /* Create a reference to a builtin function (sometimes called
 730    intrinsic functions).  */
 731 extern gcc_jit_function *
 732 gcc_jit_context_get_builtin_function (gcc_jit_context *ctxt,
 733                                       const char *name);
 734
 735 /* Upcasting from function to object.  */
 736 extern gcc_jit_object *
 737 gcc_jit_function_as_object (gcc_jit_function *func);
 738
 739 /* Get a specific param of a function by index.  */
 740 extern gcc_jit_param *
 741 gcc_jit_function_get_param (gcc_jit_function *func, int index);
 742
 743 /* Emit the function in graphviz format.  */
 744 extern void
 745 gcc_jit_function_dump_to_dot (gcc_jit_function *func,
 746                               const char *path);
 747
 748 /* Create a block.
 749
 750    The name can be NULL, or you can give it a meaningful name, which
 751    may show up in dumps of the internal representation, and in error
 752    messages.  */
 753 extern gcc_jit_block *
 754 gcc_jit_function_new_block (gcc_jit_function *func,
 755                             const char *name);
 756
 757 /* Upcasting from block to object.  */
 758 extern gcc_jit_object *
 759 gcc_jit_block_as_object (gcc_jit_block *block);
 760
 761 /* Which function is this block within?  */
 762 extern gcc_jit_function *
 763 gcc_jit_block_get_function (gcc_jit_block *block);
 764
 765 /**********************************************************************
 766  lvalues, rvalues and expressions.
 767  **********************************************************************/
 768 enum gcc_jit_global_kind
 769 {
 770   /* Global is defined by the client code and visible
 771      by name outside of this JIT context via gcc_jit_result_get_global.  */
 772   GCC_JIT_GLOBAL_EXPORTED,
 773
 774   /* Global is defined by the client code, but is invisible
 775      outside of this JIT context.  Analogous to a "static" global.  */
 776   GCC_JIT_GLOBAL_INTERNAL,
 777
 778   /* Global is not defined by the client code; we're merely
 779      referring to it.  Analogous to using an "extern" global from a
 780      header file.  */
 781   GCC_JIT_GLOBAL_IMPORTED
 782 };
 783
 784 extern gcc_jit_lvalue *
 785 gcc_jit_context_new_global (gcc_jit_context *ctxt,
 786                             gcc_jit_location *loc,
 787                             enum gcc_jit_global_kind kind,
 788                             gcc_jit_type *type,
 789                             const char *name);
 790
 791 /* Upcasting.  */
 792 extern gcc_jit_object *
 793 gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue);
 794
 795 extern gcc_jit_rvalue *
 796 gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue);
 797
 798 extern gcc_jit_object *
 799 gcc_jit_rvalue_as_object (gcc_jit_rvalue *rvalue);
 800
 801 extern gcc_jit_type *
 802 gcc_jit_rvalue_get_type (gcc_jit_rvalue *rvalue);
 803
 804 /* Integer constants. */
 805 extern gcc_jit_rvalue *
 806 gcc_jit_context_new_rvalue_from_int (gcc_jit_context *ctxt,
 807                                      gcc_jit_type *numeric_type,
 808                                      int value);
 809
 810 extern gcc_jit_rvalue *
 811 gcc_jit_context_new_rvalue_from_long (gcc_jit_context *ctxt,
 812                                       gcc_jit_type *numeric_type,
 813                                       long value);
 814
 815 extern gcc_jit_rvalue *
 816 gcc_jit_context_zero (gcc_jit_context *ctxt,
 817                       gcc_jit_type *numeric_type);
 818
 819 extern gcc_jit_rvalue *
 820 gcc_jit_context_one (gcc_jit_context *ctxt,
 821                      gcc_jit_type *numeric_type);
 822
 823 /* Floating-point constants.  */
 824 extern gcc_jit_rvalue *
 825 gcc_jit_context_new_rvalue_from_double (gcc_jit_context *ctxt,
 826                                         gcc_jit_type *numeric_type,
 827                                         double value);
 828
 829 /* Pointers.  */
 830 extern gcc_jit_rvalue *
 831 gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt,
 832                                      gcc_jit_type *pointer_type,
 833                                      void *value);
 834
 835 extern gcc_jit_rvalue *
 836 gcc_jit_context_null (gcc_jit_context *ctxt,
 837                       gcc_jit_type *pointer_type);
 838
 839 /* String literals. */
 840 extern gcc_jit_rvalue *
 841 gcc_jit_context_new_string_literal (gcc_jit_context *ctxt,
 842                                     const char *value);
 843
 844 enum gcc_jit_unary_op
 845 {
 846   /* Negate an arithmetic value; analogous to:
 847        -(EXPR)
 848      in C.  */
 849   GCC_JIT_UNARY_OP_MINUS,
 850
 851   /* Bitwise negation of an integer value (one's complement); analogous
 852      to:
 853        ~(EXPR)
 854      in C.  */
 855   GCC_JIT_UNARY_OP_BITWISE_NEGATE,
 856
 857   /* Logical negation of an arithmetic or pointer value; analogous to:
 858        !(EXPR)
 859      in C.  */
 860   GCC_JIT_UNARY_OP_LOGICAL_NEGATE,
 861
 862   /* Absolute value of an arithmetic expression; analogous to:
 863        abs (EXPR)
 864      in C.  */
 865   GCC_JIT_UNARY_OP_ABS
 866
 867 };
 868
 869 extern gcc_jit_rvalue *
 870 gcc_jit_context_new_unary_op (gcc_jit_context *ctxt,
 871                               gcc_jit_location *loc,
 872                               enum gcc_jit_unary_op op,
 873                               gcc_jit_type *result_type,
 874                               gcc_jit_rvalue *rvalue);
 875
 876 enum gcc_jit_binary_op
 877 {
 878   /* Addition of arithmetic values; analogous to:
 879        (EXPR_A) + (EXPR_B)
 880      in C.
 881      For pointer addition, use gcc_jit_context_new_array_access.  */
 882   GCC_JIT_BINARY_OP_PLUS,
 883
 884   /* Subtraction of arithmetic values; analogous to:
 885        (EXPR_A) - (EXPR_B)
 886      in C.  */
 887   GCC_JIT_BINARY_OP_MINUS,
 888
 889   /* Multiplication of a pair of arithmetic values; analogous to:
 890        (EXPR_A) * (EXPR_B)
 891      in C.  */
 892   GCC_JIT_BINARY_OP_MULT,
 893
 894   /* Quotient of division of arithmetic values; analogous to:
 895        (EXPR_A) / (EXPR_B)
 896      in C.
 897      The result type affects the kind of division: if the result type is
 898      integer-based, then the result is truncated towards zero, whereas
 899      a floating-point result type indicates floating-point division.  */
 900   GCC_JIT_BINARY_OP_DIVIDE,
 901
 902   /* Remainder of division of arithmetic values; analogous to:
 903        (EXPR_A) % (EXPR_B)
 904      in C.  */
 905   GCC_JIT_BINARY_OP_MODULO,
 906
 907   /* Bitwise AND; analogous to:
 908        (EXPR_A) & (EXPR_B)
 909      in C.  */
 910   GCC_JIT_BINARY_OP_BITWISE_AND,
 911
 912   /* Bitwise exclusive OR; analogous to:
 913        (EXPR_A) ^ (EXPR_B)
 914      in C.  */
 915   GCC_JIT_BINARY_OP_BITWISE_XOR,
 916
 917   /* Bitwise inclusive OR; analogous to:
 918        (EXPR_A) | (EXPR_B)
 919      in C.  */
 920   GCC_JIT_BINARY_OP_BITWISE_OR,
 921
 922   /* Logical AND; analogous to:
 923        (EXPR_A) && (EXPR_B)
 924      in C.  */
 925   GCC_JIT_BINARY_OP_LOGICAL_AND,
 926
 927   /* Logical OR; analogous to:
 928        (EXPR_A) || (EXPR_B)
 929      in C.  */
 930   GCC_JIT_BINARY_OP_LOGICAL_OR,
 931
 932   /* Left shift; analogous to:
 933        (EXPR_A) << (EXPR_B)
 934      in C.  */
 935   GCC_JIT_BINARY_OP_LSHIFT,
 936
 937   /* Right shift; analogous to:
 938        (EXPR_A) >> (EXPR_B)
 939      in C.  */
 940   GCC_JIT_BINARY_OP_RSHIFT
 941 };
 942
 943 extern gcc_jit_rvalue *
 944 gcc_jit_context_new_binary_op (gcc_jit_context *ctxt,
 945                                gcc_jit_location *loc,
 946                                enum gcc_jit_binary_op op,
 947                                gcc_jit_type *result_type,
 948                                gcc_jit_rvalue *a, gcc_jit_rvalue *b);
 949
 950 /* (Comparisons are treated as separate from "binary_op" to save
 951    you having to specify the result_type).  */
 952
 953 enum gcc_jit_comparison
 954 {
 955   /* (EXPR_A) == (EXPR_B).  */
 956   GCC_JIT_COMPARISON_EQ,
 957
 958   /* (EXPR_A) != (EXPR_B).  */
 959   GCC_JIT_COMPARISON_NE,
 960
 961   /* (EXPR_A) < (EXPR_B).  */
 962   GCC_JIT_COMPARISON_LT,
 963
 964   /* (EXPR_A) <=(EXPR_B).  */
 965   GCC_JIT_COMPARISON_LE,
 966
 967   /* (EXPR_A) > (EXPR_B).  */
 968   GCC_JIT_COMPARISON_GT,
 969
 970   /* (EXPR_A) >= (EXPR_B).  */
 971   GCC_JIT_COMPARISON_GE
 972 };
 973
 974 extern gcc_jit_rvalue *
 975 gcc_jit_context_new_comparison (gcc_jit_context *ctxt,
 976                                 gcc_jit_location *loc,
 977                                 enum gcc_jit_comparison op,
 978                                 gcc_jit_rvalue *a, gcc_jit_rvalue *b);
 979
 980 /* Function calls.  */
 981
 982 /* Call of a specific function.  */
 983 extern gcc_jit_rvalue *
 984 gcc_jit_context_new_call (gcc_jit_context *ctxt,
 985                           gcc_jit_location *loc,
 986                           gcc_jit_function *func,
 987                           int numargs , gcc_jit_rvalue **args);
 988
 989 /* Call through a function pointer.  */
 990 extern gcc_jit_rvalue *
 991 gcc_jit_context_new_call_through_ptr (gcc_jit_context *ctxt,
 992                                       gcc_jit_location *loc,
 993                                       gcc_jit_rvalue *fn_ptr,
 994                                       int numargs, gcc_jit_rvalue **args);
 995
 996 /* Type-coercion.
 997
 998    Currently only a limited set of conversions are possible:
 999      int <-> float
1000      int <-> bool  */
1001 extern gcc_jit_rvalue *
1002 gcc_jit_context_new_cast (gcc_jit_context *ctxt,
1003                           gcc_jit_location *loc,
1004                           gcc_jit_rvalue *rvalue,
1005                           gcc_jit_type *type);
1006
1007 extern gcc_jit_lvalue *
1008 gcc_jit_context_new_array_access (gcc_jit_context *ctxt,
1009                                   gcc_jit_location *loc,
1010                                   gcc_jit_rvalue *ptr,
1011                                   gcc_jit_rvalue *index);
1012
1013 /* Field access is provided separately for both lvalues and rvalues.  */
1014
1015 /* Accessing a field of an lvalue of struct type, analogous to:
1016       (EXPR).field = ...;
1017    in C.  */
1018 extern gcc_jit_lvalue *
1019 gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_or_union,
1020                              gcc_jit_location *loc,
1021                              gcc_jit_field *field);
1022
1023 /* Accessing a field of an rvalue of struct type, analogous to:
1024       (EXPR).field
1025    in C.  */
1026 extern gcc_jit_rvalue *
1027 gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_or_union,
1028                              gcc_jit_location *loc,
1029                              gcc_jit_field *field);
1030
1031 /* Accessing a field of an rvalue of pointer type, analogous to:
1032       (EXPR)->field
1033    in C, itself equivalent to (*EXPR).FIELD  */
1034 extern gcc_jit_lvalue *
1035 gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr,
1036                                   gcc_jit_location *loc,
1037                                   gcc_jit_field *field);
1038
1039 /* Dereferencing a pointer; analogous to:
1040      *(EXPR)
1041 */
1042 extern gcc_jit_lvalue *
1043 gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue,
1044                             gcc_jit_location *loc);
1045
1046 /* Taking the address of an lvalue; analogous to:
1047      &(EXPR)
1048    in C.  */
1049 extern gcc_jit_rvalue *
1050 gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue,
1051                             gcc_jit_location *loc);
1052
1053 extern gcc_jit_lvalue *
1054 gcc_jit_function_new_local (gcc_jit_function *func,
1055                             gcc_jit_location *loc,
1056                             gcc_jit_type *type,
1057                             const char *name);
1058
1059 /**********************************************************************
1060  Statement-creation.
1061  **********************************************************************/
1062
1063 /* Add evaluation of an rvalue, discarding the result
1064    (e.g. a function call that "returns" void).
1065
1066    This is equivalent to this C code:
1067
1068      (void)expression;
1069 */
1070 extern void
1071 gcc_jit_block_add_eval (gcc_jit_block *block,
1072                         gcc_jit_location *loc,
1073                         gcc_jit_rvalue *rvalue);
1074
1075 /* Add evaluation of an rvalue, assigning the result to the given
1076    lvalue.
1077
1078    This is roughly equivalent to this C code:
1079
1080      lvalue = rvalue;
1081 */
1082 extern void
1083 gcc_jit_block_add_assignment (gcc_jit_block *block,
1084                               gcc_jit_location *loc,
1085                               gcc_jit_lvalue *lvalue,
1086                               gcc_jit_rvalue *rvalue);
1087
1088 /* Add evaluation of an rvalue, using the result to modify an
1089    lvalue.
1090
1091    This is analogous to "+=" and friends:
1092
1093      lvalue += rvalue;
1094      lvalue *= rvalue;
1095      lvalue /= rvalue;
1096    etc  */
1097 extern void
1098 gcc_jit_block_add_assignment_op (gcc_jit_block *block,
1099                                  gcc_jit_location *loc,
1100                                  gcc_jit_lvalue *lvalue,
1101                                  enum gcc_jit_binary_op op,
1102                                  gcc_jit_rvalue *rvalue);
1103
1104 /* Add a no-op textual comment to the internal representation of the
1105    code.  It will be optimized away, but will be visible in the dumps
1106    seen via
1107      GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE
1108    and
1109      GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE,
1110    and thus may be of use when debugging how your project's internal
1111    representation gets converted to the libgccjit IR.  */
1112 extern void
1113 gcc_jit_block_add_comment (gcc_jit_block *block,
1114                            gcc_jit_location *loc,
1115                            const char *text);
1116
1117 /* Terminate a block by adding evaluation of an rvalue, branching on the
1118    result to the appropriate successor block.
1119
1120    This is roughly equivalent to this C code:
1121
1122      if (boolval)
1123        goto on_true;
1124      else
1125        goto on_false;
1126
1127    block, boolval, on_true, and on_false must be non-NULL.  */
1128 extern void
1129 gcc_jit_block_end_with_conditional (gcc_jit_block *block,
1130                                     gcc_jit_location *loc,
1131                                     gcc_jit_rvalue *boolval,
1132                                     gcc_jit_block *on_true,
1133                                     gcc_jit_block *on_false);
1134
1135 /* Terminate a block by adding a jump to the given target block.
1136
1137    This is roughly equivalent to this C code:
1138
1139       goto target;
1140 */
1141 extern void
1142 gcc_jit_block_end_with_jump (gcc_jit_block *block,
1143                              gcc_jit_location *loc,
1144                              gcc_jit_block *target);
1145
1146 /* Terminate a block by adding evaluation of an rvalue, returning the value.
1147
1148    This is roughly equivalent to this C code:
1149
1150       return expression;
1151 */
1152 extern void
1153 gcc_jit_block_end_with_return (gcc_jit_block *block,
1154                                gcc_jit_location *loc,
1155                                gcc_jit_rvalue *rvalue);
1156
1157 /* Terminate a block by adding a valueless return, for use within a function
1158    with "void" return type.
1159
1160    This is equivalent to this C code:
1161
1162       return;
1163 */
1164 extern void
1165 gcc_jit_block_end_with_void_return (gcc_jit_block *block,
1166                                     gcc_jit_location *loc);
1167
1168 /* Create a new gcc_jit_case instance for use in a switch statement.
1169    min_value and max_value must be constants of integer type.
1170
1171    This API entrypoint was added in LIBGCCJIT_ABI_3; you can test for its
1172    presence using
1173      #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS
1174 */
1175 extern gcc_jit_case *
1176 gcc_jit_context_new_case (gcc_jit_context *ctxt,
1177                           gcc_jit_rvalue *min_value,
1178                           gcc_jit_rvalue *max_value,
1179                           gcc_jit_block *dest_block);
1180
1181 /* Upcasting from case to object.
1182
1183    This API entrypoint was added in LIBGCCJIT_ABI_3; you can test for its
1184    presence using
1185      #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS
1186 */
1187
1188 extern gcc_jit_object *
1189 gcc_jit_case_as_object (gcc_jit_case *case_);
1190
1191 /* Terminate a block by adding evalation of an rvalue, then performing
1192    a multiway branch.
1193
1194    This is roughly equivalent to this C code:
1195
1196      switch (expr)
1197        {
1198        default:
1199          goto default_block;
1200
1201        case C0.min_value ... C0.max_value:
1202          goto C0.dest_block;
1203
1204        case C1.min_value ... C1.max_value:
1205          goto C1.dest_block;
1206
1207        ...etc...
1208
1209        case C[N - 1].min_value ... C[N - 1].max_value:
1210          goto C[N - 1].dest_block;
1211      }
1212
1213    block, expr, default_block and cases must all be non-NULL.
1214
1215    expr must be of the same integer type as all of the min_value
1216    and max_value within the cases.
1217
1218    num_cases must be >= 0.
1219
1220    The ranges of the cases must not overlap (or have duplicate
1221    values).
1222
1223    This API entrypoint was added in LIBGCCJIT_ABI_3; you can test for its
1224    presence using
1225      #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS
1226 */
1227
1228 extern void
1229 gcc_jit_block_end_with_switch (gcc_jit_block *block,
1230                                gcc_jit_location *loc,
1231                                gcc_jit_rvalue *expr,
1232                                gcc_jit_block *default_block,
1233                                int num_cases,
1234                                gcc_jit_case **cases);
1235
1236 /* Pre-canned feature macro to indicate the presence of
1237    gcc_jit_block_end_with_switch, gcc_jit_case_as_object, and
1238    gcc_jit_context_new_case.
1239
1240    This can be tested for with #ifdef.  */
1241 #define LIBGCCJIT_HAVE_SWITCH_STATEMENTS
1242
1243 /**********************************************************************
1244  Nested contexts.
1245  **********************************************************************/
1246
1247 /* Given an existing JIT context, create a child context.
1248
1249    The child inherits a copy of all option-settings from the parent.
1250
1251    The child can reference objects created within the parent, but not
1252    vice-versa.
1253
1254    The lifetime of the child context must be bounded by that of the
1255    parent: you should release a child context before releasing the parent
1256    context.
1257
1258    If you use a function from a parent context within a child context,
1259    you have to compile the parent context before you can compile the
1260    child context, and the gcc_jit_result of the parent context must
1261    outlive the gcc_jit_result of the child context.
1262
1263    This allows caching of shared initializations.  For example, you could
1264    create types and declarations of global functions in a parent context
1265    once within a process, and then create child contexts whenever a
1266    function or loop becomes hot. Each such child context can be used for
1267    JIT-compiling just one function or loop, but can reference types
1268    and helper functions created within the parent context.
1269
1270    Contexts can be arbitrarily nested, provided the above rules are
1271    followed, but it's probably not worth going above 2 or 3 levels, and
1272    there will likely be a performance hit for such nesting.  */
1273
1274 extern gcc_jit_context *
1275 gcc_jit_context_new_child_context (gcc_jit_context *parent_ctxt);
1276
1277 /**********************************************************************
1278  Implementation support.
1279  **********************************************************************/
1280
1281 /* Write C source code into "path" that can be compiled into a
1282    self-contained executable (i.e. with libgccjit as the only dependency).
1283    The generated code will attempt to replay the API calls that have been
1284    made into the given context.
1285
1286    This may be useful when debugging the library or client code, for
1287    reducing a complicated recipe for reproducing a bug into a simpler
1288    form.
1289
1290    Typically you need to supply the option "-Wno-unused-variable" when
1291    compiling the generated file (since the result of each API call is
1292    assigned to a unique variable within the generated C source, and not
1293    all are necessarily then used).  */
1294
1295 extern void
1296 gcc_jit_context_dump_reproducer_to_file (gcc_jit_context *ctxt,
1297                                          const char *path);
1298
1299 /* Enable the dumping of a specific set of internal state from the
1300    compilation, capturing the result in-memory as a buffer.
1301
1302    Parameter "dumpname" corresponds to the equivalent gcc command-line
1303    option, without the "-fdump-" prefix.
1304    For example, to get the equivalent of "-fdump-tree-vrp1", supply
1305    "tree-vrp1".
1306    The context directly stores the dumpname as a (const char *), so the
1307    passed string must outlive the context.
1308
1309    gcc_jit_context_compile and gcc_jit_context_to_file
1310    will capture the dump as a dynamically-allocated buffer, writing
1311    it to ``*out_ptr``.
1312
1313    The caller becomes responsible for calling
1314       free (*out_ptr)
1315    each time that gcc_jit_context_compile or gcc_jit_context_to_file
1316    are called.  *out_ptr will be written to, either with the address of a
1317    buffer, or with NULL if an error occurred.
1318
1319    This API entrypoint is likely to be less stable than the others.
1320    In particular, both the precise dumpnames, and the format and content
1321    of the dumps are subject to change.
1322
1323    It exists primarily for writing the library's own test suite.  */
1324
1325 extern void
1326 gcc_jit_context_enable_dump (gcc_jit_context *ctxt,
1327                              const char *dumpname,
1328                              char **out_ptr);
1329
1330 /**********************************************************************
1331  Timing support.
1332  **********************************************************************/
1333
1334 /* The timing API was added in LIBGCCJIT_ABI_4; you can test for its
1335    presence using
1336      #ifdef LIBGCCJIT_HAVE_TIMING_API
1337 */
1338 #define LIBGCCJIT_HAVE_TIMING_API
1339
1340 typedef struct gcc_jit_timer gcc_jit_timer;
1341
1342 /* Create a gcc_jit_timer instance, and start timing.
1343
1344    This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
1345    presence using
1346      #ifdef LIBGCCJIT_HAVE_TIMING_API
1347 */
1348 extern gcc_jit_timer *
1349 gcc_jit_timer_new (void);
1350
1351 /* Release a gcc_jit_timer instance.
1352
1353    This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
1354    presence using
1355      #ifdef LIBGCCJIT_HAVE_TIMING_API
1356 */
1357 extern void
1358 gcc_jit_timer_release (gcc_jit_timer *timer);
1359
1360 /* Associate a gcc_jit_timer instance with a context.
1361
1362    This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
1363    presence using
1364      #ifdef LIBGCCJIT_HAVE_TIMING_API
1365 */
1366 extern void
1367 gcc_jit_context_set_timer (gcc_jit_context *ctxt,
1368                            gcc_jit_timer *timer);
1369
1370 /* Get the timer associated with a context (if any).
1371
1372    This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
1373    presence using
1374      #ifdef LIBGCCJIT_HAVE_TIMING_API
1375 */
1376
1377 extern gcc_jit_timer *
1378 gcc_jit_context_get_timer (gcc_jit_context *ctxt);
1379
1380 /* Push the given item onto the timing stack.
1381
1382    This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
1383    presence using
1384      #ifdef LIBGCCJIT_HAVE_TIMING_API
1385 */
1386
1387 extern void
1388 gcc_jit_timer_push (gcc_jit_timer *timer,
1389                     const char *item_name);
1390
1391 /* Pop the top item from the timing stack.
1392
1393    This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
1394    presence using
1395      #ifdef LIBGCCJIT_HAVE_TIMING_API
1396 */
1397
1398 extern void
1399 gcc_jit_timer_pop (gcc_jit_timer *timer,
1400                    const char *item_name);
1401
1402 /* Print timing information to the given stream about activity since
1403    the timer was started.
1404
1405    This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
1406    presence using
1407      #ifdef LIBGCCJIT_HAVE_TIMING_API
1408 */
1409
1410 extern void
1411 gcc_jit_timer_print (gcc_jit_timer *timer,
1412                      FILE *f_out);
1413
1414
1415 #define LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call
1416
1417 /* Mark/clear a call as needing tail-call optimization.
1418
1419    This API entrypoint was added in LIBGCCJIT_ABI_6; you can test for its
1420    presence using
1421      #ifdef LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call
1422 */
1423 extern void
1424 gcc_jit_rvalue_set_bool_require_tail_call (gcc_jit_rvalue *call,
1425                                            int require_tail_call);
1426
1427 #define LIBGCCJIT_HAVE_gcc_jit_type_get_aligned
1428
1429 /* Given type "T", get type:
1430
1431      T __attribute__ ((aligned (ALIGNMENT_IN_BYTES)))
1432
1433    The alignment must be a power of two.
1434
1435    This API entrypoint was added in LIBGCCJIT_ABI_7; you can test for its
1436    presence using
1437      #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_aligned
1438 */
1439 extern gcc_jit_type *
1440 gcc_jit_type_get_aligned (gcc_jit_type *type,
1441                           size_t alignment_in_bytes);
1442
1443 #define LIBGCCJIT_HAVE_gcc_jit_type_get_vector
1444
1445 /* Given type "T", get type:
1446
1447      T  __attribute__ ((vector_size (sizeof(T) * num_units))
1448
1449    T must be integral/floating point; num_units must be a power of two.
1450
1451    This API entrypoint was added in LIBGCCJIT_ABI_8; you can test for its
1452    presence using
1453      #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_vector
1454 */
1455 extern gcc_jit_type *
1456 gcc_jit_type_get_vector (gcc_jit_type *type, size_t num_units);
1457
1458
1459 #define LIBGCCJIT_HAVE_gcc_jit_function_get_address
1460
1461 /* Get the address of a function as an rvalue, of function pointer
1462    type.
1463
1464    This API entrypoint was added in LIBGCCJIT_ABI_9; you can test for its
1465    presence using
1466      #ifdef LIBGCCJIT_HAVE_gcc_jit_function_get_address
1467 */
1468 extern gcc_jit_rvalue *
1469 gcc_jit_function_get_address (gcc_jit_function *fn,
1470                               gcc_jit_location *loc);
1471
1472
1473 #define LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector
1474
1475 /* Build a vector rvalue from an array of elements.
1476
1477    "vec_type" should be a vector type, created using gcc_jit_type_get_vector.
1478
1479    This API entrypoint was added in LIBGCCJIT_ABI_10; you can test for its
1480    presence using
1481      #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector
1482 */
1483 extern gcc_jit_rvalue *
1484 gcc_jit_context_new_rvalue_from_vector (gcc_jit_context *ctxt,
1485                                         gcc_jit_location *loc,
1486                                         gcc_jit_type *vec_type,
1487                                         size_t num_elements,
1488                                         gcc_jit_rvalue **elements);
1489
1490 #define LIBGCCJIT_HAVE_gcc_jit_version
1491
1492 /* Functions to retrive libgccjit version.
1493    Analogous to __GNUC__, __GNUC_MINOR__, __GNUC_PATCHLEVEL__ in C code.
1494
1495    These API entrypoints were added in LIBGCCJIT_ABI_13; you can test for their
1496    presence using
1497      #ifdef LIBGCCJIT_HAVE_gcc_jit_version
1498  */
1499 extern int
1500 gcc_jit_version_major (void);
1501 extern int
1502 gcc_jit_version_minor (void);
1503 extern int
1504 gcc_jit_version_patchlevel (void);
1505
1506 #ifdef __cplusplus
1507 }
1508 #endif /* __cplusplus */
1509
1510 #endif  /* LIBGCCJIT_H  */