gcc/jit/libgccjit.h

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