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