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