gcc/jit/libgccjit.h

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