gcc/jit/libgccjit.h

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