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.
4 This file is part of GCC.
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)
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.
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/>. */
25 #endif /* __cplusplus */
27 /**********************************************************************
29 **********************************************************************/
30 /* All structs within the API are opaque. */
32 /* A gcc_jit_context encapsulates the state of a compilation. It goes
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.
40 (2) "after compilation", when you can call gcc_jit_context_release to
42 typedef struct gcc_jit_context gcc_jit_context
;
44 /* A gcc_jit_result encapsulates the result of a compilation. */
45 typedef struct gcc_jit_result gcc_jit_result
;
47 /* An object created within a context. Such objects are automatically
48 cleaned up when the context is released.
50 The class hierarchy looks like this:
63 typedef struct gcc_jit_object gcc_jit_object
;
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.
70 Note that to do so, you also need to enable
71 GCC_JIT_BOOL_OPTION_DEBUGINFO
72 on the gcc_jit_context.
74 gcc_jit_location instances are optional; you can always pass
76 typedef struct gcc_jit_location gcc_jit_location
;
78 /* A gcc_jit_type encapsulates a type e.g. "int" or a "struct foo*". */
79 typedef struct gcc_jit_type gcc_jit_type
;
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
;
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
;
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
;
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).
98 Every block within a function must be terminated with a conditional,
99 a branch, or a return.
101 The blocks within a function form a directed graph.
103 The entrypoint to the function is the first block created within
106 All of the blocks in a function must be reachable via some path from
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
;
113 /* A gcc_jit_rvalue is an expression within your code, with some type. */
114 typedef struct gcc_jit_rvalue gcc_jit_rvalue
;
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
;
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
;
126 /* Acquire a JIT-compilation context. */
127 extern gcc_jit_context
*
128 gcc_jit_context_acquire (void);
130 /* Release the context. After this call, it's no longer valid to use
133 gcc_jit_context_release (gcc_jit_context
*ctxt
);
135 /* Options taking string values. */
136 enum gcc_jit_str_option
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
,
142 GCC_JIT_NUM_STR_OPTIONS
145 /* Options taking int values. */
146 enum gcc_jit_int_option
148 /* How much to optimize the code.
149 Valid values are 0-3, corresponding to GCC's command-line options
152 The default value is 0 (unoptimized). */
153 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL
,
155 GCC_JIT_NUM_INT_OPTIONS
158 /* Options taking boolean values.
159 These all default to "false". */
160 enum gcc_jit_bool_option
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.
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
,
171 /* If true, gcc_jit_context_compile will dump its initial "tree"
172 representation of your code to stderr (before any
174 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE
,
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
,
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
,
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.
189 GCC_JIT_BOOL_OPTION_DUMP_SUMMARY
,
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.
198 GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING
,
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
,
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
,
211 GCC_JIT_NUM_BOOL_OPTIONS
214 /* Set a string option on the given context.
216 The context takes a copy of the string, so the
217 (const char *) buffer is not needed anymore after the call
220 gcc_jit_context_set_str_option (gcc_jit_context
*ctxt
,
221 enum gcc_jit_str_option opt
,
224 /* Set an int option on the given context. */
226 gcc_jit_context_set_int_option (gcc_jit_context
*ctxt
,
227 enum gcc_jit_int_option opt
,
230 /* Set a boolean option on the given context.
232 Zero is "false" (the default), non-zero is "true". */
234 gcc_jit_context_set_bool_option (gcc_jit_context
*ctxt
,
235 enum gcc_jit_bool_option opt
,
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
);
244 /* To help with debugging: dump a C-like representation to the given path,
245 describing what's been set up on the context.
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
253 gcc_jit_context_dump_to_file (gcc_jit_context
*ctxt
,
255 int update_locations
);
257 /* To be called after a compile, this gives the first error message
258 that occurred on the context.
260 The returned string is valid for the rest of the lifetime of the
263 If no errors occurred, this will be NULL. */
265 gcc_jit_context_get_first_error (gcc_jit_context
*ctxt
);
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. */
271 gcc_jit_result_get_code (gcc_jit_result
*result
,
272 const char *funcname
);
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. */
278 gcc_jit_result_release (gcc_jit_result
*result
);
281 /**********************************************************************
282 Functions for creating "contextual" objects.
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.
288 Note that this means you can't use references to them after you've
289 released their context.
291 All (const char *) string arguments passed to these functions are
292 copied, so you don't need to keep them around.
294 You create code by adding a sequence of statements to blocks.
295 **********************************************************************/
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
);
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. */
308 gcc_jit_object_get_debug_string (gcc_jit_object
*obj
);
310 /**********************************************************************
311 Debugging information.
312 **********************************************************************/
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
,
322 /* Upcasting from location to object. */
323 extern gcc_jit_object
*
324 gcc_jit_location_as_object (gcc_jit_location
*loc
);
327 /**********************************************************************
329 **********************************************************************/
331 /* Upcasting from type to object. */
332 extern gcc_jit_object
*
333 gcc_jit_type_as_object (gcc_jit_type
*type
);
335 /* Access to specific types. */
338 /* C's "void" type. */
342 GCC_JIT_TYPE_VOID_PTR
,
344 /* C++'s bool type; also C99's "_Bool" type, aka "bool" if using
348 /* Various integer types. */
350 /* C's "char" (of some signedness) and the variants where the
351 signedness is specified. */
353 GCC_JIT_TYPE_SIGNED_CHAR
,
354 GCC_JIT_TYPE_UNSIGNED_CHAR
,
356 /* C's "short" and "unsigned short". */
357 GCC_JIT_TYPE_SHORT
, /* signed */
358 GCC_JIT_TYPE_UNSIGNED_SHORT
,
360 /* C's "int" and "unsigned int". */
361 GCC_JIT_TYPE_INT
, /* signed */
362 GCC_JIT_TYPE_UNSIGNED_INT
,
364 /* C's "long" and "unsigned long". */
365 GCC_JIT_TYPE_LONG
, /* signed */
366 GCC_JIT_TYPE_UNSIGNED_LONG
,
368 /* C99's "long long" and "unsigned long long". */
369 GCC_JIT_TYPE_LONG_LONG
, /* signed */
370 GCC_JIT_TYPE_UNSIGNED_LONG_LONG
,
372 /* Floating-point types */
376 GCC_JIT_TYPE_LONG_DOUBLE
,
378 /* C type: (const char *). */
379 GCC_JIT_TYPE_CONST_CHAR_PTR
,
381 /* The C "size_t" type. */
384 /* C type: (FILE *) */
385 GCC_JIT_TYPE_FILE_PTR
,
387 /* Complex numbers. */
388 GCC_JIT_TYPE_COMPLEX_FLOAT
,
389 GCC_JIT_TYPE_COMPLEX_DOUBLE
,
390 GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE
394 extern gcc_jit_type
*
395 gcc_jit_context_get_type (gcc_jit_context
*ctxt
,
396 enum gcc_jit_types type_
);
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
);
403 /* Constructing new types. */
405 /* Given type "T", get type "T*". */
406 extern gcc_jit_type
*
407 gcc_jit_type_get_pointer (gcc_jit_type
*type
);
409 /* Given type "T", get type "const T". */
410 extern gcc_jit_type
*
411 gcc_jit_type_get_const (gcc_jit_type
*type
);
413 /* Given type "T", get type "volatile T". */
414 extern gcc_jit_type
*
415 gcc_jit_type_get_volatile (gcc_jit_type
*type
);
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
,
424 /* Struct-handling. */
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
,
433 /* Upcasting from field to object. */
434 extern gcc_jit_object
*
435 gcc_jit_field_as_object (gcc_jit_field
*field
);
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
,
443 gcc_jit_field
**fields
);
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
,
451 /* Upcast a struct to a type. */
452 extern gcc_jit_type
*
453 gcc_jit_struct_as_type (gcc_jit_struct
*struct_type
);
455 /* Populating the fields of a formerly-opaque struct type.
456 This can only be called once on a given struct type. */
458 gcc_jit_struct_set_fields (gcc_jit_struct
*struct_type
,
459 gcc_jit_location
*loc
,
461 gcc_jit_field
**fields
);
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
,
469 gcc_jit_field
**fields
);
471 /* Function pointers. */
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
,
478 gcc_jit_type
**param_types
,
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
,
491 /* Upcasting from param to object. */
492 extern gcc_jit_object
*
493 gcc_jit_param_as_object (gcc_jit_param
*param
);
495 /* Upcasting from param to lvalue. */
496 extern gcc_jit_lvalue
*
497 gcc_jit_param_as_lvalue (gcc_jit_param
*param
);
499 /* Upcasting from param to rvalue. */
500 extern gcc_jit_rvalue
*
501 gcc_jit_param_as_rvalue (gcc_jit_param
*param
);
503 /* Kinds of function. */
504 enum gcc_jit_function_kind
506 /* Function is defined by the client code and visible
507 by name outside of the JIT. */
508 GCC_JIT_FUNCTION_EXPORTED
,
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
,
514 /* Function is not defined by the client code; we're merely
515 referring to it. Analogous to using an "extern" function from a
517 GCC_JIT_FUNCTION_IMPORTED
,
519 /* Function is only ever inlined into other functions, and is
520 invisible outside of the JIT.
522 Analogous to prefixing with "inline" and adding
523 __attribute__((always_inline)).
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
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
,
539 gcc_jit_param
**params
,
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
,
548 /* Upcasting from function to object. */
549 extern gcc_jit_object
*
550 gcc_jit_function_as_object (gcc_jit_function
*func
);
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
);
556 /* Emit the function in graphviz format. */
558 gcc_jit_function_dump_to_dot (gcc_jit_function
*func
,
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
566 extern gcc_jit_block
*
567 gcc_jit_function_new_block (gcc_jit_function
*func
,
570 /* Upcasting from block to object. */
571 extern gcc_jit_object
*
572 gcc_jit_block_as_object (gcc_jit_block
*block
);
574 /* Which function is this block within? */
575 extern gcc_jit_function
*
576 gcc_jit_block_get_function (gcc_jit_block
*block
);
578 /**********************************************************************
579 lvalues, rvalues and expressions.
580 **********************************************************************/
582 extern gcc_jit_lvalue
*
583 gcc_jit_context_new_global (gcc_jit_context
*ctxt
,
584 gcc_jit_location
*loc
,
589 extern gcc_jit_object
*
590 gcc_jit_lvalue_as_object (gcc_jit_lvalue
*lvalue
);
592 extern gcc_jit_rvalue
*
593 gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue
*lvalue
);
595 extern gcc_jit_object
*
596 gcc_jit_rvalue_as_object (gcc_jit_rvalue
*rvalue
);
598 extern gcc_jit_type
*
599 gcc_jit_rvalue_get_type (gcc_jit_rvalue
*rvalue
);
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
,
607 extern gcc_jit_rvalue
*
608 gcc_jit_context_zero (gcc_jit_context
*ctxt
,
609 gcc_jit_type
*numeric_type
);
611 extern gcc_jit_rvalue
*
612 gcc_jit_context_one (gcc_jit_context
*ctxt
,
613 gcc_jit_type
*numeric_type
);
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
,
622 extern gcc_jit_rvalue
*
623 gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context
*ctxt
,
624 gcc_jit_type
*pointer_type
,
627 extern gcc_jit_rvalue
*
628 gcc_jit_context_null (gcc_jit_context
*ctxt
,
629 gcc_jit_type
*pointer_type
);
631 /* String literals. */
632 extern gcc_jit_rvalue
*
633 gcc_jit_context_new_string_literal (gcc_jit_context
*ctxt
,
636 enum gcc_jit_unary_op
638 /* Negate an arithmetic value; analogous to:
641 GCC_JIT_UNARY_OP_MINUS
,
643 /* Bitwise negation of an integer value (one's complement); analogous
647 GCC_JIT_UNARY_OP_BITWISE_NEGATE
,
649 /* Logical negation of an arithmetic or pointer value; analogous to:
652 GCC_JIT_UNARY_OP_LOGICAL_NEGATE
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
);
662 enum gcc_jit_binary_op
664 /* Addition of arithmetic values; analogous to:
667 For pointer addition, use gcc_jit_context_new_array_access. */
668 GCC_JIT_BINARY_OP_PLUS
,
670 /* Subtraction of arithmetic values; analogous to:
673 GCC_JIT_BINARY_OP_MINUS
,
675 /* Multiplication of a pair of arithmetic values; analogous to:
678 GCC_JIT_BINARY_OP_MULT
,
680 /* Quotient of division of arithmetic values; analogous to:
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
,
688 /* Remainder of division of arithmetic values; analogous to:
691 GCC_JIT_BINARY_OP_MODULO
,
693 /* Bitwise AND; analogous to:
696 GCC_JIT_BINARY_OP_BITWISE_AND
,
698 /* Bitwise exclusive OR; analogous to:
701 GCC_JIT_BINARY_OP_BITWISE_XOR
,
703 /* Bitwise inclusive OR; analogous to:
706 GCC_JIT_BINARY_OP_BITWISE_OR
,
708 /* Logical AND; analogous to:
711 GCC_JIT_BINARY_OP_LOGICAL_AND
,
713 /* Logical OR; analogous to:
716 GCC_JIT_BINARY_OP_LOGICAL_OR
,
718 /* Left shift; analogous to:
721 GCC_JIT_BINARY_OP_LSHIFT
,
723 /* Right shift; analogous to:
726 GCC_JIT_BINARY_OP_RSHIFT
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
);
736 /* (Comparisons are treated as separate from "binary_op" to save
737 you having to specify the result_type). */
739 enum gcc_jit_comparison
741 /* (EXPR_A) == (EXPR_B). */
742 GCC_JIT_COMPARISON_EQ
,
744 /* (EXPR_A) != (EXPR_B). */
745 GCC_JIT_COMPARISON_NE
,
747 /* (EXPR_A) < (EXPR_B). */
748 GCC_JIT_COMPARISON_LT
,
750 /* (EXPR_A) <=(EXPR_B). */
751 GCC_JIT_COMPARISON_LE
,
753 /* (EXPR_A) > (EXPR_B). */
754 GCC_JIT_COMPARISON_GT
,
756 /* (EXPR_A) >= (EXPR_B). */
757 GCC_JIT_COMPARISON_GE
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
);
766 /* Function calls. */
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
);
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
);
784 Currently only a limited set of conversions are possible:
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
,
793 extern gcc_jit_lvalue
*
794 gcc_jit_context_new_array_access (gcc_jit_context
*ctxt
,
795 gcc_jit_location
*loc
,
797 gcc_jit_rvalue
*index
);
799 /* Field access is provided separately for both lvalues and rvalues. */
801 /* Accessing a field of an lvalue of struct type, analogous to:
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
);
809 /* Accessing a field of an rvalue of struct type, analogous to:
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
);
817 /* Accessing a field of an rvalue of pointer type, analogous to:
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
);
825 /* Dereferencing a pointer; analogous to:
828 extern gcc_jit_lvalue
*
829 gcc_jit_rvalue_dereference (gcc_jit_rvalue
*rvalue
,
830 gcc_jit_location
*loc
);
832 /* Taking the address of an lvalue; analogous to:
835 extern gcc_jit_rvalue
*
836 gcc_jit_lvalue_get_address (gcc_jit_lvalue
*lvalue
,
837 gcc_jit_location
*loc
);
839 extern gcc_jit_lvalue
*
840 gcc_jit_function_new_local (gcc_jit_function
*func
,
841 gcc_jit_location
*loc
,
845 /**********************************************************************
847 **********************************************************************/
849 /* Add evaluation of an rvalue, discarding the result
850 (e.g. a function call that "returns" void).
852 This is equivalent to this C code:
857 gcc_jit_block_add_eval (gcc_jit_block
*block
,
858 gcc_jit_location
*loc
,
859 gcc_jit_rvalue
*rvalue
);
861 /* Add evaluation of an rvalue, assigning the result to the given
864 This is roughly equivalent to this C code:
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
);
874 /* Add evaluation of an rvalue, using the result to modify an
877 This is analogous to "+=" and friends:
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
);
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
893 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE
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. */
899 gcc_jit_block_add_comment (gcc_jit_block
*block
,
900 gcc_jit_location
*loc
,
903 /* Terminate a block by adding evaluation of an rvalue, branching on the
904 result to the appropriate successor block.
906 This is roughly equivalent to this C code:
913 block, boolval, on_true, and on_false must be non-NULL. */
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
);
921 /* Terminate a block by adding a jump to the given target block.
923 This is roughly equivalent to this C code:
928 gcc_jit_block_end_with_jump (gcc_jit_block
*block
,
929 gcc_jit_location
*loc
,
930 gcc_jit_block
*target
);
932 /* Terminate a block by adding evaluation of an rvalue, returning the value.
934 This is roughly equivalent to this C code:
939 gcc_jit_block_end_with_return (gcc_jit_block
*block
,
940 gcc_jit_location
*loc
,
941 gcc_jit_rvalue
*rvalue
);
943 /* Terminate a block by adding a valueless return, for use within a function
944 with "void" return type.
946 This is equivalent to this C code:
951 gcc_jit_block_end_with_void_return (gcc_jit_block
*block
,
952 gcc_jit_location
*loc
);
954 /**********************************************************************
956 **********************************************************************/
958 /* Given an existing JIT context, create a child context.
960 The child inherits a copy of all option-settings from the parent.
962 The child can reference objects created within the parent, but not
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
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.
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.
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. */
985 extern gcc_jit_context
*
986 gcc_jit_context_new_child_context (gcc_jit_context
*parent_ctxt
);
988 /**********************************************************************
989 Implementation support.
990 **********************************************************************/
992 /* Enable the dumping of a specific set of internal state from the
993 compilation, capturing the result in-memory as a buffer.
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
999 The context directly stores the dumpname as a (const char *), so the
1000 passed string must outlive the context.
1002 gcc_jit_context_compile will capture the dump as a
1003 dynamically-allocated buffer, writing it to ``*out_ptr``.
1005 The caller becomes responsible for calling
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
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.
1015 It exists primarily for writing the library's own test suite. */
1018 gcc_jit_context_enable_dump (gcc_jit_context
*ctxt
,
1019 const char *dumpname
,
1024 #endif /* __cplusplus */
1026 #endif /* LIBGCCJIT_H */