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 directly stores the (const char *), so the passed string
 217    must outlive the context.  */
 218 extern void
 219 gcc_jit_context_set_str_option (gcc_jit_context *ctxt,
 220                                 enum gcc_jit_str_option opt,
 221                                 const char *value);
 222
 223 /* Set an int option on the given context.  */
 224 extern void
 225 gcc_jit_context_set_int_option (gcc_jit_context *ctxt,
 226                                 enum gcc_jit_int_option opt,
 227                                 int value);
 228
 229 /* Set a boolean option on the given context.
 230
 231    Zero is "false" (the default), non-zero is "true".  */
 232 extern void
 233 gcc_jit_context_set_bool_option (gcc_jit_context *ctxt,
 234                                  enum gcc_jit_bool_option opt,
 235                                  int value);
 236
 237 /* This actually calls into GCC and runs the build, all
 238    in a mutex for now.  The result is a wrapper around a .so file.
 239    It can only be called once on a given context.  */
 240 extern gcc_jit_result *
 241 gcc_jit_context_compile (gcc_jit_context *ctxt);
 242
 243 /* To help with debugging: dump a C-like representation to the given path,
 244    describing what's been set up on the context.
 245
 246    If "update_locations" is true, then also set up gcc_jit_location
 247    information throughout the context, pointing at the dump file as if it
 248    were a source file.  This may be of use in conjunction with
 249    GCC_JIT_BOOL_OPTION_DEBUGINFO to allow stepping through the code in a
 250    debugger.  */
 251 extern void
 252 gcc_jit_context_dump_to_file (gcc_jit_context *ctxt,
 253                               const char *path,
 254                               int update_locations);
 255
 256 /* To be called after a compile, this gives the first error message
 257    that occurred on the context.
 258
 259    The returned string is valid for the rest of the lifetime of the
 260    context.
 261
 262    If no errors occurred, this will be NULL.  */
 263 extern const char *
 264 gcc_jit_context_get_first_error (gcc_jit_context *ctxt);
 265
 266 /* Locate a given function within the built machine code.
 267    This will need to be cast to a function pointer of the
 268    correct type before it can be called. */
 269 extern void *
 270 gcc_jit_result_get_code (gcc_jit_result *result,
 271                          const char *funcname);
 272
 273 /* Once we're done with the code, this unloads the built .so file.
 274    This cleans up the result; after calling this, it's no longer
 275    valid to use the result.  */
 276 extern void
 277 gcc_jit_result_release (gcc_jit_result *result);
 278
 279
 280 /**********************************************************************
 281  Functions for creating "contextual" objects.
 282
 283  All objects created by these functions share the lifetime of the context
 284  they are created within, and are automatically cleaned up for you when
 285  you call gcc_jit_context_release on the context.
 286
 287  Note that this means you can't use references to them after you've
 288  released their context.
 289
 290  All (const char *) string arguments passed to these functions are
 291  copied, so you don't need to keep them around.  Note that this *isn't*
 292  the case for other parts of the API.
 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
 388 extern gcc_jit_type *
 389 gcc_jit_context_get_type (gcc_jit_context *ctxt,
 390                           enum gcc_jit_types type_);
 391
 392 /* Get the integer type of the given size and signedness.  */
 393 extern gcc_jit_type *
 394 gcc_jit_context_get_int_type (gcc_jit_context *ctxt,
 395                               int num_bytes, int is_signed);
 396
 397 /* Constructing new types. */
 398
 399 /* Given type "T", get type "T*".  */
 400 extern gcc_jit_type *
 401 gcc_jit_type_get_pointer (gcc_jit_type *type);
 402
 403 /* Given type "T", get type "const T".  */
 404 extern gcc_jit_type *
 405 gcc_jit_type_get_const (gcc_jit_type *type);
 406
 407 /* Given type "T", get type "volatile T".  */
 408 extern gcc_jit_type *
 409 gcc_jit_type_get_volatile (gcc_jit_type *type);
 410
 411 /* Given type "T", get type "T[N]" (for a constant N).  */
 412 extern gcc_jit_type *
 413 gcc_jit_context_new_array_type (gcc_jit_context *ctxt,
 414                                 gcc_jit_location *loc,
 415                                 gcc_jit_type *element_type,
 416                                 int num_elements);
 417
 418 /* Struct-handling.  */
 419
 420 /* Create a field, for use within a struct or union.  */
 421 extern gcc_jit_field *
 422 gcc_jit_context_new_field (gcc_jit_context *ctxt,
 423                            gcc_jit_location *loc,
 424                            gcc_jit_type *type,
 425                            const char *name);
 426
 427 /* Upcasting from field to object.  */
 428 extern gcc_jit_object *
 429 gcc_jit_field_as_object (gcc_jit_field *field);
 430
 431 /* Create a struct type from an array of fields.  */
 432 extern gcc_jit_struct *
 433 gcc_jit_context_new_struct_type (gcc_jit_context *ctxt,
 434                                  gcc_jit_location *loc,
 435                                  const char *name,
 436                                  int num_fields,
 437                                  gcc_jit_field **fields);
 438
 439 /* Create an opaque struct type.  */
 440 extern gcc_jit_struct *
 441 gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt,
 442                                    gcc_jit_location *loc,
 443                                    const char *name);
 444
 445 /* Upcast a struct to a type.  */
 446 extern gcc_jit_type *
 447 gcc_jit_struct_as_type (gcc_jit_struct *struct_type);
 448
 449 /* Populating the fields of a formerly-opaque struct type.
 450    This can only be called once on a given struct type.  */
 451 extern void
 452 gcc_jit_struct_set_fields (gcc_jit_struct *struct_type,
 453                            gcc_jit_location *loc,
 454                            int num_fields,
 455                            gcc_jit_field **fields);
 456
 457 /* Unions work similarly to structs.  */
 458 extern gcc_jit_type *
 459 gcc_jit_context_new_union_type (gcc_jit_context *ctxt,
 460                                 gcc_jit_location *loc,
 461                                 const char *name,
 462                                 int num_fields,
 463                                 gcc_jit_field **fields);
 464
 465 /* Function pointers. */
 466
 467 extern gcc_jit_type *
 468 gcc_jit_context_new_function_ptr_type (gcc_jit_context *ctxt,
 469                                        gcc_jit_location *loc,
 470                                        gcc_jit_type *return_type,
 471                                        int num_params,
 472                                        gcc_jit_type **param_types,
 473                                        int is_variadic);
 474
 475 /**********************************************************************
 476  Constructing functions.
 477  **********************************************************************/
 478 /* Create a function param.  */
 479 extern gcc_jit_param *
 480 gcc_jit_context_new_param (gcc_jit_context *ctxt,
 481                            gcc_jit_location *loc,
 482                            gcc_jit_type *type,
 483                            const char *name);
 484
 485 /* Upcasting from param to object.  */
 486 extern gcc_jit_object *
 487 gcc_jit_param_as_object (gcc_jit_param *param);
 488
 489 /* Upcasting from param to lvalue.  */
 490 extern gcc_jit_lvalue *
 491 gcc_jit_param_as_lvalue (gcc_jit_param *param);
 492
 493 /* Upcasting from param to rvalue.  */
 494 extern gcc_jit_rvalue *
 495 gcc_jit_param_as_rvalue (gcc_jit_param *param);
 496
 497 /* Kinds of function.  */
 498 enum gcc_jit_function_kind
 499 {
 500   /* Function is defined by the client code and visible
 501      by name outside of the JIT.  */
 502   GCC_JIT_FUNCTION_EXPORTED,
 503
 504   /* Function is defined by the client code, but is invisible
 505      outside of the JIT.  Analogous to a "static" function.  */
 506   GCC_JIT_FUNCTION_INTERNAL,
 507
 508   /* Function is not defined by the client code; we're merely
 509      referring to it.  Analogous to using an "extern" function from a
 510      header file.  */
 511   GCC_JIT_FUNCTION_IMPORTED,
 512
 513   /* Function is only ever inlined into other functions, and is
 514      invisible outside of the JIT.
 515
 516      Analogous to prefixing with "inline" and adding
 517      __attribute__((always_inline)).
 518
 519      Inlining will only occur when the optimization level is
 520      above 0; when optimization is off, this is essentially the
 521      same as GCC_JIT_FUNCTION_INTERNAL.  */
 522   GCC_JIT_FUNCTION_ALWAYS_INLINE
 523 };
 524
 525 /* Create a function.  */
 526 extern gcc_jit_function *
 527 gcc_jit_context_new_function (gcc_jit_context *ctxt,
 528                               gcc_jit_location *loc,
 529                               enum gcc_jit_function_kind kind,
 530                               gcc_jit_type *return_type,
 531                               const char *name,
 532                               int num_params,
 533                               gcc_jit_param **params,
 534                               int is_variadic);
 535
 536 /* Create a reference to a builtin function (sometimes called
 537    intrinsic functions).  */
 538 extern gcc_jit_function *
 539 gcc_jit_context_get_builtin_function (gcc_jit_context *ctxt,
 540                                       const char *name);
 541
 542 /* Upcasting from function to object.  */
 543 extern gcc_jit_object *
 544 gcc_jit_function_as_object (gcc_jit_function *func);
 545
 546 /* Get a specific param of a function by index.  */
 547 extern gcc_jit_param *
 548 gcc_jit_function_get_param (gcc_jit_function *func, int index);
 549
 550 /* Emit the function in graphviz format.  */
 551 extern void
 552 gcc_jit_function_dump_to_dot (gcc_jit_function *func,
 553                               const char *path);
 554
 555 /* Create a block.
 556
 557    The name can be NULL, or you can give it a meaningful name, which
 558    may show up in dumps of the internal representation, and in error
 559    messages.  */
 560 extern gcc_jit_block *
 561 gcc_jit_function_new_block (gcc_jit_function *func,
 562                             const char *name);
 563
 564 /* Upcasting from block to object.  */
 565 extern gcc_jit_object *
 566 gcc_jit_block_as_object (gcc_jit_block *block);
 567
 568 /* Which function is this block within?  */
 569 extern gcc_jit_function *
 570 gcc_jit_block_get_function (gcc_jit_block *block);
 571
 572 /**********************************************************************
 573  lvalues, rvalues and expressions.
 574  **********************************************************************/
 575
 576 extern gcc_jit_lvalue *
 577 gcc_jit_context_new_global (gcc_jit_context *ctxt,
 578                             gcc_jit_location *loc,
 579                             gcc_jit_type *type,
 580                             const char *name);
 581
 582 /* Upcasting.  */
 583 extern gcc_jit_object *
 584 gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue);
 585
 586 extern gcc_jit_rvalue *
 587 gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue);
 588
 589 extern gcc_jit_object *
 590 gcc_jit_rvalue_as_object (gcc_jit_rvalue *rvalue);
 591
 592 extern gcc_jit_type *
 593 gcc_jit_rvalue_get_type (gcc_jit_rvalue *rvalue);
 594
 595 /* Integer constants. */
 596 extern gcc_jit_rvalue *
 597 gcc_jit_context_new_rvalue_from_int (gcc_jit_context *ctxt,
 598                                      gcc_jit_type *numeric_type,
 599                                      int value);
 600
 601 extern gcc_jit_rvalue *
 602 gcc_jit_context_zero (gcc_jit_context *ctxt,
 603                       gcc_jit_type *numeric_type);
 604
 605 extern gcc_jit_rvalue *
 606 gcc_jit_context_one (gcc_jit_context *ctxt,
 607                      gcc_jit_type *numeric_type);
 608
 609 /* Floating-point constants.  */
 610 extern gcc_jit_rvalue *
 611 gcc_jit_context_new_rvalue_from_double (gcc_jit_context *ctxt,
 612                                         gcc_jit_type *numeric_type,
 613                                         double value);
 614
 615 /* Pointers.  */
 616 extern gcc_jit_rvalue *
 617 gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt,
 618                                      gcc_jit_type *pointer_type,
 619                                      void *value);
 620
 621 extern gcc_jit_rvalue *
 622 gcc_jit_context_null (gcc_jit_context *ctxt,
 623                       gcc_jit_type *pointer_type);
 624
 625 /* String literals. */
 626 extern gcc_jit_rvalue *
 627 gcc_jit_context_new_string_literal (gcc_jit_context *ctxt,
 628                                     const char *value);
 629
 630 enum gcc_jit_unary_op
 631 {
 632   /* Negate an arithmetic value; analogous to:
 633        -(EXPR)
 634      in C.  */
 635   GCC_JIT_UNARY_OP_MINUS,
 636
 637   /* Bitwise negation of an integer value (one's complement); analogous
 638      to:
 639        ~(EXPR)
 640      in C.  */
 641   GCC_JIT_UNARY_OP_BITWISE_NEGATE,
 642
 643   /* Logical negation of an arithmetic or pointer value; analogous to:
 644        !(EXPR)
 645      in C.  */
 646   GCC_JIT_UNARY_OP_LOGICAL_NEGATE
 647 };
 648
 649 extern gcc_jit_rvalue *
 650 gcc_jit_context_new_unary_op (gcc_jit_context *ctxt,
 651                               gcc_jit_location *loc,
 652                               enum gcc_jit_unary_op op,
 653                               gcc_jit_type *result_type,
 654                               gcc_jit_rvalue *rvalue);
 655
 656 enum gcc_jit_binary_op
 657 {
 658   /* Addition of arithmetic values; analogous to:
 659        (EXPR_A) + (EXPR_B)
 660      in C.
 661      For pointer addition, use gcc_jit_context_new_array_access.  */
 662   GCC_JIT_BINARY_OP_PLUS,
 663
 664   /* Subtraction of arithmetic values; analogous to:
 665        (EXPR_A) - (EXPR_B)
 666      in C.  */
 667   GCC_JIT_BINARY_OP_MINUS,
 668
 669   /* Multiplication of a pair of arithmetic values; analogous to:
 670        (EXPR_A) * (EXPR_B)
 671      in C.  */
 672   GCC_JIT_BINARY_OP_MULT,
 673
 674   /* Quotient of division of arithmetic values; analogous to:
 675        (EXPR_A) / (EXPR_B)
 676      in C.
 677      The result type affects the kind of division: if the result type is
 678      integer-based, then the result is truncated towards zero, whereas
 679      a floating-point result type indicates floating-point division.  */
 680   GCC_JIT_BINARY_OP_DIVIDE,
 681
 682   /* Remainder of division of arithmetic values; analogous to:
 683        (EXPR_A) % (EXPR_B)
 684      in C.  */
 685   GCC_JIT_BINARY_OP_MODULO,
 686
 687   /* Bitwise AND; analogous to:
 688        (EXPR_A) & (EXPR_B)
 689      in C.  */
 690   GCC_JIT_BINARY_OP_BITWISE_AND,
 691
 692   /* Bitwise exclusive OR; analogous to:
 693        (EXPR_A) ^ (EXPR_B)
 694      in C.  */
 695   GCC_JIT_BINARY_OP_BITWISE_XOR,
 696
 697   /* Bitwise inclusive OR; analogous to:
 698        (EXPR_A) | (EXPR_B)
 699      in C.  */
 700   GCC_JIT_BINARY_OP_BITWISE_OR,
 701
 702   /* Logical AND; analogous to:
 703        (EXPR_A) && (EXPR_B)
 704      in C.  */
 705   GCC_JIT_BINARY_OP_LOGICAL_AND,
 706
 707   /* Logical OR; analogous to:
 708        (EXPR_A) || (EXPR_B)
 709      in C.  */
 710   GCC_JIT_BINARY_OP_LOGICAL_OR,
 711
 712   /* Left shift; analogous to:
 713        (EXPR_A) << (EXPR_B)
 714      in C.  */
 715   GCC_JIT_BINARY_OP_LSHIFT,
 716
 717   /* Right shift; analogous to:
 718        (EXPR_A) >> (EXPR_B)
 719      in C.  */
 720   GCC_JIT_BINARY_OP_RSHIFT
 721 };
 722
 723 extern gcc_jit_rvalue *
 724 gcc_jit_context_new_binary_op (gcc_jit_context *ctxt,
 725                                gcc_jit_location *loc,
 726                                enum gcc_jit_binary_op op,
 727                                gcc_jit_type *result_type,
 728                                gcc_jit_rvalue *a, gcc_jit_rvalue *b);
 729
 730 /* (Comparisons are treated as separate from "binary_op" to save
 731    you having to specify the result_type).  */
 732
 733 enum gcc_jit_comparison
 734 {
 735   /* (EXPR_A) == (EXPR_B).  */
 736   GCC_JIT_COMPARISON_EQ,
 737
 738   /* (EXPR_A) != (EXPR_B).  */
 739   GCC_JIT_COMPARISON_NE,
 740
 741   /* (EXPR_A) < (EXPR_B).  */
 742   GCC_JIT_COMPARISON_LT,
 743
 744   /* (EXPR_A) <=(EXPR_B).  */
 745   GCC_JIT_COMPARISON_LE,
 746
 747   /* (EXPR_A) > (EXPR_B).  */
 748   GCC_JIT_COMPARISON_GT,
 749
 750   /* (EXPR_A) >= (EXPR_B).  */
 751   GCC_JIT_COMPARISON_GE
 752 };
 753
 754 extern gcc_jit_rvalue *
 755 gcc_jit_context_new_comparison (gcc_jit_context *ctxt,
 756                                 gcc_jit_location *loc,
 757                                 enum gcc_jit_comparison op,
 758                                 gcc_jit_rvalue *a, gcc_jit_rvalue *b);
 759
 760 /* Function calls.  */
 761
 762 /* Call of a specific function.  */
 763 extern gcc_jit_rvalue *
 764 gcc_jit_context_new_call (gcc_jit_context *ctxt,
 765                           gcc_jit_location *loc,
 766                           gcc_jit_function *func,
 767                           int numargs , gcc_jit_rvalue **args);
 768
 769 /* Call through a function pointer.  */
 770 extern gcc_jit_rvalue *
 771 gcc_jit_context_new_call_through_ptr (gcc_jit_context *ctxt,
 772                                       gcc_jit_location *loc,
 773                                       gcc_jit_rvalue *fn_ptr,
 774                                       int numargs, gcc_jit_rvalue **args);
 775
 776 /* Type-coercion.
 777
 778    Currently only a limited set of conversions are possible:
 779      int <-> float
 780      int <-> bool  */
 781 extern gcc_jit_rvalue *
 782 gcc_jit_context_new_cast (gcc_jit_context *ctxt,
 783                           gcc_jit_location *loc,
 784                           gcc_jit_rvalue *rvalue,
 785                           gcc_jit_type *type);
 786
 787 extern gcc_jit_lvalue *
 788 gcc_jit_context_new_array_access (gcc_jit_context *ctxt,
 789                                   gcc_jit_location *loc,
 790                                   gcc_jit_rvalue *ptr,
 791                                   gcc_jit_rvalue *index);
 792
 793 /* Field access is provided separately for both lvalues and rvalues.  */
 794
 795 /* Accessing a field of an lvalue of struct type, analogous to:
 796       (EXPR).field = ...;
 797    in C.  */
 798 extern gcc_jit_lvalue *
 799 gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_or_union,
 800                              gcc_jit_location *loc,
 801                              gcc_jit_field *field);
 802
 803 /* Accessing a field of an rvalue of struct type, analogous to:
 804       (EXPR).field
 805    in C.  */
 806 extern gcc_jit_rvalue *
 807 gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_or_union,
 808                              gcc_jit_location *loc,
 809                              gcc_jit_field *field);
 810
 811 /* Accessing a field of an rvalue of pointer type, analogous to:
 812       (EXPR)->field
 813    in C, itself equivalent to (*EXPR).FIELD  */
 814 extern gcc_jit_lvalue *
 815 gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr,
 816                                   gcc_jit_location *loc,
 817                                   gcc_jit_field *field);
 818
 819 /* Dereferencing a pointer; analogous to:
 820      *(EXPR)
 821 */
 822 extern gcc_jit_lvalue *
 823 gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue,
 824                             gcc_jit_location *loc);
 825
 826 /* Taking the address of an lvalue; analogous to:
 827      &(EXPR)
 828    in C.  */
 829 extern gcc_jit_rvalue *
 830 gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue,
 831                             gcc_jit_location *loc);
 832
 833 extern gcc_jit_lvalue *
 834 gcc_jit_function_new_local (gcc_jit_function *func,
 835                             gcc_jit_location *loc,
 836                             gcc_jit_type *type,
 837                             const char *name);
 838
 839 /**********************************************************************
 840  Statement-creation.
 841  **********************************************************************/
 842
 843 /* Add evaluation of an rvalue, discarding the result
 844    (e.g. a function call that "returns" void).
 845
 846    This is equivalent to this C code:
 847
 848      (void)expression;
 849 */
 850 extern void
 851 gcc_jit_block_add_eval (gcc_jit_block *block,
 852                         gcc_jit_location *loc,
 853                         gcc_jit_rvalue *rvalue);
 854
 855 /* Add evaluation of an rvalue, assigning the result to the given
 856    lvalue.
 857
 858    This is roughly equivalent to this C code:
 859
 860      lvalue = rvalue;
 861 */
 862 extern void
 863 gcc_jit_block_add_assignment (gcc_jit_block *block,
 864                               gcc_jit_location *loc,
 865                               gcc_jit_lvalue *lvalue,
 866                               gcc_jit_rvalue *rvalue);
 867
 868 /* Add evaluation of an rvalue, using the result to modify an
 869    lvalue.
 870
 871    This is analogous to "+=" and friends:
 872
 873      lvalue += rvalue;
 874      lvalue *= rvalue;
 875      lvalue /= rvalue;
 876    etc  */
 877 extern void
 878 gcc_jit_block_add_assignment_op (gcc_jit_block *block,
 879                                  gcc_jit_location *loc,
 880                                  gcc_jit_lvalue *lvalue,
 881                                  enum gcc_jit_binary_op op,
 882                                  gcc_jit_rvalue *rvalue);
 883
 884 /* Add a no-op textual comment to the internal representation of the
 885    code.  It will be optimized away, but will be visible in the dumps
 886    seen via
 887      GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE
 888    and
 889      GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE,
 890    and thus may be of use when debugging how your project's internal
 891    representation gets converted to the libgccjit IR.  */
 892 extern void
 893 gcc_jit_block_add_comment (gcc_jit_block *block,
 894                            gcc_jit_location *loc,
 895                            const char *text);
 896
 897 /* Terminate a block by adding evaluation of an rvalue, branching on the
 898    result to the appropriate successor block.
 899
 900    This is roughly equivalent to this C code:
 901
 902      if (boolval)
 903        goto on_true;
 904      else
 905        goto on_false;
 906
 907    block, boolval, on_true, and on_false must be non-NULL.  */
 908 extern void
 909 gcc_jit_block_end_with_conditional (gcc_jit_block *block,
 910                                     gcc_jit_location *loc,
 911                                     gcc_jit_rvalue *boolval,
 912                                     gcc_jit_block *on_true,
 913                                     gcc_jit_block *on_false);
 914
 915 /* Terminate a block by adding a jump to the given target block.
 916
 917    This is roughly equivalent to this C code:
 918
 919       goto target;
 920 */
 921 extern void
 922 gcc_jit_block_end_with_jump (gcc_jit_block *block,
 923                              gcc_jit_location *loc,
 924                              gcc_jit_block *target);
 925
 926 /* Terminate a block by adding evaluation of an rvalue, returning the value.
 927
 928    This is roughly equivalent to this C code:
 929
 930       return expression;
 931 */
 932 extern void
 933 gcc_jit_block_end_with_return (gcc_jit_block *block,
 934                                gcc_jit_location *loc,
 935                                gcc_jit_rvalue *rvalue);
 936
 937 /* Terminate a block by adding a valueless return, for use within a function
 938    with "void" return type.
 939
 940    This is equivalent to this C code:
 941
 942       return;
 943 */
 944 extern void
 945 gcc_jit_block_end_with_void_return (gcc_jit_block *block,
 946                                     gcc_jit_location *loc);
 947
 948 /**********************************************************************
 949  Nested contexts.
 950  **********************************************************************/
 951
 952 /* Given an existing JIT context, create a child context.
 953
 954    The child inherits a copy of all option-settings from the parent.
 955
 956    The child can reference objects created within the parent, but not
 957    vice-versa.
 958
 959    The lifetime of the child context must be bounded by that of the
 960    parent: you should release a child context before releasing the parent
 961    context.
 962
 963    If you use a function from a parent context within a child context,
 964    you have to compile the parent context before you can compile the
 965    child context, and the gcc_jit_result of the parent context must
 966    outlive the gcc_jit_result of the child context.
 967
 968    This allows caching of shared initializations.  For example, you could
 969    create types and declarations of global functions in a parent context
 970    once within a process, and then create child contexts whenever a
 971    function or loop becomes hot. Each such child context can be used for
 972    JIT-compiling just one function or loop, but can reference types
 973    and helper functions created within the parent context.
 974
 975    Contexts can be arbitrarily nested, provided the above rules are
 976    followed, but it's probably not worth going above 2 or 3 levels, and
 977    there will likely be a performance hit for such nesting.  */
 978
 979 extern gcc_jit_context *
 980 gcc_jit_context_new_child_context (gcc_jit_context *parent_ctxt);
 981
 982 #ifdef __cplusplus
 983 }
 984 #endif /* __cplusplus */
 985
 986 #endif  /* LIBGCCJIT_H  */