gcc/jit/libgccjit.h

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