1 /* A pure C API to enable client code to embed GCC as a JIT-compiler.
2 Copyright (C) 2013-2015 Free Software Foundation, Inc.
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/>. */
27 #endif /* __cplusplus */
29 /**********************************************************************
31 **********************************************************************/
32 /* All structs within the API are opaque. */
34 /* A gcc_jit_context encapsulates the state of a compilation. It goes
37 (1) "initial", during which you can set up options on it, and add
38 types, functions and code, using the API below.
39 Invoking gcc_jit_context_compile on it transitions it to the
40 "after compilation" state.
42 (2) "after compilation", when you can call gcc_jit_context_release to
44 typedef struct gcc_jit_context gcc_jit_context
;
46 /* A gcc_jit_result encapsulates the result of a compilation. */
47 typedef struct gcc_jit_result gcc_jit_result
;
49 /* An object created within a context. Such objects are automatically
50 cleaned up when the context is released.
52 The class hierarchy looks like this:
65 typedef struct gcc_jit_object gcc_jit_object
;
67 /* A gcc_jit_location encapsulates a source code location, so that
68 you can (optionally) associate locations in your language with
69 statements in the JIT-compiled code, allowing the debugger to
70 single-step through your language.
72 Note that to do so, you also need to enable
73 GCC_JIT_BOOL_OPTION_DEBUGINFO
74 on the gcc_jit_context.
76 gcc_jit_location instances are optional; you can always pass
78 typedef struct gcc_jit_location gcc_jit_location
;
80 /* A gcc_jit_type encapsulates a type e.g. "int" or a "struct foo*". */
81 typedef struct gcc_jit_type gcc_jit_type
;
83 /* A gcc_jit_field encapsulates a field within a struct; it is used
84 when creating a struct type (using gcc_jit_context_new_struct_type).
85 Fields cannot be shared between structs. */
86 typedef struct gcc_jit_field gcc_jit_field
;
88 /* A gcc_jit_struct encapsulates a struct type, either one that we have
89 the layout for, or an opaque type. */
90 typedef struct gcc_jit_struct gcc_jit_struct
;
92 /* A gcc_jit_function encapsulates a function: either one that you're
93 creating yourself, or a reference to one that you're dynamically
94 linking to within the rest of the process. */
95 typedef struct gcc_jit_function gcc_jit_function
;
97 /* A gcc_jit_block encapsulates a "basic block" of statements within a
98 function (i.e. with one entry point and one exit point).
100 Every block within a function must be terminated with a conditional,
101 a branch, or a return.
103 The blocks within a function form a directed graph.
105 The entrypoint to the function is the first block created within
108 All of the blocks in a function must be reachable via some path from
111 It's OK to have more than one "return" from a function (i.e. multiple
112 blocks that terminate by returning). */
113 typedef struct gcc_jit_block gcc_jit_block
;
115 /* A gcc_jit_rvalue is an expression within your code, with some type. */
116 typedef struct gcc_jit_rvalue gcc_jit_rvalue
;
118 /* A gcc_jit_lvalue is a storage location within your code (e.g. a
119 variable, a parameter, etc). It is also a gcc_jit_rvalue; use
120 gcc_jit_lvalue_as_rvalue to cast. */
121 typedef struct gcc_jit_lvalue gcc_jit_lvalue
;
123 /* A gcc_jit_param is a function parameter, used when creating a
124 gcc_jit_function. It is also a gcc_jit_lvalue (and thus also an
125 rvalue); use gcc_jit_param_as_lvalue to convert. */
126 typedef struct gcc_jit_param gcc_jit_param
;
128 /* Acquire a JIT-compilation context. */
129 extern gcc_jit_context
*
130 gcc_jit_context_acquire (void);
132 /* Release the context. After this call, it's no longer valid to use
135 gcc_jit_context_release (gcc_jit_context
*ctxt
);
137 /* Options taking string values. */
138 enum gcc_jit_str_option
140 /* The name of the program, for use as a prefix when printing error
141 messages to stderr. If NULL, or default, "libgccjit.so" is used. */
142 GCC_JIT_STR_OPTION_PROGNAME
,
144 GCC_JIT_NUM_STR_OPTIONS
147 /* Options taking int values. */
148 enum gcc_jit_int_option
150 /* How much to optimize the code.
151 Valid values are 0-3, corresponding to GCC's command-line options
154 The default value is 0 (unoptimized). */
155 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL
,
157 GCC_JIT_NUM_INT_OPTIONS
160 /* Options taking boolean values.
161 These all default to "false". */
162 enum gcc_jit_bool_option
164 /* If true, gcc_jit_context_compile will attempt to do the right
165 thing so that if you attach a debugger to the process, it will
166 be able to inspect variables and step through your code.
168 Note that you can't step through code unless you set up source
169 location information for the code (by creating and passing in
170 gcc_jit_location instances). */
171 GCC_JIT_BOOL_OPTION_DEBUGINFO
,
173 /* If true, gcc_jit_context_compile will dump its initial "tree"
174 representation of your code to stderr (before any
176 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE
,
178 /* If true, gcc_jit_context_compile will dump the "gimple"
179 representation of your code to stderr, before any optimizations
180 are performed. The dump resembles C code. */
181 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE
,
183 /* If true, gcc_jit_context_compile will dump the final
184 generated code to stderr, in the form of assembly language. */
185 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE
,
187 /* If true, gcc_jit_context_compile will print information to stderr
188 on the actions it is performing, followed by a profile showing
189 the time taken and memory usage of each phase.
191 GCC_JIT_BOOL_OPTION_DUMP_SUMMARY
,
193 /* If true, gcc_jit_context_compile will dump copious
194 amount of information on what it's doing to various
195 files within a temporary directory. Use
196 GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES (see below) to
197 see the results. The files are intended to be human-readable,
198 but the exact files and their formats are subject to change.
200 GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING
,
202 /* If true, libgccjit will aggressively run its garbage collector, to
203 shake out bugs (greatly slowing down the compile). This is likely
204 to only be of interest to developers *of* the library. It is
205 used when running the selftest suite. */
206 GCC_JIT_BOOL_OPTION_SELFCHECK_GC
,
208 /* If true, gcc_jit_context_release will not clean up
209 intermediate files written to the filesystem, and will display
210 their location on stderr. */
211 GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES
,
213 GCC_JIT_NUM_BOOL_OPTIONS
216 /* Set a string option on the given context.
218 The context takes a copy of the string, so the
219 (const char *) buffer is not needed anymore after the call
222 gcc_jit_context_set_str_option (gcc_jit_context
*ctxt
,
223 enum gcc_jit_str_option opt
,
226 /* Set an int option on the given context. */
228 gcc_jit_context_set_int_option (gcc_jit_context
*ctxt
,
229 enum gcc_jit_int_option opt
,
232 /* Set a boolean option on the given context.
234 Zero is "false" (the default), non-zero is "true". */
236 gcc_jit_context_set_bool_option (gcc_jit_context
*ctxt
,
237 enum gcc_jit_bool_option opt
,
240 /* This actually calls into GCC and runs the build, all
241 in a mutex for now. The result is a wrapper around a .so file.
242 It can only be called once on a given context. */
243 extern gcc_jit_result
*
244 gcc_jit_context_compile (gcc_jit_context
*ctxt
);
246 /* To help with debugging: dump a C-like representation to the given path,
247 describing what's been set up on the context.
249 If "update_locations" is true, then also set up gcc_jit_location
250 information throughout the context, pointing at the dump file as if it
251 were a source file. This may be of use in conjunction with
252 GCC_JIT_BOOL_OPTION_DEBUGINFO to allow stepping through the code in a
255 gcc_jit_context_dump_to_file (gcc_jit_context
*ctxt
,
257 int update_locations
);
259 /* To help with debugging; enable ongoing logging of the context's
260 activity to the given FILE *.
262 The caller remains responsible for closing "logfile".
264 Params "flags" and "verbosity" are reserved for future use, and
265 must both be 0 for now. */
267 gcc_jit_context_set_logfile (gcc_jit_context
*ctxt
,
272 /* To be called after a compile, this gives the first error message
273 that occurred on the context.
275 The returned string is valid for the rest of the lifetime of the
278 If no errors occurred, this will be NULL. */
280 gcc_jit_context_get_first_error (gcc_jit_context
*ctxt
);
282 /* Locate a given function within the built machine code.
283 This will need to be cast to a function pointer of the
284 correct type before it can be called. */
286 gcc_jit_result_get_code (gcc_jit_result
*result
,
287 const char *funcname
);
289 /* Once we're done with the code, this unloads the built .so file.
290 This cleans up the result; after calling this, it's no longer
291 valid to use the result. */
293 gcc_jit_result_release (gcc_jit_result
*result
);
296 /**********************************************************************
297 Functions for creating "contextual" objects.
299 All objects created by these functions share the lifetime of the context
300 they are created within, and are automatically cleaned up for you when
301 you call gcc_jit_context_release on the context.
303 Note that this means you can't use references to them after you've
304 released their context.
306 All (const char *) string arguments passed to these functions are
307 copied, so you don't need to keep them around.
309 You create code by adding a sequence of statements to blocks.
310 **********************************************************************/
312 /**********************************************************************
313 The base class of "contextual" object.
314 **********************************************************************/
315 /* Which context is "obj" within? */
316 extern gcc_jit_context
*
317 gcc_jit_object_get_context (gcc_jit_object
*obj
);
319 /* Get a human-readable description of this object.
320 The string buffer is created the first time this is called on a given
321 object, and persists until the object's context is released. */
323 gcc_jit_object_get_debug_string (gcc_jit_object
*obj
);
325 /**********************************************************************
326 Debugging information.
327 **********************************************************************/
329 /* Creating source code locations for use by the debugger.
330 Line and column numbers are 1-based. */
331 extern gcc_jit_location
*
332 gcc_jit_context_new_location (gcc_jit_context
*ctxt
,
333 const char *filename
,
337 /* Upcasting from location to object. */
338 extern gcc_jit_object
*
339 gcc_jit_location_as_object (gcc_jit_location
*loc
);
342 /**********************************************************************
344 **********************************************************************/
346 /* Upcasting from type to object. */
347 extern gcc_jit_object
*
348 gcc_jit_type_as_object (gcc_jit_type
*type
);
350 /* Access to specific types. */
353 /* C's "void" type. */
357 GCC_JIT_TYPE_VOID_PTR
,
359 /* C++'s bool type; also C99's "_Bool" type, aka "bool" if using
363 /* Various integer types. */
365 /* C's "char" (of some signedness) and the variants where the
366 signedness is specified. */
368 GCC_JIT_TYPE_SIGNED_CHAR
,
369 GCC_JIT_TYPE_UNSIGNED_CHAR
,
371 /* C's "short" and "unsigned short". */
372 GCC_JIT_TYPE_SHORT
, /* signed */
373 GCC_JIT_TYPE_UNSIGNED_SHORT
,
375 /* C's "int" and "unsigned int". */
376 GCC_JIT_TYPE_INT
, /* signed */
377 GCC_JIT_TYPE_UNSIGNED_INT
,
379 /* C's "long" and "unsigned long". */
380 GCC_JIT_TYPE_LONG
, /* signed */
381 GCC_JIT_TYPE_UNSIGNED_LONG
,
383 /* C99's "long long" and "unsigned long long". */
384 GCC_JIT_TYPE_LONG_LONG
, /* signed */
385 GCC_JIT_TYPE_UNSIGNED_LONG_LONG
,
387 /* Floating-point types */
391 GCC_JIT_TYPE_LONG_DOUBLE
,
393 /* C type: (const char *). */
394 GCC_JIT_TYPE_CONST_CHAR_PTR
,
396 /* The C "size_t" type. */
399 /* C type: (FILE *) */
400 GCC_JIT_TYPE_FILE_PTR
,
402 /* Complex numbers. */
403 GCC_JIT_TYPE_COMPLEX_FLOAT
,
404 GCC_JIT_TYPE_COMPLEX_DOUBLE
,
405 GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE
409 extern gcc_jit_type
*
410 gcc_jit_context_get_type (gcc_jit_context
*ctxt
,
411 enum gcc_jit_types type_
);
413 /* Get the integer type of the given size and signedness. */
414 extern gcc_jit_type
*
415 gcc_jit_context_get_int_type (gcc_jit_context
*ctxt
,
416 int num_bytes
, int is_signed
);
418 /* Constructing new types. */
420 /* Given type "T", get type "T*". */
421 extern gcc_jit_type
*
422 gcc_jit_type_get_pointer (gcc_jit_type
*type
);
424 /* Given type "T", get type "const T". */
425 extern gcc_jit_type
*
426 gcc_jit_type_get_const (gcc_jit_type
*type
);
428 /* Given type "T", get type "volatile T". */
429 extern gcc_jit_type
*
430 gcc_jit_type_get_volatile (gcc_jit_type
*type
);
432 /* Given type "T", get type "T[N]" (for a constant N). */
433 extern gcc_jit_type
*
434 gcc_jit_context_new_array_type (gcc_jit_context
*ctxt
,
435 gcc_jit_location
*loc
,
436 gcc_jit_type
*element_type
,
439 /* Struct-handling. */
441 /* Create a field, for use within a struct or union. */
442 extern gcc_jit_field
*
443 gcc_jit_context_new_field (gcc_jit_context
*ctxt
,
444 gcc_jit_location
*loc
,
448 /* Upcasting from field to object. */
449 extern gcc_jit_object
*
450 gcc_jit_field_as_object (gcc_jit_field
*field
);
452 /* Create a struct type from an array of fields. */
453 extern gcc_jit_struct
*
454 gcc_jit_context_new_struct_type (gcc_jit_context
*ctxt
,
455 gcc_jit_location
*loc
,
458 gcc_jit_field
**fields
);
460 /* Create an opaque struct type. */
461 extern gcc_jit_struct
*
462 gcc_jit_context_new_opaque_struct (gcc_jit_context
*ctxt
,
463 gcc_jit_location
*loc
,
466 /* Upcast a struct to a type. */
467 extern gcc_jit_type
*
468 gcc_jit_struct_as_type (gcc_jit_struct
*struct_type
);
470 /* Populating the fields of a formerly-opaque struct type.
471 This can only be called once on a given struct type. */
473 gcc_jit_struct_set_fields (gcc_jit_struct
*struct_type
,
474 gcc_jit_location
*loc
,
476 gcc_jit_field
**fields
);
478 /* Unions work similarly to structs. */
479 extern gcc_jit_type
*
480 gcc_jit_context_new_union_type (gcc_jit_context
*ctxt
,
481 gcc_jit_location
*loc
,
484 gcc_jit_field
**fields
);
486 /* Function pointers. */
488 extern gcc_jit_type
*
489 gcc_jit_context_new_function_ptr_type (gcc_jit_context
*ctxt
,
490 gcc_jit_location
*loc
,
491 gcc_jit_type
*return_type
,
493 gcc_jit_type
**param_types
,
496 /**********************************************************************
497 Constructing functions.
498 **********************************************************************/
499 /* Create a function param. */
500 extern gcc_jit_param
*
501 gcc_jit_context_new_param (gcc_jit_context
*ctxt
,
502 gcc_jit_location
*loc
,
506 /* Upcasting from param to object. */
507 extern gcc_jit_object
*
508 gcc_jit_param_as_object (gcc_jit_param
*param
);
510 /* Upcasting from param to lvalue. */
511 extern gcc_jit_lvalue
*
512 gcc_jit_param_as_lvalue (gcc_jit_param
*param
);
514 /* Upcasting from param to rvalue. */
515 extern gcc_jit_rvalue
*
516 gcc_jit_param_as_rvalue (gcc_jit_param
*param
);
518 /* Kinds of function. */
519 enum gcc_jit_function_kind
521 /* Function is defined by the client code and visible
522 by name outside of the JIT. */
523 GCC_JIT_FUNCTION_EXPORTED
,
525 /* Function is defined by the client code, but is invisible
526 outside of the JIT. Analogous to a "static" function. */
527 GCC_JIT_FUNCTION_INTERNAL
,
529 /* Function is not defined by the client code; we're merely
530 referring to it. Analogous to using an "extern" function from a
532 GCC_JIT_FUNCTION_IMPORTED
,
534 /* Function is only ever inlined into other functions, and is
535 invisible outside of the JIT.
537 Analogous to prefixing with "inline" and adding
538 __attribute__((always_inline)).
540 Inlining will only occur when the optimization level is
541 above 0; when optimization is off, this is essentially the
542 same as GCC_JIT_FUNCTION_INTERNAL. */
543 GCC_JIT_FUNCTION_ALWAYS_INLINE
546 /* Create a function. */
547 extern gcc_jit_function
*
548 gcc_jit_context_new_function (gcc_jit_context
*ctxt
,
549 gcc_jit_location
*loc
,
550 enum gcc_jit_function_kind kind
,
551 gcc_jit_type
*return_type
,
554 gcc_jit_param
**params
,
557 /* Create a reference to a builtin function (sometimes called
558 intrinsic functions). */
559 extern gcc_jit_function
*
560 gcc_jit_context_get_builtin_function (gcc_jit_context
*ctxt
,
563 /* Upcasting from function to object. */
564 extern gcc_jit_object
*
565 gcc_jit_function_as_object (gcc_jit_function
*func
);
567 /* Get a specific param of a function by index. */
568 extern gcc_jit_param
*
569 gcc_jit_function_get_param (gcc_jit_function
*func
, int index
);
571 /* Emit the function in graphviz format. */
573 gcc_jit_function_dump_to_dot (gcc_jit_function
*func
,
578 The name can be NULL, or you can give it a meaningful name, which
579 may show up in dumps of the internal representation, and in error
581 extern gcc_jit_block
*
582 gcc_jit_function_new_block (gcc_jit_function
*func
,
585 /* Upcasting from block to object. */
586 extern gcc_jit_object
*
587 gcc_jit_block_as_object (gcc_jit_block
*block
);
589 /* Which function is this block within? */
590 extern gcc_jit_function
*
591 gcc_jit_block_get_function (gcc_jit_block
*block
);
593 /**********************************************************************
594 lvalues, rvalues and expressions.
595 **********************************************************************/
597 extern gcc_jit_lvalue
*
598 gcc_jit_context_new_global (gcc_jit_context
*ctxt
,
599 gcc_jit_location
*loc
,
604 extern gcc_jit_object
*
605 gcc_jit_lvalue_as_object (gcc_jit_lvalue
*lvalue
);
607 extern gcc_jit_rvalue
*
608 gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue
*lvalue
);
610 extern gcc_jit_object
*
611 gcc_jit_rvalue_as_object (gcc_jit_rvalue
*rvalue
);
613 extern gcc_jit_type
*
614 gcc_jit_rvalue_get_type (gcc_jit_rvalue
*rvalue
);
616 /* Integer constants. */
617 extern gcc_jit_rvalue
*
618 gcc_jit_context_new_rvalue_from_int (gcc_jit_context
*ctxt
,
619 gcc_jit_type
*numeric_type
,
622 extern gcc_jit_rvalue
*
623 gcc_jit_context_zero (gcc_jit_context
*ctxt
,
624 gcc_jit_type
*numeric_type
);
626 extern gcc_jit_rvalue
*
627 gcc_jit_context_one (gcc_jit_context
*ctxt
,
628 gcc_jit_type
*numeric_type
);
630 /* Floating-point constants. */
631 extern gcc_jit_rvalue
*
632 gcc_jit_context_new_rvalue_from_double (gcc_jit_context
*ctxt
,
633 gcc_jit_type
*numeric_type
,
637 extern gcc_jit_rvalue
*
638 gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context
*ctxt
,
639 gcc_jit_type
*pointer_type
,
642 extern gcc_jit_rvalue
*
643 gcc_jit_context_null (gcc_jit_context
*ctxt
,
644 gcc_jit_type
*pointer_type
);
646 /* String literals. */
647 extern gcc_jit_rvalue
*
648 gcc_jit_context_new_string_literal (gcc_jit_context
*ctxt
,
651 enum gcc_jit_unary_op
653 /* Negate an arithmetic value; analogous to:
656 GCC_JIT_UNARY_OP_MINUS
,
658 /* Bitwise negation of an integer value (one's complement); analogous
662 GCC_JIT_UNARY_OP_BITWISE_NEGATE
,
664 /* Logical negation of an arithmetic or pointer value; analogous to:
667 GCC_JIT_UNARY_OP_LOGICAL_NEGATE
,
669 /* Absolute value of an arithmetic expression; analogous to:
676 extern gcc_jit_rvalue
*
677 gcc_jit_context_new_unary_op (gcc_jit_context
*ctxt
,
678 gcc_jit_location
*loc
,
679 enum gcc_jit_unary_op op
,
680 gcc_jit_type
*result_type
,
681 gcc_jit_rvalue
*rvalue
);
683 enum gcc_jit_binary_op
685 /* Addition of arithmetic values; analogous to:
688 For pointer addition, use gcc_jit_context_new_array_access. */
689 GCC_JIT_BINARY_OP_PLUS
,
691 /* Subtraction of arithmetic values; analogous to:
694 GCC_JIT_BINARY_OP_MINUS
,
696 /* Multiplication of a pair of arithmetic values; analogous to:
699 GCC_JIT_BINARY_OP_MULT
,
701 /* Quotient of division of arithmetic values; analogous to:
704 The result type affects the kind of division: if the result type is
705 integer-based, then the result is truncated towards zero, whereas
706 a floating-point result type indicates floating-point division. */
707 GCC_JIT_BINARY_OP_DIVIDE
,
709 /* Remainder of division of arithmetic values; analogous to:
712 GCC_JIT_BINARY_OP_MODULO
,
714 /* Bitwise AND; analogous to:
717 GCC_JIT_BINARY_OP_BITWISE_AND
,
719 /* Bitwise exclusive OR; analogous to:
722 GCC_JIT_BINARY_OP_BITWISE_XOR
,
724 /* Bitwise inclusive OR; analogous to:
727 GCC_JIT_BINARY_OP_BITWISE_OR
,
729 /* Logical AND; analogous to:
732 GCC_JIT_BINARY_OP_LOGICAL_AND
,
734 /* Logical OR; analogous to:
737 GCC_JIT_BINARY_OP_LOGICAL_OR
,
739 /* Left shift; analogous to:
742 GCC_JIT_BINARY_OP_LSHIFT
,
744 /* Right shift; analogous to:
747 GCC_JIT_BINARY_OP_RSHIFT
750 extern gcc_jit_rvalue
*
751 gcc_jit_context_new_binary_op (gcc_jit_context
*ctxt
,
752 gcc_jit_location
*loc
,
753 enum gcc_jit_binary_op op
,
754 gcc_jit_type
*result_type
,
755 gcc_jit_rvalue
*a
, gcc_jit_rvalue
*b
);
757 /* (Comparisons are treated as separate from "binary_op" to save
758 you having to specify the result_type). */
760 enum gcc_jit_comparison
762 /* (EXPR_A) == (EXPR_B). */
763 GCC_JIT_COMPARISON_EQ
,
765 /* (EXPR_A) != (EXPR_B). */
766 GCC_JIT_COMPARISON_NE
,
768 /* (EXPR_A) < (EXPR_B). */
769 GCC_JIT_COMPARISON_LT
,
771 /* (EXPR_A) <=(EXPR_B). */
772 GCC_JIT_COMPARISON_LE
,
774 /* (EXPR_A) > (EXPR_B). */
775 GCC_JIT_COMPARISON_GT
,
777 /* (EXPR_A) >= (EXPR_B). */
778 GCC_JIT_COMPARISON_GE
781 extern gcc_jit_rvalue
*
782 gcc_jit_context_new_comparison (gcc_jit_context
*ctxt
,
783 gcc_jit_location
*loc
,
784 enum gcc_jit_comparison op
,
785 gcc_jit_rvalue
*a
, gcc_jit_rvalue
*b
);
787 /* Function calls. */
789 /* Call of a specific function. */
790 extern gcc_jit_rvalue
*
791 gcc_jit_context_new_call (gcc_jit_context
*ctxt
,
792 gcc_jit_location
*loc
,
793 gcc_jit_function
*func
,
794 int numargs
, gcc_jit_rvalue
**args
);
796 /* Call through a function pointer. */
797 extern gcc_jit_rvalue
*
798 gcc_jit_context_new_call_through_ptr (gcc_jit_context
*ctxt
,
799 gcc_jit_location
*loc
,
800 gcc_jit_rvalue
*fn_ptr
,
801 int numargs
, gcc_jit_rvalue
**args
);
805 Currently only a limited set of conversions are possible:
808 extern gcc_jit_rvalue
*
809 gcc_jit_context_new_cast (gcc_jit_context
*ctxt
,
810 gcc_jit_location
*loc
,
811 gcc_jit_rvalue
*rvalue
,
814 extern gcc_jit_lvalue
*
815 gcc_jit_context_new_array_access (gcc_jit_context
*ctxt
,
816 gcc_jit_location
*loc
,
818 gcc_jit_rvalue
*index
);
820 /* Field access is provided separately for both lvalues and rvalues. */
822 /* Accessing a field of an lvalue of struct type, analogous to:
825 extern gcc_jit_lvalue
*
826 gcc_jit_lvalue_access_field (gcc_jit_lvalue
*struct_or_union
,
827 gcc_jit_location
*loc
,
828 gcc_jit_field
*field
);
830 /* Accessing a field of an rvalue of struct type, analogous to:
833 extern gcc_jit_rvalue
*
834 gcc_jit_rvalue_access_field (gcc_jit_rvalue
*struct_or_union
,
835 gcc_jit_location
*loc
,
836 gcc_jit_field
*field
);
838 /* Accessing a field of an rvalue of pointer type, analogous to:
840 in C, itself equivalent to (*EXPR).FIELD */
841 extern gcc_jit_lvalue
*
842 gcc_jit_rvalue_dereference_field (gcc_jit_rvalue
*ptr
,
843 gcc_jit_location
*loc
,
844 gcc_jit_field
*field
);
846 /* Dereferencing a pointer; analogous to:
849 extern gcc_jit_lvalue
*
850 gcc_jit_rvalue_dereference (gcc_jit_rvalue
*rvalue
,
851 gcc_jit_location
*loc
);
853 /* Taking the address of an lvalue; analogous to:
856 extern gcc_jit_rvalue
*
857 gcc_jit_lvalue_get_address (gcc_jit_lvalue
*lvalue
,
858 gcc_jit_location
*loc
);
860 extern gcc_jit_lvalue
*
861 gcc_jit_function_new_local (gcc_jit_function
*func
,
862 gcc_jit_location
*loc
,
866 /**********************************************************************
868 **********************************************************************/
870 /* Add evaluation of an rvalue, discarding the result
871 (e.g. a function call that "returns" void).
873 This is equivalent to this C code:
878 gcc_jit_block_add_eval (gcc_jit_block
*block
,
879 gcc_jit_location
*loc
,
880 gcc_jit_rvalue
*rvalue
);
882 /* Add evaluation of an rvalue, assigning the result to the given
885 This is roughly equivalent to this C code:
890 gcc_jit_block_add_assignment (gcc_jit_block
*block
,
891 gcc_jit_location
*loc
,
892 gcc_jit_lvalue
*lvalue
,
893 gcc_jit_rvalue
*rvalue
);
895 /* Add evaluation of an rvalue, using the result to modify an
898 This is analogous to "+=" and friends:
905 gcc_jit_block_add_assignment_op (gcc_jit_block
*block
,
906 gcc_jit_location
*loc
,
907 gcc_jit_lvalue
*lvalue
,
908 enum gcc_jit_binary_op op
,
909 gcc_jit_rvalue
*rvalue
);
911 /* Add a no-op textual comment to the internal representation of the
912 code. It will be optimized away, but will be visible in the dumps
914 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE
916 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE,
917 and thus may be of use when debugging how your project's internal
918 representation gets converted to the libgccjit IR. */
920 gcc_jit_block_add_comment (gcc_jit_block
*block
,
921 gcc_jit_location
*loc
,
924 /* Terminate a block by adding evaluation of an rvalue, branching on the
925 result to the appropriate successor block.
927 This is roughly equivalent to this C code:
934 block, boolval, on_true, and on_false must be non-NULL. */
936 gcc_jit_block_end_with_conditional (gcc_jit_block
*block
,
937 gcc_jit_location
*loc
,
938 gcc_jit_rvalue
*boolval
,
939 gcc_jit_block
*on_true
,
940 gcc_jit_block
*on_false
);
942 /* Terminate a block by adding a jump to the given target block.
944 This is roughly equivalent to this C code:
949 gcc_jit_block_end_with_jump (gcc_jit_block
*block
,
950 gcc_jit_location
*loc
,
951 gcc_jit_block
*target
);
953 /* Terminate a block by adding evaluation of an rvalue, returning the value.
955 This is roughly equivalent to this C code:
960 gcc_jit_block_end_with_return (gcc_jit_block
*block
,
961 gcc_jit_location
*loc
,
962 gcc_jit_rvalue
*rvalue
);
964 /* Terminate a block by adding a valueless return, for use within a function
965 with "void" return type.
967 This is equivalent to this C code:
972 gcc_jit_block_end_with_void_return (gcc_jit_block
*block
,
973 gcc_jit_location
*loc
);
975 /**********************************************************************
977 **********************************************************************/
979 /* Given an existing JIT context, create a child context.
981 The child inherits a copy of all option-settings from the parent.
983 The child can reference objects created within the parent, but not
986 The lifetime of the child context must be bounded by that of the
987 parent: you should release a child context before releasing the parent
990 If you use a function from a parent context within a child context,
991 you have to compile the parent context before you can compile the
992 child context, and the gcc_jit_result of the parent context must
993 outlive the gcc_jit_result of the child context.
995 This allows caching of shared initializations. For example, you could
996 create types and declarations of global functions in a parent context
997 once within a process, and then create child contexts whenever a
998 function or loop becomes hot. Each such child context can be used for
999 JIT-compiling just one function or loop, but can reference types
1000 and helper functions created within the parent context.
1002 Contexts can be arbitrarily nested, provided the above rules are
1003 followed, but it's probably not worth going above 2 or 3 levels, and
1004 there will likely be a performance hit for such nesting. */
1006 extern gcc_jit_context
*
1007 gcc_jit_context_new_child_context (gcc_jit_context
*parent_ctxt
);
1009 /**********************************************************************
1010 Implementation support.
1011 **********************************************************************/
1013 /* Enable the dumping of a specific set of internal state from the
1014 compilation, capturing the result in-memory as a buffer.
1016 Parameter "dumpname" corresponds to the equivalent gcc command-line
1017 option, without the "-fdump-" prefix.
1018 For example, to get the equivalent of "-fdump-tree-vrp1", supply
1020 The context directly stores the dumpname as a (const char *), so the
1021 passed string must outlive the context.
1023 gcc_jit_context_compile will capture the dump as a
1024 dynamically-allocated buffer, writing it to ``*out_ptr``.
1026 The caller becomes responsible for calling
1028 each time that gcc_jit_context_compile is called. *out_ptr will be
1029 written to, either with the address of a buffer, or with NULL if an
1032 This API entrypoint is likely to be less stable than the others.
1033 In particular, both the precise dumpnames, and the format and content
1034 of the dumps are subject to change.
1036 It exists primarily for writing the library's own test suite. */
1039 gcc_jit_context_enable_dump (gcc_jit_context
*ctxt
,
1040 const char *dumpname
,
1045 #endif /* __cplusplus */
1047 #endif /* LIBGCCJIT_H */