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