1 \input texinfo @c -*-texinfo-*-
3 @setfilename libgccjit.info
4 @documentencoding UTF-8
6 @*Generated by Sphinx 1.1.3.@*
8 @settitle libgccjit Documentation
13 @dircategory Miscellaneous
15 * libgccjit: (libgccjit.info). One line description of project.
22 libgccjit 5.0.0 (experimental 20150112), January 12, 2015
26 Copyright @copyright{} 2014, Free Software Foundation
32 @title libgccjit Documentation
37 @c %** start of user preamble
39 @c %** end of user preamble
43 @top libgccjit Documentation
48 @anchor{index doc}@anchor{0}
49 @c Copyright (C) 2014 Free Software Foundation, Inc.
50 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
52 @c This is free software: you can redistribute it and/or modify it
53 @c under the terms of the GNU General Public License as published by
54 @c the Free Software Foundation, either version 3 of the License, or
55 @c (at your option) any later version.
57 @c This program is distributed in the hope that it will be useful, but
58 @c WITHOUT ANY WARRANTY; without even the implied warranty of
59 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
60 @c General Public License for more details.
62 @c You should have received a copy of the GNU General Public License
63 @c along with this program. If not, see
64 @c <http://www.gnu.org/licenses/>.
66 This document describes libgccjit@footnote{http://gcc.gnu.org/wiki/JIT}, an API
67 for embedding GCC inside programs and libraries.
69 Note that libgccjit is currently of "Alpha" quality;
70 the APIs are not yet set in stone, and they shouldn't be used in
73 There are actually two APIs for the library:
79 a pure C API: @code{libgccjit.h}
82 a C++ wrapper API: @code{libgccjit++.h}. This is a collection of "thin"
83 wrapper classes around the C API, to save typing.
88 @c Copyright (C) 2014 Free Software Foundation, Inc.
89 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
91 @c This is free software: you can redistribute it and/or modify it
92 @c under the terms of the GNU General Public License as published by
93 @c the Free Software Foundation, either version 3 of the License, or
94 @c (at your option) any later version.
96 @c This program is distributed in the hope that it will be useful, but
97 @c WITHOUT ANY WARRANTY; without even the implied warranty of
98 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
99 @c General Public License for more details.
101 @c You should have received a copy of the GNU General Public License
102 @c along with this program. If not, see
103 @c <http://www.gnu.org/licenses/>.
108 * C++ bindings for libgccjit::
110 * Indices and tables::
114 --- The Detailed Node Listing ---
118 * Tutorial part 1; "Hello world": Tutorial part 1 "Hello world".
119 * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function.
120 * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables.
121 * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter.
123 Tutorial part 2: Creating a trivial machine code function
129 Tutorial part 3: Loops and variables
131 * Expressions; lvalues and rvalues: Expressions lvalues and rvalues.
133 * Visualizing the control flow graph::
134 * Full example: Full example<2>.
136 Tutorial part 4: Adding JIT-compilation to a toy interpreter
138 * Our toy interpreter::
139 * Compiling to machine code::
140 * Setting things up::
141 * Populating the function::
142 * Verifying the control flow graph::
143 * Compiling the context::
144 * Single-stepping through the generated code::
145 * Examining the generated code::
146 * Putting it all together::
147 * Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?.
149 Behind the curtain: How does our code get optimized?
151 * Optimizing away stack manipulation::
152 * Elimination of tail recursion::
156 * Compilation contexts::
160 * Creating and using functions::
162 * Compilation results::
166 * Lifetime-management::
168 * Error-handling: Error-handling<2>.
170 * Options: Options<2>.
181 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile.
182 * Structures and unions::
188 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions.
192 * Simple expressions::
194 * Binary Operations::
203 Creating and using functions
214 C++ bindings for libgccjit
216 * Tutorial: Tutorial<2>.
217 * Topic Reference: Topic Reference<2>.
221 * Tutorial part 1; "Hello world": Tutorial part 1 "Hello world"<2>.
222 * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>.
223 * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>.
224 * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>.
226 Tutorial part 2: Creating a trivial machine code function
228 * Options: Options<3>.
229 * Full example: Full example<3>.
231 Tutorial part 3: Loops and variables
233 * Expressions; lvalues and rvalues: Expressions lvalues and rvalues<2>.
234 * Control flow: Control flow<2>.
235 * Visualizing the control flow graph: Visualizing the control flow graph<2>.
236 * Full example: Full example<4>.
238 Tutorial part 4: Adding JIT-compilation to a toy interpreter
240 * Our toy interpreter: Our toy interpreter<2>.
241 * Compiling to machine code: Compiling to machine code<2>.
242 * Setting things up: Setting things up<2>.
243 * Populating the function: Populating the function<2>.
244 * Verifying the control flow graph: Verifying the control flow graph<2>.
245 * Compiling the context: Compiling the context<2>.
246 * Single-stepping through the generated code: Single-stepping through the generated code<2>.
247 * Examining the generated code: Examining the generated code<2>.
248 * Putting it all together: Putting it all together<2>.
249 * Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?<2>.
251 Behind the curtain: How does our code get optimized?
253 * Optimizing away stack manipulation: Optimizing away stack manipulation<2>.
254 * Elimination of tail recursion: Elimination of tail recursion<2>.
258 * Compilation contexts: Compilation contexts<2>.
259 * Objects: Objects<2>.
261 * Expressions: Expressions<2>.
262 * Creating and using functions: Creating and using functions<2>.
263 * Source Locations: Source Locations<2>.
264 * Compilation results: Compilation results<2>.
268 * Lifetime-management: Lifetime-management<2>.
269 * Thread-safety: Thread-safety<2>.
270 * Error-handling: Error-handling<3>.
271 * Debugging: Debugging<2>.
272 * Options: Options<4>.
276 * String Options: String Options<2>.
277 * Boolean options: Boolean options<2>.
278 * Integer options: Integer options<2>.
282 * Standard types: Standard types<2>.
283 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
284 * Structures and unions: Structures and unions<2>.
288 * Rvalues: Rvalues<2>.
289 * Lvalues: Lvalues<2>.
290 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
294 * Simple expressions: Simple expressions<2>.
295 * Unary Operations: Unary Operations<2>.
296 * Binary Operations: Binary Operations<2>.
297 * Comparisons: Comparisons<2>.
298 * Function calls: Function calls<2>.
299 * Type-coercion: Type-coercion<2>.
303 * Global variables: Global variables<2>.
305 Creating and using functions
308 * Functions: Functions<2>.
310 * Statements: Statements<2>.
314 * Faking it: Faking it<2>.
318 * Working on the JIT library::
319 * Running the test suite::
320 * Environment variables::
321 * Overview of code structure::
323 Running the test suite
325 * Running under valgrind::
331 @node Tutorial,Topic Reference,Top,Top
332 @anchor{intro/index libgccjit}@anchor{1}@anchor{intro/index doc}@anchor{2}@anchor{intro/index tutorial}@anchor{3}
336 @c Copyright (C) 2014 Free Software Foundation, Inc.
337 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
339 @c This is free software: you can redistribute it and/or modify it
340 @c under the terms of the GNU General Public License as published by
341 @c the Free Software Foundation, either version 3 of the License, or
342 @c (at your option) any later version.
344 @c This program is distributed in the hope that it will be useful, but
345 @c WITHOUT ANY WARRANTY; without even the implied warranty of
346 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
347 @c General Public License for more details.
349 @c You should have received a copy of the GNU General Public License
350 @c along with this program. If not, see
351 @c <http://www.gnu.org/licenses/>.
354 * Tutorial part 1; "Hello world": Tutorial part 1 "Hello world".
355 * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function.
356 * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables.
357 * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter.
361 @node Tutorial part 1 "Hello world",Tutorial part 2 Creating a trivial machine code function,,Tutorial
362 @anchor{intro/tutorial01 doc}@anchor{4}@anchor{intro/tutorial01 tutorial-part-1-hello-world}@anchor{5}
363 @section Tutorial part 1: "Hello world"
366 Before we look at the details of the API, let's look at building and
367 running programs that use the library.
369 Here's a toy "hello world" program that uses the library to synthesize
370 a call to @cite{printf} and uses it to write a message to stdout.
372 Don't worry about the content of the program for now; we'll cover
373 the details in later parts of this tutorial.
378 /* Smoketest example for libgccjit.so
379 Copyright (C) 2014 Free Software Foundation, Inc.
381 This file is part of GCC.
383 GCC is free software; you can redistribute it and/or modify it
384 under the terms of the GNU General Public License as published by
385 the Free Software Foundation; either version 3, or (at your option)
388 GCC is distributed in the hope that it will be useful, but
389 WITHOUT ANY WARRANTY; without even the implied warranty of
390 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
391 General Public License for more details.
393 You should have received a copy of the GNU General Public License
394 along with GCC; see the file COPYING3. If not see
395 <http://www.gnu.org/licenses/>. */
397 #include <libgccjit.h>
403 create_code (gcc_jit_context *ctxt)
405 /* Let's try to inject the equivalent of:
407 greet (const char *name)
409 printf ("hello %s\n", name);
412 gcc_jit_type *void_type =
413 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_VOID);
414 gcc_jit_type *const_char_ptr_type =
415 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_CONST_CHAR_PTR);
416 gcc_jit_param *param_name =
417 gcc_jit_context_new_param (ctxt, NULL, const_char_ptr_type, "name");
418 gcc_jit_function *func =
419 gcc_jit_context_new_function (ctxt, NULL,
420 GCC_JIT_FUNCTION_EXPORTED,
426 gcc_jit_param *param_format =
427 gcc_jit_context_new_param (ctxt, NULL, const_char_ptr_type, "format");
428 gcc_jit_function *printf_func =
429 gcc_jit_context_new_function (ctxt, NULL,
430 GCC_JIT_FUNCTION_IMPORTED,
431 gcc_jit_context_get_type (
432 ctxt, GCC_JIT_TYPE_INT),
436 gcc_jit_rvalue *args[2];
437 args[0] = gcc_jit_context_new_string_literal (ctxt, "hello %s\n");
438 args[1] = gcc_jit_param_as_rvalue (param_name);
440 gcc_jit_block *block = gcc_jit_function_new_block (func, NULL);
442 gcc_jit_block_add_eval (
444 gcc_jit_context_new_call (ctxt,
448 gcc_jit_block_end_with_void_return (block, NULL);
452 main (int argc, char **argv)
454 gcc_jit_context *ctxt;
455 gcc_jit_result *result;
457 /* Get a "context" object for working with the library. */
458 ctxt = gcc_jit_context_acquire ();
461 fprintf (stderr, "NULL ctxt");
465 /* Set some options on the context.
466 Let's see the code being generated, in assembler form. */
467 gcc_jit_context_set_bool_option (
469 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
472 /* Populate the context. */
475 /* Compile the code. */
476 result = gcc_jit_context_compile (ctxt);
479 fprintf (stderr, "NULL result");
483 /* Extract the generated code from "result". */
484 typedef void (*fn_type) (const char *);
486 (fn_type)gcc_jit_result_get_code (result, "greet");
489 fprintf (stderr, "NULL greet");
493 /* Now call the generated function: */
497 gcc_jit_context_release (ctxt);
498 gcc_jit_result_release (result);
507 Copy the above to @cite{tut01-hello-world.c}.
509 Assuming you have the jit library installed, build the test program
514 tut01-hello-world.c \
515 -o tut01-hello-world \
521 You should then be able to run the built program:
524 $ ./tut01-hello-world
530 @c Copyright (C) 2014 Free Software Foundation, Inc.
531 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
533 @c This is free software: you can redistribute it and/or modify it
534 @c under the terms of the GNU General Public License as published by
535 @c the Free Software Foundation, either version 3 of the License, or
536 @c (at your option) any later version.
538 @c This program is distributed in the hope that it will be useful, but
539 @c WITHOUT ANY WARRANTY; without even the implied warranty of
540 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
541 @c General Public License for more details.
543 @c You should have received a copy of the GNU General Public License
544 @c along with this program. If not, see
545 @c <http://www.gnu.org/licenses/>.
547 @node Tutorial part 2 Creating a trivial machine code function,Tutorial part 3 Loops and variables,Tutorial part 1 "Hello world",Tutorial
548 @anchor{intro/tutorial02 doc}@anchor{6}@anchor{intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{7}
549 @section Tutorial part 2: Creating a trivial machine code function
552 Consider this C function:
563 How can we construct this at run-time using libgccjit?
565 First we need to include the relevant header:
568 #include <libgccjit.h>
573 All state associated with compilation is associated with a
574 @pxref{8,,gcc_jit_context *}.
576 Create one using @pxref{9,,gcc_jit_context_acquire()}:
579 gcc_jit_context *ctxt;
580 ctxt = gcc_jit_context_acquire ();
585 The JIT library has a system of types. It is statically-typed: every
586 expression is of a specific type, fixed at compile-time. In our example,
587 all of the expressions are of the C @cite{int} type, so let's obtain this from
588 the context, as a @pxref{a,,gcc_jit_type *}, using
589 @pxref{b,,gcc_jit_context_get_type()}:
592 gcc_jit_type *int_type =
593 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
598 @pxref{a,,gcc_jit_type *} is an example of a "contextual" object: every
599 entity in the API is associated with a @pxref{8,,gcc_jit_context *}.
601 Memory management is easy: all such "contextual" objects are automatically
602 cleaned up for you when the context is released, using
603 @pxref{c,,gcc_jit_context_release()}:
606 gcc_jit_context_release (ctxt);
611 so you don't need to manually track and cleanup all objects, just the
614 Although the API is C-based, there is a form of class hierarchy, which
632 There are casting methods for upcasting from subclasses to parent classes.
633 For example, @pxref{d,,gcc_jit_type_as_object()}:
636 gcc_jit_object *obj = gcc_jit_type_as_object (int_type);
641 One thing you can do with a @pxref{e,,gcc_jit_object *} is
642 to ask it for a human-readable description, using
643 @pxref{f,,gcc_jit_object_get_debug_string()}:
646 printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj));
651 giving this text on stdout:
659 This is invaluable when debugging.
661 Let's create the function. To do so, we first need to construct
662 its single parameter, specifying its type and giving it a name,
663 using @pxref{10,,gcc_jit_context_new_param()}:
666 gcc_jit_param *param_i =
667 gcc_jit_context_new_param (ctxt, NULL, int_type, "i");
672 Now we can create the function, using
673 @pxref{11,,gcc_jit_context_new_function()}:
676 gcc_jit_function *func =
677 gcc_jit_context_new_function (ctxt, NULL,
678 GCC_JIT_FUNCTION_EXPORTED,
687 To define the code within the function, we must create basic blocks
688 containing statements.
690 Every basic block contains a list of statements, eventually terminated
691 by a statement that either returns, or jumps to another basic block.
693 Our function has no control-flow, so we just need one basic block:
696 gcc_jit_block *block = gcc_jit_function_new_block (func, NULL);
701 Our basic block is relatively simple: it immediately terminates by
702 returning the value of an expression.
704 We can build the expression using @pxref{12,,gcc_jit_context_new_binary_op()}:
707 gcc_jit_rvalue *expr =
708 gcc_jit_context_new_binary_op (
710 GCC_JIT_BINARY_OP_MULT, int_type,
711 gcc_jit_param_as_rvalue (param_i),
712 gcc_jit_param_as_rvalue (param_i));
717 A @pxref{13,,gcc_jit_rvalue *} is another example of a
718 @pxref{e,,gcc_jit_object *} subclass. We can upcast it using
719 @pxref{14,,gcc_jit_rvalue_as_object()} and as before print it with
720 @pxref{f,,gcc_jit_object_get_debug_string()}.
723 printf ("expr: %s\n",
724 gcc_jit_object_get_debug_string (
725 gcc_jit_rvalue_as_object (expr)));
738 Creating the expression in itself doesn't do anything; we have to add
739 this expression to a statement within the block. In this case, we use it
740 to build a return statement, which terminates the basic block:
743 gcc_jit_block_end_with_return (block, NULL, expr);
748 OK, we've populated the context. We can now compile it using
749 @pxref{15,,gcc_jit_context_compile()}:
752 gcc_jit_result *result;
753 result = gcc_jit_context_compile (ctxt);
758 and get a @pxref{16,,gcc_jit_result *}.
760 At this point we're done with the context; we can release it:
763 gcc_jit_context_release (ctxt);
768 We can now use @pxref{17,,gcc_jit_result_get_code()} to look up a specific
769 machine code routine within the result, in this case, the function we
773 void *fn_ptr = gcc_jit_result_get_code (result, "square");
776 fprintf (stderr, "NULL fn_ptr");
783 We can now cast the pointer to an appropriate function pointer type, and
787 typedef int (*fn_type) (int);
788 fn_type square = (fn_type)fn_ptr;
789 printf ("result: %d", square (5));
800 Once we're done with the code, we can release the result:
803 gcc_jit_result_release (result);
808 We can't call @code{square} anymore once we've released @code{result}.
817 @node Error-handling,Options,,Tutorial part 2 Creating a trivial machine code function
818 @anchor{intro/tutorial02 error-handling}@anchor{18}
819 @subsection Error-handling
822 Various kinds of errors are possible when using the API, such as
823 mismatched types in an assignment. You can only compile and get code
824 from a context if no errors occur.
826 Errors are printed on stderr; they typically contain the name of the API
827 entrypoint where the error occurred, and pertinent information on the
831 ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *)
836 The API is designed to cope with errors without crashing, so you can get
837 away with having a single error-handling check in your code:
840 void *fn_ptr = gcc_jit_result_get_code (result, "square");
843 fprintf (stderr, "NULL fn_ptr");
850 For more information, see the @pxref{19,,error-handling guide}
851 within the Topic eference.
853 @node Options,Full example,Error-handling,Tutorial part 2 Creating a trivial machine code function
854 @anchor{intro/tutorial02 options}@anchor{1a}
858 To get more information on what's going on, you can set debugging flags
859 on the context using @pxref{1b,,gcc_jit_context_set_bool_option()}.
861 @c (I'm deliberately not mentioning
862 @c :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE` here since I think
863 @c it's probably more of use to implementors than to users)
865 Setting @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE} will dump a
866 C-like representation to stderr when you compile (GCC's "GIMPLE"
870 gcc_jit_context_set_bool_option (
872 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE,
874 result = gcc_jit_context_compile (ctxt);
880 square (signed int i)
892 We can see the generated machine code in assembler form (on stderr) by
893 setting @pxref{1d,,GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE} on the context
897 gcc_jit_context_set_bool_option (
899 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
901 result = gcc_jit_context_compile (ctxt);
910 .type square, @@function
915 .cfi_def_cfa_offset 16
918 .cfi_def_cfa_register 6
928 .size square, .-square
929 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
930 .section .note.GNU-stack,"",@@progbits
935 By default, no optimizations are performed, the equivalent of GCC's
936 @cite{-O0} option. We can turn things up to e.g. @cite{-O3} by calling
937 @pxref{1e,,gcc_jit_context_set_int_option()} with
938 @pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
941 gcc_jit_context_set_int_option (
943 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL,
954 .type square, @@function
964 .size square, .-square
965 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
966 .section .note.GNU-stack,"",@@progbits
971 Naturally this has only a small effect on such a trivial function.
973 @node Full example,,Options,Tutorial part 2 Creating a trivial machine code function
974 @anchor{intro/tutorial02 full-example}@anchor{20}
975 @subsection Full example
978 Here's what the above looks like as a complete program:
983 /* Usage example for libgccjit.so
984 Copyright (C) 2014 Free Software Foundation, Inc.
986 This file is part of GCC.
988 GCC is free software; you can redistribute it and/or modify it
989 under the terms of the GNU General Public License as published by
990 the Free Software Foundation; either version 3, or (at your option)
993 GCC is distributed in the hope that it will be useful, but
994 WITHOUT ANY WARRANTY; without even the implied warranty of
995 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
996 General Public License for more details.
998 You should have received a copy of the GNU General Public License
999 along with GCC; see the file COPYING3. If not see
1000 <http://www.gnu.org/licenses/>. */
1002 #include <libgccjit.h>
1008 create_code (gcc_jit_context *ctxt)
1010 /* Let's try to inject the equivalent of:
1017 gcc_jit_type *int_type =
1018 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
1019 gcc_jit_param *param_i =
1020 gcc_jit_context_new_param (ctxt, NULL, int_type, "i");
1021 gcc_jit_function *func =
1022 gcc_jit_context_new_function (ctxt, NULL,
1023 GCC_JIT_FUNCTION_EXPORTED,
1029 gcc_jit_block *block = gcc_jit_function_new_block (func, NULL);
1031 gcc_jit_rvalue *expr =
1032 gcc_jit_context_new_binary_op (
1034 GCC_JIT_BINARY_OP_MULT, int_type,
1035 gcc_jit_param_as_rvalue (param_i),
1036 gcc_jit_param_as_rvalue (param_i));
1038 gcc_jit_block_end_with_return (block, NULL, expr);
1042 main (int argc, char **argv)
1044 gcc_jit_context *ctxt = NULL;
1045 gcc_jit_result *result = NULL;
1047 /* Get a "context" object for working with the library. */
1048 ctxt = gcc_jit_context_acquire ();
1051 fprintf (stderr, "NULL ctxt");
1055 /* Set some options on the context.
1056 Let's see the code being generated, in assembler form. */
1057 gcc_jit_context_set_bool_option (
1059 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
1062 /* Populate the context. */
1065 /* Compile the code. */
1066 result = gcc_jit_context_compile (ctxt);
1069 fprintf (stderr, "NULL result");
1073 /* We're done with the context; we can release it: */
1074 gcc_jit_context_release (ctxt);
1077 /* Extract the generated code from "result". */
1078 void *fn_ptr = gcc_jit_result_get_code (result, "square");
1081 fprintf (stderr, "NULL fn_ptr");
1085 typedef int (*fn_type) (int);
1086 fn_type square = (fn_type)fn_ptr;
1087 printf ("result: %d\n", square (5));
1091 gcc_jit_context_release (ctxt);
1093 gcc_jit_result_release (result);
1102 Building and running it:
1110 # Run the built program:
1117 @c Copyright (C) 2014 Free Software Foundation, Inc.
1118 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
1120 @c This is free software: you can redistribute it and/or modify it
1121 @c under the terms of the GNU General Public License as published by
1122 @c the Free Software Foundation, either version 3 of the License, or
1123 @c (at your option) any later version.
1125 @c This program is distributed in the hope that it will be useful, but
1126 @c WITHOUT ANY WARRANTY; without even the implied warranty of
1127 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1128 @c General Public License for more details.
1130 @c You should have received a copy of the GNU General Public License
1131 @c along with this program. If not, see
1132 @c <http://www.gnu.org/licenses/>.
1134 @node Tutorial part 3 Loops and variables,Tutorial part 4 Adding JIT-compilation to a toy interpreter,Tutorial part 2 Creating a trivial machine code function,Tutorial
1135 @anchor{intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{21}@anchor{intro/tutorial03 doc}@anchor{22}
1136 @section Tutorial part 3: Loops and variables
1139 Consider this C function:
1144 int loop_test (int n)
1147 for (int i = 0; i < n; i++)
1156 This example demonstrates some more features of libgccjit, with local
1157 variables and a loop.
1159 To break this down into libgccjit terms, it's usually easier to reword
1160 the @cite{for} loop as a @cite{while} loop, giving:
1165 int loop_test (int n)
1181 Here's what the final control flow graph will look like:
1188 @image{sum-of-squares1,,,image of a control flow graph,png}
1194 As before, we include the libgccjit header and make a
1195 @pxref{8,,gcc_jit_context *}.
1198 #include <libgccjit.h>
1202 gcc_jit_context *ctxt;
1203 ctxt = gcc_jit_context_acquire ();
1208 The function works with the C @cite{int} type:
1211 gcc_jit_type *the_type =
1212 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
1213 gcc_jit_type *return_type = the_type;
1218 though we could equally well make it work on, say, @cite{double}:
1221 gcc_jit_type *the_type =
1222 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_DOUBLE);
1227 Let's build the function:
1231 gcc_jit_context_new_param (ctxt, NULL, the_type, "n");
1232 gcc_jit_param *params[1] = @{n@};
1233 gcc_jit_function *func =
1234 gcc_jit_context_new_function (ctxt, NULL,
1235 GCC_JIT_FUNCTION_EXPORTED,
1244 * Expressions; lvalues and rvalues: Expressions lvalues and rvalues.
1246 * Visualizing the control flow graph::
1247 * Full example: Full example<2>.
1251 @node Expressions lvalues and rvalues,Control flow,,Tutorial part 3 Loops and variables
1252 @anchor{intro/tutorial03 expressions-lvalues-and-rvalues}@anchor{23}
1253 @subsection Expressions: lvalues and rvalues
1256 The base class of expression is the @pxref{13,,gcc_jit_rvalue *},
1257 representing an expression that can be on the @emph{right}-hand side of
1258 an assignment: a value that can be computed somehow, and assigned
1259 @emph{to} a storage area (such as a variable). It has a specific
1260 @pxref{a,,gcc_jit_type *}.
1262 Anothe important class is @pxref{24,,gcc_jit_lvalue *}.
1263 A @pxref{24,,gcc_jit_lvalue *}. is something that can of the @emph{left}-hand
1264 side of an assignment: a storage area (such as a variable).
1266 In other words, every assignment can be thought of as:
1274 Note that @pxref{24,,gcc_jit_lvalue *} is a subclass of
1275 @pxref{13,,gcc_jit_rvalue *}, where in an assignment of the form:
1278 LVALUE_A = LVALUE_B;
1283 the @cite{LVALUE_B} implies reading the current value of that storage
1284 area, assigning it into the @cite{LVALUE_A}.
1286 So far the only expressions we've seen are @cite{i * i}:
1289 gcc_jit_rvalue *expr =
1290 gcc_jit_context_new_binary_op (
1292 GCC_JIT_BINARY_OP_MULT, int_type,
1293 gcc_jit_param_as_rvalue (param_i),
1294 gcc_jit_param_as_rvalue (param_i));
1299 which is a @pxref{13,,gcc_jit_rvalue *}, and the various function
1300 parameters: @cite{param_i} and @cite{param_n}, instances of
1301 @pxref{25,,gcc_jit_param *}, which is a subclass of
1302 @pxref{24,,gcc_jit_lvalue *} (and, in turn, of @pxref{13,,gcc_jit_rvalue *}):
1303 we can both read from and write to function parameters within the
1306 Our new example has a couple of local variables. We create them by
1307 calling @pxref{26,,gcc_jit_function_new_local()}, supplying a type and a
1313 gcc_jit_function_new_local (func, NULL, the_type, "i");
1314 gcc_jit_lvalue *sum =
1315 gcc_jit_function_new_local (func, NULL, the_type, "sum");
1320 These are instances of @pxref{24,,gcc_jit_lvalue *} - they can be read from
1323 Note that there is no precanned way to create @emph{and} initialize a variable
1332 Instead, having added the local to the function, we have to separately add
1333 an assignment of @cite{0} to @cite{local_i} at the beginning of the function.
1335 @node Control flow,Visualizing the control flow graph,Expressions lvalues and rvalues,Tutorial part 3 Loops and variables
1336 @anchor{intro/tutorial03 control-flow}@anchor{27}
1337 @subsection Control flow
1340 This function has a loop, so we need to build some basic blocks to
1341 handle the control flow. In this case, we need 4 blocks:
1347 before the loop (initializing the locals)
1350 the conditional at the top of the loop (comparing @cite{i < n})
1353 the body of the loop
1356 after the loop terminates (@cite{return sum})
1359 so we create these as @pxref{28,,gcc_jit_block *} instances within the
1360 @pxref{29,,gcc_jit_function *}:
1363 gcc_jit_block *b_initial =
1364 gcc_jit_function_new_block (func, "initial");
1365 gcc_jit_block *b_loop_cond =
1366 gcc_jit_function_new_block (func, "loop_cond");
1367 gcc_jit_block *b_loop_body =
1368 gcc_jit_function_new_block (func, "loop_body");
1369 gcc_jit_block *b_after_loop =
1370 gcc_jit_function_new_block (func, "after_loop");
1375 We now populate each block with statements.
1377 The entry block @cite{b_initial} consists of initializations followed by a jump
1378 to the conditional. We assign @cite{0} to @cite{i} and to @cite{sum}, using
1379 @pxref{2a,,gcc_jit_block_add_assignment()} to add
1380 an assignment statement, and using @pxref{2b,,gcc_jit_context_zero()} to get
1381 the constant value @cite{0} for the relevant type for the right-hand side of
1386 gcc_jit_block_add_assignment (
1389 gcc_jit_context_zero (ctxt, the_type));
1392 gcc_jit_block_add_assignment (
1395 gcc_jit_context_zero (ctxt, the_type));
1400 We can then terminate the entry block by jumping to the conditional:
1403 gcc_jit_block_end_with_jump (b_initial, NULL, b_loop_cond);
1408 The conditional block is equivalent to the line @cite{while (i < n)} from our
1409 C example. It contains a single statement: a conditional, which jumps to
1410 one of two destination blocks depending on a boolean
1411 @pxref{13,,gcc_jit_rvalue *}, in this case the comparison of @cite{i} and @cite{n}.
1412 We build the comparison using @pxref{2c,,gcc_jit_context_new_comparison()}:
1415 gcc_jit_rvalue *guard =
1416 gcc_jit_context_new_comparison (
1418 GCC_JIT_COMPARISON_GE,
1419 gcc_jit_lvalue_as_rvalue (i),
1420 gcc_jit_param_as_rvalue (n));
1425 and can then use this to add @cite{b_loop_cond}'s sole statement, via
1426 @pxref{2d,,gcc_jit_block_end_with_conditional()}:
1429 gcc_jit_block_end_with_conditional (b_loop_cond, NULL, guard);
1434 Next, we populate the body of the loop.
1436 The C statement @cite{sum += i * i;} is an assignment operation, where an
1437 lvalue is modified "in-place". We use
1438 @pxref{2e,,gcc_jit_block_add_assignment_op()} to handle these operations:
1442 gcc_jit_block_add_assignment_op (
1445 GCC_JIT_BINARY_OP_PLUS,
1446 gcc_jit_context_new_binary_op (
1448 GCC_JIT_BINARY_OP_MULT, the_type,
1449 gcc_jit_lvalue_as_rvalue (i),
1450 gcc_jit_lvalue_as_rvalue (i)));
1455 The @cite{i++} can be thought of as @cite{i += 1}, and can thus be handled in
1456 a similar way. We use @pxref{2f,,gcc_jit_context_one()} to get the constant
1457 value @cite{1} (for the relevant type) for the right-hand side
1462 gcc_jit_block_add_assignment_op (
1465 GCC_JIT_BINARY_OP_PLUS,
1466 gcc_jit_context_one (ctxt, the_type));
1473 For numeric constants other than 0 or 1, we could use
1474 @pxref{30,,gcc_jit_context_new_rvalue_from_int()} and
1475 @pxref{31,,gcc_jit_context_new_rvalue_from_double()}.
1479 The loop body completes by jumping back to the conditional:
1482 gcc_jit_block_end_with_jump (b_loop_body, NULL, b_loop_cond);
1487 Finally, we populate the @cite{b_after_loop} block, reached when the loop
1488 conditional is false. We want to generate the equivalent of:
1496 so the block is just one statement:
1500 gcc_jit_block_end_with_return (
1503 gcc_jit_lvalue_as_rvalue (sum));
1510 You can intermingle block creation with statement creation,
1511 but given that the terminator statements generally include references
1512 to other blocks, I find it's clearer to create all the blocks,
1513 @emph{then} all the statements.
1517 We've finished populating the function. As before, we can now compile it
1521 gcc_jit_result *result;
1522 result = gcc_jit_context_compile (ctxt);
1524 typedef int (*loop_test_fn_type) (int);
1525 loop_test_fn_type loop_test =
1526 (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
1529 printf ("result: %d", loop_test (10));
1540 @node Visualizing the control flow graph,Full example<2>,Control flow,Tutorial part 3 Loops and variables
1541 @anchor{intro/tutorial03 visualizing-the-control-flow-graph}@anchor{32}
1542 @subsection Visualizing the control flow graph
1545 You can see the control flow graph of a function using
1546 @pxref{33,,gcc_jit_function_dump_to_dot()}:
1549 gcc_jit_function_dump_to_dot (func, "/tmp/sum-of-squares.dot");
1554 giving a .dot file in GraphViz format.
1556 You can convert this to an image using @cite{dot}:
1559 $ dot -Tpng /tmp/sum-of-squares.dot -o /tmp/sum-of-squares.png
1564 or use a viewer (my preferred one is xdot.py; see
1565 @indicateurl{https://github.com/jrfonseca/xdot.py}; on Fedora you can
1566 install it with @cite{yum install python-xdot}):
1573 @image{sum-of-squares1,,,image of a control flow graph,png}
1579 @node Full example<2>,,Visualizing the control flow graph,Tutorial part 3 Loops and variables
1580 @anchor{intro/tutorial03 full-example}@anchor{34}
1581 @subsection Full example
1587 /* Usage example for libgccjit.so
1588 Copyright (C) 2014 Free Software Foundation, Inc.
1590 This file is part of GCC.
1592 GCC is free software; you can redistribute it and/or modify it
1593 under the terms of the GNU General Public License as published by
1594 the Free Software Foundation; either version 3, or (at your option)
1597 GCC is distributed in the hope that it will be useful, but
1598 WITHOUT ANY WARRANTY; without even the implied warranty of
1599 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1600 General Public License for more details.
1602 You should have received a copy of the GNU General Public License
1603 along with GCC; see the file COPYING3. If not see
1604 <http://www.gnu.org/licenses/>. */
1606 #include <libgccjit.h>
1612 create_code (gcc_jit_context *ctxt)
1615 Simple sum-of-squares, to test conditionals and looping
1617 int loop_test (int n)
1621 for (i = 0; i < n ; i ++)
1627 gcc_jit_type *the_type =
1628 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
1629 gcc_jit_type *return_type = the_type;
1632 gcc_jit_context_new_param (ctxt, NULL, the_type, "n");
1633 gcc_jit_param *params[1] = @{n@};
1634 gcc_jit_function *func =
1635 gcc_jit_context_new_function (ctxt, NULL,
1636 GCC_JIT_FUNCTION_EXPORTED,
1643 gcc_jit_function_new_local (func, NULL, the_type, "i");
1644 gcc_jit_lvalue *sum =
1645 gcc_jit_function_new_local (func, NULL, the_type, "sum");
1647 gcc_jit_block *b_initial =
1648 gcc_jit_function_new_block (func, "initial");
1649 gcc_jit_block *b_loop_cond =
1650 gcc_jit_function_new_block (func, "loop_cond");
1651 gcc_jit_block *b_loop_body =
1652 gcc_jit_function_new_block (func, "loop_body");
1653 gcc_jit_block *b_after_loop =
1654 gcc_jit_function_new_block (func, "after_loop");
1657 gcc_jit_block_add_assignment (
1660 gcc_jit_context_zero (ctxt, the_type));
1663 gcc_jit_block_add_assignment (
1666 gcc_jit_context_zero (ctxt, the_type));
1668 gcc_jit_block_end_with_jump (b_initial, NULL, b_loop_cond);
1671 gcc_jit_block_end_with_conditional (
1673 gcc_jit_context_new_comparison (
1675 GCC_JIT_COMPARISON_GE,
1676 gcc_jit_lvalue_as_rvalue (i),
1677 gcc_jit_param_as_rvalue (n)),
1682 gcc_jit_block_add_assignment_op (
1685 GCC_JIT_BINARY_OP_PLUS,
1686 gcc_jit_context_new_binary_op (
1688 GCC_JIT_BINARY_OP_MULT, the_type,
1689 gcc_jit_lvalue_as_rvalue (i),
1690 gcc_jit_lvalue_as_rvalue (i)));
1693 gcc_jit_block_add_assignment_op (
1696 GCC_JIT_BINARY_OP_PLUS,
1697 gcc_jit_context_one (ctxt, the_type));
1699 gcc_jit_block_end_with_jump (b_loop_body, NULL, b_loop_cond);
1702 gcc_jit_block_end_with_return (
1705 gcc_jit_lvalue_as_rvalue (sum));
1709 main (int argc, char **argv)
1711 gcc_jit_context *ctxt = NULL;
1712 gcc_jit_result *result = NULL;
1714 /* Get a "context" object for working with the library. */
1715 ctxt = gcc_jit_context_acquire ();
1718 fprintf (stderr, "NULL ctxt");
1722 /* Set some options on the context.
1723 Let's see the code being generated, in assembler form. */
1724 gcc_jit_context_set_bool_option (
1726 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
1729 /* Populate the context. */
1732 /* Compile the code. */
1733 result = gcc_jit_context_compile (ctxt);
1736 fprintf (stderr, "NULL result");
1740 /* Extract the generated code from "result". */
1741 typedef int (*loop_test_fn_type) (int);
1742 loop_test_fn_type loop_test =
1743 (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
1746 fprintf (stderr, "NULL loop_test");
1750 /* Run the generated code. */
1751 int val = loop_test (10);
1752 printf("loop_test returned: %d\n", val);
1755 gcc_jit_context_release (ctxt);
1756 gcc_jit_result_release (result);
1765 Building and running it:
1769 tut03-sum-of-squares.c \
1770 -o tut03-sum-of-squares \
1773 # Run the built program:
1774 $ ./tut03-sum-of-squares
1775 loop_test returned: 285
1780 @c Copyright (C) 2014 Free Software Foundation, Inc.
1781 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
1783 @c This is free software: you can redistribute it and/or modify it
1784 @c under the terms of the GNU General Public License as published by
1785 @c the Free Software Foundation, either version 3 of the License, or
1786 @c (at your option) any later version.
1788 @c This program is distributed in the hope that it will be useful, but
1789 @c WITHOUT ANY WARRANTY; without even the implied warranty of
1790 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1791 @c General Public License for more details.
1793 @c You should have received a copy of the GNU General Public License
1794 @c along with this program. If not, see
1795 @c <http://www.gnu.org/licenses/>.
1797 @node Tutorial part 4 Adding JIT-compilation to a toy interpreter,,Tutorial part 3 Loops and variables,Tutorial
1798 @anchor{intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{35}@anchor{intro/tutorial04 doc}@anchor{36}
1799 @section Tutorial part 4: Adding JIT-compilation to a toy interpreter
1802 In this example we construct a "toy" interpreter, and add JIT-compilation
1806 * Our toy interpreter::
1807 * Compiling to machine code::
1808 * Setting things up::
1809 * Populating the function::
1810 * Verifying the control flow graph::
1811 * Compiling the context::
1812 * Single-stepping through the generated code::
1813 * Examining the generated code::
1814 * Putting it all together::
1815 * Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?.
1819 @node Our toy interpreter,Compiling to machine code,,Tutorial part 4 Adding JIT-compilation to a toy interpreter
1820 @anchor{intro/tutorial04 our-toy-interpreter}@anchor{37}
1821 @subsection Our toy interpreter
1824 It's a stack-based interpreter, and is intended as a (very simple) example
1825 of the kind of bytecode interpreter seen in dynamic languages such as
1828 For the sake of simplicity, our toy virtual machine is very limited:
1836 The only data type is @cite{int}
1839 It can only work on one function at a time (so that the only
1840 function call that can be made is to recurse).
1843 Functions can only take one parameter.
1846 Functions have a stack of @cite{int} values.
1849 We'll implement function call within the interpreter by calling a
1850 function in our implementation, rather than implementing our own
1854 The parser is only good enough to get the examples to work.
1858 Naturally, a real interpreter would be much more complicated that this.
1860 The following operations are supported:
1863 @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx}
1886 Duplicate top of stack.
1902 Swap top two elements
1919 Add the top two elements
1936 Likewise, but subtract.
1952 Likewise, but multiply.
1969 elements on the stack
1970 and push a nonzero/zero
1987 Recurse, passing the top
2005 Return the top of the
2018 PUSH_CONST @cite{arg}
2034 JUMP_ABS_IF_TRUE @cite{arg}
2038 Pop; if top of stack was
2053 Programs can be interpreted, disassembled, and compiled to machine code.
2055 The interpreter reads @code{.toy} scripts. Here's what a simple recursive
2056 factorial program looks like, the script @code{factorial.toy}.
2057 The parser ignores lines beginning with a @cite{#}.
2062 # Simple recursive factorial implementation, roughly equivalent to:
2064 # int factorial (int arg)
2068 # return arg * factorial (arg - 1)
2080 # stack: [arg, arg, 2]
2084 # stack: [arg, (arg < 2)]
2096 # stack: [arg, arg, 1]
2100 # stack: [arg, (arg - 1)
2104 # stack: [arg, factorial(arg - 1)]
2108 # stack: [arg * factorial(arg - 1)]
2118 The interpreter is a simple infinite loop with a big @code{switch} statement
2119 based on what the next opcode is:
2126 toyvm_function_interpret (toyvm_function *fn, int arg, FILE *trace)
2129 #define PUSH(ARG) (toyvm_frame_push (&frame, (ARG)))
2130 #define POP(ARG) (toyvm_frame_pop (&frame))
2132 frame.frm_function = fn;
2134 frame.frm_cur_depth = 0;
2142 assert (frame.frm_pc < fn->fn_num_ops);
2143 op = &fn->fn_ops[frame.frm_pc++];
2147 toyvm_frame_dump_stack (&frame, trace);
2148 toyvm_function_disassemble_op (fn, op, frame.frm_pc, trace);
2151 switch (op->op_opcode)
2153 /* Ops taking no operand. */
2173 case BINARY_SUBTRACT:
2185 case BINARY_COMPARE_LT:
2193 x = toyvm_function_interpret (fn, x, trace);
2200 /* Ops taking an operand. */
2202 PUSH (op->op_operand);
2205 case JUMP_ABS_IF_TRUE:
2208 frame.frm_pc = op->op_operand;
2212 assert (0); /* unknown opcode */
2214 @} /* end of switch on opcode */
2215 @} /* end of while loop */
2227 @node Compiling to machine code,Setting things up,Our toy interpreter,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2228 @anchor{intro/tutorial04 compiling-to-machine-code}@anchor{38}
2229 @subsection Compiling to machine code
2232 We want to generate machine code that can be cast to this type and
2233 then directly executed in-process:
2238 typedef int (*toyvm_compiled_code) (int);
2246 The lifetime of the code is tied to that of a @pxref{16,,gcc_jit_result *}.
2247 We'll handle this by bundling them up in a structure, so that we can
2248 clean them up together by calling @pxref{39,,gcc_jit_result_release()}:
2254 struct toyvm_compiled_function
2256 gcc_jit_result *cf_jit_result;
2257 toyvm_compiled_code cf_code;
2266 Our compiler isn't very sophisticated; it takes the implementation of
2267 each opcode above, and maps it directly to the operations supported by
2270 How should we handle the stack? In theory we could calculate what the
2271 stack depth will be at each opcode, and optimize away the stack
2272 manipulation "by hand". We'll see below that libgccjit is able to do
2273 this for us, so we'll implement stack manipulation
2274 in a direct way, by creating a @code{stack} array and @code{stack_depth}
2275 variables, local within the generated function, equivalent to this C code:
2279 int stack[MAX_STACK_DEPTH];
2284 We'll also have local variables @code{x} and @code{y} for use when implementing
2285 the opcodes, equivalent to this:
2294 This means our compiler has the following state:
2300 struct compilation_state
2302 gcc_jit_context *ctxt;
2304 gcc_jit_type *int_type;
2305 gcc_jit_type *bool_type;
2306 gcc_jit_type *stack_type; /* int[MAX_STACK_DEPTH] */
2308 gcc_jit_rvalue *const_one;
2310 gcc_jit_function *fn;
2311 gcc_jit_param *param_arg;
2312 gcc_jit_lvalue *stack;
2313 gcc_jit_lvalue *stack_depth;
2317 gcc_jit_location *op_locs[MAX_OPS];
2318 gcc_jit_block *initial_block;
2319 gcc_jit_block *op_blocks[MAX_OPS];
2329 @node Setting things up,Populating the function,Compiling to machine code,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2330 @anchor{intro/tutorial04 setting-things-up}@anchor{3a}
2331 @subsection Setting things up
2334 First we create our types:
2340 gcc_jit_context_get_type (state.ctxt, GCC_JIT_TYPE_INT);
2342 gcc_jit_context_get_type (state.ctxt, GCC_JIT_TYPE_BOOL);
2344 gcc_jit_context_new_array_type (state.ctxt, NULL,
2345 state.int_type, MAX_STACK_DEPTH);
2353 along with extracting a useful @cite{int} constant:
2358 state.const_one = gcc_jit_context_one (state.ctxt, state.int_type);
2366 We'll implement push and pop in terms of the @code{stack} array and
2367 @code{stack_depth}. Here are helper functions for adding statements to
2368 a block, implementing pushing and popping values:
2375 add_push (compilation_state *state,
2376 gcc_jit_block *block,
2377 gcc_jit_rvalue *rvalue,
2378 gcc_jit_location *loc)
2380 /* stack[stack_depth] = RVALUE */
2381 gcc_jit_block_add_assignment (
2384 /* stack[stack_depth] */
2385 gcc_jit_context_new_array_access (
2388 gcc_jit_lvalue_as_rvalue (state->stack),
2389 gcc_jit_lvalue_as_rvalue (state->stack_depth)),
2392 /* "stack_depth++;". */
2393 gcc_jit_block_add_assignment_op (
2397 GCC_JIT_BINARY_OP_PLUS,
2402 add_pop (compilation_state *state,
2403 gcc_jit_block *block,
2404 gcc_jit_lvalue *lvalue,
2405 gcc_jit_location *loc)
2407 /* "--stack_depth;". */
2408 gcc_jit_block_add_assignment_op (
2412 GCC_JIT_BINARY_OP_MINUS,
2415 /* "LVALUE = stack[stack_depth];". */
2416 gcc_jit_block_add_assignment (
2420 /* stack[stack_depth] */
2421 gcc_jit_lvalue_as_rvalue (
2422 gcc_jit_context_new_array_access (
2425 gcc_jit_lvalue_as_rvalue (state->stack),
2426 gcc_jit_lvalue_as_rvalue (state->stack_depth))));
2435 We will support single-stepping through the generated code in the
2436 debugger, so we need to create @pxref{3b,,gcc_jit_location} instances, one
2437 per operation in the source code. These will reference the lines of
2438 e.g. @code{factorial.toy}.
2443 for (pc = 0; pc < fn->fn_num_ops; pc++)
2445 toyvm_op *op = &fn->fn_ops[pc];
2447 state.op_locs[pc] = gcc_jit_context_new_location (state.ctxt,
2459 Let's create the function itself. As usual, we create its parameter
2460 first, then use the parameter to create the function:
2466 gcc_jit_context_new_param (state.ctxt, state.op_locs[0],
2467 state.int_type, "arg");
2469 gcc_jit_context_new_function (state.ctxt,
2471 GCC_JIT_FUNCTION_EXPORTED,
2474 1, &state.param_arg, 0);
2482 We create the locals within the function.
2488 gcc_jit_function_new_local (state.fn, NULL,
2489 state.stack_type, "stack");
2491 gcc_jit_function_new_local (state.fn, NULL,
2492 state.int_type, "stack_depth");
2494 gcc_jit_function_new_local (state.fn, NULL,
2495 state.int_type, "x");
2497 gcc_jit_function_new_local (state.fn, NULL,
2498 state.int_type, "y");
2506 @node Populating the function,Verifying the control flow graph,Setting things up,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2507 @anchor{intro/tutorial04 populating-the-function}@anchor{3c}
2508 @subsection Populating the function
2511 There's some one-time initialization, and the API treats the first block
2512 you create as the entrypoint of the function, so we need to create that
2518 state.initial_block = gcc_jit_function_new_block (state.fn, "initial");
2526 We can now create blocks for each of the operations. Most of these will
2527 be consolidated into larger blocks when the optimizer runs.
2532 for (pc = 0; pc < fn->fn_num_ops; pc++)
2535 sprintf (buf, "instr%i", pc);
2536 state.op_blocks[pc] = gcc_jit_function_new_block (state.fn, buf);
2545 Now that we have a block it can jump to when it's done, we can populate
2552 /* "stack_depth = 0;". */
2553 gcc_jit_block_add_assignment (
2554 state.initial_block,
2557 gcc_jit_context_zero (state.ctxt, state.int_type));
2559 /* "PUSH (arg);". */
2561 state.initial_block,
2562 gcc_jit_param_as_rvalue (state.param_arg),
2565 /* ...and jump to insn 0. */
2566 gcc_jit_block_end_with_jump (state.initial_block,
2568 state.op_blocks[0]);
2576 We can now populate the blocks for the individual operations. We loop
2577 through them, adding instructions to their blocks:
2582 for (pc = 0; pc < fn->fn_num_ops; pc++)
2584 gcc_jit_location *loc = state.op_locs[pc];
2586 gcc_jit_block *block = state.op_blocks[pc];
2587 gcc_jit_block *next_block = (pc < fn->fn_num_ops
2588 ? state.op_blocks[pc + 1]
2592 op = &fn->fn_ops[pc];
2600 We're going to have another big @code{switch} statement for implementing
2601 the opcodes, this time for compiling them, rather than interpreting
2602 them. It's helpful to have macros for implementing push and pop, so that
2603 we can make the @code{switch} statement that's coming up look as much as
2604 possible like the one above within the interpreter:
2608 #define X_EQUALS_POP()\
2609 add_pop (&state, block, state.x, loc)
2610 #define Y_EQUALS_POP()\
2611 add_pop (&state, block, state.y, loc)
2612 #define PUSH_RVALUE(RVALUE)\
2613 add_push (&state, block, (RVALUE), loc)
2615 PUSH_RVALUE (gcc_jit_lvalue_as_rvalue (state.x))
2617 PUSH_RVALUE (gcc_jit_lvalue_as_rvalue (state.y))
2626 A particularly clever implementation would have an @emph{identical}
2627 @code{switch} statement shared by the interpreter and the compiler, with
2628 some preprocessor "magic". We're not doing that here, for the sake
2633 When I first implemented this compiler, I accidentally missed an edit
2634 when copying and pasting the @code{Y_EQUALS_POP} macro, so that popping the
2635 stack into @code{y} instead erroneously assigned it to @code{x}, leaving @code{y}
2638 To track this kind of thing down, we can use
2639 @pxref{3d,,gcc_jit_block_add_comment()} to add descriptive comments
2640 to the internal representation. This is invaluable when looking through
2641 the generated IR for, say @code{factorial}:
2647 gcc_jit_block_add_comment (block, loc, opcode_names[op->op_opcode]);
2655 We can now write the big @code{switch} statement that implements the
2656 individual opcodes, populating the relevant block with statements:
2662 switch (op->op_opcode)
2681 gcc_jit_context_new_binary_op (
2684 GCC_JIT_BINARY_OP_PLUS,
2686 gcc_jit_lvalue_as_rvalue (state.x),
2687 gcc_jit_lvalue_as_rvalue (state.y)));
2690 case BINARY_SUBTRACT:
2694 gcc_jit_context_new_binary_op (
2697 GCC_JIT_BINARY_OP_MINUS,
2699 gcc_jit_lvalue_as_rvalue (state.x),
2700 gcc_jit_lvalue_as_rvalue (state.y)));
2707 gcc_jit_context_new_binary_op (
2710 GCC_JIT_BINARY_OP_MULT,
2712 gcc_jit_lvalue_as_rvalue (state.x),
2713 gcc_jit_lvalue_as_rvalue (state.y)));
2716 case BINARY_COMPARE_LT:
2720 /* cast of bool to int */
2721 gcc_jit_context_new_cast (
2724 /* (x < y) as a bool */
2725 gcc_jit_context_new_comparison (
2728 GCC_JIT_COMPARISON_LT,
2729 gcc_jit_lvalue_as_rvalue (state.x),
2730 gcc_jit_lvalue_as_rvalue (state.y)),
2737 gcc_jit_rvalue *arg = gcc_jit_lvalue_as_rvalue (state.x);
2739 gcc_jit_context_new_call (
2749 gcc_jit_block_end_with_return (
2752 gcc_jit_lvalue_as_rvalue (state.x));
2755 /* Ops taking an operand. */
2758 gcc_jit_context_new_rvalue_from_int (
2764 case JUMP_ABS_IF_TRUE:
2766 gcc_jit_block_end_with_conditional (
2770 gcc_jit_context_new_cast (
2773 gcc_jit_lvalue_as_rvalue (state.x),
2775 state.op_blocks[op->op_operand], /* on_true */
2776 next_block); /* on_false */
2781 @} /* end of switch on opcode */
2789 Every block must be terminated, via a call to one of the
2790 @code{gcc_jit_block_end_with_} entrypoints. This has been done for two
2791 of the opcodes, but we need to do it for the other ones, by jumping
2797 if (op->op_opcode != JUMP_ABS_IF_TRUE
2798 && op->op_opcode != RETURN)
2799 gcc_jit_block_end_with_jump (
2810 This is analogous to simply incrementing the program counter.
2812 @node Verifying the control flow graph,Compiling the context,Populating the function,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2813 @anchor{intro/tutorial04 verifying-the-control-flow-graph}@anchor{3e}
2814 @subsection Verifying the control flow graph
2817 Having finished looping over the blocks, the context is complete.
2819 As before, we can verify that the control flow and statements are sane by
2820 using @pxref{33,,gcc_jit_function_dump_to_dot()}:
2823 gcc_jit_function_dump_to_dot (state.fn, "/tmp/factorial.dot");
2828 and viewing the result. Note how the label names, comments, and
2829 variable names show up in the dump, to make it easier to spot
2830 errors in our compiler.
2837 @image{factorial1,,,image of a control flow graph,png}
2843 @node Compiling the context,Single-stepping through the generated code,Verifying the control flow graph,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2844 @anchor{intro/tutorial04 compiling-the-context}@anchor{3f}
2845 @subsection Compiling the context
2848 Having finished looping over the blocks and populating them with
2849 statements, the context is complete.
2851 We can now compile it, and extract machine code from the result:
2856 gcc_jit_result *jit_result = gcc_jit_context_compile (state.ctxt);
2857 gcc_jit_context_release (state.ctxt);
2859 toyvm_compiled_function *toyvm_result =
2860 (toyvm_compiled_function *)calloc (1, sizeof (toyvm_compiled_function));
2863 fprintf (stderr, "out of memory allocating toyvm_compiled_function\n");
2864 gcc_jit_result_release (jit_result);
2868 toyvm_result->cf_jit_result = jit_result;
2869 toyvm_result->cf_code =
2870 (toyvm_compiled_code)gcc_jit_result_get_code (jit_result,
2875 return toyvm_result;
2880 #define CHECK_NON_NULL(PTR) \
2882 if ((PTR) != NULL) \
2884 pass ("%s: %s is non-null", test, #PTR); \
2888 fail ("%s: %s is NULL", test, #PTR); \
2893 #define CHECK_VALUE(ACTUAL, EXPECTED) \
2895 if ((ACTUAL) == (EXPECTED)) \
2897 pass ("%s: actual: %s == expected: %s", test, #ACTUAL, #EXPECTED); \
2901 fail ("%s: actual: %s != expected: %s", test, #ACTUAL, #EXPECTED); \
2902 fprintf (stderr, "incorrect value\n"); \
2908 test_script (const char *scripts_dir, const char *script_name, int input,
2909 int expected_result)
2913 int interpreted_result;
2914 toyvm_compiled_function *compiled_fn;
2915 toyvm_compiled_code code;
2916 int compiled_result;
2918 snprintf (test, sizeof (test), "toyvm.c: %s", script_name);
2920 script_path = (char *)malloc (strlen (scripts_dir)
2921 + strlen (script_name) + 1);
2922 CHECK_NON_NULL (script_path);
2923 sprintf (script_path, "%s%s", scripts_dir, script_name);
2925 fn = toyvm_function_parse (script_path, script_name);
2926 CHECK_NON_NULL (fn);
2928 interpreted_result = toyvm_function_interpret (fn, input, NULL);
2929 CHECK_VALUE (interpreted_result, expected_result);
2931 compiled_fn = toyvm_function_compile (fn);
2932 CHECK_NON_NULL (compiled_fn);
2934 code = (toyvm_compiled_code)compiled_fn->cf_code;
2935 CHECK_NON_NULL (code);
2937 compiled_result = code (input);
2938 CHECK_VALUE (compiled_result, expected_result);
2940 gcc_jit_result_release (compiled_fn->cf_jit_result);
2946 #define PATH_TO_SCRIPTS ("/jit/docs/examples/tut04-toyvm/")
2954 snprintf (test, sizeof (test), "toyvm.c");
2956 /* We need to locate the test scripts.
2957 Rely on "srcdir" being set in the environment. */
2959 srcdir = getenv ("srcdir");
2960 CHECK_NON_NULL (srcdir);
2962 scripts_dir = (char *)malloc (strlen (srcdir) + strlen(PATH_TO_SCRIPTS)
2964 CHECK_NON_NULL (scripts_dir);
2965 sprintf (scripts_dir, "%s%s", srcdir, PATH_TO_SCRIPTS);
2967 test_script (scripts_dir, "factorial.toy", 10, 3628800);
2968 test_script (scripts_dir, "fibonacci.toy", 10, 55);
2974 main (int argc, char **argv)
2976 const char *filename = NULL;
2977 toyvm_function *fn = NULL;
2979 /* If called with no args, assume we're being run by the test suite. */
2989 "%s FILENAME INPUT: Parse and run a .toy file\n",
2995 fn = toyvm_function_parse (filename, filename);
3000 toyvm_function_disassemble (fn, stdout);
3002 printf ("interpreter result: %d\n",
3003 toyvm_function_interpret (fn, atoi (argv[2]), NULL));
3005 /* JIT-compilation. */
3006 toyvm_compiled_function *compiled_fn
3007 = toyvm_function_compile (fn);
3009 toyvm_compiled_code code = compiled_fn->cf_code;
3010 printf ("compiler result: %d\n",
3011 code (atoi (argv[2])));
3013 gcc_jit_result_release (compiled_fn->cf_jit_result);
3024 We can now run the result:
3029 toyvm_compiled_function *compiled_fn
3030 = toyvm_function_compile (fn);
3032 toyvm_compiled_code code = compiled_fn->cf_code;
3033 printf ("compiler result: %d\n",
3034 code (atoi (argv[2])));
3036 gcc_jit_result_release (compiled_fn->cf_jit_result);
3045 @node Single-stepping through the generated code,Examining the generated code,Compiling the context,Tutorial part 4 Adding JIT-compilation to a toy interpreter
3046 @anchor{intro/tutorial04 single-stepping-through-the-generated-code}@anchor{40}
3047 @subsection Single-stepping through the generated code
3050 It's possible to debug the generated code. To do this we need to both:
3058 Set up source code locations for our statements, so that we can
3059 meaningfully step through the code. We did this above by
3060 calling @pxref{41,,gcc_jit_context_new_location()} and using the
3064 Enable the generation of debugging information, by setting
3065 @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
3066 @pxref{8,,gcc_jit_context} via
3067 @pxref{1b,,gcc_jit_context_set_bool_option()}:
3070 gcc_jit_context_set_bool_option (
3072 GCC_JIT_BOOL_OPTION_DEBUGINFO,
3080 Having done this, we can put a breakpoint on the generated function:
3083 $ gdb --args ./toyvm factorial.toy 10
3084 (gdb) break factorial
3085 Function "factorial" not defined.
3086 Make breakpoint pending on future shared library load? (y or [n]) y
3087 Breakpoint 1 (factorial) pending.
3089 Breakpoint 1, factorial (arg=10) at factorial.toy:14
3095 We've set up location information, which references @code{factorial.toy}.
3096 This allows us to use e.g. @code{list} to see where we are in the script:
3106 15 # stack: [arg, arg]
3114 and to step through the function, examining the data:
3120 22 BINARY_COMPARE_LT
3122 $5 = @{10, 10, 2, 0, -7152, 32767, 0, 0@}
3123 (gdb) print stack_depth
3129 You'll see that the parts of the @code{stack} array that haven't been
3130 touched yet are uninitialized.
3134 Turning on optimizations may lead to unpredictable results when
3135 stepping through the generated code: the execution may appear to
3136 "jump around" the source code. This is analogous to turning up the
3137 optimization level in a regular compiler.
3141 @node Examining the generated code,Putting it all together,Single-stepping through the generated code,Tutorial part 4 Adding JIT-compilation to a toy interpreter
3142 @anchor{intro/tutorial04 examining-the-generated-code}@anchor{43}
3143 @subsection Examining the generated code
3146 How good is the optimized code?
3148 We can turn up optimizations, by calling
3149 @pxref{1e,,gcc_jit_context_set_int_option()} with
3150 @pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
3153 gcc_jit_context_set_int_option (
3155 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL,
3161 One of GCC's internal representations is called "gimple". A dump of the
3162 initial gimple representation of the code can be seen by setting:
3165 gcc_jit_context_set_bool_option (ctxt,
3166 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE,
3172 With optimization on and source locations displayed, this gives:
3174 @c We'll use "c" for gimple dumps
3177 factorial (signed int arg)
3179 <unnamed type> D.80;
3187 signed int stack_depth;
3188 signed int stack[8];
3194 stack[stack_depth] = arg;
3195 stack_depth = stack_depth + 1;
3199 stack_depth = stack_depth + -1;
3200 x = stack[stack_depth];
3201 stack[stack_depth] = x;
3202 stack_depth = stack_depth + 1;
3203 stack[stack_depth] = x;
3204 stack_depth = stack_depth + 1;
3208 stack[stack_depth] = 2;
3209 stack_depth = stack_depth + 1;
3217 You can see the generated machine code in assembly form via:
3220 gcc_jit_context_set_bool_option (
3222 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
3224 result = gcc_jit_context_compile (ctxt);
3229 which shows that (on this x86_64 box) the compiler has unrolled the loop
3230 and is using MMX instructions to perform several multiplications
3239 .type factorial, @@function
3242 .file 1 "factorial.toy"
3253 leal 0(,%rcx,4), %esi
3259 movl %eax, -16(%rsp)
3261 movd -16(%rsp), %xmm0
3262 movl %edi, -16(%rsp)
3263 movl %eax, -12(%rsp)
3264 movd -16(%rsp), %xmm1
3266 movl %edx, -16(%rsp)
3267 movd -12(%rsp), %xmm4
3268 movd -16(%rsp), %xmm6
3269 punpckldq %xmm4, %xmm0
3270 movdqa .LC1(%rip), %xmm4
3271 punpckldq %xmm6, %xmm1
3272 punpcklqdq %xmm0, %xmm1
3273 movdqa .LC0(%rip), %xmm0
3275 # etc - edited for brevity
3280 This is clearly overkill for a function that will likely overflow the
3281 @code{int} type before the vectorization is worthwhile - but then again, this
3284 Turning down the optimization level to 2:
3287 gcc_jit_context_set_int_option (
3289 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL,
3295 yields this code, which is simple enough to quote in its entirety:
3302 .type factorial, @@function
3331 .size factorial, .-factorial
3332 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-%@{gcc_release@})"
3333 .section .note.GNU-stack,"",@@progbits
3338 Note that the stack pushing and popping have been eliminated, as has the
3339 recursive call (in favor of an iteration).
3341 @node Putting it all together,Behind the curtain How does our code get optimized?,Examining the generated code,Tutorial part 4 Adding JIT-compilation to a toy interpreter
3342 @anchor{intro/tutorial04 putting-it-all-together}@anchor{44}
3343 @subsection Putting it all together
3346 The complete example can be seen in the source tree at
3347 @code{gcc/jit/docs/examples/tut04-toyvm/toyvm.c}
3349 along with a Makefile and a couple of sample .toy scripts:
3353 drwxrwxr-x. 2 david david 4096 Sep 19 17:46 .
3354 drwxrwxr-x. 3 david david 4096 Sep 19 15:26 ..
3355 -rw-rw-r--. 1 david david 615 Sep 19 12:43 factorial.toy
3356 -rw-rw-r--. 1 david david 834 Sep 19 13:08 fibonacci.toy
3357 -rw-rw-r--. 1 david david 238 Sep 19 14:22 Makefile
3358 -rw-rw-r--. 1 david david 16457 Sep 19 17:07 toyvm.c
3361 g++ -Wall -g -o toyvm toyvm.c -lgccjit
3363 $ ./toyvm factorial.toy 10
3364 interpreter result: 3628800
3365 compiler result: 3628800
3367 $ ./toyvm fibonacci.toy 10
3368 interpreter result: 55
3374 @node Behind the curtain How does our code get optimized?,,Putting it all together,Tutorial part 4 Adding JIT-compilation to a toy interpreter
3375 @anchor{intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{45}
3376 @subsection Behind the curtain: How does our code get optimized?
3379 Our example is done, but you may be wondering about exactly how the
3380 compiler turned what we gave it into the machine code seen above.
3382 We can examine what the compiler is doing in detail by setting:
3385 gcc_jit_context_set_bool_option (state.ctxt,
3386 GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING,
3388 gcc_jit_context_set_bool_option (state.ctxt,
3389 GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES,
3395 This will dump detailed information about the compiler's state to a
3396 directory under @code{/tmp}, and keep it from being cleaned up.
3398 The precise names and their formats of these files is subject to change.
3399 Higher optimization levels lead to more files.
3400 Here's what I saw (edited for brevity; there were almost 200 files):
3403 intermediate files written to /tmp/libgccjit-KPQbGw
3404 $ ls /tmp/libgccjit-KPQbGw/
3406 fake.c.000i.type-inheritance
3408 fake.c.007t.omplower
3412 fake.c.014i.visibility
3413 fake.c.015i.early_local_cleanups
3420 The gimple code is converted into Static Single Assignment form,
3421 with annotations for use when generating the debuginfo:
3424 $ less /tmp/libgccjit-KPQbGw/fake.c.016t.ssa
3430 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3432 factorial (signed int arg)
3434 signed int stack[8];
3435 signed int stack_depth;
3447 # DEBUG stack_depth => stack_depth_3
3448 stack[stack_depth_3] = arg_5(D);
3449 stack_depth_7 = stack_depth_3 + 1;
3450 # DEBUG stack_depth => stack_depth_7
3451 # DEBUG instr0 => NULL
3452 # DEBUG /* DUP */ => NULL
3453 stack_depth_8 = stack_depth_7 + -1;
3454 # DEBUG stack_depth => stack_depth_8
3455 x_9 = stack[stack_depth_8];
3457 stack[stack_depth_8] = x_9;
3458 stack_depth_11 = stack_depth_8 + 1;
3459 # DEBUG stack_depth => stack_depth_11
3460 stack[stack_depth_11] = x_9;
3461 stack_depth_13 = stack_depth_11 + 1;
3462 # DEBUG stack_depth => stack_depth_13
3463 # DEBUG instr1 => NULL
3464 # DEBUG /* PUSH_CONST */ => NULL
3465 stack[stack_depth_13] = 2;
3467 /* etc; edited for brevity */
3472 We can perhaps better see the code by turning off
3473 @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to suppress all those @code{DEBUG}
3477 $ less /tmp/libgccjit-1Hywc0/fake.c.016t.ssa
3483 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3485 factorial (signed int arg)
3487 signed int stack[8];
3488 signed int stack_depth;
3500 stack[stack_depth_3] = arg_5(D);
3501 stack_depth_7 = stack_depth_3 + 1;
3502 stack_depth_8 = stack_depth_7 + -1;
3503 x_9 = stack[stack_depth_8];
3504 stack[stack_depth_8] = x_9;
3505 stack_depth_11 = stack_depth_8 + 1;
3506 stack[stack_depth_11] = x_9;
3507 stack_depth_13 = stack_depth_11 + 1;
3508 stack[stack_depth_13] = 2;
3509 stack_depth_15 = stack_depth_13 + 1;
3510 stack_depth_16 = stack_depth_15 + -1;
3511 y_17 = stack[stack_depth_16];
3512 stack_depth_18 = stack_depth_16 + -1;
3513 x_19 = stack[stack_depth_18];
3515 _21 = (signed int) _20;
3516 stack[stack_depth_18] = _21;
3517 stack_depth_23 = stack_depth_18 + 1;
3518 stack_depth_24 = stack_depth_23 + -1;
3519 x_25 = stack[stack_depth_24];
3521 goto <bb 4> (instr9);
3523 goto <bb 3> (instr4);
3527 stack_depth_26 = stack_depth_24 + -1;
3528 x_27 = stack[stack_depth_26];
3529 stack[stack_depth_26] = x_27;
3530 stack_depth_29 = stack_depth_26 + 1;
3531 stack[stack_depth_29] = x_27;
3532 stack_depth_31 = stack_depth_29 + 1;
3533 stack[stack_depth_31] = 1;
3534 stack_depth_33 = stack_depth_31 + 1;
3535 stack_depth_34 = stack_depth_33 + -1;
3536 y_35 = stack[stack_depth_34];
3537 stack_depth_36 = stack_depth_34 + -1;
3538 x_37 = stack[stack_depth_36];
3540 stack[stack_depth_36] = _38;
3541 stack_depth_40 = stack_depth_36 + 1;
3542 stack_depth_41 = stack_depth_40 + -1;
3543 x_42 = stack[stack_depth_41];
3544 _44 = factorial (x_42);
3545 stack[stack_depth_41] = _44;
3546 stack_depth_46 = stack_depth_41 + 1;
3547 stack_depth_47 = stack_depth_46 + -1;
3548 y_48 = stack[stack_depth_47];
3549 stack_depth_49 = stack_depth_47 + -1;
3550 x_50 = stack[stack_depth_49];
3552 stack[stack_depth_49] = _51;
3553 stack_depth_53 = stack_depth_49 + 1;
3555 # stack_depth_1 = PHI <stack_depth_24(2), stack_depth_53(3)>
3558 stack_depth_54 = stack_depth_1 + -1;
3559 x_55 = stack[stack_depth_54];
3561 stack =@{v@} @{CLOBBER@};
3569 Note in the above how all the @pxref{28,,gcc_jit_block} instances we
3570 created have been consolidated into just 3 blocks in GCC's internal
3571 representation: @code{initial}, @code{instr4} and @code{instr9}.
3574 * Optimizing away stack manipulation::
3575 * Elimination of tail recursion::
3579 @node Optimizing away stack manipulation,Elimination of tail recursion,,Behind the curtain How does our code get optimized?
3580 @anchor{intro/tutorial04 optimizing-away-stack-manipulation}@anchor{46}
3581 @subsubsection Optimizing away stack manipulation
3584 Recall our simple implementation of stack operations. Let's examine
3585 how the stack operations are optimized away.
3587 After a pass of constant-propagation, the depth of the stack at each
3588 opcode can be determined at compile-time:
3591 $ less /tmp/libgccjit-1Hywc0/fake.c.021t.ccp1
3597 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3599 factorial (signed int arg)
3601 signed int stack[8];
3602 signed int stack_depth;
3612 stack[0] = arg_5(D);
3620 _21 = (signed int) _20;
3624 goto <bb 4> (instr9);
3626 goto <bb 3> (instr4);
3639 _44 = factorial (x_42);
3650 stack =@{v@} @{CLOBBER@};
3658 Note how, in the above, all those @code{stack_depth} values are now just
3659 constants: we're accessing specific stack locations at each opcode.
3661 The "esra" pass ("Early Scalar Replacement of Aggregates") breaks
3662 out our "stack" array into individual elements:
3665 $ less /tmp/libgccjit-1Hywc0/fake.c.024t.esra
3671 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3673 Created a replacement for stack offset: 0, size: 32: stack$0
3674 Created a replacement for stack offset: 32, size: 32: stack$1
3675 Created a replacement for stack offset: 64, size: 32: stack$2
3677 Symbols to be put in SSA form
3678 @{ D.89 D.90 D.91 @}
3679 Incremental SSA update started at block: 0
3680 Number of blocks in CFG: 5
3681 Number of blocks to update: 4 ( 80%)
3684 factorial (signed int arg)
3689 signed int stack[8];
3690 signed int stack_depth;
3700 stack$0_45 = arg_5(D);
3708 _21 = (signed int) _20;
3712 goto <bb 4> (instr9);
3714 goto <bb 3> (instr4);
3727 _44 = factorial (x_42);
3734 # stack$0_52 = PHI <stack$0_39(2), stack$0_1(3)>
3739 stack =@{v@} @{CLOBBER@};
3747 Hence at this point, all those pushes and pops of the stack are now
3748 simply assignments to specific temporary variables.
3750 After some copy propagation, the stack manipulation has been completely
3754 $ less /tmp/libgccjit-1Hywc0/fake.c.026t.copyprop1
3760 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3762 factorial (signed int arg)
3767 signed int stack[8];
3768 signed int stack_depth;
3778 stack$0_39 = arg_5(D);
3779 _20 = arg_5(D) <= 1;
3780 _21 = (signed int) _20;
3782 goto <bb 4> (instr9);
3784 goto <bb 3> (instr4);
3788 _38 = arg_5(D) + -1;
3789 _44 = factorial (_38);
3790 _51 = arg_5(D) * _44;
3793 # stack$0_52 = PHI <arg_5(D)(2), _51(3)>
3796 stack =@{v@} @{CLOBBER@};
3804 Later on, another pass finally eliminated @code{stack_depth} local and the
3805 unused parts of the @cite{stack`} array altogether:
3808 $ less /tmp/libgccjit-1Hywc0/fake.c.036t.release_ssa
3814 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3816 Released 44 names, 314.29%, removed 44 holes
3817 factorial (signed int arg)
3820 signed int mult_acc_1;
3824 signed int mul_tmp_10;
3825 signed int mult_acc_11;
3826 signed int mult_acc_13;
3828 # arg_9 = PHI <arg_8(D)(0)>
3829 # mult_acc_13 = PHI <1(0)>
3833 # arg_4 = PHI <arg_9(2), _7(3)>
3834 # mult_acc_1 = PHI <mult_acc_13(2), mult_acc_11(3)>
3836 _6 = (signed int) _5;
3838 goto <bb 4> (instr9);
3840 goto <bb 3> (instr4);
3845 mult_acc_11 = mult_acc_1 * arg_4;
3848 # stack$0_12 = PHI <arg_4(5)>
3851 mul_tmp_10 = mult_acc_1 * stack$0_12;
3859 @node Elimination of tail recursion,,Optimizing away stack manipulation,Behind the curtain How does our code get optimized?
3860 @anchor{intro/tutorial04 elimination-of-tail-recursion}@anchor{47}
3861 @subsubsection Elimination of tail recursion
3864 Another significant optimization is the detection that the call to
3865 @code{factorial} is tail recursion, which can be eliminated in favor of
3869 $ less /tmp/libgccjit-1Hywc0/fake.c.030t.tailr1
3875 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3878 Symbols to be put in SSA form
3880 Incremental SSA update started at block: 0
3881 Number of blocks in CFG: 5
3882 Number of blocks to update: 4 ( 80%)
3885 factorial (signed int arg)
3890 signed int stack[8];
3891 signed int stack_depth;
3894 signed int mult_acc_1;
3898 signed int mul_tmp_44;
3899 signed int mult_acc_51;
3901 # arg_5 = PHI <arg_39(D)(0), _38(3)>
3902 # mult_acc_1 = PHI <1(0), mult_acc_51(3)>
3905 _21 = (signed int) _20;
3907 goto <bb 4> (instr9);
3909 goto <bb 3> (instr4);
3914 mult_acc_51 = mult_acc_1 * arg_5;
3915 goto <bb 2> (initial);
3917 # stack$0_52 = PHI <arg_5(2)>
3920 stack =@{v@} @{CLOBBER@};
3921 mul_tmp_44 = mult_acc_1 * stack$0_52;
3929 @c Copyright (C) 2014 Free Software Foundation, Inc.
3930 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
3932 @c This is free software: you can redistribute it and/or modify it
3933 @c under the terms of the GNU General Public License as published by
3934 @c the Free Software Foundation, either version 3 of the License, or
3935 @c (at your option) any later version.
3937 @c This program is distributed in the hope that it will be useful, but
3938 @c WITHOUT ANY WARRANTY; without even the implied warranty of
3939 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
3940 @c General Public License for more details.
3942 @c You should have received a copy of the GNU General Public License
3943 @c along with this program. If not, see
3944 @c <http://www.gnu.org/licenses/>.
3946 @node Topic Reference,C++ bindings for libgccjit,Tutorial,Top
3947 @anchor{topics/index doc}@anchor{48}@anchor{topics/index topic-reference}@anchor{49}
3948 @chapter Topic Reference
3951 @c Copyright (C) 2014 Free Software Foundation, Inc.
3952 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
3954 @c This is free software: you can redistribute it and/or modify it
3955 @c under the terms of the GNU General Public License as published by
3956 @c the Free Software Foundation, either version 3 of the License, or
3957 @c (at your option) any later version.
3959 @c This program is distributed in the hope that it will be useful, but
3960 @c WITHOUT ANY WARRANTY; without even the implied warranty of
3961 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
3962 @c General Public License for more details.
3964 @c You should have received a copy of the GNU General Public License
3965 @c along with this program. If not, see
3966 @c <http://www.gnu.org/licenses/>.
3969 * Compilation contexts::
3973 * Creating and using functions::
3974 * Source Locations::
3975 * Compilation results::
3977 Compilation contexts
3979 * Lifetime-management::
3981 * Error-handling: Error-handling<2>.
3983 * Options: Options<2>.
3994 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile.
3995 * Structures and unions::
4001 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions.
4005 * Simple expressions::
4006 * Unary Operations::
4007 * Binary Operations::
4014 * Global variables::
4016 Creating and using functions
4030 @node Compilation contexts,Objects,,Topic Reference
4031 @anchor{topics/contexts compilation-contexts}@anchor{4a}@anchor{topics/contexts doc}@anchor{4b}
4032 @section Compilation contexts
4035 @geindex gcc_jit_context (C type)
4036 @anchor{topics/contexts gcc_jit_context}@anchor{8}
4037 @deffn {C Type} gcc_jit_context
4040 The top-level of the API is the @pxref{8,,gcc_jit_context} type.
4042 A @pxref{8,,gcc_jit_context} instance encapsulates the state of a
4045 You can set up options on it, and add types, functions and code.
4046 Invoking @pxref{15,,gcc_jit_context_compile()} on it gives you a
4047 @pxref{16,,gcc_jit_result}.
4050 * Lifetime-management::
4052 * Error-handling: Error-handling<2>.
4054 * Options: Options<2>.
4058 @node Lifetime-management,Thread-safety,,Compilation contexts
4059 @anchor{topics/contexts lifetime-management}@anchor{4c}
4060 @subsection Lifetime-management
4063 Contexts are the unit of lifetime-management within the API: objects
4064 have their lifetime bounded by the context they are created within, and
4065 cleanup of such objects is done for you when the context is released.
4067 @geindex gcc_jit_context_acquire (C function)
4068 @anchor{topics/contexts gcc_jit_context_acquire}@anchor{9}
4069 @deffn {C Function} gcc_jit_context *gcc_jit_context_acquire (void)
4071 This function acquires a new @pxref{e,,gcc_jit_object *} instance,
4072 which is independent of any others that may be present within this
4076 @geindex gcc_jit_context_release (C function)
4077 @anchor{topics/contexts gcc_jit_context_release}@anchor{c}
4078 @deffn {C Function} void gcc_jit_context_release (gcc_jit_context@w{ }*ctxt)
4080 This function releases all resources associated with the given context.
4081 Both the context itself and all of its @pxref{e,,gcc_jit_object *}
4082 instances are cleaned up. It should be called exactly once on a given
4085 It is invalid to use the context or any of its "contextual" objects
4089 gcc_jit_context_release (ctxt);
4095 @geindex gcc_jit_context_new_child_context (C function)
4096 @anchor{topics/contexts gcc_jit_context_new_child_context}@anchor{4d}
4097 @deffn {C Function} gcc_jit_context * gcc_jit_context_new_child_context (gcc_jit_context@w{ }*parent_ctxt)
4099 Given an existing JIT context, create a child context.
4101 The child inherits a copy of all option-settings from the parent.
4103 The child can reference objects created within the parent, but not
4106 The lifetime of the child context must be bounded by that of the
4107 parent: you should release a child context before releasing the parent
4110 If you use a function from a parent context within a child context,
4111 you have to compile the parent context before you can compile the
4112 child context, and the gcc_jit_result of the parent context must
4113 outlive the gcc_jit_result of the child context.
4115 This allows caching of shared initializations. For example, you could
4116 create types and declarations of global functions in a parent context
4117 once within a process, and then create child contexts whenever a
4118 function or loop becomes hot. Each such child context can be used for
4119 JIT-compiling just one function or loop, but can reference types
4120 and helper functions created within the parent context.
4122 Contexts can be arbitrarily nested, provided the above rules are
4123 followed, but it's probably not worth going above 2 or 3 levels, and
4124 there will likely be a performance hit for such nesting.
4127 @node Thread-safety,Error-handling<2>,Lifetime-management,Compilation contexts
4128 @anchor{topics/contexts thread-safety}@anchor{4e}
4129 @subsection Thread-safety
4132 Instances of @pxref{8,,gcc_jit_context *} created via
4133 @pxref{9,,gcc_jit_context_acquire()} are independent from each other:
4134 only one thread may use a given context at once, but multiple threads
4135 could each have their own contexts without needing locks.
4137 Contexts created via @pxref{4d,,gcc_jit_context_new_child_context()} are
4138 related to their parent context. They can be partitioned by their
4139 ultimate ancestor into independent "family trees". Only one thread
4140 within a process may use a given "family tree" of such contexts at once,
4141 and if you're using multiple threads you should provide your own locking
4142 around entire such context partitions.
4144 @node Error-handling<2>,Debugging,Thread-safety,Compilation contexts
4145 @anchor{topics/contexts error-handling}@anchor{19}@anchor{topics/contexts id1}@anchor{4f}
4146 @subsection Error-handling
4149 Various kinds of errors are possible when using the API, such as
4150 mismatched types in an assignment. You can only compile and get code from
4151 a context if no errors occur.
4153 Errors are printed on stderr and can be queried using
4154 @pxref{50,,gcc_jit_context_get_first_error()}.
4156 They typically contain the name of the API entrypoint where the error
4157 occurred, and pertinent information on the problem:
4160 ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *)
4165 In general, if an error occurs when using an API entrypoint, the
4166 entrypoint returns NULL. You don't have to check everywhere for NULL
4167 results, since the API handles a NULL being passed in for any
4168 argument by issuing another error. This typically leads to a cascade of
4169 followup error messages, but is safe (albeit verbose). The first error
4170 message is usually the one to pay attention to, since it is likely to
4171 be responsible for all of the rest:
4173 @geindex gcc_jit_context_get_first_error (C function)
4174 @anchor{topics/contexts gcc_jit_context_get_first_error}@anchor{50}
4175 @deffn {C Function} const char * gcc_jit_context_get_first_error (gcc_jit_context@w{ }*ctxt)
4177 Returns the first error message that occurred on the context.
4179 The returned string is valid for the rest of the lifetime of the
4182 If no errors occurred, this will be NULL.
4185 If you are wrapping the C API for a higher-level language that supports
4186 exception-handling, you may instead by interested in the last error that
4187 occurred on the context, so that you can embed this in an exception:
4189 @geindex gcc_jit_context_get_last_error (C function)
4190 @anchor{topics/contexts gcc_jit_context_get_last_error}@anchor{51}
4191 @deffn {C Function} const char * gcc_jit_context_get_last_error (gcc_jit_context@w{ }*ctxt)
4193 Returns the last error message that occurred on the context.
4195 The returned string is valid for the rest of the lifetime of the
4198 If no errors occurred, this will be NULL.
4201 @node Debugging,Options<2>,Error-handling<2>,Compilation contexts
4202 @anchor{topics/contexts debugging}@anchor{52}
4203 @subsection Debugging
4206 @geindex gcc_jit_context_dump_to_file (C function)
4207 @anchor{topics/contexts gcc_jit_context_dump_to_file}@anchor{53}
4208 @deffn {C Function} void gcc_jit_context_dump_to_file (gcc_jit_context@w{ }*ctxt, const char@w{ }*path, int@w{ }update_locations)
4210 To help with debugging: dump a C-like representation to the given path,
4211 describing what's been set up on the context.
4213 If "update_locations" is true, then also set up @pxref{3b,,gcc_jit_location}
4214 information throughout the context, pointing at the dump file as if it
4215 were a source file. This may be of use in conjunction with
4216 @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to allow stepping through the
4220 @geindex gcc_jit_context_set_logfile (C function)
4221 @anchor{topics/contexts gcc_jit_context_set_logfile}@anchor{54}
4222 @deffn {C Function} void gcc_jit_context_set_logfile (gcc_jit_context@w{ }*ctxt, FILE@w{ }*logfile, int@w{ }flags, int@w{ }verbosity)
4224 To help with debugging; enable ongoing logging of the context's
4225 activity to the given file.
4227 For example, the following will enable logging to stderr.
4230 gcc_jit_context_set_logfile (ctxt, stderr, 0, 0);
4235 Examples of information logged include:
4244 the various steps involved within compilation
4247 activity on any @pxref{16,,gcc_jit_result} instances created by
4251 activity within any child contexts
4254 An example of a log can be seen @pxref{55,,here},
4255 though the precise format and kinds of information logged is subject
4258 The caller remains responsible for closing @cite{logfile}, and it must not
4259 be closed until all users are released. In particular, note that
4260 child contexts and @pxref{16,,gcc_jit_result} instances created by
4261 the context will use the logfile.
4263 There may a performance cost for logging.
4265 You can turn off logging on @cite{ctxt} by passing @cite{NULL} for @cite{logfile}.
4266 Doing so only affects the context; it does not affect child contexts
4267 or @pxref{16,,gcc_jit_result} instances already created by
4270 The parameters "flags" and "verbosity" are reserved for future
4271 expansion, and must be zero for now.
4274 To contrast the above: @pxref{53,,gcc_jit_context_dump_to_file()} dumps the
4275 current state of a context to the given path, whereas
4276 @pxref{54,,gcc_jit_context_set_logfile()} enables on-going logging of
4277 future activies on a context to the given @cite{FILE *}.
4279 @geindex gcc_jit_context_enable_dump (C function)
4280 @anchor{topics/contexts gcc_jit_context_enable_dump}@anchor{56}
4281 @deffn {C Function} void gcc_jit_context_enable_dump (gcc_jit_context@w{ }*ctxt, const char@w{ }*dumpname, char@w{ }**out_ptr)
4283 Enable the dumping of a specific set of internal state from the
4284 compilation, capturing the result in-memory as a buffer.
4286 Parameter "dumpname" corresponds to the equivalent gcc command-line
4287 option, without the "-fdump-" prefix.
4288 For example, to get the equivalent of @code{-fdump-tree-vrp1},
4289 supply @code{"tree-vrp1"}:
4292 static char *dump_vrp1;
4295 create_code (gcc_jit_context *ctxt)
4297 gcc_jit_context_enable_dump (ctxt, "tree-vrp1", &dump_vrp1);
4298 /* (other API calls omitted for brevity) */
4304 The context directly stores the dumpname as a @code{(const char *)}, so
4305 the passed string must outlive the context.
4307 @pxref{15,,gcc_jit_context_compile()} will capture the dump as a
4308 dynamically-allocated buffer, writing it to @code{*out_ptr}.
4310 The caller becomes responsible for calling:
4318 each time that @pxref{15,,gcc_jit_context_compile()} is called.
4319 @code{*out_ptr} will be written to, either with the address of a buffer,
4320 or with @code{NULL} if an error occurred.
4324 This API entrypoint is likely to be less stable than the others.
4325 In particular, both the precise dumpnames, and the format and content
4326 of the dumps are subject to change.
4328 It exists primarily for writing the library's own test suite.
4333 @node Options<2>,,Debugging,Compilation contexts
4334 @anchor{topics/contexts options}@anchor{57}
4345 @node String Options,Boolean options,,Options<2>
4346 @anchor{topics/contexts string-options}@anchor{58}
4347 @subsubsection String Options
4350 @geindex gcc_jit_context_set_str_option (C function)
4351 @anchor{topics/contexts gcc_jit_context_set_str_option}@anchor{59}
4352 @deffn {C Function} void gcc_jit_context_set_str_option (gcc_jit_context@w{ }*ctxt, enum gcc_jit_str_option@w{ }opt, const char@w{ }*value)
4354 Set a string option of the context.
4356 @geindex gcc_jit_str_option (C type)
4357 @anchor{topics/contexts gcc_jit_str_option}@anchor{5a}
4358 @deffn {C Type} enum gcc_jit_str_option
4361 There is currently just one string option:
4363 @geindex GCC_JIT_STR_OPTION_PROGNAME (C macro)
4364 @anchor{topics/contexts GCC_JIT_STR_OPTION_PROGNAME}@anchor{5b}
4365 @deffn {C Macro} GCC_JIT_STR_OPTION_PROGNAME
4367 The name of the program, for use as a prefix when printing error
4368 messages to stderr. If @cite{NULL}, or default, "libgccjit.so" is used.
4372 @node Boolean options,Integer options,String Options,Options<2>
4373 @anchor{topics/contexts boolean-options}@anchor{5c}
4374 @subsubsection Boolean options
4377 @geindex gcc_jit_context_set_bool_option (C function)
4378 @anchor{topics/contexts gcc_jit_context_set_bool_option}@anchor{1b}
4379 @deffn {C Function} void gcc_jit_context_set_bool_option (gcc_jit_context@w{ }*ctxt, enum gcc_jit_bool_option@w{ }opt, int@w{ }value)
4381 Set a boolean option of the context.
4382 Zero is "false" (the default), non-zero is "true".
4384 @geindex gcc_jit_bool_option (C type)
4385 @anchor{topics/contexts gcc_jit_bool_option}@anchor{5d}
4386 @deffn {C Type} enum gcc_jit_bool_option
4389 @geindex GCC_JIT_BOOL_OPTION_DEBUGINFO (C macro)
4390 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_DEBUGINFO}@anchor{42}
4391 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DEBUGINFO
4393 If true, @pxref{15,,gcc_jit_context_compile()} will attempt to do the right
4394 thing so that if you attach a debugger to the process, it will
4395 be able to inspect variables and step through your code.
4397 Note that you can't step through code unless you set up source
4398 location information for the code (by creating and passing in
4399 @pxref{3b,,gcc_jit_location} instances).
4402 @geindex GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE (C macro)
4403 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}@anchor{5e}
4404 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE
4406 If true, @pxref{15,,gcc_jit_context_compile()} will dump its initial
4407 "tree" representation of your code to stderr (before any
4410 Here's some sample output (from the @cite{square} example):
4413 <statement_list 0x7f4875a62cc0
4414 type <void_type 0x7f4875a64bd0 VOID
4415 align 8 symtab 0 alias set -1 canonical type 0x7f4875a64bd0
4416 pointer_to_this <pointer_type 0x7f4875a64c78>>
4417 side-effects head 0x7f4875a761e0 tail 0x7f4875a761f8 stmts 0x7f4875a62d20 0x7f4875a62d00
4419 stmt <label_expr 0x7f4875a62d20 type <void_type 0x7f4875a64bd0>
4421 arg 0 <label_decl 0x7f4875a79080 entry type <void_type 0x7f4875a64bd0>
4422 VOID file (null) line 0 col 0
4423 align 1 context <function_decl 0x7f4875a77500 square>>>
4424 stmt <return_expr 0x7f4875a62d00
4425 type <integer_type 0x7f4875a645e8 public SI
4426 size <integer_cst 0x7f4875a623a0 constant 32>
4427 unit size <integer_cst 0x7f4875a623c0 constant 4>
4428 align 32 symtab 0 alias set -1 canonical type 0x7f4875a645e8 precision 32 min <integer_cst 0x7f4875a62340 -2147483648> max <integer_cst 0x7f4875a62360 2147483647>
4429 pointer_to_this <pointer_type 0x7f4875a6b348>>
4431 arg 0 <modify_expr 0x7f4875a72a78 type <integer_type 0x7f4875a645e8>
4432 side-effects arg 0 <result_decl 0x7f4875a7a000 D.54>
4433 arg 1 <mult_expr 0x7f4875a72a50 type <integer_type 0x7f4875a645e8>
4434 arg 0 <parm_decl 0x7f4875a79000 i> arg 1 <parm_decl 0x7f4875a79000 i>>>>>
4440 @geindex GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE (C macro)
4441 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE}@anchor{1c}
4442 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE
4444 If true, @pxref{15,,gcc_jit_context_compile()} will dump the "gimple"
4445 representation of your code to stderr, before any optimizations
4446 are performed. The dump resembles C code:
4449 square (signed int i)
4462 @geindex GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE (C macro)
4463 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE}@anchor{1d}
4464 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE
4466 If true, @pxref{15,,gcc_jit_context_compile()} will dump the final
4467 generated code to stderr, in the form of assembly language:
4473 .type square, @@function
4478 .cfi_def_cfa_offset 16
4481 .cfi_def_cfa_register 6
4485 imull -4(%rbp), %eax
4491 .size square, .-square
4492 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.1-%@{gcc_release@})"
4493 .section .note.GNU-stack,"",@@progbits
4499 @geindex GCC_JIT_BOOL_OPTION_DUMP_SUMMARY (C macro)
4500 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_SUMMARY}@anchor{5f}
4501 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_SUMMARY
4503 If true, @pxref{15,,gcc_jit_context_compile()} will print information to stderr
4504 on the actions it is performing, followed by a profile showing
4505 the time taken and memory usage of each phase.
4508 @geindex GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING (C macro)
4509 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING}@anchor{60}
4510 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING
4512 If true, @pxref{15,,gcc_jit_context_compile()} will dump copious
4513 amount of information on what it's doing to various
4514 files within a temporary directory. Use
4515 @pxref{61,,GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES} (see below) to
4516 see the results. The files are intended to be human-readable,
4517 but the exact files and their formats are subject to change.
4520 @geindex GCC_JIT_BOOL_OPTION_SELFCHECK_GC (C macro)
4521 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_SELFCHECK_GC}@anchor{62}
4522 @deffn {C Macro} GCC_JIT_BOOL_OPTION_SELFCHECK_GC
4524 If true, libgccjit will aggressively run its garbage collector, to
4525 shake out bugs (greatly slowing down the compile). This is likely
4526 to only be of interest to developers @emph{of} the library. It is
4527 used when running the selftest suite.
4530 @geindex GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES (C macro)
4531 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES}@anchor{61}
4532 @deffn {C Macro} GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES
4534 If true, the @pxref{8,,gcc_jit_context} will not clean up intermediate files
4535 written to the filesystem, and will display their location on stderr.
4539 @node Integer options,,Boolean options,Options<2>
4540 @anchor{topics/contexts integer-options}@anchor{63}
4541 @subsubsection Integer options
4544 @geindex gcc_jit_context_set_int_option (C function)
4545 @anchor{topics/contexts gcc_jit_context_set_int_option}@anchor{1e}
4546 @deffn {C Function} void gcc_jit_context_set_int_option (gcc_jit_context@w{ }*ctxt, enum gcc_jit_int_option@w{ }opt, int@w{ }value)
4548 Set an integer option of the context.
4550 @geindex gcc_jit_int_option (C type)
4551 @anchor{topics/contexts gcc_jit_int_option}@anchor{64}
4552 @deffn {C Type} enum gcc_jit_int_option
4555 There is currently just one integer option:
4557 @geindex GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL (C macro)
4558 @anchor{topics/contexts GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}@anchor{1f}
4559 @deffn {C Macro} GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL
4561 How much to optimize the code.
4563 Valid values are 0-3, corresponding to GCC's command-line options
4566 The default value is 0 (unoptimized).
4570 @c Copyright (C) 2014 Free Software Foundation, Inc.
4571 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
4573 @c This is free software: you can redistribute it and/or modify it
4574 @c under the terms of the GNU General Public License as published by
4575 @c the Free Software Foundation, either version 3 of the License, or
4576 @c (at your option) any later version.
4578 @c This program is distributed in the hope that it will be useful, but
4579 @c WITHOUT ANY WARRANTY; without even the implied warranty of
4580 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4581 @c General Public License for more details.
4583 @c You should have received a copy of the GNU General Public License
4584 @c along with this program. If not, see
4585 @c <http://www.gnu.org/licenses/>.
4587 @node Objects,Types,Compilation contexts,Topic Reference
4588 @anchor{topics/objects objects}@anchor{65}@anchor{topics/objects doc}@anchor{66}
4592 @geindex gcc_jit_object (C type)
4593 @anchor{topics/objects gcc_jit_object}@anchor{e}
4594 @deffn {C Type} gcc_jit_object
4597 Almost every entity in the API (with the exception of
4598 @pxref{8,,gcc_jit_context *} and @pxref{16,,gcc_jit_result *}) is a
4599 "contextual" object, a @pxref{e,,gcc_jit_object *}
4609 is associated with a @pxref{8,,gcc_jit_context *}.
4612 is automatically cleaned up for you when its context is released so
4613 you don't need to manually track and cleanup all objects, just the
4618 Although the API is C-based, there is a form of class hierarchy, which
4636 There are casting methods for upcasting from subclasses to parent classes.
4637 For example, @pxref{d,,gcc_jit_type_as_object()}:
4640 gcc_jit_object *obj = gcc_jit_type_as_object (int_type);
4645 The object "base class" has the following operations:
4647 @geindex gcc_jit_object_get_context (C function)
4648 @anchor{topics/objects gcc_jit_object_get_context}@anchor{67}
4649 @deffn {C Function} gcc_jit_context *gcc_jit_object_get_context (gcc_jit_object@w{ }*obj)
4651 Which context is "obj" within?
4654 @geindex gcc_jit_object_get_debug_string (C function)
4655 @anchor{topics/objects gcc_jit_object_get_debug_string}@anchor{f}
4656 @deffn {C Function} const char *gcc_jit_object_get_debug_string (gcc_jit_object@w{ }*obj)
4658 Generate a human-readable description for the given object.
4663 printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj));
4668 might give this text on stdout:
4678 If you call this on an object, the @cite{const char *} buffer is allocated
4679 and generated on the first call for that object, and the buffer will
4680 have the same lifetime as the object i.e. it will exist until the
4681 object's context is released.
4686 @c Copyright (C) 2014 Free Software Foundation, Inc.
4687 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
4689 @c This is free software: you can redistribute it and/or modify it
4690 @c under the terms of the GNU General Public License as published by
4691 @c the Free Software Foundation, either version 3 of the License, or
4692 @c (at your option) any later version.
4694 @c This program is distributed in the hope that it will be useful, but
4695 @c WITHOUT ANY WARRANTY; without even the implied warranty of
4696 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4697 @c General Public License for more details.
4699 @c You should have received a copy of the GNU General Public License
4700 @c along with this program. If not, see
4701 @c <http://www.gnu.org/licenses/>.
4703 @node Types,Expressions,Objects,Topic Reference
4704 @anchor{topics/types doc}@anchor{68}@anchor{topics/types types}@anchor{69}
4708 @geindex gcc_jit_type (C type)
4709 @anchor{topics/types gcc_jit_type}@anchor{a}
4710 @deffn {C Type} gcc_jit_type
4712 gcc_jit_type represents a type within the library.
4715 @geindex gcc_jit_type_as_object (C function)
4716 @anchor{topics/types gcc_jit_type_as_object}@anchor{d}
4717 @deffn {C Function} gcc_jit_object *gcc_jit_type_as_object (gcc_jit_type@w{ }*type)
4719 Upcast a type to an object.
4722 Types can be created in several ways:
4728 fundamental types can be accessed using
4729 @pxref{b,,gcc_jit_context_get_type()}:
4732 gcc_jit_type *int_type = gcc_jit_context_get_type (GCC_JIT_TYPE_INT);
4737 See @pxref{b,,gcc_jit_context_get_type()} for the available types.
4740 derived types can be accessed by using functions such as
4741 @pxref{6a,,gcc_jit_type_get_pointer()} and @pxref{6b,,gcc_jit_type_get_const()}:
4744 gcc_jit_type *const_int_star = gcc_jit_type_get_pointer (gcc_jit_type_get_const (int_type));
4745 gcc_jit_type *int_const_star = gcc_jit_type_get_const (gcc_jit_type_get_pointer (int_type));
4751 by creating structures (see below).
4756 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile.
4757 * Structures and unions::
4761 @node Standard types,Pointers const and volatile,,Types
4762 @anchor{topics/types standard-types}@anchor{6c}
4763 @subsection Standard types
4766 @geindex gcc_jit_context_get_type (C function)
4767 @anchor{topics/types gcc_jit_context_get_type}@anchor{b}
4768 @deffn {C Function} gcc_jit_type *gcc_jit_context_get_type (gcc_jit_context@w{ }*ctxt, enum gcc_jit_types@w{ }type_)
4770 Access a specific type. The available types are:
4773 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
4776 @cite{enum gcc_jit_types} value
4784 @code{GCC_JIT_TYPE_VOID}
4788 C's @code{void} type.
4792 @code{GCC_JIT_TYPE_VOID_PTR}
4800 @code{GCC_JIT_TYPE_BOOL}
4804 C++'s @code{bool} type; also C99's
4805 @code{_Bool} type, aka @code{bool} if
4810 @code{GCC_JIT_TYPE_CHAR}
4814 C's @code{char} (of some signedness)
4818 @code{GCC_JIT_TYPE_SIGNED_CHAR}
4822 C's @code{signed char}
4826 @code{GCC_JIT_TYPE_UNSIGNED_CHAR}
4830 C's @code{unsigned char}
4834 @code{GCC_JIT_TYPE_SHORT}
4838 C's @code{short} (signed)
4842 @code{GCC_JIT_TYPE_UNSIGNED_SHORT}
4846 C's @code{unsigned short}
4850 @code{GCC_JIT_TYPE_INT}
4854 C's @code{int} (signed)
4858 @code{GCC_JIT_TYPE_UNSIGNED_INT}
4862 C's @code{unsigned int}
4866 @code{GCC_JIT_TYPE_LONG}
4870 C's @code{long} (signed)
4874 @code{GCC_JIT_TYPE_UNSIGNED_LONG}
4878 C's @code{unsigned long}
4882 @code{GCC_JIT_TYPE_LONG_LONG}
4886 C99's @code{long long} (signed)
4890 @code{GCC_JIT_TYPE_UNSIGNED_LONG_LONG}
4894 C99's @code{unsigned long long}
4898 @code{GCC_JIT_TYPE_FLOAT}
4904 @code{GCC_JIT_TYPE_DOUBLE}
4910 @code{GCC_JIT_TYPE_LONG_DOUBLE}
4916 @code{GCC_JIT_TYPE_CONST_CHAR_PTR}
4920 C type: @code{(const char *)}
4924 @code{GCC_JIT_TYPE_SIZE_T}
4928 C's @code{size_t} type
4932 @code{GCC_JIT_TYPE_FILE_PTR}
4936 C type: @code{(FILE *)}
4940 @code{GCC_JIT_TYPE_COMPLEX_FLOAT}
4944 C99's @code{_Complex float}
4948 @code{GCC_JIT_TYPE_COMPLEX_DOUBLE}
4952 C99's @code{_Complex double}
4956 @code{GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE}
4960 C99's @code{_Complex long double}
4966 @geindex gcc_jit_context_get_int_type (C function)
4967 @anchor{topics/types gcc_jit_context_get_int_type}@anchor{6d}
4968 @deffn {C Function} gcc_jit_type * gcc_jit_context_get_int_type (gcc_jit_context@w{ }*ctxt, int@w{ }num_bytes, int@w{ }is_signed)
4970 Access the integer type of the given size.
4973 @node Pointers const and volatile,Structures and unions,Standard types,Types
4974 @anchor{topics/types pointers-const-and-volatile}@anchor{6e}
4975 @subsection Pointers, @cite{const}, and @cite{volatile}
4978 @geindex gcc_jit_type_get_pointer (C function)
4979 @anchor{topics/types gcc_jit_type_get_pointer}@anchor{6a}
4980 @deffn {C Function} gcc_jit_type *gcc_jit_type_get_pointer (gcc_jit_type@w{ }*type)
4982 Given type "T", get type "T*".
4985 @geindex gcc_jit_type_get_const (C function)
4986 @anchor{topics/types gcc_jit_type_get_const}@anchor{6b}
4987 @deffn {C Function} gcc_jit_type *gcc_jit_type_get_const (gcc_jit_type@w{ }*type)
4989 Given type "T", get type "const T".
4992 @geindex gcc_jit_type_get_volatile (C function)
4993 @anchor{topics/types gcc_jit_type_get_volatile}@anchor{6f}
4994 @deffn {C Function} gcc_jit_type *gcc_jit_type_get_volatile (gcc_jit_type@w{ }*type)
4996 Given type "T", get type "volatile T".
4999 @geindex gcc_jit_context_new_array_type (C function)
5000 @anchor{topics/types gcc_jit_context_new_array_type}@anchor{70}
5001 @deffn {C Function} gcc_jit_type * gcc_jit_context_new_array_type (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*element_type, int@w{ }num_elements)
5003 Given type "T", get type "T[N]" (for a constant N).
5006 @node Structures and unions,,Pointers const and volatile,Types
5007 @anchor{topics/types structures-and-unions}@anchor{71}
5008 @subsection Structures and unions
5011 @geindex gcc_jit_struct (C type)
5012 @anchor{topics/types gcc_jit_struct}@anchor{72}
5013 @deffn {C Type} gcc_jit_struct
5016 A compound type analagous to a C @cite{struct}.
5018 @geindex gcc_jit_field (C type)
5019 @anchor{topics/types gcc_jit_field}@anchor{73}
5020 @deffn {C Type} gcc_jit_field
5023 A field within a @pxref{72,,gcc_jit_struct}.
5025 You can model C @cite{struct} types by creating @pxref{72,,gcc_jit_struct *} and
5026 @pxref{73,,gcc_jit_field} instances, in either order:
5032 by creating the fields, then the structure. For example, to model:
5035 struct coord @{double x; double y; @};
5043 gcc_jit_field *field_x =
5044 gcc_jit_context_new_field (ctxt, NULL, double_type, "x");
5045 gcc_jit_field *field_y =
5046 gcc_jit_context_new_field (ctxt, NULL, double_type, "y");
5047 gcc_jit_field *fields[2] = @{field_x, field_y@};
5048 gcc_jit_struct *coord =
5049 gcc_jit_context_new_struct_type (ctxt, NULL, "coord", 2, fields);
5055 by creating the structure, then populating it with fields, typically
5056 to allow modelling self-referential structs such as:
5059 struct node @{ int m_hash; struct node *m_next; @};
5067 gcc_jit_type *node =
5068 gcc_jit_context_new_opaque_struct (ctxt, NULL, "node");
5069 gcc_jit_type *node_ptr =
5070 gcc_jit_type_get_pointer (node);
5071 gcc_jit_field *field_hash =
5072 gcc_jit_context_new_field (ctxt, NULL, int_type, "m_hash");
5073 gcc_jit_field *field_next =
5074 gcc_jit_context_new_field (ctxt, NULL, node_ptr, "m_next");
5075 gcc_jit_field *fields[2] = @{field_hash, field_next@};
5076 gcc_jit_struct_set_fields (node, NULL, 2, fields);
5082 @geindex gcc_jit_context_new_field (C function)
5083 @anchor{topics/types gcc_jit_context_new_field}@anchor{74}
5084 @deffn {C Function} gcc_jit_field * gcc_jit_context_new_field (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, const char@w{ }*name)
5086 Construct a new field, with the given type and name.
5089 @geindex gcc_jit_field_as_object (C function)
5090 @anchor{topics/types gcc_jit_field_as_object}@anchor{75}
5091 @deffn {C Function} gcc_jit_object * gcc_jit_field_as_object (gcc_jit_field@w{ }*field)
5093 Upcast from field to object.
5096 @geindex gcc_jit_context_new_struct_type (C function)
5097 @anchor{topics/types gcc_jit_context_new_struct_type}@anchor{76}
5098 @deffn {C Function} gcc_jit_struct *gcc_jit_context_new_struct_type (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, const char@w{ }*name, int@w{ }num_fields, gcc_jit_field@w{ }**fields)
5102 Construct a new struct type, with the given name and fields.
5106 @geindex gcc_jit_context_new_opaque_struct (C function)
5107 @anchor{topics/types gcc_jit_context_new_opaque_struct}@anchor{77}
5108 @deffn {C Function} gcc_jit_struct * gcc_jit_context_new_opaque_struct (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, const char@w{ }*name)
5110 Construct a new struct type, with the given name, but without
5111 specifying the fields. The fields can be omitted (in which case the
5112 size of the struct is not known), or later specified using
5113 @pxref{78,,gcc_jit_struct_set_fields()}.
5116 @geindex gcc_jit_struct_as_type (C function)
5117 @anchor{topics/types gcc_jit_struct_as_type}@anchor{79}
5118 @deffn {C Function} gcc_jit_type * gcc_jit_struct_as_type (gcc_jit_struct@w{ }*struct_type)
5120 Upcast from struct to type.
5123 @geindex gcc_jit_struct_set_fields (C function)
5124 @anchor{topics/types gcc_jit_struct_set_fields}@anchor{78}
5125 @deffn {C Function} void gcc_jit_struct_set_fields (gcc_jit_struct@w{ }*struct_type, gcc_jit_location@w{ }*loc, int@w{ }num_fields, gcc_jit_field@w{ }**fields)
5127 Populate the fields of a formerly-opaque struct type.
5129 This can only be called once on a given struct type.
5132 @c Copyright (C) 2014 Free Software Foundation, Inc.
5133 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
5135 @c This is free software: you can redistribute it and/or modify it
5136 @c under the terms of the GNU General Public License as published by
5137 @c the Free Software Foundation, either version 3 of the License, or
5138 @c (at your option) any later version.
5140 @c This program is distributed in the hope that it will be useful, but
5141 @c WITHOUT ANY WARRANTY; without even the implied warranty of
5142 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5143 @c General Public License for more details.
5145 @c You should have received a copy of the GNU General Public License
5146 @c along with this program. If not, see
5147 @c <http://www.gnu.org/licenses/>.
5149 @node Expressions,Creating and using functions,Types,Topic Reference
5150 @anchor{topics/expressions expressions}@anchor{7a}@anchor{topics/expressions doc}@anchor{7b}
5151 @section Expressions
5157 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions.
5161 * Simple expressions::
5162 * Unary Operations::
5163 * Binary Operations::
5170 * Global variables::
5175 @node Rvalues,Lvalues,,Expressions
5176 @anchor{topics/expressions rvalues}@anchor{7c}
5180 @geindex gcc_jit_rvalue (C type)
5181 @anchor{topics/expressions gcc_jit_rvalue}@anchor{13}
5182 @deffn {C Type} gcc_jit_rvalue
5185 A @pxref{13,,gcc_jit_rvalue *} is an expression that can be computed.
5187 It can be simple, e.g.:
5195 an integer value e.g. @cite{0} or @cite{42}
5198 a string literal e.g. @cite{"Hello world"}
5201 a variable e.g. @cite{i}. These are also lvalues (see below).
5213 a unary expression e.g. @cite{!cond}
5216 a binary expression e.g. @cite{(a + b)}
5219 a function call e.g. @cite{get_distance (&player_ship@comma{} &target)}
5226 Every rvalue has an associated type, and the API will check to ensure
5227 that types match up correctly (otherwise the context will emit an error).
5229 @geindex gcc_jit_rvalue_get_type (C function)
5230 @anchor{topics/expressions gcc_jit_rvalue_get_type}@anchor{7d}
5231 @deffn {C Function} gcc_jit_type *gcc_jit_rvalue_get_type (gcc_jit_rvalue@w{ }*rvalue)
5233 Get the type of this rvalue.
5236 @geindex gcc_jit_rvalue_as_object (C function)
5237 @anchor{topics/expressions gcc_jit_rvalue_as_object}@anchor{14}
5238 @deffn {C Function} gcc_jit_object *gcc_jit_rvalue_as_object (gcc_jit_rvalue@w{ }*rvalue)
5240 Upcast the given rvalue to be an object.
5244 * Simple expressions::
5245 * Unary Operations::
5246 * Binary Operations::
5253 @node Simple expressions,Unary Operations,,Rvalues
5254 @anchor{topics/expressions simple-expressions}@anchor{7e}
5255 @subsubsection Simple expressions
5258 @geindex gcc_jit_context_new_rvalue_from_int (C function)
5259 @anchor{topics/expressions gcc_jit_context_new_rvalue_from_int}@anchor{30}
5260 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_rvalue_from_int (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type, int@w{ }value)
5262 Given a numeric type (integer or floating point), build an rvalue for
5263 the given constant @code{int} value.
5266 @geindex gcc_jit_context_new_rvalue_from_long (C function)
5267 @anchor{topics/expressions gcc_jit_context_new_rvalue_from_long}@anchor{7f}
5268 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_rvalue_from_long (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type, long@w{ }value)
5270 Given a numeric type (integer or floating point), build an rvalue for
5271 the given constant @code{long} value.
5274 @geindex gcc_jit_context_zero (C function)
5275 @anchor{topics/expressions gcc_jit_context_zero}@anchor{2b}
5276 @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type)
5278 Given a numeric type (integer or floating point), get the rvalue for
5279 zero. Essentially this is just a shortcut for:
5282 gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 0)
5288 @geindex gcc_jit_context_one (C function)
5289 @anchor{topics/expressions gcc_jit_context_one}@anchor{2f}
5290 @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_one (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type)
5292 Given a numeric type (integer or floating point), get the rvalue for
5293 zero. Essentially this is just a shortcut for:
5296 gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 1)
5302 @geindex gcc_jit_context_new_rvalue_from_double (C function)
5303 @anchor{topics/expressions gcc_jit_context_new_rvalue_from_double}@anchor{31}
5304 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_rvalue_from_double (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type, double@w{ }value)
5306 Given a numeric type (integer or floating point), build an rvalue for
5307 the given constant @code{double} value.
5310 @geindex gcc_jit_context_new_rvalue_from_ptr (C function)
5311 @anchor{topics/expressions gcc_jit_context_new_rvalue_from_ptr}@anchor{80}
5312 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*pointer_type, void@w{ }*value)
5314 Given a pointer type, build an rvalue for the given address.
5317 @geindex gcc_jit_context_null (C function)
5318 @anchor{topics/expressions gcc_jit_context_null}@anchor{81}
5319 @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_null (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*pointer_type)
5321 Given a pointer type, build an rvalue for @code{NULL}. Essentially this
5322 is just a shortcut for:
5325 gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL)
5331 @geindex gcc_jit_context_new_string_literal (C function)
5332 @anchor{topics/expressions gcc_jit_context_new_string_literal}@anchor{82}
5333 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_string_literal (gcc_jit_context@w{ }*ctxt, const char@w{ }*value)
5335 Generate an rvalue for the given NIL-terminated string, of type
5336 @code{GCC_JIT_TYPE_CONST_CHAR_PTR}.
5339 @node Unary Operations,Binary Operations,Simple expressions,Rvalues
5340 @anchor{topics/expressions unary-operations}@anchor{83}
5341 @subsubsection Unary Operations
5344 @geindex gcc_jit_context_new_unary_op (C function)
5345 @anchor{topics/expressions gcc_jit_context_new_unary_op}@anchor{84}
5346 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_unary_op (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, enum gcc_jit_unary_op@w{ }op, gcc_jit_type@w{ }*result_type, gcc_jit_rvalue@w{ }*rvalue)
5348 Build a unary operation out of an input rvalue.
5351 @geindex gcc_jit_unary_op (C type)
5352 @anchor{topics/expressions gcc_jit_unary_op}@anchor{85}
5353 @deffn {C Type} enum gcc_jit_unary_op
5356 The available unary operations are:
5359 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx}
5370 @pxref{86,,GCC_JIT_UNARY_OP_MINUS}
5378 @pxref{87,,GCC_JIT_UNARY_OP_BITWISE_NEGATE}
5386 @pxref{88,,GCC_JIT_UNARY_OP_LOGICAL_NEGATE}
5394 @pxref{89,,GCC_JIT_UNARY_OP_ABS}
5403 @geindex GCC_JIT_UNARY_OP_MINUS (C macro)
5404 @anchor{topics/expressions GCC_JIT_UNARY_OP_MINUS}@anchor{86}
5405 @deffn {C Macro} GCC_JIT_UNARY_OP_MINUS
5407 Negate an arithmetic value; analogous to:
5418 @geindex GCC_JIT_UNARY_OP_BITWISE_NEGATE (C macro)
5419 @anchor{topics/expressions GCC_JIT_UNARY_OP_BITWISE_NEGATE}@anchor{87}
5420 @deffn {C Macro} GCC_JIT_UNARY_OP_BITWISE_NEGATE
5422 Bitwise negation of an integer value (one's complement); analogous
5434 @geindex GCC_JIT_UNARY_OP_LOGICAL_NEGATE (C macro)
5435 @anchor{topics/expressions GCC_JIT_UNARY_OP_LOGICAL_NEGATE}@anchor{88}
5436 @deffn {C Macro} GCC_JIT_UNARY_OP_LOGICAL_NEGATE
5438 Logical negation of an arithmetic or pointer value; analogous to:
5449 @geindex GCC_JIT_UNARY_OP_ABS (C macro)
5450 @anchor{topics/expressions GCC_JIT_UNARY_OP_ABS}@anchor{89}
5451 @deffn {C Macro} GCC_JIT_UNARY_OP_ABS
5453 Absolute value of an arithmetic expression; analogous to:
5464 @node Binary Operations,Comparisons,Unary Operations,Rvalues
5465 @anchor{topics/expressions binary-operations}@anchor{8a}
5466 @subsubsection Binary Operations
5469 @geindex gcc_jit_context_new_binary_op (C function)
5470 @anchor{topics/expressions gcc_jit_context_new_binary_op}@anchor{12}
5471 @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_new_binary_op (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, enum gcc_jit_binary_op@w{ }op, gcc_jit_type@w{ }*result_type, gcc_jit_rvalue@w{ }*a, gcc_jit_rvalue@w{ }*b)
5473 Build a binary operation out of two constituent rvalues.
5476 @geindex gcc_jit_binary_op (C type)
5477 @anchor{topics/expressions gcc_jit_binary_op}@anchor{8b}
5478 @deffn {C Type} enum gcc_jit_binary_op
5481 The available binary operations are:
5484 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx}
5495 @pxref{8c,,GCC_JIT_BINARY_OP_PLUS}
5503 @code{GCC_JIT_BINARY_OP_MINUS}
5511 @pxref{8d,,GCC_JIT_BINARY_OP_MULT}
5519 @pxref{8e,,GCC_JIT_BINARY_OP_DIVIDE}
5527 @pxref{8f,,GCC_JIT_BINARY_OP_MODULO}
5535 @pxref{90,,GCC_JIT_BINARY_OP_BITWISE_AND}
5543 @pxref{91,,GCC_JIT_BINARY_OP_BITWISE_XOR}
5551 @pxref{92,,GCC_JIT_BINARY_OP_BITWISE_OR}
5559 @pxref{93,,GCC_JIT_BINARY_OP_LOGICAL_AND}
5567 @pxref{94,,GCC_JIT_BINARY_OP_LOGICAL_OR}
5575 @pxref{95,,GCC_JIT_BINARY_OP_LSHIFT}
5583 @pxref{96,,GCC_JIT_BINARY_OP_RSHIFT}
5592 @geindex GCC_JIT_BINARY_OP_PLUS (C macro)
5593 @anchor{topics/expressions GCC_JIT_BINARY_OP_PLUS}@anchor{8c}
5594 @deffn {C Macro} GCC_JIT_BINARY_OP_PLUS
5596 Addition of arithmetic values; analogous to:
5606 For pointer addition, use @pxref{97,,gcc_jit_context_new_array_access()}.
5610 @deffn {C Macro} GCC_JIT_BINARY_OP_MINUS`
5612 Subtraction of arithmetic values; analogous to:
5623 @geindex GCC_JIT_BINARY_OP_MULT (C macro)
5624 @anchor{topics/expressions GCC_JIT_BINARY_OP_MULT}@anchor{8d}
5625 @deffn {C Macro} GCC_JIT_BINARY_OP_MULT
5627 Multiplication of a pair of arithmetic values; analogous to:
5638 @geindex GCC_JIT_BINARY_OP_DIVIDE (C macro)
5639 @anchor{topics/expressions GCC_JIT_BINARY_OP_DIVIDE}@anchor{8e}
5640 @deffn {C Macro} GCC_JIT_BINARY_OP_DIVIDE
5642 Quotient of division of arithmetic values; analogous to:
5652 The result type affects the kind of division: if the result type is
5653 integer-based, then the result is truncated towards zero, whereas
5654 a floating-point result type indicates floating-point division.
5657 @geindex GCC_JIT_BINARY_OP_MODULO (C macro)
5658 @anchor{topics/expressions GCC_JIT_BINARY_OP_MODULO}@anchor{8f}
5659 @deffn {C Macro} GCC_JIT_BINARY_OP_MODULO
5661 Remainder of division of arithmetic values; analogous to:
5672 @geindex GCC_JIT_BINARY_OP_BITWISE_AND (C macro)
5673 @anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_AND}@anchor{90}
5674 @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_AND
5676 Bitwise AND; analogous to:
5687 @geindex GCC_JIT_BINARY_OP_BITWISE_XOR (C macro)
5688 @anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_XOR}@anchor{91}
5689 @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_XOR
5691 Bitwise exclusive OR; analogous to:
5702 @geindex GCC_JIT_BINARY_OP_BITWISE_OR (C macro)
5703 @anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_OR}@anchor{92}
5704 @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_OR
5706 Bitwise inclusive OR; analogous to:
5717 @geindex GCC_JIT_BINARY_OP_LOGICAL_AND (C macro)
5718 @anchor{topics/expressions GCC_JIT_BINARY_OP_LOGICAL_AND}@anchor{93}
5719 @deffn {C Macro} GCC_JIT_BINARY_OP_LOGICAL_AND
5721 Logical AND; analogous to:
5724 (EXPR_A) && (EXPR_B)
5732 @geindex GCC_JIT_BINARY_OP_LOGICAL_OR (C macro)
5733 @anchor{topics/expressions GCC_JIT_BINARY_OP_LOGICAL_OR}@anchor{94}
5734 @deffn {C Macro} GCC_JIT_BINARY_OP_LOGICAL_OR
5736 Logical OR; analogous to:
5739 (EXPR_A) || (EXPR_B)
5747 @geindex GCC_JIT_BINARY_OP_LSHIFT (C macro)
5748 @anchor{topics/expressions GCC_JIT_BINARY_OP_LSHIFT}@anchor{95}
5749 @deffn {C Macro} GCC_JIT_BINARY_OP_LSHIFT
5751 Left shift; analogous to:
5754 (EXPR_A) << (EXPR_B)
5762 @geindex GCC_JIT_BINARY_OP_RSHIFT (C macro)
5763 @anchor{topics/expressions GCC_JIT_BINARY_OP_RSHIFT}@anchor{96}
5764 @deffn {C Macro} GCC_JIT_BINARY_OP_RSHIFT
5766 Right shift; analogous to:
5769 (EXPR_A) >> (EXPR_B)
5777 @node Comparisons,Function calls,Binary Operations,Rvalues
5778 @anchor{topics/expressions comparisons}@anchor{98}
5779 @subsubsection Comparisons
5782 @geindex gcc_jit_context_new_comparison (C function)
5783 @anchor{topics/expressions gcc_jit_context_new_comparison}@anchor{2c}
5784 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_comparison (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, enum gcc_jit_comparison@w{ }op, gcc_jit_rvalue@w{ }*a, gcc_jit_rvalue@w{ }*b)
5786 Build a boolean rvalue out of the comparison of two other rvalues.
5789 @geindex gcc_jit_comparison (C type)
5790 @anchor{topics/expressions gcc_jit_comparison}@anchor{99}
5791 @deffn {C Type} enum gcc_jit_comparison
5795 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx}
5806 @code{GCC_JIT_COMPARISON_EQ}
5814 @code{GCC_JIT_COMPARISON_NE}
5822 @code{GCC_JIT_COMPARISON_LT}
5830 @code{GCC_JIT_COMPARISON_LE}
5838 @code{GCC_JIT_COMPARISON_GT}
5846 @code{GCC_JIT_COMPARISON_GE}
5855 @node Function calls,Type-coercion,Comparisons,Rvalues
5856 @anchor{topics/expressions function-calls}@anchor{9a}
5857 @subsubsection Function calls
5860 @geindex gcc_jit_context_new_call (C function)
5861 @anchor{topics/expressions gcc_jit_context_new_call}@anchor{9b}
5862 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_call (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_function@w{ }*func, int@w{ }numargs, gcc_jit_rvalue@w{ }**args)
5864 Given a function and the given table of argument rvalues, construct a
5865 call to the function, with the result as an rvalue.
5869 @pxref{9b,,gcc_jit_context_new_call()} merely builds a
5870 @pxref{13,,gcc_jit_rvalue} i.e. an expression that can be evaluated,
5871 perhaps as part of a more complicated expression.
5872 The call @emph{won't} happen unless you add a statement to a function
5873 that evaluates the expression.
5875 For example, if you want to call a function and discard the result
5876 (or to call a function with @code{void} return type), use
5877 @pxref{9c,,gcc_jit_block_add_eval()}:
5880 /* Add "(void)printf (arg0, arg1);". */
5881 gcc_jit_block_add_eval (
5883 gcc_jit_context_new_call (
5895 @node Type-coercion,,Function calls,Rvalues
5896 @anchor{topics/expressions type-coercion}@anchor{9d}
5897 @subsubsection Type-coercion
5900 @geindex gcc_jit_context_new_cast (C function)
5901 @anchor{topics/expressions gcc_jit_context_new_cast}@anchor{9e}
5902 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_cast (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*rvalue, gcc_jit_type@w{ }*type)
5904 Given an rvalue of T, construct another rvalue of another type.
5906 Currently only a limited set of conversions are possible:
5920 P* <-> Q*, for pointer types P and Q
5925 @node Lvalues,Working with pointers structs and unions,Rvalues,Expressions
5926 @anchor{topics/expressions lvalues}@anchor{9f}
5930 @geindex gcc_jit_lvalue (C type)
5931 @anchor{topics/expressions gcc_jit_lvalue}@anchor{24}
5932 @deffn {C Type} gcc_jit_lvalue
5935 An lvalue is something that can of the @emph{left}-hand side of an assignment:
5936 a storage area (such as a variable). It is also usable as an rvalue,
5937 where the rvalue is computed by reading from the storage area.
5939 @geindex gcc_jit_lvalue_as_object (C function)
5940 @anchor{topics/expressions gcc_jit_lvalue_as_object}@anchor{a0}
5941 @deffn {C Function} gcc_jit_object * gcc_jit_lvalue_as_object (gcc_jit_lvalue@w{ }*lvalue)
5943 Upcast an lvalue to be an object.
5946 @geindex gcc_jit_lvalue_as_rvalue (C function)
5947 @anchor{topics/expressions gcc_jit_lvalue_as_rvalue}@anchor{a1}
5948 @deffn {C Function} gcc_jit_rvalue * gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue@w{ }*lvalue)
5950 Upcast an lvalue to be an rvalue.
5953 @geindex gcc_jit_lvalue_get_address (C function)
5954 @anchor{topics/expressions gcc_jit_lvalue_get_address}@anchor{a2}
5955 @deffn {C Function} gcc_jit_rvalue * gcc_jit_lvalue_get_address (gcc_jit_lvalue@w{ }*lvalue, gcc_jit_location@w{ }*loc)
5957 Take the address of an lvalue; analogous to:
5969 * Global variables::
5973 @node Global variables,,,Lvalues
5974 @anchor{topics/expressions global-variables}@anchor{a3}
5975 @subsubsection Global variables
5978 @geindex gcc_jit_context_new_global (C function)
5979 @anchor{topics/expressions gcc_jit_context_new_global}@anchor{a4}
5980 @deffn {C Function} gcc_jit_lvalue * gcc_jit_context_new_global (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, enum gcc_jit_global_kind@w{ }kind, gcc_jit_type@w{ }*type, const char@w{ }*name)
5982 Add a new global variable of the given type and name to the context.
5984 The "kind" parameter determines the visibility of the "global" outside
5985 of the @pxref{16,,gcc_jit_result}:
5987 @geindex gcc_jit_global_kind (C type)
5988 @anchor{topics/expressions gcc_jit_global_kind}@anchor{a5}
5989 @deffn {C Type} enum gcc_jit_global_kind
5992 @geindex GCC_JIT_GLOBAL_EXPORTED (C macro)
5993 @anchor{topics/expressions GCC_JIT_GLOBAL_EXPORTED}@anchor{a6}
5994 @deffn {C Macro} GCC_JIT_GLOBAL_EXPORTED
5996 Global is defined by the client code and is visible
5997 by name outside of this JIT context via
5998 @pxref{a7,,gcc_jit_result_get_global()} (and this value is required for
5999 the global to be accessible via that entrypoint).
6002 @geindex GCC_JIT_GLOBAL_INTERNAL (C macro)
6003 @anchor{topics/expressions GCC_JIT_GLOBAL_INTERNAL}@anchor{a8}
6004 @deffn {C Macro} GCC_JIT_GLOBAL_INTERNAL
6006 Global is defined by the client code, but is invisible
6007 outside of it. Analogous to a "static" global within a .c file.
6008 Specifically, the variable will only be visible within this
6009 context and within child contexts.
6012 @geindex GCC_JIT_GLOBAL_IMPORTED (C macro)
6013 @anchor{topics/expressions GCC_JIT_GLOBAL_IMPORTED}@anchor{a9}
6014 @deffn {C Macro} GCC_JIT_GLOBAL_IMPORTED
6016 Global is not defined by the client code; we're merely
6017 referring to it. Analogous to using an "extern" global from a
6022 @node Working with pointers structs and unions,,Lvalues,Expressions
6023 @anchor{topics/expressions working-with-pointers-structs-and-unions}@anchor{aa}
6024 @subsection Working with pointers, structs and unions
6027 @geindex gcc_jit_rvalue_dereference (C function)
6028 @anchor{topics/expressions gcc_jit_rvalue_dereference}@anchor{ab}
6029 @deffn {C Function} gcc_jit_lvalue * gcc_jit_rvalue_dereference (gcc_jit_rvalue@w{ }*rvalue, gcc_jit_location@w{ }*loc)
6031 Given an rvalue of pointer type @code{T *}, dereferencing the pointer,
6032 getting an lvalue of type @code{T}. Analogous to:
6043 Field access is provided separately for both lvalues and rvalues.
6045 @geindex gcc_jit_lvalue_access_field (C function)
6046 @anchor{topics/expressions gcc_jit_lvalue_access_field}@anchor{ac}
6047 @deffn {C Function} gcc_jit_lvalue * gcc_jit_lvalue_access_field (gcc_jit_lvalue@w{ }*struct_, gcc_jit_location@w{ }*loc, gcc_jit_field@w{ }*field)
6049 Given an lvalue of struct or union type, access the given field,
6050 getting an lvalue of the field's type. Analogous to:
6061 @geindex gcc_jit_rvalue_access_field (C function)
6062 @anchor{topics/expressions gcc_jit_rvalue_access_field}@anchor{ad}
6063 @deffn {C Function} gcc_jit_rvalue * gcc_jit_rvalue_access_field (gcc_jit_rvalue@w{ }*struct_, gcc_jit_location@w{ }*loc, gcc_jit_field@w{ }*field)
6065 Given an rvalue of struct or union type, access the given field
6066 as an rvalue. Analogous to:
6077 @geindex gcc_jit_rvalue_dereference_field (C function)
6078 @anchor{topics/expressions gcc_jit_rvalue_dereference_field}@anchor{ae}
6079 @deffn {C Function} gcc_jit_lvalue * gcc_jit_rvalue_dereference_field (gcc_jit_rvalue@w{ }*ptr, gcc_jit_location@w{ }*loc, gcc_jit_field@w{ }*field)
6081 Given an rvalue of pointer type @code{T *} where T is of struct or union
6082 type, access the given field as an lvalue. Analogous to:
6090 in C, itself equivalent to @code{(*EXPR).FIELD}.
6093 @geindex gcc_jit_context_new_array_access (C function)
6094 @anchor{topics/expressions gcc_jit_context_new_array_access}@anchor{97}
6095 @deffn {C Function} gcc_jit_lvalue * gcc_jit_context_new_array_access (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*ptr, gcc_jit_rvalue@w{ }*index)
6097 Given an rvalue of pointer type @code{T *}, get at the element @cite{T} at
6098 the given index, using standard C array indexing rules i.e. each
6099 increment of @code{index} corresponds to @code{sizeof(T)} bytes.
6108 in C (or, indeed, to @code{PTR + INDEX}).
6111 @c Copyright (C) 2014 Free Software Foundation, Inc.
6112 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
6114 @c This is free software: you can redistribute it and/or modify it
6115 @c under the terms of the GNU General Public License as published by
6116 @c the Free Software Foundation, either version 3 of the License, or
6117 @c (at your option) any later version.
6119 @c This program is distributed in the hope that it will be useful, but
6120 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6121 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6122 @c General Public License for more details.
6124 @c You should have received a copy of the GNU General Public License
6125 @c along with this program. If not, see
6126 @c <http://www.gnu.org/licenses/>.
6128 @node Creating and using functions,Source Locations,Expressions,Topic Reference
6129 @anchor{topics/functions doc}@anchor{af}@anchor{topics/functions creating-and-using-functions}@anchor{b0}
6130 @section Creating and using functions
6141 @node Params,Functions,,Creating and using functions
6142 @anchor{topics/functions params}@anchor{b1}
6146 @geindex gcc_jit_param (C type)
6147 @anchor{topics/functions gcc_jit_param}@anchor{25}
6148 @deffn {C Type} gcc_jit_param
6150 A @cite{gcc_jit_param} represents a parameter to a function.
6153 @geindex gcc_jit_context_new_param (C function)
6154 @anchor{topics/functions gcc_jit_context_new_param}@anchor{10}
6155 @deffn {C Function} gcc_jit_param * gcc_jit_context_new_param (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, const char@w{ }*name)
6157 In preparation for creating a function, create a new parameter of the
6158 given type and name.
6161 Parameters are lvalues, and thus are also rvalues (and objects), so the
6162 following upcasts are available:
6164 @geindex gcc_jit_param_as_lvalue (C function)
6165 @anchor{topics/functions gcc_jit_param_as_lvalue}@anchor{b2}
6166 @deffn {C Function} gcc_jit_lvalue * gcc_jit_param_as_lvalue (gcc_jit_param@w{ }*param)
6168 Upcasting from param to lvalue.
6171 @geindex gcc_jit_param_as_rvalue (C function)
6172 @anchor{topics/functions gcc_jit_param_as_rvalue}@anchor{b3}
6173 @deffn {C Function} gcc_jit_rvalue * gcc_jit_param_as_rvalue (gcc_jit_param@w{ }*param)
6175 Upcasting from param to rvalue.
6178 @geindex gcc_jit_param_as_object (C function)
6179 @anchor{topics/functions gcc_jit_param_as_object}@anchor{b4}
6180 @deffn {C Function} gcc_jit_object * gcc_jit_param_as_object (gcc_jit_param@w{ }*param)
6182 Upcasting from param to object.
6185 @node Functions,Blocks,Params,Creating and using functions
6186 @anchor{topics/functions functions}@anchor{b5}
6187 @subsection Functions
6190 @geindex gcc_jit_function (C type)
6191 @anchor{topics/functions gcc_jit_function}@anchor{29}
6192 @deffn {C Type} gcc_jit_function
6194 A @cite{gcc_jit_function} represents a function - either one that we're
6195 creating ourselves, or one that we're referencing.
6198 @geindex gcc_jit_context_new_function (C function)
6199 @anchor{topics/functions gcc_jit_context_new_function}@anchor{11}
6200 @deffn {C Function} gcc_jit_function * gcc_jit_context_new_function (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, enum gcc_jit_function_kind@w{ }kind, gcc_jit_type@w{ }*return_type, const char@w{ }*name, int@w{ }num_params, gcc_jit_param@w{ }**params, int@w{ }is_variadic)
6202 Create a gcc_jit_function with the given name and parameters.
6204 @geindex gcc_jit_function_kind (C type)
6205 @anchor{topics/functions gcc_jit_function_kind}@anchor{b6}
6206 @deffn {C Type} enum gcc_jit_function_kind
6209 This enum controls the kind of function created, and has the following
6214 @geindex GCC_JIT_FUNCTION_EXPORTED (C macro)
6215 @anchor{topics/functions GCC_JIT_FUNCTION_EXPORTED}@anchor{b7}
6216 @deffn {C Macro} GCC_JIT_FUNCTION_EXPORTED
6218 Function is defined by the client code and visible
6219 by name outside of the JIT.
6221 This value is required if you want to extract machine code
6222 for this function from a @pxref{16,,gcc_jit_result} via
6223 @pxref{17,,gcc_jit_result_get_code()}.
6226 @geindex GCC_JIT_FUNCTION_INTERNAL (C macro)
6227 @anchor{topics/functions GCC_JIT_FUNCTION_INTERNAL}@anchor{b8}
6228 @deffn {C Macro} GCC_JIT_FUNCTION_INTERNAL
6230 Function is defined by the client code, but is invisible
6231 outside of the JIT. Analogous to a "static" function.
6234 @geindex GCC_JIT_FUNCTION_IMPORTED (C macro)
6235 @anchor{topics/functions GCC_JIT_FUNCTION_IMPORTED}@anchor{b9}
6236 @deffn {C Macro} GCC_JIT_FUNCTION_IMPORTED
6238 Function is not defined by the client code; we're merely
6239 referring to it. Analogous to using an "extern" function from a
6243 @geindex GCC_JIT_FUNCTION_ALWAYS_INLINE (C macro)
6244 @anchor{topics/functions GCC_JIT_FUNCTION_ALWAYS_INLINE}@anchor{ba}
6245 @deffn {C Macro} GCC_JIT_FUNCTION_ALWAYS_INLINE
6247 Function is only ever inlined into other functions, and is
6248 invisible outside of the JIT.
6250 Analogous to prefixing with @code{inline} and adding
6251 @code{__attribute__((always_inline))}
6253 Inlining will only occur when the optimization level is
6254 above 0; when optimization is off, this is essentially the
6255 same as GCC_JIT_FUNCTION_INTERNAL.
6260 @geindex gcc_jit_context_get_builtin_function (C function)
6261 @anchor{topics/functions gcc_jit_context_get_builtin_function}@anchor{bb}
6262 @deffn {C Function} gcc_jit_function *gcc_jit_context_get_builtin_function (gcc_jit_context@w{ }*ctxt, const char@w{ }*name)
6265 @geindex gcc_jit_function_as_object (C function)
6266 @anchor{topics/functions gcc_jit_function_as_object}@anchor{bc}
6267 @deffn {C Function} gcc_jit_object * gcc_jit_function_as_object (gcc_jit_function@w{ }*func)
6269 Upcasting from function to object.
6272 @geindex gcc_jit_function_get_param (C function)
6273 @anchor{topics/functions gcc_jit_function_get_param}@anchor{bd}
6274 @deffn {C Function} gcc_jit_param * gcc_jit_function_get_param (gcc_jit_function@w{ }*func, int@w{ }index)
6276 Get the param of the given index (0-based).
6279 @geindex gcc_jit_function_dump_to_dot (C function)
6280 @anchor{topics/functions gcc_jit_function_dump_to_dot}@anchor{33}
6281 @deffn {C Function} void gcc_jit_function_dump_to_dot (gcc_jit_function@w{ }*func, const char@w{ }*path)
6283 Emit the function in graphviz format to the given path.
6286 @geindex gcc_jit_function_new_local (C function)
6287 @anchor{topics/functions gcc_jit_function_new_local}@anchor{26}
6288 @deffn {C Function} gcc_jit_lvalue * gcc_jit_function_new_local (gcc_jit_function@w{ }*func, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, const char@w{ }*name)
6290 Create a new local variable within the function, of the given type and
6294 @node Blocks,Statements,Functions,Creating and using functions
6295 @anchor{topics/functions blocks}@anchor{be}
6299 @geindex gcc_jit_block (C type)
6300 @anchor{topics/functions gcc_jit_block}@anchor{28}
6301 @deffn {C Type} gcc_jit_block
6303 A @cite{gcc_jit_block} represents a basic block within a function i.e. a
6304 sequence of statements with a single entry point and a single exit
6307 The first basic block that you create within a function will
6310 Each basic block that you create within a function must be
6311 terminated, either with a conditional, a jump, or a return.
6313 It's legal to have multiple basic blocks that return within
6317 @geindex gcc_jit_function_new_block (C function)
6318 @anchor{topics/functions gcc_jit_function_new_block}@anchor{bf}
6319 @deffn {C Function} gcc_jit_block * gcc_jit_function_new_block (gcc_jit_function@w{ }*func, const char@w{ }*name)
6321 Create a basic block of the given name. The name may be NULL, but
6322 providing meaningful names is often helpful when debugging: it may
6323 show up in dumps of the internal representation, and in error
6327 @geindex gcc_jit_block_as_object (C function)
6328 @anchor{topics/functions gcc_jit_block_as_object}@anchor{c0}
6329 @deffn {C Function} gcc_jit_object * gcc_jit_block_as_object (gcc_jit_block@w{ }*block)
6331 Upcast from block to object.
6334 @geindex gcc_jit_block_get_function (C function)
6335 @anchor{topics/functions gcc_jit_block_get_function}@anchor{c1}
6336 @deffn {C Function} gcc_jit_function * gcc_jit_block_get_function (gcc_jit_block@w{ }*block)
6338 Which function is this block within?
6341 @node Statements,,Blocks,Creating and using functions
6342 @anchor{topics/functions statements}@anchor{c2}
6343 @subsection Statements
6346 @geindex gcc_jit_block_add_eval (C function)
6347 @anchor{topics/functions gcc_jit_block_add_eval}@anchor{9c}
6348 @deffn {C Function} void gcc_jit_block_add_eval (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*rvalue)
6350 Add evaluation of an rvalue, discarding the result
6351 (e.g. a function call that "returns" void).
6353 This is equivalent to this C code:
6362 @geindex gcc_jit_block_add_assignment (C function)
6363 @anchor{topics/functions gcc_jit_block_add_assignment}@anchor{2a}
6364 @deffn {C Function} void gcc_jit_block_add_assignment (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_lvalue@w{ }*lvalue, gcc_jit_rvalue@w{ }*rvalue)
6366 Add evaluation of an rvalue, assigning the result to the given
6369 This is roughly equivalent to this C code:
6378 @geindex gcc_jit_block_add_assignment_op (C function)
6379 @anchor{topics/functions gcc_jit_block_add_assignment_op}@anchor{2e}
6380 @deffn {C Function} void gcc_jit_block_add_assignment_op (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_lvalue@w{ }*lvalue, enum gcc_jit_binary_op@w{ }op, gcc_jit_rvalue@w{ }*rvalue)
6382 Add evaluation of an rvalue, using the result to modify an
6385 This is analogous to "+=" and friends:
6399 gcc_jit_block_add_assignment_op (
6402 GCC_JIT_BINARY_OP_PLUS,
6403 gcc_jit_context_one (ctxt, int_type));
6409 @geindex gcc_jit_block_add_comment (C function)
6410 @anchor{topics/functions gcc_jit_block_add_comment}@anchor{3d}
6411 @deffn {C Function} void gcc_jit_block_add_comment (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, const char@w{ }*text)
6413 Add a no-op textual comment to the internal representation of the
6414 code. It will be optimized away, but will be visible in the dumps
6415 seen via @pxref{5e,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}
6416 and @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE},
6417 and thus may be of use when debugging how your project's internal
6418 representation gets converted to the libgccjit IR.
6421 @geindex gcc_jit_block_end_with_conditional (C function)
6422 @anchor{topics/functions gcc_jit_block_end_with_conditional}@anchor{2d}
6423 @deffn {C Function} void gcc_jit_block_end_with_conditional (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*boolval, gcc_jit_block@w{ }*on_true, gcc_jit_block@w{ }*on_false)
6425 Terminate a block by adding evaluation of an rvalue, branching on the
6426 result to the appropriate successor block.
6428 This is roughly equivalent to this C code:
6439 block, boolval, on_true, and on_false must be non-NULL.
6442 @geindex gcc_jit_block_end_with_jump (C function)
6443 @anchor{topics/functions gcc_jit_block_end_with_jump}@anchor{c3}
6444 @deffn {C Function} void gcc_jit_block_end_with_jump (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_block@w{ }*target)
6446 Terminate a block by adding a jump to the given target block.
6448 This is roughly equivalent to this C code:
6457 @geindex gcc_jit_block_end_with_return (C function)
6458 @anchor{topics/functions gcc_jit_block_end_with_return}@anchor{c4}
6459 @deffn {C Function} void gcc_jit_block_end_with_return (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*rvalue)
6461 Terminate a block by adding evaluation of an rvalue, returning the value.
6463 This is roughly equivalent to this C code:
6472 @geindex gcc_jit_block_end_with_void_return (C function)
6473 @anchor{topics/functions gcc_jit_block_end_with_void_return}@anchor{c5}
6474 @deffn {C Function} void gcc_jit_block_end_with_void_return (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc)
6476 Terminate a block by adding a valueless return, for use within a function
6477 with "void" return type.
6479 This is equivalent to this C code:
6488 @c Copyright (C) 2014 Free Software Foundation, Inc.
6489 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
6491 @c This is free software: you can redistribute it and/or modify it
6492 @c under the terms of the GNU General Public License as published by
6493 @c the Free Software Foundation, either version 3 of the License, or
6494 @c (at your option) any later version.
6496 @c This program is distributed in the hope that it will be useful, but
6497 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6498 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6499 @c General Public License for more details.
6501 @c You should have received a copy of the GNU General Public License
6502 @c along with this program. If not, see
6503 @c <http://www.gnu.org/licenses/>.
6505 @node Source Locations,Compilation results,Creating and using functions,Topic Reference
6506 @anchor{topics/locations source-locations}@anchor{c6}@anchor{topics/locations doc}@anchor{c7}
6507 @section Source Locations
6510 @geindex gcc_jit_location (C type)
6511 @anchor{topics/locations gcc_jit_location}@anchor{3b}
6512 @deffn {C Type} gcc_jit_location
6514 A @cite{gcc_jit_location} encapsulates a source code location, so that
6515 you can (optionally) associate locations in your language with
6516 statements in the JIT-compiled code, allowing the debugger to
6517 single-step through your language.
6519 @cite{gcc_jit_location} instances are optional: you can always pass NULL to
6520 any API entrypoint accepting one.
6522 You can construct them using @pxref{41,,gcc_jit_context_new_location()}.
6524 You need to enable @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
6525 @pxref{8,,gcc_jit_context} for these locations to actually be usable by
6529 gcc_jit_context_set_bool_option (
6531 GCC_JIT_BOOL_OPTION_DEBUGINFO,
6538 @geindex gcc_jit_context_new_location (C function)
6539 @anchor{topics/locations gcc_jit_context_new_location}@anchor{41}
6540 @deffn {C Function} gcc_jit_location * gcc_jit_context_new_location (gcc_jit_context@w{ }*ctxt, const char@w{ }*filename, int@w{ }line, int@w{ }column)
6542 Create a @cite{gcc_jit_location} instance representing the given source
6551 @node Faking it,,,Source Locations
6552 @anchor{topics/locations faking-it}@anchor{c8}
6553 @subsection Faking it
6556 If you don't have source code for your internal representation, but need
6557 to debug, you can generate a C-like representation of the functions in
6558 your context using @pxref{53,,gcc_jit_context_dump_to_file()}:
6561 gcc_jit_context_dump_to_file (ctxt, "/tmp/something.c",
6562 1 /* update_locations */);
6567 This will dump C-like code to the given path. If the @cite{update_locations}
6568 argument is true, this will also set up @cite{gcc_jit_location} information
6569 throughout the context, pointing at the dump file as if it were a source
6570 file, giving you @emph{something} you can step through in the debugger.
6572 @c Copyright (C) 2014 Free Software Foundation, Inc.
6573 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
6575 @c This is free software: you can redistribute it and/or modify it
6576 @c under the terms of the GNU General Public License as published by
6577 @c the Free Software Foundation, either version 3 of the License, or
6578 @c (at your option) any later version.
6580 @c This program is distributed in the hope that it will be useful, but
6581 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6582 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6583 @c General Public License for more details.
6585 @c You should have received a copy of the GNU General Public License
6586 @c along with this program. If not, see
6587 @c <http://www.gnu.org/licenses/>.
6589 @node Compilation results,,Source Locations,Topic Reference
6590 @anchor{topics/results compilation-results}@anchor{c9}@anchor{topics/results doc}@anchor{ca}
6591 @section Compilation results
6594 @geindex gcc_jit_result (C type)
6595 @anchor{topics/results gcc_jit_result}@anchor{16}
6596 @deffn {C Type} gcc_jit_result
6598 A @cite{gcc_jit_result} encapsulates the result of compiling a context,
6599 and the lifetimes of any machine code functions or globals that are
6603 @geindex gcc_jit_context_compile (C function)
6604 @anchor{topics/results gcc_jit_context_compile}@anchor{15}
6605 @deffn {C Function} gcc_jit_result * gcc_jit_context_compile (gcc_jit_context@w{ }*ctxt)
6607 This calls into GCC and builds the code, returning a
6608 @cite{gcc_jit_result *}.
6610 If this is non-NULL, the caller becomes responsible for
6611 calling @pxref{39,,gcc_jit_result_release()} on it once they're done
6615 @geindex gcc_jit_result_get_code (C function)
6616 @anchor{topics/results gcc_jit_result_get_code}@anchor{17}
6617 @deffn {C Function} void * gcc_jit_result_get_code (gcc_jit_result@w{ }*result, const char@w{ }*funcname)
6619 Locate a given function within the built machine code.
6621 Functions are looked up by name. For this to succeed, a function
6622 with a name matching @cite{funcname} must have been created on
6623 @cite{result}'s context (or a parent context) via a call to
6624 @pxref{11,,gcc_jit_context_new_function()} with @cite{kind}
6625 @pxref{b7,,GCC_JIT_FUNCTION_EXPORTED}:
6628 gcc_jit_context_new_function (ctxt,
6629 any_location, /* or NULL */
6630 /* Required for func to be visible to
6631 gcc_jit_result_get_code: */
6632 GCC_JIT_FUNCTION_EXPORTED,
6634 /* Must string-compare equal: */
6641 If such a function is not found (or @cite{result} or @cite{funcname} are
6642 @code{NULL}), an error message will be emitted on stderr and
6643 @code{NULL} will be returned.
6645 If the function is found, the result will need to be cast to a
6646 function pointer of the correct type before it can be called.
6648 Note that the resulting machine code becomes invalid after
6649 @pxref{39,,gcc_jit_result_release()} is called on the
6650 @pxref{16,,gcc_jit_result *}; attempting to call it after that may lead
6651 to a segmentation fault.
6654 @geindex gcc_jit_result_get_global (C function)
6655 @anchor{topics/results gcc_jit_result_get_global}@anchor{a7}
6656 @deffn {C Function} void * gcc_jit_result_get_global (gcc_jit_result@w{ }*result, const char@w{ }*name)
6658 Locate a given global within the built machine code.
6660 Globals are looked up by name. For this to succeed, a global
6661 with a name matching @cite{name} must have been created on
6662 @cite{result}'s context (or a parent context) via a call to
6663 @pxref{a4,,gcc_jit_context_new_global()} with @cite{kind}
6664 @pxref{a6,,GCC_JIT_GLOBAL_EXPORTED}.
6666 If the global is found, the result will need to be cast to a
6667 pointer of the correct type before it can be called.
6669 This is a @emph{pointer} to the global, so e.g. for an @code{int} this is
6672 For example, given an @code{int foo;} created this way:
6675 gcc_jit_lvalue *exported_global =
6676 gcc_jit_context_new_global (ctxt,
6677 any_location, /* or NULL */
6678 GCC_JIT_GLOBAL_EXPORTED,
6685 we can access it like this:
6689 (int *)gcc_jit_result_get_global (result, "foo");
6694 If such a global is not found (or @cite{result} or @cite{name} are
6695 @code{NULL}), an error message will be emitted on stderr and
6696 @code{NULL} will be returned.
6698 Note that the resulting address becomes invalid after
6699 @pxref{39,,gcc_jit_result_release()} is called on the
6700 @pxref{16,,gcc_jit_result *}; attempting to use it after that may lead
6701 to a segmentation fault.
6704 @geindex gcc_jit_result_release (C function)
6705 @anchor{topics/results gcc_jit_result_release}@anchor{39}
6706 @deffn {C Function} void gcc_jit_result_release (gcc_jit_result@w{ }*result)
6708 Once we're done with the code, this unloads the built .so file.
6709 This cleans up the result; after calling this, it's no longer
6710 valid to use the result, or any code or globals that were obtained
6711 by calling @pxref{17,,gcc_jit_result_get_code()} or
6712 @pxref{a7,,gcc_jit_result_get_global()} on it.
6715 @c Copyright (C) 2014 Free Software Foundation, Inc.
6716 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
6718 @c This is free software: you can redistribute it and/or modify it
6719 @c under the terms of the GNU General Public License as published by
6720 @c the Free Software Foundation, either version 3 of the License, or
6721 @c (at your option) any later version.
6723 @c This program is distributed in the hope that it will be useful, but
6724 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6725 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6726 @c General Public License for more details.
6728 @c You should have received a copy of the GNU General Public License
6729 @c along with this program. If not, see
6730 @c <http://www.gnu.org/licenses/>.
6732 @node C++ bindings for libgccjit,Internals,Topic Reference,Top
6733 @anchor{cp/index c-bindings-for-libgccjit}@anchor{cb}@anchor{cp/index doc}@anchor{cc}
6734 @chapter C++ bindings for libgccjit
6737 This document describes the C++ bindings to
6738 libgccjit@footnote{http://gcc.gnu.org/wiki/JIT}, an API for embedding GCC
6739 inside programs and libraries.
6741 The C++ bindings consist of a single header file @code{libgccjit++.h}.
6743 This is a collection of "thin" wrapper classes around the C API.
6744 Everything is an inline function, implemented in terms of the C API,
6745 so there is nothing extra to link against.
6747 Note that libgccjit is currently of "Alpha" quality;
6748 the APIs are not yet set in stone, and they shouldn't be used in
6753 @c Copyright (C) 2014 Free Software Foundation, Inc.
6754 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
6756 @c This is free software: you can redistribute it and/or modify it
6757 @c under the terms of the GNU General Public License as published by
6758 @c the Free Software Foundation, either version 3 of the License, or
6759 @c (at your option) any later version.
6761 @c This program is distributed in the hope that it will be useful, but
6762 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6763 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6764 @c General Public License for more details.
6766 @c You should have received a copy of the GNU General Public License
6767 @c along with this program. If not, see
6768 @c <http://www.gnu.org/licenses/>.
6771 * Tutorial: Tutorial<2>.
6772 * Topic Reference: Topic Reference<2>.
6776 * Tutorial part 1; "Hello world": Tutorial part 1 "Hello world"<2>.
6777 * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>.
6778 * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>.
6779 * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>.
6781 Tutorial part 2: Creating a trivial machine code function
6783 * Options: Options<3>.
6784 * Full example: Full example<3>.
6786 Tutorial part 3: Loops and variables
6788 * Expressions; lvalues and rvalues: Expressions lvalues and rvalues<2>.
6789 * Control flow: Control flow<2>.
6790 * Visualizing the control flow graph: Visualizing the control flow graph<2>.
6791 * Full example: Full example<4>.
6793 Tutorial part 4: Adding JIT-compilation to a toy interpreter
6795 * Our toy interpreter: Our toy interpreter<2>.
6796 * Compiling to machine code: Compiling to machine code<2>.
6797 * Setting things up: Setting things up<2>.
6798 * Populating the function: Populating the function<2>.
6799 * Verifying the control flow graph: Verifying the control flow graph<2>.
6800 * Compiling the context: Compiling the context<2>.
6801 * Single-stepping through the generated code: Single-stepping through the generated code<2>.
6802 * Examining the generated code: Examining the generated code<2>.
6803 * Putting it all together: Putting it all together<2>.
6804 * Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?<2>.
6806 Behind the curtain: How does our code get optimized?
6808 * Optimizing away stack manipulation: Optimizing away stack manipulation<2>.
6809 * Elimination of tail recursion: Elimination of tail recursion<2>.
6813 * Compilation contexts: Compilation contexts<2>.
6814 * Objects: Objects<2>.
6816 * Expressions: Expressions<2>.
6817 * Creating and using functions: Creating and using functions<2>.
6818 * Source Locations: Source Locations<2>.
6819 * Compilation results: Compilation results<2>.
6821 Compilation contexts
6823 * Lifetime-management: Lifetime-management<2>.
6824 * Thread-safety: Thread-safety<2>.
6825 * Error-handling: Error-handling<3>.
6826 * Debugging: Debugging<2>.
6827 * Options: Options<4>.
6831 * String Options: String Options<2>.
6832 * Boolean options: Boolean options<2>.
6833 * Integer options: Integer options<2>.
6837 * Standard types: Standard types<2>.
6838 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
6839 * Structures and unions: Structures and unions<2>.
6843 * Rvalues: Rvalues<2>.
6844 * Lvalues: Lvalues<2>.
6845 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
6849 * Simple expressions: Simple expressions<2>.
6850 * Unary Operations: Unary Operations<2>.
6851 * Binary Operations: Binary Operations<2>.
6852 * Comparisons: Comparisons<2>.
6853 * Function calls: Function calls<2>.
6854 * Type-coercion: Type-coercion<2>.
6858 * Global variables: Global variables<2>.
6860 Creating and using functions
6862 * Params: Params<2>.
6863 * Functions: Functions<2>.
6864 * Blocks: Blocks<2>.
6865 * Statements: Statements<2>.
6869 * Faking it: Faking it<2>.
6874 @node Tutorial<2>,Topic Reference<2>,,C++ bindings for libgccjit
6875 @anchor{cp/intro/index doc}@anchor{cd}@anchor{cp/intro/index tutorial}@anchor{ce}
6879 @c Copyright (C) 2014 Free Software Foundation, Inc.
6880 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
6882 @c This is free software: you can redistribute it and/or modify it
6883 @c under the terms of the GNU General Public License as published by
6884 @c the Free Software Foundation, either version 3 of the License, or
6885 @c (at your option) any later version.
6887 @c This program is distributed in the hope that it will be useful, but
6888 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6889 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6890 @c General Public License for more details.
6892 @c You should have received a copy of the GNU General Public License
6893 @c along with this program. If not, see
6894 @c <http://www.gnu.org/licenses/>.
6897 * Tutorial part 1; "Hello world": Tutorial part 1 "Hello world"<2>.
6898 * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>.
6899 * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>.
6900 * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>.
6904 @node Tutorial part 1 "Hello world"<2>,Tutorial part 2 Creating a trivial machine code function<2>,,Tutorial<2>
6905 @anchor{cp/intro/tutorial01 doc}@anchor{cf}@anchor{cp/intro/tutorial01 tutorial-part-1-hello-world}@anchor{d0}
6906 @subsection Tutorial part 1: "Hello world"
6909 Before we look at the details of the API, let's look at building and
6910 running programs that use the library.
6912 Here's a toy "hello world" program that uses the library's C++ API to
6913 synthesize a call to @cite{printf} and uses it to write a message to stdout.
6915 Don't worry about the content of the program for now; we'll cover
6916 the details in later parts of this tutorial.
6921 /* Smoketest example for libgccjit.so C++ API
6922 Copyright (C) 2014 Free Software Foundation, Inc.
6924 This file is part of GCC.
6926 GCC is free software; you can redistribute it and/or modify it
6927 under the terms of the GNU General Public License as published by
6928 the Free Software Foundation; either version 3, or (at your option)
6931 GCC is distributed in the hope that it will be useful, but
6932 WITHOUT ANY WARRANTY; without even the implied warranty of
6933 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6934 General Public License for more details.
6936 You should have received a copy of the GNU General Public License
6937 along with GCC; see the file COPYING3. If not see
6938 <http://www.gnu.org/licenses/>. */
6940 #include <libgccjit++.h>
6946 create_code (gccjit::context ctxt)
6948 /* Let's try to inject the equivalent of this C code:
6950 greet (const char *name)
6952 printf ("hello %s\n", name);
6955 gccjit::type void_type = ctxt.get_type (GCC_JIT_TYPE_VOID);
6956 gccjit::type const_char_ptr_type =
6957 ctxt.get_type (GCC_JIT_TYPE_CONST_CHAR_PTR);
6958 gccjit::param param_name =
6959 ctxt.new_param (const_char_ptr_type, "name");
6960 std::vector<gccjit::param> func_params;
6961 func_params.push_back (param_name);
6962 gccjit::function func =
6963 ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
6968 gccjit::param param_format =
6969 ctxt.new_param (const_char_ptr_type, "format");
6970 std::vector<gccjit::param> printf_params;
6971 printf_params.push_back (param_format);
6972 gccjit::function printf_func =
6973 ctxt.new_function (GCC_JIT_FUNCTION_IMPORTED,
6974 ctxt.get_type (GCC_JIT_TYPE_INT),
6978 gccjit::block block = func.new_block ();
6979 block.add_eval (ctxt.new_call (printf_func,
6980 ctxt.new_rvalue ("hello %s\n"),
6982 block.end_with_return ();
6986 main (int argc, char **argv)
6988 gccjit::context ctxt;
6989 gcc_jit_result *result;
6991 /* Get a "context" object for working with the library. */
6992 ctxt = gccjit::context::acquire ();
6994 /* Set some options on the context.
6995 Turn this on to see the code being generated, in assembler form. */
6996 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 0);
6998 /* Populate the context. */
7001 /* Compile the code. */
7002 result = ctxt.compile ();
7005 fprintf (stderr, "NULL result");
7011 /* Extract the generated code from "result". */
7012 typedef void (*fn_type) (const char *);
7014 (fn_type)gcc_jit_result_get_code (result, "greet");
7017 fprintf (stderr, "NULL greet");
7021 /* Now call the generated function: */
7025 gcc_jit_result_release (result);
7034 Copy the above to @cite{tut01-hello-world.cc}.
7036 Assuming you have the jit library installed, build the test program
7041 tut01-hello-world.cc \
7042 -o tut01-hello-world \
7048 You should then be able to run the built program:
7051 $ ./tut01-hello-world
7057 @c Copyright (C) 2014 Free Software Foundation, Inc.
7058 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
7060 @c This is free software: you can redistribute it and/or modify it
7061 @c under the terms of the GNU General Public License as published by
7062 @c the Free Software Foundation, either version 3 of the License, or
7063 @c (at your option) any later version.
7065 @c This program is distributed in the hope that it will be useful, but
7066 @c WITHOUT ANY WARRANTY; without even the implied warranty of
7067 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
7068 @c General Public License for more details.
7070 @c You should have received a copy of the GNU General Public License
7071 @c along with this program. If not, see
7072 @c <http://www.gnu.org/licenses/>.
7074 @node Tutorial part 2 Creating a trivial machine code function<2>,Tutorial part 3 Loops and variables<2>,Tutorial part 1 "Hello world"<2>,Tutorial<2>
7075 @anchor{cp/intro/tutorial02 doc}@anchor{d1}@anchor{cp/intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{d2}
7076 @subsection Tutorial part 2: Creating a trivial machine code function
7079 Consider this C function:
7090 How can we construct this at run-time using libgccjit's C++ API?
7092 First we need to include the relevant header:
7095 #include <libgccjit++.h>
7100 All state associated with compilation is associated with a
7101 @code{gccjit::context}, which is a thin C++ wrapper around the C API's
7102 @pxref{8,,gcc_jit_context *}.
7104 Create one using @pxref{d3,,gccjit;;context;;acquire()}:
7107 gccjit::context ctxt;
7108 ctxt = gccjit::context::acquire ();
7113 The JIT library has a system of types. It is statically-typed: every
7114 expression is of a specific type, fixed at compile-time. In our example,
7115 all of the expressions are of the C @cite{int} type, so let's obtain this from
7116 the context, as a @code{gccjit::type}, using
7117 @pxref{d4,,gccjit;;context;;get_type()}:
7120 gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
7125 @code{gccjit::type} is an example of a "contextual" object: every
7126 entity in the API is associated with a @code{gccjit::context}.
7128 Memory management is easy: all such "contextual" objects are automatically
7129 cleaned up for you when the context is released, using
7130 @pxref{d5,,gccjit;;context;;release()}:
7138 so you don't need to manually track and cleanup all objects, just the
7141 All of the C++ classes in the API are thin wrappers around pointers to
7144 The C++ class hierarchy within the @code{gccjit} namespace looks like this:
7161 One thing you can do with a @code{gccjit::object} is
7162 to ask it for a human-readable description as a @code{std::string}, using
7163 @pxref{d6,,gccjit;;object;;get_debug_string()}:
7166 printf ("obj: %s\n", obj.get_debug_string ().c_str ());
7171 giving this text on stdout:
7179 This is invaluable when debugging.
7181 Let's create the function. To do so, we first need to construct
7182 its single parameter, specifying its type and giving it a name,
7183 using @pxref{d7,,gccjit;;context;;new_param()}:
7186 gccjit::param param_i = ctxt.new_param (int_type, "i");
7191 and we can then make a vector of all of the params of the function,
7192 in this case just one:
7195 std::vector<gccjit::param> params;
7196 params.push_back (param_i);
7201 Now we can create the function, using
7202 @code{gccjit::context::new_function()}:
7205 gccjit::function func =
7206 ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
7215 To define the code within the function, we must create basic blocks
7216 containing statements.
7218 Every basic block contains a list of statements, eventually terminated
7219 by a statement that either returns, or jumps to another basic block.
7221 Our function has no control-flow, so we just need one basic block:
7224 gccjit::block block = func.new_block ();
7229 Our basic block is relatively simple: it immediately terminates by
7230 returning the value of an expression.
7232 We can build the expression using @pxref{d8,,gccjit;;context;;new_binary_op()}:
7235 gccjit::rvalue expr =
7236 ctxt.new_binary_op (
7237 GCC_JIT_BINARY_OP_MULT, int_type,
7243 A @code{gccjit::rvalue} is another example of a
7244 @code{gccjit::object} subclass. As before, we can print it with
7245 @pxref{d6,,gccjit;;object;;get_debug_string()}.
7248 printf ("expr: %s\n", expr.get_debug_string ().c_str ());
7261 Note that @code{gccjit::rvalue} provides numerous overloaded operators
7262 which can be used to dramatically reduce the amount of typing needed.
7263 We can build the above binary operation more directly with this one-liner:
7266 gccjit::rvalue expr = param_i * param_i;
7271 Creating the expression in itself doesn't do anything; we have to add
7272 this expression to a statement within the block. In this case, we use it
7273 to build a return statement, which terminates the basic block:
7276 block.end_with_return (expr);
7281 OK, we've populated the context. We can now compile it using
7282 @pxref{d9,,gccjit;;context;;compile()}:
7285 gcc_jit_result *result;
7286 result = ctxt.compile ();
7291 and get a @pxref{16,,gcc_jit_result *}.
7293 We can now use @pxref{17,,gcc_jit_result_get_code()} to look up a specific
7294 machine code routine within the result, in this case, the function we
7298 void *fn_ptr = gcc_jit_result_get_code (result, "square");
7301 fprintf (stderr, "NULL fn_ptr");
7308 We can now cast the pointer to an appropriate function pointer type, and
7312 typedef int (*fn_type) (int);
7313 fn_type square = (fn_type)fn_ptr;
7314 printf ("result: %d", square (5));
7326 * Options: Options<3>.
7327 * Full example: Full example<3>.
7331 @node Options<3>,Full example<3>,,Tutorial part 2 Creating a trivial machine code function<2>
7332 @anchor{cp/intro/tutorial02 options}@anchor{da}
7333 @subsubsection Options
7336 To get more information on what's going on, you can set debugging flags
7337 on the context using @pxref{db,,gccjit;;context;;set_bool_option()}.
7339 @c (I'm deliberately not mentioning
7340 @c :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE` here since I think
7341 @c it's probably more of use to implementors than to users)
7343 Setting @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE} will dump a
7344 C-like representation to stderr when you compile (GCC's "GIMPLE"
7348 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1);
7349 result = ctxt.compile ();
7355 square (signed int i)
7367 We can see the generated machine code in assembler form (on stderr) by
7368 setting @pxref{1d,,GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE} on the context
7372 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 1);
7373 result = ctxt.compile ();
7382 .type square, @@function
7387 .cfi_def_cfa_offset 16
7390 .cfi_def_cfa_register 6
7394 imull -4(%rbp), %eax
7400 .size square, .-square
7401 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
7402 .section .note.GNU-stack,"",@@progbits
7407 By default, no optimizations are performed, the equivalent of GCC's
7408 @cite{-O0} option. We can turn things up to e.g. @cite{-O3} by calling
7409 @pxref{dc,,gccjit;;context;;set_int_option()} with
7410 @pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
7413 ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3);
7423 .type square, @@function
7433 .size square, .-square
7434 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
7435 .section .note.GNU-stack,"",@@progbits
7440 Naturally this has only a small effect on such a trivial function.
7442 @node Full example<3>,,Options<3>,Tutorial part 2 Creating a trivial machine code function<2>
7443 @anchor{cp/intro/tutorial02 full-example}@anchor{dd}
7444 @subsubsection Full example
7447 Here's what the above looks like as a complete program:
7452 /* Usage example for libgccjit.so's C++ API
7453 Copyright (C) 2014 Free Software Foundation, Inc.
7455 This file is part of GCC.
7457 GCC is free software; you can redistribute it and/or modify it
7458 under the terms of the GNU General Public License as published by
7459 the Free Software Foundation; either version 3, or (at your option)
7462 GCC is distributed in the hope that it will be useful, but
7463 WITHOUT ANY WARRANTY; without even the implied warranty of
7464 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
7465 General Public License for more details.
7467 You should have received a copy of the GNU General Public License
7468 along with GCC; see the file COPYING3. If not see
7469 <http://www.gnu.org/licenses/>. */
7471 #include <libgccjit++.h>
7477 create_code (gccjit::context ctxt)
7479 /* Let's try to inject the equivalent of this C code:
7486 gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
7487 gccjit::param param_i = ctxt.new_param (int_type, "i");
7488 std::vector<gccjit::param> params;
7489 params.push_back (param_i);
7490 gccjit::function func = ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
7495 gccjit::block block = func.new_block ();
7497 gccjit::rvalue expr =
7498 ctxt.new_binary_op (GCC_JIT_BINARY_OP_MULT, int_type,
7501 block.end_with_return (expr);
7505 main (int argc, char **argv)
7507 /* Get a "context" object for working with the library. */
7508 gccjit::context ctxt = gccjit::context::acquire ();
7510 /* Set some options on the context.
7511 Turn this on to see the code being generated, in assembler form. */
7512 ctxt.set_bool_option (
7513 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
7516 /* Populate the context. */
7519 /* Compile the code. */
7520 gcc_jit_result *result = ctxt.compile ();
7522 /* We're done with the context; we can release it: */
7527 fprintf (stderr, "NULL result");
7531 /* Extract the generated code from "result". */
7532 void *fn_ptr = gcc_jit_result_get_code (result, "square");
7535 fprintf (stderr, "NULL fn_ptr");
7536 gcc_jit_result_release (result);
7540 typedef int (*fn_type) (int);
7541 fn_type square = (fn_type)fn_ptr;
7542 printf ("result: %d\n", square (5));
7544 gcc_jit_result_release (result);
7553 Building and running it:
7561 # Run the built program:
7568 @c Copyright (C) 2014 Free Software Foundation, Inc.
7569 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
7571 @c This is free software: you can redistribute it and/or modify it
7572 @c under the terms of the GNU General Public License as published by
7573 @c the Free Software Foundation, either version 3 of the License, or
7574 @c (at your option) any later version.
7576 @c This program is distributed in the hope that it will be useful, but
7577 @c WITHOUT ANY WARRANTY; without even the implied warranty of
7578 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
7579 @c General Public License for more details.
7581 @c You should have received a copy of the GNU General Public License
7582 @c along with this program. If not, see
7583 @c <http://www.gnu.org/licenses/>.
7585 @node Tutorial part 3 Loops and variables<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>,Tutorial part 2 Creating a trivial machine code function<2>,Tutorial<2>
7586 @anchor{cp/intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{de}@anchor{cp/intro/tutorial03 doc}@anchor{df}
7587 @subsection Tutorial part 3: Loops and variables
7590 Consider this C function:
7595 int loop_test (int n)
7598 for (int i = 0; i < n; i++)
7607 This example demonstrates some more features of libgccjit, with local
7608 variables and a loop.
7610 To break this down into libgccjit terms, it's usually easier to reword
7611 the @cite{for} loop as a @cite{while} loop, giving:
7616 int loop_test (int n)
7632 Here's what the final control flow graph will look like:
7639 @image{sum-of-squares,,,image of a control flow graph,png}
7645 As before, we include the libgccjit++ header and make a
7646 @code{gccjit::context}.
7649 #include <libgccjit++.h>
7653 gccjit::context ctxt;
7654 ctxt = gccjit::context::acquire ();
7659 The function works with the C @cite{int} type.
7661 In the previous tutorial we acquired this via
7664 gccjit::type the_type = ctxt.get_type (ctxt, GCC_JIT_TYPE_INT);
7669 though we could equally well make it work on, say, @cite{double}:
7672 gccjit::type the_type = ctxt.get_type (ctxt, GCC_JIT_TYPE_DOUBLE);
7677 For integer types we can use @code{gccjit::context::get_int_type}
7678 to directly bind a specific type:
7681 gccjit::type the_type = ctxt.get_int_type <int> ();
7686 Let's build the function:
7689 gcc_jit_param n = ctxt.new_param (the_type, "n");
7690 std::vector<gccjit::param> params;
7691 params.push_back (n);
7692 gccjit::function func =
7693 ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
7702 * Expressions; lvalues and rvalues: Expressions lvalues and rvalues<2>.
7703 * Control flow: Control flow<2>.
7704 * Visualizing the control flow graph: Visualizing the control flow graph<2>.
7705 * Full example: Full example<4>.
7709 @node Expressions lvalues and rvalues<2>,Control flow<2>,,Tutorial part 3 Loops and variables<2>
7710 @anchor{cp/intro/tutorial03 expressions-lvalues-and-rvalues}@anchor{e0}
7711 @subsubsection Expressions: lvalues and rvalues
7714 The base class of expression is the @code{gccjit::rvalue},
7715 representing an expression that can be on the @emph{right}-hand side of
7716 an assignment: a value that can be computed somehow, and assigned
7717 @emph{to} a storage area (such as a variable). It has a specific
7718 @code{gccjit::type}.
7720 Anothe important class is @code{gccjit::lvalue}.
7721 A @code{gccjit::lvalue}. is something that can of the @emph{left}-hand
7722 side of an assignment: a storage area (such as a variable).
7724 In other words, every assignment can be thought of as:
7732 Note that @code{gccjit::lvalue} is a subclass of
7733 @code{gccjit::rvalue}, where in an assignment of the form:
7736 LVALUE_A = LVALUE_B;
7741 the @cite{LVALUE_B} implies reading the current value of that storage
7742 area, assigning it into the @cite{LVALUE_A}.
7744 So far the only expressions we've seen are from the previous tutorial:
7750 the multiplication @cite{i * i}:
7756 gccjit::rvalue expr =
7757 ctxt.new_binary_op (
7758 GCC_JIT_BINARY_OP_MULT, int_type,
7761 /* Alternatively, using operator-overloading: */
7762 gccjit::rvalue expr = param_i * param_i;
7767 which is a @code{gccjit::rvalue}, and
7774 the various function parameters: @cite{param_i} and @cite{param_n}, instances of
7775 @code{gccjit::param}, which is a subclass of @code{gccjit::lvalue}
7776 (and, in turn, of @code{gccjit::rvalue}):
7777 we can both read from and write to function parameters within the
7781 Our new example has a new kind of expression: we have two local
7782 variables. We create them by calling
7783 @pxref{e1,,gccjit;;function;;new_local()}, supplying a type and a name:
7787 gccjit::lvalue i = func.new_local (the_type, "i");
7788 gccjit::lvalue sum = func.new_local (the_type, "sum");
7793 These are instances of @code{gccjit::lvalue} - they can be read from
7796 Note that there is no precanned way to create @emph{and} initialize a variable
7805 Instead, having added the local to the function, we have to separately add
7806 an assignment of @cite{0} to @cite{local_i} at the beginning of the function.
7808 @node Control flow<2>,Visualizing the control flow graph<2>,Expressions lvalues and rvalues<2>,Tutorial part 3 Loops and variables<2>
7809 @anchor{cp/intro/tutorial03 control-flow}@anchor{e2}
7810 @subsubsection Control flow
7813 This function has a loop, so we need to build some basic blocks to
7814 handle the control flow. In this case, we need 4 blocks:
7820 before the loop (initializing the locals)
7823 the conditional at the top of the loop (comparing @cite{i < n})
7826 the body of the loop
7829 after the loop terminates (@cite{return sum})
7832 so we create these as @code{gccjit::block} instances within the
7833 @code{gccjit::function}:
7836 gccjit::block b_initial = func.new_block ("initial");
7837 gccjit::block b_loop_cond = func.new_block ("loop_cond");
7838 gccjit::block b_loop_body = func.new_block ("loop_body");
7839 gccjit::block b_after_loop = func.new_block ("after_loop");
7844 We now populate each block with statements.
7846 The entry block @cite{b_initial} consists of initializations followed by a jump
7847 to the conditional. We assign @cite{0} to @cite{i} and to @cite{sum}, using
7848 @pxref{e3,,gccjit;;block;;add_assignment()} to add
7849 an assignment statement, and using @pxref{e4,,gccjit;;context;;zero()} to get
7850 the constant value @cite{0} for the relevant type for the right-hand side of
7855 b_initial.add_assignment (sum, ctxt.zero (the_type));
7858 b_initial.add_assignment (i, ctxt.zero (the_type));
7863 We can then terminate the entry block by jumping to the conditional:
7866 b_initial.end_with_jump (b_loop_cond);
7871 The conditional block is equivalent to the line @cite{while (i < n)} from our
7872 C example. It contains a single statement: a conditional, which jumps to
7873 one of two destination blocks depending on a boolean
7874 @code{gccjit::rvalue}, in this case the comparison of @cite{i} and @cite{n}.
7876 We could build the comparison using @pxref{e5,,gccjit;;context;;new_comparison()}:
7879 gccjit::rvalue guard =
7880 ctxt.new_comparison (GCC_JIT_COMPARISON_GE,
7886 and can then use this to add @cite{b_loop_cond}'s sole statement, via
7887 @pxref{e6,,gccjit;;block;;end_with_conditional()}:
7890 b_loop_cond.end_with_conditional (guard);
7895 However @code{gccjit::rvalue} has overloaded operators for this, so we
7896 express the conditional as
7899 gccjit::rvalue guard = (i >= n);
7904 and hence write the block more concisely as:
7907 b_loop_cond.end_with_conditional (
7915 Next, we populate the body of the loop.
7917 The C statement @cite{sum += i * i;} is an assignment operation, where an
7918 lvalue is modified "in-place". We use
7919 @pxref{e7,,gccjit;;block;;add_assignment_op()} to handle these operations:
7923 b_loop_body.add_assignment_op (sum,
7924 GCC_JIT_BINARY_OP_PLUS,
7930 The @cite{i++} can be thought of as @cite{i += 1}, and can thus be handled in
7931 a similar way. We use @pxref{2f,,gcc_jit_context_one()} to get the constant
7932 value @cite{1} (for the relevant type) for the right-hand side
7937 b_loop_body.add_assignment_op (i,
7938 GCC_JIT_BINARY_OP_PLUS,
7939 ctxt.one (the_type));
7946 For numeric constants other than 0 or 1, we could use
7947 @pxref{e8,,gccjit;;context;;new_rvalue()}, which has overloads
7948 for both @code{int} and @code{double}.
7952 The loop body completes by jumping back to the conditional:
7955 b_loop_body.end_with_jump (b_loop_cond);
7960 Finally, we populate the @cite{b_after_loop} block, reached when the loop
7961 conditional is false. We want to generate the equivalent of:
7969 so the block is just one statement:
7973 b_after_loop.end_with_return (sum);
7980 You can intermingle block creation with statement creation,
7981 but given that the terminator statements generally include references
7982 to other blocks, I find it's clearer to create all the blocks,
7983 @emph{then} all the statements.
7987 We've finished populating the function. As before, we can now compile it
7991 gcc_jit_result *result;
7992 result = ctxt.compile ();
7998 fprintf (stderr, "NULL result");
8002 typedef int (*loop_test_fn_type) (int);
8003 loop_test_fn_type loop_test =
8004 (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
8007 fprintf (stderr, "NULL loop_test");
8008 gcc_jit_result_release (result);
8011 printf ("result: %d", loop_test (10));
8022 @node Visualizing the control flow graph<2>,Full example<4>,Control flow<2>,Tutorial part 3 Loops and variables<2>
8023 @anchor{cp/intro/tutorial03 visualizing-the-control-flow-graph}@anchor{e9}
8024 @subsubsection Visualizing the control flow graph
8027 You can see the control flow graph of a function using
8028 @pxref{ea,,gccjit;;function;;dump_to_dot()}:
8031 func.dump_to_dot ("/tmp/sum-of-squares.dot");
8036 giving a .dot file in GraphViz format.
8038 You can convert this to an image using @cite{dot}:
8041 $ dot -Tpng /tmp/sum-of-squares.dot -o /tmp/sum-of-squares.png
8046 or use a viewer (my preferred one is xdot.py; see
8047 @indicateurl{https://github.com/jrfonseca/xdot.py}; on Fedora you can
8048 install it with @cite{yum install python-xdot}):
8055 @image{sum-of-squares,,,image of a control flow graph,png}
8061 @node Full example<4>,,Visualizing the control flow graph<2>,Tutorial part 3 Loops and variables<2>
8062 @anchor{cp/intro/tutorial03 full-example}@anchor{eb}
8063 @subsubsection Full example
8069 /* Usage example for libgccjit.so's C++ API
8070 Copyright (C) 2014 Free Software Foundation, Inc.
8072 This file is part of GCC.
8074 GCC is free software; you can redistribute it and/or modify it
8075 under the terms of the GNU General Public License as published by
8076 the Free Software Foundation; either version 3, or (at your option)
8079 GCC is distributed in the hope that it will be useful, but
8080 WITHOUT ANY WARRANTY; without even the implied warranty of
8081 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
8082 General Public License for more details.
8084 You should have received a copy of the GNU General Public License
8085 along with GCC; see the file COPYING3. If not see
8086 <http://www.gnu.org/licenses/>. */
8088 #include <libgccjit++.h>
8094 create_code (gccjit::context ctxt)
8097 Simple sum-of-squares, to test conditionals and looping
8099 int loop_test (int n)
8103 for (i = 0; i < n ; i ++)
8109 gccjit::type the_type = ctxt.get_int_type <int> ();
8110 gccjit::type return_type = the_type;
8112 gccjit::param n = ctxt.new_param (the_type, "n");
8113 std::vector<gccjit::param> params;
8114 params.push_back (n);
8115 gccjit::function func =
8116 ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
8122 gccjit::lvalue i = func.new_local (the_type, "i");
8123 gccjit::lvalue sum = func.new_local (the_type, "sum");
8125 gccjit::block b_initial = func.new_block ("initial");
8126 gccjit::block b_loop_cond = func.new_block ("loop_cond");
8127 gccjit::block b_loop_body = func.new_block ("loop_body");
8128 gccjit::block b_after_loop = func.new_block ("after_loop");
8131 b_initial.add_assignment (sum, ctxt.zero (the_type));
8134 b_initial.add_assignment (i, ctxt.zero (the_type));
8136 b_initial.end_with_jump (b_loop_cond);
8139 b_loop_cond.end_with_conditional (
8145 b_loop_body.add_assignment_op (sum,
8146 GCC_JIT_BINARY_OP_PLUS,
8150 b_loop_body.add_assignment_op (i,
8151 GCC_JIT_BINARY_OP_PLUS,
8152 ctxt.one (the_type));
8154 b_loop_body.end_with_jump (b_loop_cond);
8157 b_after_loop.end_with_return (sum);
8161 main (int argc, char **argv)
8163 gccjit::context ctxt;
8164 gcc_jit_result *result = NULL;
8166 /* Get a "context" object for working with the library. */
8167 ctxt = gccjit::context::acquire ();
8169 /* Set some options on the context.
8170 Turn this on to see the code being generated, in assembler form. */
8171 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
8174 /* Populate the context. */
8177 /* Compile the code. */
8178 result = ctxt.compile ();
8184 fprintf (stderr, "NULL result");
8188 /* Extract the generated code from "result". */
8189 typedef int (*loop_test_fn_type) (int);
8190 loop_test_fn_type loop_test =
8191 (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
8194 fprintf (stderr, "NULL loop_test");
8195 gcc_jit_result_release (result);
8199 /* Run the generated code. */
8200 int val = loop_test (10);
8201 printf("loop_test returned: %d\n", val);
8203 gcc_jit_result_release (result);
8212 Building and running it:
8216 tut03-sum-of-squares.cc \
8217 -o tut03-sum-of-squares \
8220 # Run the built program:
8221 $ ./tut03-sum-of-squares
8222 loop_test returned: 285
8227 @c Copyright (C) 2014 Free Software Foundation, Inc.
8228 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
8230 @c This is free software: you can redistribute it and/or modify it
8231 @c under the terms of the GNU General Public License as published by
8232 @c the Free Software Foundation, either version 3 of the License, or
8233 @c (at your option) any later version.
8235 @c This program is distributed in the hope that it will be useful, but
8236 @c WITHOUT ANY WARRANTY; without even the implied warranty of
8237 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
8238 @c General Public License for more details.
8240 @c You should have received a copy of the GNU General Public License
8241 @c along with this program. If not, see
8242 @c <http://www.gnu.org/licenses/>.
8244 @node Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>,,Tutorial part 3 Loops and variables<2>,Tutorial<2>
8245 @anchor{cp/intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{ec}@anchor{cp/intro/tutorial04 doc}@anchor{ed}
8246 @subsection Tutorial part 4: Adding JIT-compilation to a toy interpreter
8249 In this example we construct a "toy" interpreter, and add JIT-compilation
8253 * Our toy interpreter: Our toy interpreter<2>.
8254 * Compiling to machine code: Compiling to machine code<2>.
8255 * Setting things up: Setting things up<2>.
8256 * Populating the function: Populating the function<2>.
8257 * Verifying the control flow graph: Verifying the control flow graph<2>.
8258 * Compiling the context: Compiling the context<2>.
8259 * Single-stepping through the generated code: Single-stepping through the generated code<2>.
8260 * Examining the generated code: Examining the generated code<2>.
8261 * Putting it all together: Putting it all together<2>.
8262 * Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?<2>.
8266 @node Our toy interpreter<2>,Compiling to machine code<2>,,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
8267 @anchor{cp/intro/tutorial04 our-toy-interpreter}@anchor{ee}
8268 @subsubsection Our toy interpreter
8271 It's a stack-based interpreter, and is intended as a (very simple) example
8272 of the kind of bytecode interpreter seen in dynamic languages such as
8275 For the sake of simplicity, our toy virtual machine is very limited:
8283 The only data type is @cite{int}
8286 It can only work on one function at a time (so that the only
8287 function call that can be made is to recurse).
8290 Functions can only take one parameter.
8293 Functions have a stack of @cite{int} values.
8296 We'll implement function call within the interpreter by calling a
8297 function in our implementation, rather than implementing our own
8301 The parser is only good enough to get the examples to work.
8305 Naturally, a real interpreter would be much more complicated that this.
8307 The following operations are supported:
8310 @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx}
8333 Duplicate top of stack.
8349 Swap top two elements
8366 Add the top two elements
8383 Likewise, but subtract.
8399 Likewise, but multiply.
8416 elements on the stack
8417 and push a nonzero/zero
8434 Recurse, passing the top
8452 Return the top of the
8465 PUSH_CONST @cite{arg}
8481 JUMP_ABS_IF_TRUE @cite{arg}
8485 Pop; if top of stack was
8500 Programs can be interpreted, disassembled, and compiled to machine code.
8502 The interpreter reads @code{.toy} scripts. Here's what a simple recursive
8503 factorial program looks like, the script @code{factorial.toy}.
8504 The parser ignores lines beginning with a @cite{#}.
8509 # Simple recursive factorial implementation, roughly equivalent to:
8511 # int factorial (int arg)
8515 # return arg * factorial (arg - 1)
8527 # stack: [arg, arg, 2]
8531 # stack: [arg, (arg < 2)]
8543 # stack: [arg, arg, 1]
8547 # stack: [arg, (arg - 1)
8551 # stack: [arg, factorial(arg - 1)]
8555 # stack: [arg * factorial(arg - 1)]
8565 The interpreter is a simple infinite loop with a big @code{switch} statement
8566 based on what the next opcode is:
8573 toyvm_function::interpret (int arg, FILE *trace)
8576 #define PUSH(ARG) (frame.push (ARG))
8577 #define POP(ARG) (frame.pop ())
8579 frame.frm_function = this;
8581 frame.frm_cur_depth = 0;
8589 assert (frame.frm_pc < fn_num_ops);
8590 op = &fn_ops[frame.frm_pc++];
8594 frame.dump_stack (trace);
8595 disassemble_op (op, frame.frm_pc, trace);
8598 switch (op->op_opcode)
8600 /* Ops taking no operand. */
8620 case BINARY_SUBTRACT:
8632 case BINARY_COMPARE_LT:
8640 x = interpret (x, trace);
8647 /* Ops taking an operand. */
8649 PUSH (op->op_operand);
8652 case JUMP_ABS_IF_TRUE:
8655 frame.frm_pc = op->op_operand;
8659 assert (0); /* unknown opcode */
8661 @} /* end of switch on opcode */
8662 @} /* end of while loop */
8674 @node Compiling to machine code<2>,Setting things up<2>,Our toy interpreter<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
8675 @anchor{cp/intro/tutorial04 compiling-to-machine-code}@anchor{ef}
8676 @subsubsection Compiling to machine code
8679 We want to generate machine code that can be cast to this type and
8680 then directly executed in-process:
8685 typedef int (*toyvm_compiled_func) (int);
8693 Our compiler isn't very sophisticated; it takes the implementation of
8694 each opcode above, and maps it directly to the operations supported by
8697 How should we handle the stack? In theory we could calculate what the
8698 stack depth will be at each opcode, and optimize away the stack
8699 manipulation "by hand". We'll see below that libgccjit is able to do
8700 this for us, so we'll implement stack manipulation
8701 in a direct way, by creating a @code{stack} array and @code{stack_depth}
8702 variables, local within the generated function, equivalent to this C code:
8706 int stack[MAX_STACK_DEPTH];
8711 We'll also have local variables @code{x} and @code{y} for use when implementing
8712 the opcodes, equivalent to this:
8721 This means our compiler has the following state:
8727 toyvm_function &toyvmfn;
8729 gccjit::context ctxt;
8731 gccjit::type int_type;
8732 gccjit::type bool_type;
8733 gccjit::type stack_type; /* int[MAX_STACK_DEPTH] */
8735 gccjit::rvalue const_one;
8737 gccjit::function fn;
8738 gccjit::param param_arg;
8739 gccjit::lvalue stack;
8740 gccjit::lvalue stack_depth;
8744 gccjit::location op_locs[MAX_OPS];
8745 gccjit::block initial_block;
8746 gccjit::block op_blocks[MAX_OPS];
8754 @node Setting things up<2>,Populating the function<2>,Compiling to machine code<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
8755 @anchor{cp/intro/tutorial04 setting-things-up}@anchor{f0}
8756 @subsubsection Setting things up
8759 First we create our types:
8766 compilation_state::create_types ()
8769 int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
8770 bool_type = ctxt.get_type (GCC_JIT_TYPE_BOOL);
8771 stack_type = ctxt.new_array_type (int_type, MAX_STACK_DEPTH);
8779 along with extracting a useful @cite{int} constant:
8784 const_one = ctxt.one (int_type);
8794 We'll implement push and pop in terms of the @code{stack} array and
8795 @code{stack_depth}. Here are helper functions for adding statements to
8796 a block, implementing pushing and popping values:
8803 compilation_state::add_push (gccjit::block block,
8804 gccjit::rvalue rvalue,
8805 gccjit::location loc)
8807 /* stack[stack_depth] = RVALUE */
8808 block.add_assignment (
8809 /* stack[stack_depth] */
8810 ctxt.new_array_access (
8817 /* "stack_depth++;". */
8818 block.add_assignment_op (
8820 GCC_JIT_BINARY_OP_PLUS,
8826 compilation_state::add_pop (gccjit::block block,
8827 gccjit::lvalue lvalue,
8828 gccjit::location loc)
8830 /* "--stack_depth;". */
8831 block.add_assignment_op (
8833 GCC_JIT_BINARY_OP_MINUS,
8837 /* "LVALUE = stack[stack_depth];". */
8838 block.add_assignment (
8840 /* stack[stack_depth] */
8841 ctxt.new_array_access (stack,
8853 We will support single-stepping through the generated code in the
8854 debugger, so we need to create @code{gccjit::location} instances, one
8855 per operation in the source code. These will reference the lines of
8856 e.g. @code{factorial.toy}.
8863 compilation_state::create_locations ()
8865 for (int pc = 0; pc < toyvmfn.fn_num_ops; pc++)
8867 toyvm_op *op = &toyvmfn.fn_ops[pc];
8869 op_locs[pc] = ctxt.new_location (toyvmfn.fn_filename,
8881 Let's create the function itself. As usual, we create its parameter
8882 first, then use the parameter to create the function:
8889 compilation_state::create_function (const char *funcname)
8891 std::vector <gccjit::param> params;
8892 param_arg = ctxt.new_param (int_type, "arg", op_locs[0]);
8893 params.push_back (param_arg);
8894 fn = ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
8906 We create the locals within the function.
8911 stack = fn.new_local (stack_type, "stack");
8912 stack_depth = fn.new_local (int_type, "stack_depth");
8913 x = fn.new_local (int_type, "x");
8914 y = fn.new_local (int_type, "y");
8922 @node Populating the function<2>,Verifying the control flow graph<2>,Setting things up<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
8923 @anchor{cp/intro/tutorial04 populating-the-function}@anchor{f1}
8924 @subsubsection Populating the function
8927 There's some one-time initialization, and the API treats the first block
8928 you create as the entrypoint of the function, so we need to create that
8934 initial_block = fn.new_block ("initial");
8942 We can now create blocks for each of the operations. Most of these will
8943 be consolidated into larger blocks when the optimizer runs.
8948 for (int pc = 0; pc < toyvmfn.fn_num_ops; pc++)
8951 sprintf (buf, "instr%i", pc);
8952 op_blocks[pc] = fn.new_block (buf);
8961 Now that we have a block it can jump to when it's done, we can populate
8968 /* "stack_depth = 0;". */
8969 initial_block.add_assignment (stack_depth,
8970 ctxt.zero (int_type),
8973 /* "PUSH (arg);". */
8974 add_push (initial_block,
8978 /* ...and jump to insn 0. */
8979 initial_block.end_with_jump (op_blocks[0],
8988 We can now populate the blocks for the individual operations. We loop
8989 through them, adding instructions to their blocks:
8994 for (int pc = 0; pc < toyvmfn.fn_num_ops; pc++)
8996 gccjit::location loc = op_locs[pc];
8998 gccjit::block block = op_blocks[pc];
8999 gccjit::block next_block = (pc < toyvmfn.fn_num_ops
9004 op = &toyvmfn.fn_ops[pc];
9012 We're going to have another big @code{switch} statement for implementing
9013 the opcodes, this time for compiling them, rather than interpreting
9014 them. It's helpful to have macros for implementing push and pop, so that
9015 we can make the @code{switch} statement that's coming up look as much as
9016 possible like the one above within the interpreter:
9020 #define X_EQUALS_POP()\
9021 add_pop (block, x, loc)
9022 #define Y_EQUALS_POP()\
9023 add_pop (block, y, loc)
9024 #define PUSH_RVALUE(RVALUE)\
9025 add_push (block, (RVALUE), loc)
9038 A particularly clever implementation would have an @emph{identical}
9039 @code{switch} statement shared by the interpreter and the compiler, with
9040 some preprocessor "magic". We're not doing that here, for the sake
9045 When I first implemented this compiler, I accidentally missed an edit
9046 when copying and pasting the @code{Y_EQUALS_POP} macro, so that popping the
9047 stack into @code{y} instead erroneously assigned it to @code{x}, leaving @code{y}
9050 To track this kind of thing down, we can use
9051 @pxref{f2,,gccjit;;block;;add_comment()} to add descriptive comments
9052 to the internal representation. This is invaluable when looking through
9053 the generated IR for, say @code{factorial}:
9059 block.add_comment (opcode_names[op->op_opcode], loc);
9067 We can now write the big @code{switch} statement that implements the
9068 individual opcodes, populating the relevant block with statements:
9074 switch (op->op_opcode)
9093 ctxt.new_binary_op (
9094 GCC_JIT_BINARY_OP_PLUS,
9100 case BINARY_SUBTRACT:
9104 ctxt.new_binary_op (
9105 GCC_JIT_BINARY_OP_MINUS,
9115 ctxt.new_binary_op (
9116 GCC_JIT_BINARY_OP_MULT,
9122 case BINARY_COMPARE_LT:
9126 /* cast of bool to int */
9128 /* (x < y) as a bool */
9129 ctxt.new_comparison (
9130 GCC_JIT_COMPARISON_LT,
9150 block.end_with_return (x, loc);
9153 /* Ops taking an operand. */
9156 ctxt.new_rvalue (int_type, op->op_operand));
9159 case JUMP_ABS_IF_TRUE:
9161 block.end_with_conditional (
9163 ctxt.new_cast (x, bool_type, loc),
9164 op_blocks[op->op_operand], /* on_true */
9165 next_block, /* on_false */
9171 @} /* end of switch on opcode */
9179 Every block must be terminated, via a call to one of the
9180 @code{gccjit::block::end_with_} entrypoints. This has been done for two
9181 of the opcodes, but we need to do it for the other ones, by jumping
9187 if (op->op_opcode != JUMP_ABS_IF_TRUE
9188 && op->op_opcode != RETURN)
9189 block.end_with_jump (next_block, loc);
9197 This is analogous to simply incrementing the program counter.
9199 @node Verifying the control flow graph<2>,Compiling the context<2>,Populating the function<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
9200 @anchor{cp/intro/tutorial04 verifying-the-control-flow-graph}@anchor{f3}
9201 @subsubsection Verifying the control flow graph
9204 Having finished looping over the blocks, the context is complete.
9206 As before, we can verify that the control flow and statements are sane by
9207 using @pxref{ea,,gccjit;;function;;dump_to_dot()}:
9210 fn.dump_to_dot ("/tmp/factorial.dot");
9215 and viewing the result. Note how the label names, comments, and
9216 variable names show up in the dump, to make it easier to spot
9217 errors in our compiler.
9224 @image{factorial,,,image of a control flow graph,png}
9230 @node Compiling the context<2>,Single-stepping through the generated code<2>,Verifying the control flow graph<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
9231 @anchor{cp/intro/tutorial04 compiling-the-context}@anchor{f4}
9232 @subsubsection Compiling the context
9235 Having finished looping over the blocks and populating them with
9236 statements, the context is complete.
9238 We can now compile it, and extract machine code from the result:
9243 gcc_jit_result *result = state.compile ();
9245 return (toyvm_compiled_func)gcc_jit_result_get_code (result, funcname);
9252 We can now run the result:
9257 toyvm_compiled_func code = fn->compile ();
9258 printf ("compiler result: %d\n",
9259 code (atoi (argv[2])));
9267 @node Single-stepping through the generated code<2>,Examining the generated code<2>,Compiling the context<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
9268 @anchor{cp/intro/tutorial04 single-stepping-through-the-generated-code}@anchor{f5}
9269 @subsubsection Single-stepping through the generated code
9272 It's possible to debug the generated code. To do this we need to both:
9280 Set up source code locations for our statements, so that we can
9281 meaningfully step through the code. We did this above by
9282 calling @pxref{f6,,gccjit;;context;;new_location()} and using the
9286 Enable the generation of debugging information, by setting
9287 @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
9288 @code{gccjit::context} via
9289 @pxref{db,,gccjit;;context;;set_bool_option()}:
9292 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1);
9299 Having done this, we can put a breakpoint on the generated function:
9302 $ gdb --args ./toyvm factorial.toy 10
9303 (gdb) break factorial
9304 Function "factorial" not defined.
9305 Make breakpoint pending on future shared library load? (y or [n]) y
9306 Breakpoint 1 (factorial) pending.
9308 Breakpoint 1, factorial (arg=10) at factorial.toy:14
9314 We've set up location information, which references @code{factorial.toy}.
9315 This allows us to use e.g. @code{list} to see where we are in the script:
9325 15 # stack: [arg, arg]
9333 and to step through the function, examining the data:
9339 22 BINARY_COMPARE_LT
9341 $5 = @{10, 10, 2, 0, -7152, 32767, 0, 0@}
9342 (gdb) print stack_depth
9348 You'll see that the parts of the @code{stack} array that haven't been
9349 touched yet are uninitialized.
9353 Turning on optimizations may lead to unpredictable results when
9354 stepping through the generated code: the execution may appear to
9355 "jump around" the source code. This is analogous to turning up the
9356 optimization level in a regular compiler.
9360 @node Examining the generated code<2>,Putting it all together<2>,Single-stepping through the generated code<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
9361 @anchor{cp/intro/tutorial04 examining-the-generated-code}@anchor{f7}
9362 @subsubsection Examining the generated code
9365 How good is the optimized code?
9367 We can turn up optimizations, by calling
9368 @pxref{dc,,gccjit;;context;;set_int_option()} with
9369 @pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
9372 ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3);
9377 One of GCC's internal representations is called "gimple". A dump of the
9378 initial gimple representation of the code can be seen by setting:
9381 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1);
9386 With optimization on and source locations displayed, this gives:
9388 @c We'll use "c" for gimple dumps
9391 factorial (signed int arg)
9393 <unnamed type> D.80;
9401 signed int stack_depth;
9402 signed int stack[8];
9408 stack[stack_depth] = arg;
9409 stack_depth = stack_depth + 1;
9413 stack_depth = stack_depth + -1;
9414 x = stack[stack_depth];
9415 stack[stack_depth] = x;
9416 stack_depth = stack_depth + 1;
9417 stack[stack_depth] = x;
9418 stack_depth = stack_depth + 1;
9422 stack[stack_depth] = 2;
9423 stack_depth = stack_depth + 1;
9431 You can see the generated machine code in assembly form via:
9434 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 1);
9435 result = ctxt.compile ();
9440 which shows that (on this x86_64 box) the compiler has unrolled the loop
9441 and is using MMX instructions to perform several multiplications
9450 .type factorial, @@function
9453 .file 1 "factorial.toy"
9464 leal 0(,%rcx,4), %esi
9470 movl %eax, -16(%rsp)
9472 movd -16(%rsp), %xmm0
9473 movl %edi, -16(%rsp)
9474 movl %eax, -12(%rsp)
9475 movd -16(%rsp), %xmm1
9477 movl %edx, -16(%rsp)
9478 movd -12(%rsp), %xmm4
9479 movd -16(%rsp), %xmm6
9480 punpckldq %xmm4, %xmm0
9481 movdqa .LC1(%rip), %xmm4
9482 punpckldq %xmm6, %xmm1
9483 punpcklqdq %xmm0, %xmm1
9484 movdqa .LC0(%rip), %xmm0
9486 # etc - edited for brevity
9491 This is clearly overkill for a function that will likely overflow the
9492 @code{int} type before the vectorization is worthwhile - but then again, this
9495 Turning down the optimization level to 2:
9498 ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 2);
9503 yields this code, which is simple enough to quote in its entirety:
9510 .type factorial, @@function
9539 .size factorial, .-factorial
9540 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-%@{gcc_release@})"
9541 .section .note.GNU-stack,"",@@progbits
9546 Note that the stack pushing and popping have been eliminated, as has the
9547 recursive call (in favor of an iteration).
9549 @node Putting it all together<2>,Behind the curtain How does our code get optimized?<2>,Examining the generated code<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
9550 @anchor{cp/intro/tutorial04 putting-it-all-together}@anchor{f8}
9551 @subsubsection Putting it all together
9554 The complete example can be seen in the source tree at
9555 @code{gcc/jit/docs/examples/tut04-toyvm/toyvm.cc}
9557 along with a Makefile and a couple of sample .toy scripts:
9561 drwxrwxr-x. 2 david david 4096 Sep 19 17:46 .
9562 drwxrwxr-x. 3 david david 4096 Sep 19 15:26 ..
9563 -rw-rw-r--. 1 david david 615 Sep 19 12:43 factorial.toy
9564 -rw-rw-r--. 1 david david 834 Sep 19 13:08 fibonacci.toy
9565 -rw-rw-r--. 1 david david 238 Sep 19 14:22 Makefile
9566 -rw-rw-r--. 1 david david 16457 Sep 19 17:07 toyvm.cc
9569 g++ -Wall -g -o toyvm toyvm.cc -lgccjit
9571 $ ./toyvm factorial.toy 10
9572 interpreter result: 3628800
9573 compiler result: 3628800
9575 $ ./toyvm fibonacci.toy 10
9576 interpreter result: 55
9582 @node Behind the curtain How does our code get optimized?<2>,,Putting it all together<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
9583 @anchor{cp/intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{f9}
9584 @subsubsection Behind the curtain: How does our code get optimized?
9587 Our example is done, but you may be wondering about exactly how the
9588 compiler turned what we gave it into the machine code seen above.
9590 We can examine what the compiler is doing in detail by setting:
9593 state.ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING, 1);
9594 state.ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES, 1);
9599 This will dump detailed information about the compiler's state to a
9600 directory under @code{/tmp}, and keep it from being cleaned up.
9602 The precise names and their formats of these files is subject to change.
9603 Higher optimization levels lead to more files.
9604 Here's what I saw (edited for brevity; there were almost 200 files):
9607 intermediate files written to /tmp/libgccjit-KPQbGw
9608 $ ls /tmp/libgccjit-KPQbGw/
9610 fake.c.000i.type-inheritance
9612 fake.c.007t.omplower
9616 fake.c.014i.visibility
9617 fake.c.015i.early_local_cleanups
9624 The gimple code is converted into Static Single Assignment form,
9625 with annotations for use when generating the debuginfo:
9628 $ less /tmp/libgccjit-KPQbGw/fake.c.016t.ssa
9634 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
9636 factorial (signed int arg)
9638 signed int stack[8];
9639 signed int stack_depth;
9651 # DEBUG stack_depth => stack_depth_3
9652 stack[stack_depth_3] = arg_5(D);
9653 stack_depth_7 = stack_depth_3 + 1;
9654 # DEBUG stack_depth => stack_depth_7
9655 # DEBUG instr0 => NULL
9656 # DEBUG /* DUP */ => NULL
9657 stack_depth_8 = stack_depth_7 + -1;
9658 # DEBUG stack_depth => stack_depth_8
9659 x_9 = stack[stack_depth_8];
9661 stack[stack_depth_8] = x_9;
9662 stack_depth_11 = stack_depth_8 + 1;
9663 # DEBUG stack_depth => stack_depth_11
9664 stack[stack_depth_11] = x_9;
9665 stack_depth_13 = stack_depth_11 + 1;
9666 # DEBUG stack_depth => stack_depth_13
9667 # DEBUG instr1 => NULL
9668 # DEBUG /* PUSH_CONST */ => NULL
9669 stack[stack_depth_13] = 2;
9671 /* etc; edited for brevity */
9676 We can perhaps better see the code by turning off
9677 @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to suppress all those @code{DEBUG}
9681 $ less /tmp/libgccjit-1Hywc0/fake.c.016t.ssa
9687 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
9689 factorial (signed int arg)
9691 signed int stack[8];
9692 signed int stack_depth;
9704 stack[stack_depth_3] = arg_5(D);
9705 stack_depth_7 = stack_depth_3 + 1;
9706 stack_depth_8 = stack_depth_7 + -1;
9707 x_9 = stack[stack_depth_8];
9708 stack[stack_depth_8] = x_9;
9709 stack_depth_11 = stack_depth_8 + 1;
9710 stack[stack_depth_11] = x_9;
9711 stack_depth_13 = stack_depth_11 + 1;
9712 stack[stack_depth_13] = 2;
9713 stack_depth_15 = stack_depth_13 + 1;
9714 stack_depth_16 = stack_depth_15 + -1;
9715 y_17 = stack[stack_depth_16];
9716 stack_depth_18 = stack_depth_16 + -1;
9717 x_19 = stack[stack_depth_18];
9719 _21 = (signed int) _20;
9720 stack[stack_depth_18] = _21;
9721 stack_depth_23 = stack_depth_18 + 1;
9722 stack_depth_24 = stack_depth_23 + -1;
9723 x_25 = stack[stack_depth_24];
9725 goto <bb 4> (instr9);
9727 goto <bb 3> (instr4);
9731 stack_depth_26 = stack_depth_24 + -1;
9732 x_27 = stack[stack_depth_26];
9733 stack[stack_depth_26] = x_27;
9734 stack_depth_29 = stack_depth_26 + 1;
9735 stack[stack_depth_29] = x_27;
9736 stack_depth_31 = stack_depth_29 + 1;
9737 stack[stack_depth_31] = 1;
9738 stack_depth_33 = stack_depth_31 + 1;
9739 stack_depth_34 = stack_depth_33 + -1;
9740 y_35 = stack[stack_depth_34];
9741 stack_depth_36 = stack_depth_34 + -1;
9742 x_37 = stack[stack_depth_36];
9744 stack[stack_depth_36] = _38;
9745 stack_depth_40 = stack_depth_36 + 1;
9746 stack_depth_41 = stack_depth_40 + -1;
9747 x_42 = stack[stack_depth_41];
9748 _44 = factorial (x_42);
9749 stack[stack_depth_41] = _44;
9750 stack_depth_46 = stack_depth_41 + 1;
9751 stack_depth_47 = stack_depth_46 + -1;
9752 y_48 = stack[stack_depth_47];
9753 stack_depth_49 = stack_depth_47 + -1;
9754 x_50 = stack[stack_depth_49];
9756 stack[stack_depth_49] = _51;
9757 stack_depth_53 = stack_depth_49 + 1;
9759 # stack_depth_1 = PHI <stack_depth_24(2), stack_depth_53(3)>
9762 stack_depth_54 = stack_depth_1 + -1;
9763 x_55 = stack[stack_depth_54];
9765 stack =@{v@} @{CLOBBER@};
9773 Note in the above how all the @code{gccjit::block} instances we
9774 created have been consolidated into just 3 blocks in GCC's internal
9775 representation: @code{initial}, @code{instr4} and @code{instr9}.
9778 * Optimizing away stack manipulation: Optimizing away stack manipulation<2>.
9779 * Elimination of tail recursion: Elimination of tail recursion<2>.
9783 @node Optimizing away stack manipulation<2>,Elimination of tail recursion<2>,,Behind the curtain How does our code get optimized?<2>
9784 @anchor{cp/intro/tutorial04 optimizing-away-stack-manipulation}@anchor{fa}
9785 @subsubsection Optimizing away stack manipulation
9788 Recall our simple implementation of stack operations. Let's examine
9789 how the stack operations are optimized away.
9791 After a pass of constant-propagation, the depth of the stack at each
9792 opcode can be determined at compile-time:
9795 $ less /tmp/libgccjit-1Hywc0/fake.c.021t.ccp1
9801 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
9803 factorial (signed int arg)
9805 signed int stack[8];
9806 signed int stack_depth;
9816 stack[0] = arg_5(D);
9824 _21 = (signed int) _20;
9828 goto <bb 4> (instr9);
9830 goto <bb 3> (instr4);
9843 _44 = factorial (x_42);
9854 stack =@{v@} @{CLOBBER@};
9862 Note how, in the above, all those @code{stack_depth} values are now just
9863 constants: we're accessing specific stack locations at each opcode.
9865 The "esra" pass ("Early Scalar Replacement of Aggregates") breaks
9866 out our "stack" array into individual elements:
9869 $ less /tmp/libgccjit-1Hywc0/fake.c.024t.esra
9875 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
9877 Created a replacement for stack offset: 0, size: 32: stack$0
9878 Created a replacement for stack offset: 32, size: 32: stack$1
9879 Created a replacement for stack offset: 64, size: 32: stack$2
9881 Symbols to be put in SSA form
9882 @{ D.89 D.90 D.91 @}
9883 Incremental SSA update started at block: 0
9884 Number of blocks in CFG: 5
9885 Number of blocks to update: 4 ( 80%)
9888 factorial (signed int arg)
9893 signed int stack[8];
9894 signed int stack_depth;
9904 stack$0_45 = arg_5(D);
9912 _21 = (signed int) _20;
9916 goto <bb 4> (instr9);
9918 goto <bb 3> (instr4);
9931 _44 = factorial (x_42);
9938 # stack$0_52 = PHI <stack$0_39(2), stack$0_1(3)>
9943 stack =@{v@} @{CLOBBER@};
9951 Hence at this point, all those pushes and pops of the stack are now
9952 simply assignments to specific temporary variables.
9954 After some copy propagation, the stack manipulation has been completely
9958 $ less /tmp/libgccjit-1Hywc0/fake.c.026t.copyprop1
9964 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
9966 factorial (signed int arg)
9971 signed int stack[8];
9972 signed int stack_depth;
9982 stack$0_39 = arg_5(D);
9983 _20 = arg_5(D) <= 1;
9984 _21 = (signed int) _20;
9986 goto <bb 4> (instr9);
9988 goto <bb 3> (instr4);
9992 _38 = arg_5(D) + -1;
9993 _44 = factorial (_38);
9994 _51 = arg_5(D) * _44;
9997 # stack$0_52 = PHI <arg_5(D)(2), _51(3)>
10000 stack =@{v@} @{CLOBBER@};
10008 Later on, another pass finally eliminated @code{stack_depth} local and the
10009 unused parts of the @cite{stack`} array altogether:
10012 $ less /tmp/libgccjit-1Hywc0/fake.c.036t.release_ssa
10018 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
10020 Released 44 names, 314.29%, removed 44 holes
10021 factorial (signed int arg)
10023 signed int stack$0;
10024 signed int mult_acc_1;
10028 signed int mul_tmp_10;
10029 signed int mult_acc_11;
10030 signed int mult_acc_13;
10032 # arg_9 = PHI <arg_8(D)(0)>
10033 # mult_acc_13 = PHI <1(0)>
10037 # arg_4 = PHI <arg_9(2), _7(3)>
10038 # mult_acc_1 = PHI <mult_acc_13(2), mult_acc_11(3)>
10040 _6 = (signed int) _5;
10042 goto <bb 4> (instr9);
10044 goto <bb 3> (instr4);
10049 mult_acc_11 = mult_acc_1 * arg_4;
10052 # stack$0_12 = PHI <arg_4(5)>
10055 mul_tmp_10 = mult_acc_1 * stack$0_12;
10063 @node Elimination of tail recursion<2>,,Optimizing away stack manipulation<2>,Behind the curtain How does our code get optimized?<2>
10064 @anchor{cp/intro/tutorial04 elimination-of-tail-recursion}@anchor{fb}
10065 @subsubsection Elimination of tail recursion
10068 Another significant optimization is the detection that the call to
10069 @code{factorial} is tail recursion, which can be eliminated in favor of
10073 $ less /tmp/libgccjit-1Hywc0/fake.c.030t.tailr1
10079 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
10082 Symbols to be put in SSA form
10084 Incremental SSA update started at block: 0
10085 Number of blocks in CFG: 5
10086 Number of blocks to update: 4 ( 80%)
10089 factorial (signed int arg)
10091 signed int stack$2;
10092 signed int stack$1;
10093 signed int stack$0;
10094 signed int stack[8];
10095 signed int stack_depth;
10098 signed int mult_acc_1;
10099 <unnamed type> _20;
10102 signed int mul_tmp_44;
10103 signed int mult_acc_51;
10105 # arg_5 = PHI <arg_39(D)(0), _38(3)>
10106 # mult_acc_1 = PHI <1(0), mult_acc_51(3)>
10109 _21 = (signed int) _20;
10111 goto <bb 4> (instr9);
10113 goto <bb 3> (instr4);
10118 mult_acc_51 = mult_acc_1 * arg_5;
10119 goto <bb 2> (initial);
10121 # stack$0_52 = PHI <arg_5(2)>
10124 stack =@{v@} @{CLOBBER@};
10125 mul_tmp_44 = mult_acc_1 * stack$0_52;
10133 @c Copyright (C) 2014 Free Software Foundation, Inc.
10134 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
10136 @c This is free software: you can redistribute it and/or modify it
10137 @c under the terms of the GNU General Public License as published by
10138 @c the Free Software Foundation, either version 3 of the License, or
10139 @c (at your option) any later version.
10141 @c This program is distributed in the hope that it will be useful, but
10142 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10143 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10144 @c General Public License for more details.
10146 @c You should have received a copy of the GNU General Public License
10147 @c along with this program. If not, see
10148 @c <http://www.gnu.org/licenses/>.
10150 @node Topic Reference<2>,,Tutorial<2>,C++ bindings for libgccjit
10151 @anchor{cp/topics/index doc}@anchor{fc}@anchor{cp/topics/index topic-reference}@anchor{fd}
10152 @section Topic Reference
10155 @c Copyright (C) 2014 Free Software Foundation, Inc.
10156 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
10158 @c This is free software: you can redistribute it and/or modify it
10159 @c under the terms of the GNU General Public License as published by
10160 @c the Free Software Foundation, either version 3 of the License, or
10161 @c (at your option) any later version.
10163 @c This program is distributed in the hope that it will be useful, but
10164 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10165 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10166 @c General Public License for more details.
10168 @c You should have received a copy of the GNU General Public License
10169 @c along with this program. If not, see
10170 @c <http://www.gnu.org/licenses/>.
10173 * Compilation contexts: Compilation contexts<2>.
10174 * Objects: Objects<2>.
10176 * Expressions: Expressions<2>.
10177 * Creating and using functions: Creating and using functions<2>.
10178 * Source Locations: Source Locations<2>.
10179 * Compilation results: Compilation results<2>.
10181 Compilation contexts
10183 * Lifetime-management: Lifetime-management<2>.
10184 * Thread-safety: Thread-safety<2>.
10185 * Error-handling: Error-handling<3>.
10186 * Debugging: Debugging<2>.
10187 * Options: Options<4>.
10191 * String Options: String Options<2>.
10192 * Boolean options: Boolean options<2>.
10193 * Integer options: Integer options<2>.
10197 * Standard types: Standard types<2>.
10198 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
10199 * Structures and unions: Structures and unions<2>.
10203 * Rvalues: Rvalues<2>.
10204 * Lvalues: Lvalues<2>.
10205 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
10209 * Simple expressions: Simple expressions<2>.
10210 * Unary Operations: Unary Operations<2>.
10211 * Binary Operations: Binary Operations<2>.
10212 * Comparisons: Comparisons<2>.
10213 * Function calls: Function calls<2>.
10214 * Type-coercion: Type-coercion<2>.
10218 * Global variables: Global variables<2>.
10220 Creating and using functions
10222 * Params: Params<2>.
10223 * Functions: Functions<2>.
10224 * Blocks: Blocks<2>.
10225 * Statements: Statements<2>.
10229 * Faking it: Faking it<2>.
10234 @node Compilation contexts<2>,Objects<2>,,Topic Reference<2>
10235 @anchor{cp/topics/contexts compilation-contexts}@anchor{fe}@anchor{cp/topics/contexts doc}@anchor{ff}
10236 @subsection Compilation contexts
10239 @geindex gccjit;;context (C++ class)
10240 @anchor{cp/topics/contexts gccjit context}@anchor{100}
10241 @deffn {C++ Class} gccjit::context
10244 The top-level of the C++ API is the @pxref{100,,gccjit;;context} type.
10246 A @pxref{100,,gccjit;;context} instance encapsulates the state of a
10249 You can set up options on it, and add types, functions and code.
10250 Invoking @pxref{d9,,gccjit;;context;;compile()} on it gives you a
10251 @pxref{16,,gcc_jit_result *}.
10253 It is a thin wrapper around the C API's @pxref{8,,gcc_jit_context *}.
10256 * Lifetime-management: Lifetime-management<2>.
10257 * Thread-safety: Thread-safety<2>.
10258 * Error-handling: Error-handling<3>.
10259 * Debugging: Debugging<2>.
10260 * Options: Options<4>.
10264 @node Lifetime-management<2>,Thread-safety<2>,,Compilation contexts<2>
10265 @anchor{cp/topics/contexts lifetime-management}@anchor{101}
10266 @subsubsection Lifetime-management
10269 Contexts are the unit of lifetime-management within the API: objects
10270 have their lifetime bounded by the context they are created within, and
10271 cleanup of such objects is done for you when the context is released.
10273 @geindex gccjit;;context;;acquire (C++ function)
10274 @anchor{cp/topics/contexts gccjit context acquire}@anchor{d3}
10275 @deffn {C++ Function} gccjit::context gccjit::context::acquire ()
10277 This function acquires a new @pxref{100,,gccjit;;context} instance,
10278 which is independent of any others that may be present within this
10282 @geindex gccjit;;context;;release (C++ function)
10283 @anchor{cp/topics/contexts gccjit context release}@anchor{d5}
10284 @deffn {C++ Function} void gccjit::context::release ()
10286 This function releases all resources associated with the given context.
10287 Both the context itself and all of its @code{gccjit::object *}
10288 instances are cleaned up. It should be called exactly once on a given
10291 It is invalid to use the context or any of its "contextual" objects
10292 after calling this.
10301 @geindex gccjit;;context;;new_child_context (C++ function)
10302 @anchor{cp/topics/contexts gccjit context new_child_context}@anchor{102}
10303 @deffn {C++ Function} gccjit::context gccjit::context::new_child_context ()
10305 Given an existing JIT context, create a child context.
10307 The child inherits a copy of all option-settings from the parent.
10309 The child can reference objects created within the parent, but not
10312 The lifetime of the child context must be bounded by that of the
10313 parent: you should release a child context before releasing the parent
10316 If you use a function from a parent context within a child context,
10317 you have to compile the parent context before you can compile the
10318 child context, and the gccjit::result of the parent context must
10319 outlive the gccjit::result of the child context.
10321 This allows caching of shared initializations. For example, you could
10322 create types and declarations of global functions in a parent context
10323 once within a process, and then create child contexts whenever a
10324 function or loop becomes hot. Each such child context can be used for
10325 JIT-compiling just one function or loop, but can reference types
10326 and helper functions created within the parent context.
10328 Contexts can be arbitrarily nested, provided the above rules are
10329 followed, but it's probably not worth going above 2 or 3 levels, and
10330 there will likely be a performance hit for such nesting.
10333 @node Thread-safety<2>,Error-handling<3>,Lifetime-management<2>,Compilation contexts<2>
10334 @anchor{cp/topics/contexts thread-safety}@anchor{103}
10335 @subsubsection Thread-safety
10338 Instances of @pxref{100,,gccjit;;context} created via
10339 @pxref{d3,,gccjit;;context;;acquire()} are independent from each other:
10340 only one thread may use a given context at once, but multiple threads
10341 could each have their own contexts without needing locks.
10343 Contexts created via @pxref{102,,gccjit;;context;;new_child_context()} are
10344 related to their parent context. They can be partitioned by their
10345 ultimate ancestor into independent "family trees". Only one thread
10346 within a process may use a given "family tree" of such contexts at once,
10347 and if you're using multiple threads you should provide your own locking
10348 around entire such context partitions.
10350 @node Error-handling<3>,Debugging<2>,Thread-safety<2>,Compilation contexts<2>
10351 @anchor{cp/topics/contexts error-handling}@anchor{104}
10352 @subsubsection Error-handling
10355 @c FIXME: How does error-handling work for C++ API?
10357 You can only compile and get code from a context if no errors occur.
10359 In general, if an error occurs when using an API entrypoint, it returns
10360 NULL. You don't have to check everywhere for NULL results, since the
10361 API gracefully handles a NULL being passed in for any argument.
10363 Errors are printed on stderr and can be queried using
10364 @pxref{105,,gccjit;;context;;get_first_error()}.
10366 @geindex gccjit;;context;;get_first_error (C++ function)
10367 @anchor{cp/topics/contexts gccjit context get_first_error__gccjit contextP}@anchor{105}
10368 @deffn {C++ Function} const char* gccjit::context::get_first_error (gccjit::context* ctxt)
10370 Returns the first error message that occurred on the context.
10372 The returned string is valid for the rest of the lifetime of the
10375 If no errors occurred, this will be NULL.
10378 @node Debugging<2>,Options<4>,Error-handling<3>,Compilation contexts<2>
10379 @anchor{cp/topics/contexts debugging}@anchor{106}
10380 @subsubsection Debugging
10383 @geindex gccjit;;context;;dump_to_file (C++ function)
10384 @anchor{cp/topics/contexts gccjit context dump_to_file__ssCR i}@anchor{107}
10385 @deffn {C++ Function} void gccjit::context::dump_to_file (const std::string& path, int update_locations)
10387 To help with debugging: dump a C-like representation to the given path,
10388 describing what's been set up on the context.
10390 If "update_locations" is true, then also set up @pxref{108,,gccjit;;location}
10391 information throughout the context, pointing at the dump file as if it
10392 were a source file. This may be of use in conjunction with
10393 @code{GCCJIT::BOOL_OPTION_DEBUGINFO} to allow stepping through the
10394 code in a debugger.
10397 @node Options<4>,,Debugging<2>,Compilation contexts<2>
10398 @anchor{cp/topics/contexts options}@anchor{109}
10399 @subsubsection Options
10403 * String Options: String Options<2>.
10404 * Boolean options: Boolean options<2>.
10405 * Integer options: Integer options<2>.
10409 @node String Options<2>,Boolean options<2>,,Options<4>
10410 @anchor{cp/topics/contexts string-options}@anchor{10a}
10411 @subsubsection String Options
10414 @geindex gccjit;;context;;set_str_option (C++ function)
10415 @anchor{cp/topics/contexts gccjit context set_str_option__enum cCP}@anchor{10b}
10416 @deffn {C++ Function} void gccjit::context::set_str_option (enum gcc_jit_str_option, const char* value)
10418 Set a string option of the context.
10420 This is a thin wrapper around the C API
10421 @pxref{59,,gcc_jit_context_set_str_option()}; the options have the same
10425 @node Boolean options<2>,Integer options<2>,String Options<2>,Options<4>
10426 @anchor{cp/topics/contexts boolean-options}@anchor{10c}
10427 @subsubsection Boolean options
10430 @geindex gccjit;;context;;set_bool_option (C++ function)
10431 @anchor{cp/topics/contexts gccjit context set_bool_option__enum i}@anchor{db}
10432 @deffn {C++ Function} void gccjit::context::set_bool_option (enum gcc_jit_bool_option, int value)
10434 Set a boolean option of the context.
10436 This is a thin wrapper around the C API
10437 @pxref{1b,,gcc_jit_context_set_bool_option()}; the options have the same
10441 @node Integer options<2>,,Boolean options<2>,Options<4>
10442 @anchor{cp/topics/contexts integer-options}@anchor{10d}
10443 @subsubsection Integer options
10446 @geindex gccjit;;context;;set_int_option (C++ function)
10447 @anchor{cp/topics/contexts gccjit context set_int_option__enum i}@anchor{dc}
10448 @deffn {C++ Function} void gccjit::context::set_int_option (enum gcc_jit_int_option, int value)
10450 Set an integer option of the context.
10452 This is a thin wrapper around the C API
10453 @pxref{1e,,gcc_jit_context_set_int_option()}; the options have the same
10457 @c Copyright (C) 2014 Free Software Foundation, Inc.
10458 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
10460 @c This is free software: you can redistribute it and/or modify it
10461 @c under the terms of the GNU General Public License as published by
10462 @c the Free Software Foundation, either version 3 of the License, or
10463 @c (at your option) any later version.
10465 @c This program is distributed in the hope that it will be useful, but
10466 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10467 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10468 @c General Public License for more details.
10470 @c You should have received a copy of the GNU General Public License
10471 @c along with this program. If not, see
10472 @c <http://www.gnu.org/licenses/>.
10474 @node Objects<2>,Types<2>,Compilation contexts<2>,Topic Reference<2>
10475 @anchor{cp/topics/objects objects}@anchor{10e}@anchor{cp/topics/objects doc}@anchor{10f}
10476 @subsection Objects
10479 @geindex gccjit;;object (C++ class)
10480 @anchor{cp/topics/objects gccjit object}@anchor{110}
10481 @deffn {C++ Class} gccjit::object
10484 Almost every entity in the API (with the exception of
10485 @pxref{100,,gccjit;;context} and @pxref{16,,gcc_jit_result *}) is a
10486 "contextual" object, a @pxref{110,,gccjit;;object}.
10496 is associated with a @pxref{100,,gccjit;;context}.
10499 is automatically cleaned up for you when its context is released so
10500 you don't need to manually track and cleanup all objects, just the
10505 The C++ class hierarchy within the @code{gccjit} namespace looks like this:
10522 The @pxref{110,,gccjit;;object} base class has the following operations:
10524 @geindex gccjit;;object;;get_context (C++ function)
10525 @anchor{cp/topics/objects gccjit object get_contextC}@anchor{111}
10526 @deffn {C++ Function} gccjit::context gccjit::object::get_context () const
10528 Which context is the obj within?
10531 @geindex gccjit;;object;;get_debug_string (C++ function)
10532 @anchor{cp/topics/objects gccjit object get_debug_stringC}@anchor{d6}
10533 @deffn {C++ Function} std::string gccjit::object::get_debug_string () const
10535 Generate a human-readable description for the given object.
10540 printf ("obj: %s\n", obj.get_debug_string ().c_str ());
10545 might give this text on stdout:
10548 obj: 4.0 * (float)i
10554 @c Copyright (C) 2014 Free Software Foundation, Inc.
10555 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
10557 @c This is free software: you can redistribute it and/or modify it
10558 @c under the terms of the GNU General Public License as published by
10559 @c the Free Software Foundation, either version 3 of the License, or
10560 @c (at your option) any later version.
10562 @c This program is distributed in the hope that it will be useful, but
10563 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10564 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10565 @c General Public License for more details.
10567 @c You should have received a copy of the GNU General Public License
10568 @c along with this program. If not, see
10569 @c <http://www.gnu.org/licenses/>.
10571 @node Types<2>,Expressions<2>,Objects<2>,Topic Reference<2>
10572 @anchor{cp/topics/types doc}@anchor{112}@anchor{cp/topics/types types}@anchor{113}
10576 @geindex gccjit;;type (C++ class)
10577 @anchor{cp/topics/types gccjit type}@anchor{114}
10578 @deffn {C++ Class} gccjit::type
10580 gccjit::type represents a type within the library. It is a subclass
10581 of @pxref{110,,gccjit;;object}.
10584 Types can be created in several ways:
10590 fundamental types can be accessed using
10591 @pxref{d4,,gccjit;;context;;get_type()}:
10594 gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
10599 or using the @code{gccjit::context::get_int_type} template:
10602 gccjit::type t = ctxt.get_int_type <unsigned short> ();
10607 See @pxref{b,,gcc_jit_context_get_type()} for the available types.
10610 derived types can be accessed by using functions such as
10611 @pxref{115,,gccjit;;type;;get_pointer()} and @pxref{116,,gccjit;;type;;get_const()}:
10614 gccjit::type const_int_star = int_type.get_const ().get_pointer ();
10615 gccjit::type int_const_star = int_type.get_pointer ().get_const ();
10621 by creating structures (see below).
10625 * Standard types: Standard types<2>.
10626 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
10627 * Structures and unions: Structures and unions<2>.
10631 @node Standard types<2>,Pointers const and volatile<2>,,Types<2>
10632 @anchor{cp/topics/types standard-types}@anchor{117}
10633 @subsubsection Standard types
10636 @geindex gccjit;;context;;get_type (C++ function)
10637 @anchor{cp/topics/types gccjit context get_type__enum}@anchor{d4}
10638 @deffn {C++ Function} gccjit::type gccjit::context::get_type (enum gcc_jit_types)
10640 Access a specific type. This is a thin wrapper around
10641 @pxref{b,,gcc_jit_context_get_type()}; the parameter has the same meaning.
10644 @geindex gccjit;;context;;get_int_type (C++ function)
10645 @anchor{cp/topics/types gccjit context get_int_type__s i}@anchor{118}
10646 @deffn {C++ Function} gccjit::type gccjit::context::get_int_type (size_t num_bytes, int is_signed)
10648 Access the integer type of the given size.
10651 @geindex gccjit;;context;;get_int_type<T> (C++ function)
10652 @anchor{cp/topics/types gccjit context get_int_type T}@anchor{119}
10653 @deffn {C++ Function} gccjit::type gccjit::context::get_int_type<T> ()
10655 Access the given integer type. For example, you could map the
10656 @code{unsigned short} type into a gccjit::type via:
10659 gccjit::type t = ctxt.get_int_type <unsigned short> ();
10665 @node Pointers const and volatile<2>,Structures and unions<2>,Standard types<2>,Types<2>
10666 @anchor{cp/topics/types pointers-const-and-volatile}@anchor{11a}
10667 @subsubsection Pointers, @cite{const}, and @cite{volatile}
10670 @geindex gccjit;;type;;get_pointer (C++ function)
10671 @anchor{cp/topics/types gccjit type get_pointer}@anchor{115}
10672 @deffn {C++ Function} gccjit::type gccjit::type::get_pointer ()
10674 Given type "T", get type "T*".
10677 @c FIXME: get_const doesn't seem to exist
10679 @geindex gccjit;;type;;get_const (C++ function)
10680 @anchor{cp/topics/types gccjit type get_const}@anchor{116}
10681 @deffn {C++ Function} gccjit::type gccjit::type::get_const ()
10683 Given type "T", get type "const T".
10686 @geindex gccjit;;type;;get_volatile (C++ function)
10687 @anchor{cp/topics/types gccjit type get_volatile}@anchor{11b}
10688 @deffn {C++ Function} gccjit::type gccjit::type::get_volatile ()
10690 Given type "T", get type "volatile T".
10693 @geindex gccjit;;context;;new_array_type (C++ function)
10694 @anchor{cp/topics/types gccjit context new_array_type__gccjit type i gccjit location}@anchor{11c}
10695 @deffn {C++ Function} gccjit::type gccjit::context::new_array_type (gccjit::type element_type, int num_elements, gccjit::location loc)
10697 Given type "T", get type "T[N]" (for a constant N).
10698 Param "loc" is optional.
10701 @node Structures and unions<2>,,Pointers const and volatile<2>,Types<2>
10702 @anchor{cp/topics/types structures-and-unions}@anchor{11d}
10703 @subsubsection Structures and unions
10706 @geindex gccjit;;struct_ (C++ class)
10707 @anchor{cp/topics/types gccjit struct_}@anchor{11e}
10708 @deffn {C++ Class} gccjit::struct_
10711 A compound type analagous to a C @cite{struct}.
10713 @pxref{11e,,gccjit;;struct_} is a subclass of @pxref{114,,gccjit;;type} (and thus
10714 of @pxref{110,,gccjit;;object} in turn).
10716 @geindex gccjit;;field (C++ class)
10717 @anchor{cp/topics/types gccjit field}@anchor{11f}
10718 @deffn {C++ Class} gccjit::field
10721 A field within a @pxref{11e,,gccjit;;struct_}.
10723 @pxref{11f,,gccjit;;field} is a subclass of @pxref{110,,gccjit;;object}.
10725 You can model C @cite{struct} types by creating @pxref{11e,,gccjit;;struct_} and
10726 @pxref{11f,,gccjit;;field} instances, in either order:
10732 by creating the fields, then the structure. For example, to model:
10735 struct coord @{double x; double y; @};
10743 gccjit::field field_x = ctxt.new_field (double_type, "x");
10744 gccjit::field field_y = ctxt.new_field (double_type, "y");
10745 std::vector fields;
10746 fields.push_back (field_x);
10747 fields.push_back (field_y);
10748 gccjit::struct_ coord = ctxt.new_struct_type ("coord", fields);
10754 by creating the structure, then populating it with fields, typically
10755 to allow modelling self-referential structs such as:
10758 struct node @{ int m_hash; struct node *m_next; @};
10766 gccjit::struct_ node = ctxt.new_opaque_struct_type ("node");
10767 gccjit::type node_ptr = node.get_pointer ();
10768 gccjit::field field_hash = ctxt.new_field (int_type, "m_hash");
10769 gccjit::field field_next = ctxt.new_field (node_ptr, "m_next");
10770 std::vector fields;
10771 fields.push_back (field_hash);
10772 fields.push_back (field_next);
10773 node.set_fields (fields);
10779 @c FIXME: the above API doesn't seem to exist yet
10781 @geindex gccjit;;context;;new_field (C++ function)
10782 @anchor{cp/topics/types gccjit context new_field__gccjit type cCP gccjit location}@anchor{120}
10783 @deffn {C++ Function} gccjit::field gccjit::context::new_field (gccjit::type type, const char* name, gccjit::location loc)
10785 Construct a new field, with the given type and name.
10788 @geindex gccjit;;context;;new_struct_type (C++ function)
10789 @anchor{cp/topics/types gccjit context new_struct_type__ssCR std vector field R gccjit location}@anchor{121}
10790 @deffn {C++ Function} gccjit::struct_ gccjit::context::new_struct_type (const std::string& name, std::vector<field>& fields, gccjit::location loc)
10794 Construct a new struct type, with the given name and fields.
10798 @geindex gccjit;;context;;new_opaque_struct (C++ function)
10799 @anchor{cp/topics/types gccjit context new_opaque_struct__ssCR gccjit location}@anchor{122}
10800 @deffn {C++ Function} gccjit::struct_ gccjit::context::new_opaque_struct (const std::string& name, gccjit::location loc)
10802 Construct a new struct type, with the given name, but without
10803 specifying the fields. The fields can be omitted (in which case the
10804 size of the struct is not known), or later specified using
10805 @pxref{78,,gcc_jit_struct_set_fields()}.
10808 @c Copyright (C) 2014 Free Software Foundation, Inc.
10809 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
10811 @c This is free software: you can redistribute it and/or modify it
10812 @c under the terms of the GNU General Public License as published by
10813 @c the Free Software Foundation, either version 3 of the License, or
10814 @c (at your option) any later version.
10816 @c This program is distributed in the hope that it will be useful, but
10817 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10818 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10819 @c General Public License for more details.
10821 @c You should have received a copy of the GNU General Public License
10822 @c along with this program. If not, see
10823 @c <http://www.gnu.org/licenses/>.
10825 @node Expressions<2>,Creating and using functions<2>,Types<2>,Topic Reference<2>
10826 @anchor{cp/topics/expressions expressions}@anchor{123}@anchor{cp/topics/expressions doc}@anchor{124}
10827 @subsection Expressions
10831 * Rvalues: Rvalues<2>.
10832 * Lvalues: Lvalues<2>.
10833 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
10837 * Simple expressions: Simple expressions<2>.
10838 * Unary Operations: Unary Operations<2>.
10839 * Binary Operations: Binary Operations<2>.
10840 * Comparisons: Comparisons<2>.
10841 * Function calls: Function calls<2>.
10842 * Type-coercion: Type-coercion<2>.
10846 * Global variables: Global variables<2>.
10851 @node Rvalues<2>,Lvalues<2>,,Expressions<2>
10852 @anchor{cp/topics/expressions rvalues}@anchor{125}
10853 @subsubsection Rvalues
10856 @geindex gccjit;;rvalue (C++ class)
10857 @anchor{cp/topics/expressions gccjit rvalue}@anchor{126}
10858 @deffn {C++ Class} gccjit::rvalue
10861 A @pxref{126,,gccjit;;rvalue} is an expression that can be computed. It is a
10862 subclass of @pxref{110,,gccjit;;object}, and is a thin wrapper around
10863 @pxref{13,,gcc_jit_rvalue *} from the C API.
10865 It can be simple, e.g.:
10873 an integer value e.g. @cite{0} or @cite{42}
10876 a string literal e.g. @cite{"Hello world"}
10879 a variable e.g. @cite{i}. These are also lvalues (see below).
10891 a unary expression e.g. @cite{!cond}
10894 a binary expression e.g. @cite{(a + b)}
10897 a function call e.g. @cite{get_distance (&player_ship@comma{} &target)}
10904 Every rvalue has an associated type, and the API will check to ensure
10905 that types match up correctly (otherwise the context will emit an error).
10907 @geindex gccjit;;rvalue;;get_type (C++ function)
10908 @anchor{cp/topics/expressions gccjit rvalue get_type}@anchor{127}
10909 @deffn {C++ Function} gccjit::type gccjit::rvalue::get_type ()
10911 Get the type of this rvalue.
10915 * Simple expressions: Simple expressions<2>.
10916 * Unary Operations: Unary Operations<2>.
10917 * Binary Operations: Binary Operations<2>.
10918 * Comparisons: Comparisons<2>.
10919 * Function calls: Function calls<2>.
10920 * Type-coercion: Type-coercion<2>.
10924 @node Simple expressions<2>,Unary Operations<2>,,Rvalues<2>
10925 @anchor{cp/topics/expressions simple-expressions}@anchor{128}
10926 @subsubsection Simple expressions
10929 @geindex gccjit;;context;;new_rvalue (C++ function)
10930 @anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type iC}@anchor{e8}
10931 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, int value) const
10933 Given a numeric type (integer or floating point), build an rvalue for
10934 the given constant @code{int} value.
10937 @geindex gccjit;;context;;new_rvalue (C++ function)
10938 @anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type lC}@anchor{129}
10939 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, long value) const
10941 Given a numeric type (integer or floating point), build an rvalue for
10942 the given constant @code{long} value.
10945 @geindex gccjit;;context;;zero (C++ function)
10946 @anchor{cp/topics/expressions gccjit context zero__gccjit typeC}@anchor{e4}
10947 @deffn {C++ Function} gccjit::rvalue gccjit::context::zero (gccjit::type numeric_type) const
10949 Given a numeric type (integer or floating point), get the rvalue for
10950 zero. Essentially this is just a shortcut for:
10953 ctxt.new_rvalue (numeric_type, 0)
10959 @geindex gccjit;;context;;one (C++ function)
10960 @anchor{cp/topics/expressions gccjit context one__gccjit typeC}@anchor{12a}
10961 @deffn {C++ Function} gccjit::rvalue gccjit::context::one (gccjit::type numeric_type) const
10963 Given a numeric type (integer or floating point), get the rvalue for
10964 zero. Essentially this is just a shortcut for:
10967 ctxt.new_rvalue (numeric_type, 1)
10973 @geindex gccjit;;context;;new_rvalue (C++ function)
10974 @anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type doubleC}@anchor{12b}
10975 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, double value) const
10977 Given a numeric type (integer or floating point), build an rvalue for
10978 the given constant @code{double} value.
10981 @geindex gccjit;;context;;new_rvalue (C++ function)
10982 @anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type voidPC}@anchor{12c}
10983 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type pointer_type, void* value) const
10985 Given a pointer type, build an rvalue for the given address.
10988 @geindex gccjit;;context;;new_rvalue (C++ function)
10989 @anchor{cp/topics/expressions gccjit context new_rvalue__ssCRC}@anchor{12d}
10990 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (const std::string& value) const
10992 Generate an rvalue of type @code{GCC_JIT_TYPE_CONST_CHAR_PTR} for
10993 the given string. This is akin to a string literal.
10996 @node Unary Operations<2>,Binary Operations<2>,Simple expressions<2>,Rvalues<2>
10997 @anchor{cp/topics/expressions unary-operations}@anchor{12e}
10998 @subsubsection Unary Operations
11001 @geindex gccjit;;context;;new_unary_op (C++ function)
11002 @anchor{cp/topics/expressions gccjit context new_unary_op__enum gccjit type gccjit rvalue gccjit location}@anchor{12f}
11003 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_unary_op (enum gcc_jit_unary_op, gccjit::type result_type, gccjit::rvalue rvalue, gccjit::location loc)
11005 Build a unary operation out of an input rvalue.
11007 Parameter @code{loc} is optional.
11009 This is a thin wrapper around the C API's
11010 @pxref{84,,gcc_jit_context_new_unary_op()} and the available unary
11011 operations are documented there.
11014 There are shorter ways to spell the various specific kinds of unary
11017 @geindex gccjit;;context;;new_minus (C++ function)
11018 @anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit location}@anchor{130}
11019 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
11021 Negate an arithmetic value; for example:
11024 gccjit::rvalue negpi = ctxt.new_minus (t_double, pi);
11029 builds the equivalent of this C expression:
11038 @geindex new_bitwise_negate (C++ function)
11039 @anchor{cp/topics/expressions new_bitwise_negate__gccjit type gccjit rvalue gccjit location}@anchor{131}
11040 @deffn {C++ Function} gccjit::rvalue new_bitwise_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
11042 Bitwise negation of an integer value (one's complement); for example:
11045 gccjit::rvalue mask = ctxt.new_bitwise_negate (t_int, a);
11050 builds the equivalent of this C expression:
11059 @geindex new_logical_negate (C++ function)
11060 @anchor{cp/topics/expressions new_logical_negate__gccjit type gccjit rvalue gccjit location}@anchor{132}
11061 @deffn {C++ Function} gccjit::rvalue new_logical_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
11063 Logical negation of an arithmetic or pointer value; for example:
11066 gccjit::rvalue guard = ctxt.new_logical_negate (t_bool, cond);
11071 builds the equivalent of this C expression:
11080 The most concise way to spell them is with overloaded operators:
11082 @geindex operator- (C++ function)
11083 @anchor{cp/topics/expressions sub-operator__gccjit rvalue}@anchor{133}
11084 @deffn {C++ Function} gccjit::rvalue operator- (gccjit::rvalue a)
11087 gccjit::rvalue negpi = -pi;
11093 @geindex operator~ (C++ function)
11094 @anchor{cp/topics/expressions inv-operator__gccjit rvalue}@anchor{134}
11095 @deffn {C++ Function} gccjit::rvalue operator~ (gccjit::rvalue a)
11098 gccjit::rvalue mask = ~a;
11104 @geindex operator! (C++ function)
11105 @anchor{cp/topics/expressions not-operator__gccjit rvalue}@anchor{135}
11106 @deffn {C++ Function} gccjit::rvalue operator! (gccjit::rvalue a)
11109 gccjit::rvalue guard = !cond;
11115 @node Binary Operations<2>,Comparisons<2>,Unary Operations<2>,Rvalues<2>
11116 @anchor{cp/topics/expressions binary-operations}@anchor{136}
11117 @subsubsection Binary Operations
11120 @geindex gccjit;;context;;new_binary_op (C++ function)
11121 @anchor{cp/topics/expressions gccjit context new_binary_op__enum gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{d8}
11122 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_binary_op (enum gcc_jit_binary_op, gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11124 Build a binary operation out of two constituent rvalues.
11126 Parameter @code{loc} is optional.
11128 This is a thin wrapper around the C API's
11129 @pxref{12,,gcc_jit_context_new_binary_op()} and the available binary
11130 operations are documented there.
11133 There are shorter ways to spell the various specific kinds of binary
11136 @geindex gccjit;;context;;new_plus (C++ function)
11137 @anchor{cp/topics/expressions gccjit context new_plus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{137}
11138 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_plus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11141 @geindex gccjit;;context;;new_minus (C++ function)
11142 @anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{138}
11143 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11146 @geindex gccjit;;context;;new_mult (C++ function)
11147 @anchor{cp/topics/expressions gccjit context new_mult__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{139}
11148 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_mult (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11151 @geindex gccjit;;context;;new_divide (C++ function)
11152 @anchor{cp/topics/expressions gccjit context new_divide__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{13a}
11153 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_divide (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11156 @geindex gccjit;;context;;new_modulo (C++ function)
11157 @anchor{cp/topics/expressions gccjit context new_modulo__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{13b}
11158 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_modulo (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11161 @geindex gccjit;;context;;new_bitwise_and (C++ function)
11162 @anchor{cp/topics/expressions gccjit context new_bitwise_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{13c}
11163 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11166 @geindex gccjit;;context;;new_bitwise_xor (C++ function)
11167 @anchor{cp/topics/expressions gccjit context new_bitwise_xor__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{13d}
11168 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_xor (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11171 @geindex gccjit;;context;;new_bitwise_or (C++ function)
11172 @anchor{cp/topics/expressions gccjit context new_bitwise_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{13e}
11173 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11176 @geindex gccjit;;context;;new_logical_and (C++ function)
11177 @anchor{cp/topics/expressions gccjit context new_logical_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{13f}
11178 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_logical_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11181 @geindex gccjit;;context;;new_logical_or (C++ function)
11182 @anchor{cp/topics/expressions gccjit context new_logical_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{140}
11183 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_logical_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11186 The most concise way to spell them is with overloaded operators:
11188 @geindex operator+ (C++ function)
11189 @anchor{cp/topics/expressions add-operator__gccjit rvalue gccjit rvalue}@anchor{141}
11190 @deffn {C++ Function} gccjit::rvalue operator+ (gccjit::rvalue a, gccjit::rvalue b)
11193 gccjit::rvalue sum = a + b;
11199 @geindex operator- (C++ function)
11200 @anchor{cp/topics/expressions sub-operator__gccjit rvalue gccjit rvalue}@anchor{142}
11201 @deffn {C++ Function} gccjit::rvalue operator- (gccjit::rvalue a, gccjit::rvalue b)
11204 gccjit::rvalue diff = a - b;
11210 @geindex operator* (C++ function)
11211 @anchor{cp/topics/expressions mul-operator__gccjit rvalue gccjit rvalue}@anchor{143}
11212 @deffn {C++ Function} gccjit::rvalue operator* (gccjit::rvalue a, gccjit::rvalue b)
11215 gccjit::rvalue prod = a * b;
11221 @geindex operator/ (C++ function)
11222 @anchor{cp/topics/expressions div-operator__gccjit rvalue gccjit rvalue}@anchor{144}
11223 @deffn {C++ Function} gccjit::rvalue operator/ (gccjit::rvalue a, gccjit::rvalue b)
11226 gccjit::rvalue result = a / b;
11232 @geindex operator% (C++ function)
11233 @anchor{cp/topics/expressions mod-operator__gccjit rvalue gccjit rvalue}@anchor{145}
11234 @deffn {C++ Function} gccjit::rvalue operator% (gccjit::rvalue a, gccjit::rvalue b)
11237 gccjit::rvalue mod = a % b;
11243 @geindex operator& (C++ function)
11244 @anchor{cp/topics/expressions and-operator__gccjit rvalue gccjit rvalue}@anchor{146}
11245 @deffn {C++ Function} gccjit::rvalue operator& (gccjit::rvalue a, gccjit::rvalue b)
11248 gccjit::rvalue x = a & b;
11254 @geindex operator^ (C++ function)
11255 @anchor{cp/topics/expressions xor-operator__gccjit rvalue gccjit rvalue}@anchor{147}
11256 @deffn {C++ Function} gccjit::rvalue operator^ (gccjit::rvalue a, gccjit::rvalue b)
11259 gccjit::rvalue x = a ^ b;
11265 @geindex operator| (C++ function)
11266 @anchor{cp/topics/expressions or-operator__gccjit rvalue gccjit rvalue}@anchor{148}
11267 @deffn {C++ Function} gccjit::rvalue operator| (gccjit::rvalue a, gccjit::rvalue b)
11270 gccjit::rvalue x = a | b;
11276 @geindex operator&& (C++ function)
11277 @anchor{cp/topics/expressions sand-operator__gccjit rvalue gccjit rvalue}@anchor{149}
11278 @deffn {C++ Function} gccjit::rvalue operator&& (gccjit::rvalue a, gccjit::rvalue b)
11281 gccjit::rvalue cond = a && b;
11287 @geindex operator|| (C++ function)
11288 @anchor{cp/topics/expressions sor-operator__gccjit rvalue gccjit rvalue}@anchor{14a}
11289 @deffn {C++ Function} gccjit::rvalue operator|| (gccjit::rvalue a, gccjit::rvalue b)
11292 gccjit::rvalue cond = a || b;
11298 These can of course be combined, giving a terse way to build compound
11304 gccjit::rvalue discriminant = (b * b) - (four * a * c);
11310 @node Comparisons<2>,Function calls<2>,Binary Operations<2>,Rvalues<2>
11311 @anchor{cp/topics/expressions comparisons}@anchor{14b}
11312 @subsubsection Comparisons
11315 @geindex gccjit;;context;;new_comparison (C++ function)
11316 @anchor{cp/topics/expressions gccjit context new_comparison__enum gccjit rvalue gccjit rvalue gccjit location}@anchor{e5}
11317 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_comparison (enum gcc_jit_comparison, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11319 Build a boolean rvalue out of the comparison of two other rvalues.
11321 Parameter @code{loc} is optional.
11323 This is a thin wrapper around the C API's
11324 @pxref{2c,,gcc_jit_context_new_comparison()} and the available kinds
11325 of comparison are documented there.
11328 There are shorter ways to spell the various specific kinds of binary
11331 @geindex gccjit;;context;;new_eq (C++ function)
11332 @anchor{cp/topics/expressions gccjit context new_eq__gccjit rvalue gccjit rvalue gccjit location}@anchor{14c}
11333 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_eq (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11336 @geindex gccjit;;context;;new_ne (C++ function)
11337 @anchor{cp/topics/expressions gccjit context new_ne__gccjit rvalue gccjit rvalue gccjit location}@anchor{14d}
11338 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_ne (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11341 @geindex gccjit;;context;;new_lt (C++ function)
11342 @anchor{cp/topics/expressions gccjit context new_lt__gccjit rvalue gccjit rvalue gccjit location}@anchor{14e}
11343 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_lt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11346 @geindex gccjit;;context;;new_le (C++ function)
11347 @anchor{cp/topics/expressions gccjit context new_le__gccjit rvalue gccjit rvalue gccjit location}@anchor{14f}
11348 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_le (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11351 @geindex gccjit;;context;;new_gt (C++ function)
11352 @anchor{cp/topics/expressions gccjit context new_gt__gccjit rvalue gccjit rvalue gccjit location}@anchor{150}
11353 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_gt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11356 @geindex gccjit;;context;;new_ge (C++ function)
11357 @anchor{cp/topics/expressions gccjit context new_ge__gccjit rvalue gccjit rvalue gccjit location}@anchor{151}
11358 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_ge (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11361 The most concise way to spell them is with overloaded operators:
11363 @geindex operator== (C++ function)
11364 @anchor{cp/topics/expressions eq-operator__gccjit rvalue gccjit rvalue}@anchor{152}
11365 @deffn {C++ Function} gccjit::rvalue operator== (gccjit::rvalue a, gccjit::rvalue b)
11368 gccjit::rvalue cond = (a == ctxt.zero (t_int));
11374 @geindex operator!= (C++ function)
11375 @anchor{cp/topics/expressions neq-operator__gccjit rvalue gccjit rvalue}@anchor{153}
11376 @deffn {C++ Function} gccjit::rvalue operator!= (gccjit::rvalue a, gccjit::rvalue b)
11379 gccjit::rvalue cond = (i != j);
11385 @geindex operator< (C++ function)
11386 @anchor{cp/topics/expressions lt-operator__gccjit rvalue gccjit rvalue}@anchor{154}
11387 @deffn {C++ Function} gccjit::rvalue operator< (gccjit::rvalue a, gccjit::rvalue b)
11390 gccjit::rvalue cond = i < n;
11396 @geindex operator<= (C++ function)
11397 @anchor{cp/topics/expressions lte-operator__gccjit rvalue gccjit rvalue}@anchor{155}
11398 @deffn {C++ Function} gccjit::rvalue operator<= (gccjit::rvalue a, gccjit::rvalue b)
11401 gccjit::rvalue cond = i <= n;
11407 @geindex operator> (C++ function)
11408 @anchor{cp/topics/expressions gt-operator__gccjit rvalue gccjit rvalue}@anchor{156}
11409 @deffn {C++ Function} gccjit::rvalue operator> (gccjit::rvalue a, gccjit::rvalue b)
11412 gccjit::rvalue cond = (ch > limit);
11418 @geindex operator>= (C++ function)
11419 @anchor{cp/topics/expressions gte-operator__gccjit rvalue gccjit rvalue}@anchor{157}
11420 @deffn {C++ Function} gccjit::rvalue operator>= (gccjit::rvalue a, gccjit::rvalue b)
11423 gccjit::rvalue cond = (score >= ctxt.new_rvalue (t_int, 100));
11429 @c TODO: beyond this point
11431 @node Function calls<2>,Type-coercion<2>,Comparisons<2>,Rvalues<2>
11432 @anchor{cp/topics/expressions function-calls}@anchor{158}
11433 @subsubsection Function calls
11436 @geindex gcc_jit_context_new_call (C++ function)
11437 @anchor{cp/topics/expressions gcc_jit_context_new_call__gcc_jit_contextP gcc_jit_locationP gcc_jit_functionP i gcc_jit_rvaluePP}@anchor{159}
11438 @deffn {C++ Function} gcc_jit_rvalue* gcc_jit_context_new_call (gcc_jit_context* ctxt, gcc_jit_location* loc, gcc_jit_function* func, int numargs, gcc_jit_rvalue** args)
11440 Given a function and the given table of argument rvalues, construct a
11441 call to the function, with the result as an rvalue.
11445 @code{gccjit::context::new_call()} merely builds a
11446 @pxref{126,,gccjit;;rvalue} i.e. an expression that can be evaluated,
11447 perhaps as part of a more complicated expression.
11448 The call @emph{won't} happen unless you add a statement to a function
11449 that evaluates the expression.
11451 For example, if you want to call a function and discard the result
11452 (or to call a function with @code{void} return type), use
11453 @pxref{15a,,gccjit;;block;;add_eval()}:
11456 /* Add "(void)printf (arg0, arg1);". */
11457 block.add_eval (ctxt.new_call (printf_func, arg0, arg1));
11465 @node Type-coercion<2>,,Function calls<2>,Rvalues<2>
11466 @anchor{cp/topics/expressions type-coercion}@anchor{15b}
11467 @subsubsection Type-coercion
11470 @geindex gccjit;;context;;new_cast (C++ function)
11471 @anchor{cp/topics/expressions gccjit context new_cast__gccjit rvalue gccjit type gccjit location}@anchor{15c}
11472 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_cast (gccjit::rvalue rvalue, gccjit::type type, gccjit::location loc)
11474 Given an rvalue of T, construct another rvalue of another type.
11476 Currently only a limited set of conversions are possible:
11490 P* <-> Q*, for pointer types P and Q
11495 @node Lvalues<2>,Working with pointers structs and unions<2>,Rvalues<2>,Expressions<2>
11496 @anchor{cp/topics/expressions lvalues}@anchor{15d}
11497 @subsubsection Lvalues
11500 @geindex gccjit;;lvalue (C++ class)
11501 @anchor{cp/topics/expressions gccjit lvalue}@anchor{15e}
11502 @deffn {C++ Class} gccjit::lvalue
11505 An lvalue is something that can of the @emph{left}-hand side of an assignment:
11506 a storage area (such as a variable). It is a subclass of
11507 @pxref{126,,gccjit;;rvalue}, where the rvalue is computed by reading from the
11510 It iss a thin wrapper around @pxref{24,,gcc_jit_lvalue *} from the C API.
11512 @geindex gccjit;;lvalue;;get_address (C++ function)
11513 @anchor{cp/topics/expressions gccjit lvalue get_address__gccjit location}@anchor{15f}
11514 @deffn {C++ Function} gccjit::rvalue gccjit::lvalue::get_address (gccjit::location loc)
11516 Take the address of an lvalue; analogous to:
11526 Parameter "loc" is optional.
11530 * Global variables: Global variables<2>.
11534 @node Global variables<2>,,,Lvalues<2>
11535 @anchor{cp/topics/expressions global-variables}@anchor{160}
11536 @subsubsection Global variables
11539 @geindex gccjit;;context;;new_global (C++ function)
11540 @anchor{cp/topics/expressions gccjit context new_global__enum gccjit type cCP gccjit location}@anchor{161}
11541 @deffn {C++ Function} gccjit::lvalue gccjit::context::new_global (enum gcc_jit_global_kind, gccjit::type type, const char* name, gccjit::location loc)
11543 Add a new global variable of the given type and name to the context.
11545 This is a thin wrapper around @pxref{a4,,gcc_jit_context_new_global()} from
11546 the C API; the "kind" parameter has the same meaning as there.
11549 @node Working with pointers structs and unions<2>,,Lvalues<2>,Expressions<2>
11550 @anchor{cp/topics/expressions working-with-pointers-structs-and-unions}@anchor{162}
11551 @subsubsection Working with pointers, structs and unions
11554 @geindex gccjit;;rvalue;;dereference (C++ function)
11555 @anchor{cp/topics/expressions gccjit rvalue dereference__gccjit location}@anchor{163}
11556 @deffn {C++ Function} gccjit::lvalue gccjit::rvalue::dereference (gccjit::location loc)
11558 Given an rvalue of pointer type @code{T *}, dereferencing the pointer,
11559 getting an lvalue of type @code{T}. Analogous to:
11569 Parameter "loc" is optional.
11572 If you don't need to specify the location, this can also be expressed using
11573 an overloaded operator:
11576 @deffn {C++ Function} gccjit::lvalue gccjit::rvalue::operator* ();
11579 gccjit::lvalue content = *ptr;
11585 Field access is provided separately for both lvalues and rvalues:
11587 @geindex gccjit;;lvalue;;access_field (C++ function)
11588 @anchor{cp/topics/expressions gccjit lvalue access_field__gccjit field gccjit location}@anchor{164}
11589 @deffn {C++ Function} gccjit::lvalue gccjit::lvalue::access_field (gccjit::field field, gccjit::location loc)
11591 Given an lvalue of struct or union type, access the given field,
11592 getting an lvalue of the field's type. Analogous to:
11595 (EXPR).field = ...;
11603 @geindex gccjit;;rvalue;;access_field (C++ function)
11604 @anchor{cp/topics/expressions gccjit rvalue access_field__gccjit field gccjit location}@anchor{165}
11605 @deffn {C++ Function} gccjit::rvalue gccjit::rvalue::access_field (gccjit::field field, gccjit::location loc)
11607 Given an rvalue of struct or union type, access the given field
11608 as an rvalue. Analogous to:
11619 @geindex gccjit;;rvalue;;dereference_field (C++ function)
11620 @anchor{cp/topics/expressions gccjit rvalue dereference_field__gccjit field gccjit location}@anchor{166}
11621 @deffn {C++ Function} gccjit::lvalue gccjit::rvalue::dereference_field (gccjit::field field, gccjit::location loc)
11623 Given an rvalue of pointer type @code{T *} where T is of struct or union
11624 type, access the given field as an lvalue. Analogous to:
11632 in C, itself equivalent to @code{(*EXPR).FIELD}.
11635 @geindex gccjit;;context;;new_array_access (C++ function)
11636 @anchor{cp/topics/expressions gccjit context new_array_access__gccjit rvalue gccjit rvalue gccjit location}@anchor{167}
11637 @deffn {C++ Function} gccjit::lvalue gccjit::context::new_array_access (gccjit::rvalue ptr, gccjit::rvalue index, gccjit::location loc)
11639 Given an rvalue of pointer type @code{T *}, get at the element @cite{T} at
11640 the given index, using standard C array indexing rules i.e. each
11641 increment of @code{index} corresponds to @code{sizeof(T)} bytes.
11650 in C (or, indeed, to @code{PTR + INDEX}).
11652 Parameter "loc" is optional.
11655 For array accesses where you don't need to specify a @pxref{108,,gccjit;;location},
11656 two overloaded operators are available:
11660 gccjit::lvalue gccjit::rvalue::operator[] (gccjit::rvalue index)
11663 gccjit::lvalue element = array[idx];
11668 gccjit::lvalue gccjit::rvalue::operator[] (int index)
11671 gccjit::lvalue element = array[0];
11677 @c Copyright (C) 2014 Free Software Foundation, Inc.
11678 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
11680 @c This is free software: you can redistribute it and/or modify it
11681 @c under the terms of the GNU General Public License as published by
11682 @c the Free Software Foundation, either version 3 of the License, or
11683 @c (at your option) any later version.
11685 @c This program is distributed in the hope that it will be useful, but
11686 @c WITHOUT ANY WARRANTY; without even the implied warranty of
11687 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11688 @c General Public License for more details.
11690 @c You should have received a copy of the GNU General Public License
11691 @c along with this program. If not, see
11692 @c <http://www.gnu.org/licenses/>.
11694 @node Creating and using functions<2>,Source Locations<2>,Expressions<2>,Topic Reference<2>
11695 @anchor{cp/topics/functions doc}@anchor{168}@anchor{cp/topics/functions creating-and-using-functions}@anchor{169}
11696 @subsection Creating and using functions
11700 * Params: Params<2>.
11701 * Functions: Functions<2>.
11702 * Blocks: Blocks<2>.
11703 * Statements: Statements<2>.
11707 @node Params<2>,Functions<2>,,Creating and using functions<2>
11708 @anchor{cp/topics/functions params}@anchor{16a}
11709 @subsubsection Params
11712 @geindex gccjit;;param (C++ class)
11713 @anchor{cp/topics/functions gccjit param}@anchor{16b}
11714 @deffn {C++ Class} gccjit::param
11716 A @cite{gccjit::param} represents a parameter to a function.
11719 @geindex gccjit;;context;;new_param (C++ function)
11720 @anchor{cp/topics/functions gccjit context new_param__gccjit type cCP gccjit location}@anchor{d7}
11721 @deffn {C++ Function} gccjit::param gccjit::context::new_param (gccjit::type type, const char* name, gccjit::location loc)
11723 In preparation for creating a function, create a new parameter of the
11724 given type and name.
11727 @pxref{16b,,gccjit;;param} is a subclass of @pxref{15e,,gccjit;;lvalue} (and thus
11728 of @pxref{126,,gccjit;;rvalue} and @pxref{110,,gccjit;;object}). It is a thin
11729 wrapper around the C API's @pxref{25,,gcc_jit_param *}.
11731 @node Functions<2>,Blocks<2>,Params<2>,Creating and using functions<2>
11732 @anchor{cp/topics/functions functions}@anchor{16c}
11733 @subsubsection Functions
11736 @geindex gccjit;;function (C++ class)
11737 @anchor{cp/topics/functions gccjit function}@anchor{16d}
11738 @deffn {C++ Class} gccjit::function
11740 A @cite{gccjit::function} represents a function - either one that we're
11741 creating ourselves, or one that we're referencing.
11745 @deffn {C++ Function} gccjit::function gccjit::context::new_function (enum gcc_jit_function_kind, gccjit::type return_type, const char *name, std::vector<param> ¶ms, int is_variadic, gccjit::location loc) \
11747 Create a gcc_jit_function with the given name and parameters.
11749 Parameters "is_variadic" and "loc" are optional.
11751 This is a wrapper around the C API's @pxref{11,,gcc_jit_context_new_function()}.
11754 @geindex gccjit;;context;;get_builtin_function (C++ function)
11755 @anchor{cp/topics/functions gccjit context get_builtin_function__cCP}@anchor{16e}
11756 @deffn {C++ Function} gccjit::function gccjit::context::get_builtin_function (const char* name)
11758 This is a wrapper around the C API's
11759 @pxref{bb,,gcc_jit_context_get_builtin_function()}.
11762 @geindex gccjit;;function;;get_param (C++ function)
11763 @anchor{cp/topics/functions gccjit function get_param__iC}@anchor{16f}
11764 @deffn {C++ Function} gccjit::param gccjit::function::get_param (int index) const
11766 Get the param of the given index (0-based).
11769 @geindex gccjit;;function;;dump_to_dot (C++ function)
11770 @anchor{cp/topics/functions gccjit function dump_to_dot__cCP}@anchor{ea}
11771 @deffn {C++ Function} void gccjit::function::dump_to_dot (const char* path)
11773 Emit the function in graphviz format to the given path.
11776 @geindex gccjit;;function;;new_local (C++ function)
11777 @anchor{cp/topics/functions gccjit function new_local__gccjit type cCP gccjit location}@anchor{e1}
11778 @deffn {C++ Function} gccjit::lvalue gccjit::function::new_local (gccjit::type type, const char* name, gccjit::location loc)
11780 Create a new local variable within the function, of the given type and
11784 @node Blocks<2>,Statements<2>,Functions<2>,Creating and using functions<2>
11785 @anchor{cp/topics/functions blocks}@anchor{170}
11786 @subsubsection Blocks
11789 @geindex gccjit;;block (C++ class)
11790 @anchor{cp/topics/functions gccjit block}@anchor{171}
11791 @deffn {C++ Class} gccjit::block
11793 A @cite{gccjit::block} represents a basic block within a function i.e. a
11794 sequence of statements with a single entry point and a single exit
11797 @pxref{171,,gccjit;;block} is a subclass of @pxref{110,,gccjit;;object}.
11799 The first basic block that you create within a function will
11802 Each basic block that you create within a function must be
11803 terminated, either with a conditional, a jump, or a return.
11805 It's legal to have multiple basic blocks that return within
11809 @geindex gccjit;;function;;new_block (C++ function)
11810 @anchor{cp/topics/functions gccjit function new_block__cCP}@anchor{172}
11811 @deffn {C++ Function} gccjit::block gccjit::function::new_block (const char* name)
11813 Create a basic block of the given name. The name may be NULL, but
11814 providing meaningful names is often helpful when debugging: it may
11815 show up in dumps of the internal representation, and in error
11819 @node Statements<2>,,Blocks<2>,Creating and using functions<2>
11820 @anchor{cp/topics/functions statements}@anchor{173}
11821 @subsubsection Statements
11824 @geindex gccjit;;block;;add_eval (C++ function)
11825 @anchor{cp/topics/functions gccjit block add_eval__gccjit rvalue gccjit location}@anchor{15a}
11826 @deffn {C++ Function} void gccjit::block::add_eval (gccjit::rvalue rvalue, gccjit::location loc)
11828 Add evaluation of an rvalue, discarding the result
11829 (e.g. a function call that "returns" void).
11831 This is equivalent to this C code:
11840 @geindex gccjit;;block;;add_assignment (C++ function)
11841 @anchor{cp/topics/functions gccjit block add_assignment__gccjit lvalue gccjit rvalue gccjit location}@anchor{e3}
11842 @deffn {C++ Function} void gccjit::block::add_assignment (gccjit::lvalue lvalue, gccjit::rvalue rvalue, gccjit::location loc)
11844 Add evaluation of an rvalue, assigning the result to the given
11847 This is roughly equivalent to this C code:
11856 @geindex gccjit;;block;;add_assignment_op (C++ function)
11857 @anchor{cp/topics/functions gccjit block add_assignment_op__gccjit lvalue enum gccjit rvalue gccjit location}@anchor{e7}
11858 @deffn {C++ Function} void gccjit::block::add_assignment_op (gccjit::lvalue lvalue, enum gcc_jit_binary_op, gccjit::rvalue rvalue, gccjit::location loc)
11860 Add evaluation of an rvalue, using the result to modify an
11863 This is analogous to "+=" and friends:
11877 loop_body.add_assignment_op (
11879 GCC_JIT_BINARY_OP_PLUS,
11880 ctxt.one (int_type));
11886 @geindex gccjit;;block;;add_comment (C++ function)
11887 @anchor{cp/topics/functions gccjit block add_comment__cCP gccjit location}@anchor{f2}
11888 @deffn {C++ Function} void gccjit::block::add_comment (const char* text, gccjit::location loc)
11890 Add a no-op textual comment to the internal representation of the
11891 code. It will be optimized away, but will be visible in the dumps
11892 seen via @pxref{5e,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}
11893 and @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE},
11894 and thus may be of use when debugging how your project's internal
11895 representation gets converted to the libgccjit IR.
11897 Parameter "loc" is optional.
11900 @geindex gccjit;;block;;end_with_conditional (C++ function)
11901 @anchor{cp/topics/functions gccjit block end_with_conditional__gccjit rvalue gccjit block gccjit block gccjit location}@anchor{e6}
11902 @deffn {C++ Function} void gccjit::block::end_with_conditional (gccjit::rvalue boolval, gccjit::block on_true, gccjit::block on_false, gccjit::location loc)
11904 Terminate a block by adding evaluation of an rvalue, branching on the
11905 result to the appropriate successor block.
11907 This is roughly equivalent to this C code:
11918 block, boolval, on_true, and on_false must be non-NULL.
11921 @geindex gccjit;;block;;end_with_jump (C++ function)
11922 @anchor{cp/topics/functions gccjit block end_with_jump__gccjit block gccjit location}@anchor{174}
11923 @deffn {C++ Function} void gccjit::block::end_with_jump (gccjit::block target, gccjit::location loc)
11925 Terminate a block by adding a jump to the given target block.
11927 This is roughly equivalent to this C code:
11936 @geindex gccjit;;block;;end_with_return (C++ function)
11937 @anchor{cp/topics/functions gccjit block end_with_return__gccjit rvalue gccjit location}@anchor{175}
11938 @deffn {C++ Function} void gccjit::block::end_with_return (gccjit::rvalue rvalue, gccjit::location loc)
11942 Both params are optional.
11944 An rvalue must be provided for a function returning non-void, and
11945 must not be provided by a function "returning" @cite{void}.
11947 If an rvalue is provided, the block is terminated by evaluating the
11948 rvalue and returning the value.
11950 This is roughly equivalent to this C code:
11958 If an rvalue is not provided, the block is terminated by adding a
11959 valueless return, for use within a function with "void" return type.
11961 This is equivalent to this C code:
11970 @c Copyright (C) 2014 Free Software Foundation, Inc.
11971 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
11973 @c This is free software: you can redistribute it and/or modify it
11974 @c under the terms of the GNU General Public License as published by
11975 @c the Free Software Foundation, either version 3 of the License, or
11976 @c (at your option) any later version.
11978 @c This program is distributed in the hope that it will be useful, but
11979 @c WITHOUT ANY WARRANTY; without even the implied warranty of
11980 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11981 @c General Public License for more details.
11983 @c You should have received a copy of the GNU General Public License
11984 @c along with this program. If not, see
11985 @c <http://www.gnu.org/licenses/>.
11987 @node Source Locations<2>,Compilation results<2>,Creating and using functions<2>,Topic Reference<2>
11988 @anchor{cp/topics/locations source-locations}@anchor{176}@anchor{cp/topics/locations doc}@anchor{177}
11989 @subsection Source Locations
11992 @geindex gccjit;;location (C++ class)
11993 @anchor{cp/topics/locations gccjit location}@anchor{108}
11994 @deffn {C++ Class} gccjit::location
11996 A @cite{gccjit::location} encapsulates a source code location, so that
11997 you can (optionally) associate locations in your language with
11998 statements in the JIT-compiled code, allowing the debugger to
11999 single-step through your language.
12001 @cite{gccjit::location} instances are optional: you can always omit them
12002 from any C++ API entrypoint accepting one.
12004 You can construct them using @pxref{f6,,gccjit;;context;;new_location()}.
12006 You need to enable @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
12007 @pxref{100,,gccjit;;context} for these locations to actually be usable by
12011 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1);
12017 @geindex gccjit;;context;;new_location (C++ function)
12018 @anchor{cp/topics/locations gccjit context new_location__cCP i i}@anchor{f6}
12019 @deffn {C++ Function} gccjit::location gccjit::context::new_location (const char* filename, int line, int column)
12021 Create a @cite{gccjit::location} instance representing the given source
12026 * Faking it: Faking it<2>.
12030 @node Faking it<2>,,,Source Locations<2>
12031 @anchor{cp/topics/locations faking-it}@anchor{178}
12032 @subsubsection Faking it
12035 If you don't have source code for your internal representation, but need
12036 to debug, you can generate a C-like representation of the functions in
12037 your context using @pxref{107,,gccjit;;context;;dump_to_file()}:
12040 ctxt.dump_to_file ("/tmp/something.c",
12041 1 /* update_locations */);
12046 This will dump C-like code to the given path. If the @cite{update_locations}
12047 argument is true, this will also set up @cite{gccjit::location} information
12048 throughout the context, pointing at the dump file as if it were a source
12049 file, giving you @emph{something} you can step through in the debugger.
12051 @c Copyright (C) 2014 Free Software Foundation, Inc.
12052 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
12054 @c This is free software: you can redistribute it and/or modify it
12055 @c under the terms of the GNU General Public License as published by
12056 @c the Free Software Foundation, either version 3 of the License, or
12057 @c (at your option) any later version.
12059 @c This program is distributed in the hope that it will be useful, but
12060 @c WITHOUT ANY WARRANTY; without even the implied warranty of
12061 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12062 @c General Public License for more details.
12064 @c You should have received a copy of the GNU General Public License
12065 @c along with this program. If not, see
12066 @c <http://www.gnu.org/licenses/>.
12068 @node Compilation results<2>,,Source Locations<2>,Topic Reference<2>
12069 @anchor{cp/topics/results compilation-results}@anchor{179}@anchor{cp/topics/results doc}@anchor{17a}
12070 @subsection Compilation results
12073 @geindex gcc_jit_result (C++ type)
12074 @anchor{cp/topics/results gcc_jit_result}@anchor{17b}
12075 @deffn {C++ Type} gcc_jit_result
12077 A @cite{gcc_jit_result} encapsulates the result of compiling a context.
12080 @geindex gccjit;;context;;compile (C++ function)
12081 @anchor{cp/topics/results gccjit context compile}@anchor{d9}
12082 @deffn {C++ Function} @pxref{17b,,gcc_jit_result*} gccjit::context::compile ()
12084 This calls into GCC and builds the code, returning a
12085 @cite{gcc_jit_result *}.
12088 @geindex gcc_jit_result_get_code (C++ function)
12089 @anchor{cp/topics/results gcc_jit_result_get_code__gcc_jit_resultP cCP}@anchor{17c}
12090 @deffn {C++ Function} void* gcc_jit_result_get_code (gcc_jit_result* result, const char* funcname)
12092 Locate a given function within the built machine code.
12093 This will need to be cast to a function pointer of the
12094 correct type before it can be called.
12097 @geindex gcc_jit_result_release (C++ function)
12098 @anchor{cp/topics/results gcc_jit_result_release__gcc_jit_resultP}@anchor{17d}
12099 @deffn {C++ Function} void gcc_jit_result_release (gcc_jit_result* result)
12101 Once we're done with the code, this unloads the built .so file.
12102 This cleans up the result; after calling this, it's no longer
12103 valid to use the result.
12106 @c Copyright (C) 2014 Free Software Foundation, Inc.
12107 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
12109 @c This is free software: you can redistribute it and/or modify it
12110 @c under the terms of the GNU General Public License as published by
12111 @c the Free Software Foundation, either version 3 of the License, or
12112 @c (at your option) any later version.
12114 @c This program is distributed in the hope that it will be useful, but
12115 @c WITHOUT ANY WARRANTY; without even the implied warranty of
12116 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12117 @c General Public License for more details.
12119 @c You should have received a copy of the GNU General Public License
12120 @c along with this program. If not, see
12121 @c <http://www.gnu.org/licenses/>.
12123 @node Internals,Indices and tables,C++ bindings for libgccjit,Top
12124 @anchor{internals/index internals}@anchor{17e}@anchor{internals/index doc}@anchor{17f}
12129 * Working on the JIT library::
12130 * Running the test suite::
12131 * Environment variables::
12132 * Overview of code structure::
12136 @node Working on the JIT library,Running the test suite,,Internals
12137 @anchor{internals/index working-on-the-jit-library}@anchor{180}
12138 @section Working on the JIT library
12141 Having checked out the source code (to "src"), you can configure and build
12142 the JIT library like this:
12147 PREFIX=$(pwd)/install
12150 --enable-host-shared \
12151 --enable-languages=jit,c++ \
12152 --disable-bootstrap \
12153 --enable-checking=release \
12155 nice make -j4 # altering the "4" to however many cores you have
12160 This should build a libgccjit.so within jit/build/gcc:
12163 [build] $ file gcc/libgccjit.so*
12164 gcc/libgccjit.so: symbolic link to `libgccjit.so.0'
12165 gcc/libgccjit.so.0: symbolic link to `libgccjit.so.0.0.1'
12166 gcc/libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, not stripped
12171 Here's what those configuration options mean:
12173 @geindex command line option; --enable-host-shared
12174 @anchor{internals/index cmdoption--enable-host-shared}@anchor{181}
12175 @deffn {Option} --enable-host-shared
12177 Configuring with this option means that the compiler is built as
12178 position-independent code, which incurs a slight performance hit,
12179 but it necessary for a shared library.
12182 @geindex command line option; --enable-languages=jit@comma{}c++
12183 @anchor{internals/index cmdoption--enable-languages}@anchor{182}
12184 @deffn {Option} --enable-languages=jit,c++
12186 This specifies which frontends to build. The JIT library looks like
12187 a frontend to the rest of the code.
12189 The C++ portion of the JIT test suite requires the C++ frontend to be
12190 enabled at configure-time, or you may see errors like this when
12191 running the test suite:
12194 xgcc: error: /home/david/jit/src/gcc/testsuite/jit.dg/test-quadratic.cc: C++ compiler not installed on this system
12195 c++: error trying to exec 'cc1plus': execvp: No such file or directory
12201 @geindex command line option; --disable-bootstrap
12202 @anchor{internals/index cmdoption--disable-bootstrap}@anchor{183}
12203 @deffn {Option} --disable-bootstrap
12205 For hacking on the "jit" subdirectory, performing a full
12206 bootstrap can be overkill, since it's unused by a bootstrap. However,
12207 when submitting patches, you should remove this option, to ensure that
12208 the compiler can still bootstrap itself.
12211 @geindex command line option; --enable-checking=release
12212 @anchor{internals/index cmdoption--enable-checking}@anchor{184}
12213 @deffn {Option} --enable-checking=release
12215 The compile can perform extensive self-checking as it runs, useful when
12216 debugging, but slowing things down.
12218 For maximum speed, configure with @code{--enable-checking=release} to
12219 disable this self-checking.
12222 @node Running the test suite,Environment variables,Working on the JIT library,Internals
12223 @anchor{internals/index running-the-test-suite}@anchor{185}
12224 @section Running the test suite
12229 [gcc] $ make check-jit RUNTESTFLAGS="-v -v -v"
12234 A summary of the tests can then be seen in:
12237 jit/build/gcc/testsuite/jit/jit.sum
12242 and detailed logs in:
12245 jit/build/gcc/testsuite/jit/jit.log
12250 The test executables can be seen as:
12253 jit/build/gcc/testsuite/jit/*.exe
12258 which can be run independently.
12260 You can compile and run individual tests by passing "jit.exp=TESTNAME" to RUNTESTFLAGS e.g.:
12263 [gcc] $ make check-jit RUNTESTFLAGS="-v -v -v jit.exp=test-factorial.c"
12268 and once a test has been compiled, you can debug it directly:
12271 [gcc] $ PATH=.:$PATH \
12272 LD_LIBRARY_PATH=. \
12275 testsuite/jit/test-factorial.c.exe
12281 * Running under valgrind::
12285 @node Running under valgrind,,,Running the test suite
12286 @anchor{internals/index running-under-valgrind}@anchor{186}
12287 @subsection Running under valgrind
12290 The jit testsuite detects if RUN_UNDER_VALGRIND is present in the
12291 environment (with any value). If it is present, it runs the test client
12292 code under valgrind@footnote{http://valgrind.org},
12293 specifcally, the default
12294 memcheck@footnote{http://valgrind.org/docs/manual/mc-manual.html}
12296 --leak-check=full@footnote{http://valgrind.org/docs/manual/mc-manual.html#opt.leak-check}.
12298 It automatically parses the output from valgrind, injecting XFAIL results if
12299 any issues are found, or PASS results if the output is clean. The output
12300 is saved to @code{TESTNAME.exe.valgrind.txt}.
12302 For example, the following invocation verbosely runs the testcase
12303 @code{test-sum-of-squares.c} under valgrind, showing an issue:
12306 $ RUN_UNDER_VALGRIND= \
12308 RUNTESTFLAGS="-v -v -v jit.exp=test-sum-of-squares.c"
12310 (...verbose log contains detailed valgrind errors, if any...)
12312 === jit Summary ===
12314 # of expected passes 28
12315 # of expected failures 2
12317 $ less testsuite/jit/jit.sum
12318 (...other results...)
12319 XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.c.exe.valgrind.txt: definitely lost: 8 bytes in 1 blocks
12320 XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.c.exe.valgrind.txt: unsuppressed errors: 1
12321 (...other results...)
12323 $ less testsuite/jit/test-sum-of-squares.c.exe.valgrind.txt
12324 (...shows full valgrind report for this test case...)
12329 When running under valgrind, it's best to have configured gcc with
12330 @code{--enable-valgrind-annotations}, which automatically suppresses
12331 various known false positives.
12333 @node Environment variables,Overview of code structure,Running the test suite,Internals
12334 @anchor{internals/index environment-variables}@anchor{187}
12335 @section Environment variables
12338 When running client code against a locally-built libgccjit, three
12339 environment variables need to be set up:
12341 @geindex environment variable; LD_LIBRARY_PATH
12342 @anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{188}
12343 @deffn {Environment Variable} LD_LIBRARY_PATH
12347 @cite{libgccjit.so} is dynamically linked into client code, so if running
12348 against a locally-built library, @code{LD_LIBRARY_PATH} needs to be set
12349 up appropriately. The library can be found within the "gcc"
12350 subdirectory of the build tree:
12354 $ file libgccjit.so*
12355 libgccjit.so: symbolic link to `libgccjit.so.0'
12356 libgccjit.so.0: symbolic link to `libgccjit.so.0.0.1'
12357 libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (GNU/Linux), dynamically linked, not stripped
12363 @geindex environment variable; PATH
12364 @anchor{internals/index envvar-PATH}@anchor{189}
12365 @deffn {Environment Variable} PATH
12367 The library uses a driver executable for converting from .s assembler
12368 files to .so shared libraries. Specifically, it looks for a name
12370 @code{$@{target_noncanonical@}-gcc-$@{gcc_BASEVER@}$@{exeext@}}
12371 such as @code{x86_64-unknown-linux-gnu-gcc-5.0.0}.
12373 Hence @code{PATH} needs to include a directory where the library can
12374 locate this executable.
12376 The executable is normally installed to the installation bindir
12377 (e.g. /usr/bin), but a copy is also created within the "gcc"
12378 subdirectory of the build tree for running the testsuite, and for ease
12382 @geindex environment variable; LIBRARY_PATH
12383 @anchor{internals/index envvar-LIBRARY_PATH}@anchor{18a}
12384 @deffn {Environment Variable} LIBRARY_PATH
12386 The driver executable invokes the linker, and the latter needs to locate
12387 support libraries needed by the generated code, or you will see errors
12391 ld: cannot find crtbeginS.o: No such file or directory
12392 ld: cannot find -lgcc
12393 ld: cannot find -lgcc_s
12398 Hence if running directly from a locally-built copy (without installing),
12399 @code{LIBRARY_PATH} needs to contain the "gcc" subdirectory of the build
12403 For example, to run a binary that uses the library against a non-installed
12404 build of the library in LIBGCCJIT_BUILD_DIR you need an invocation of the
12405 client code like this, to preprend the dir to each of the environment
12409 $ LD_LIBRARY_PATH=$(LIBGCCJIT_BUILD_DIR):$(LD_LIBRARY_PATH) \
12410 PATH=$(LIBGCCJIT_BUILD_DIR):$(PATH) \
12411 LIBRARY_PATH=$(LIBGCCJIT_BUILD_DIR):$(LIBRARY_PATH) \
12418 @node Overview of code structure,,Environment variables,Internals
12419 @anchor{internals/index overview-of-code-structure}@anchor{18b}
12420 @section Overview of code structure
12427 @code{libgccjit.c} implements the API entrypoints. It performs error
12428 checking, then calls into classes of the gcc::jit::recording namespace
12429 within @code{jit-recording.c} and @code{jit-recording.h}.
12432 The gcc::jit::recording classes (within @code{jit-recording.c} and
12433 @code{jit-recording.h}) record the API calls that are made:
12439 /* Indentation indicates inheritance: */
12445 class function_type;
12446 class compound_type;
12467 When the context is compiled, the gcc::jit::playback classes (within
12468 @code{jit-playback.c} and @code{jit-playback.h}) replay the API calls
12469 within langhook:parse_file:
12475 /* Indentation indicates inheritance: */
12479 class compound_type;
12496 Client Code . Generated . libgccjit.so
12498 . . JIT API . JIT "Frontend". (libbackend.a)
12499 ....................................................................................
12501 ──────────────────────────> . .
12504 . . ──> libgccjit.c .
12505 . . │ (error-checking).
12507 . . ──> jit-recording.c
12508 . . (record API calls)
12509 . . <─────── .
12511 <─────────────────────────── . .
12514 V . . gcc_jit_context_compile .
12515 ──────────────────────────> . .
12516 . . │ start of recording::context::compile ()
12518 . . │ start of playback::context::compile ()
12519 . . │ (create tempdir) .
12521 . . │ ACQUIRE MUTEX .
12523 . . V───────────────────────> toplev::main (for now)
12525 . . . . (various code)
12528 . . . <───────────────── langhook:parse_file
12530 . . . │ (jit_langhook_parse_file)
12532 ..........................................│..................VVVVVVVVVVVVV...
12533 . . . │ . No GC in here
12534 . . . │ jit-playback.c
12535 . . . │ (playback of API calls)
12536 . . . ───────────────> creation of functions,
12537 . . . . types, expression trees
12538 . . . <──────────────── etc
12539 . . . │(handle_locations: add locations to
12540 . . . │ linemap and associate them with trees)
12542 . . . │ . No GC in here
12543 ..........................................│..................AAAAAAAAAAAAA...
12544 . . . │ for each function
12545 . . . ──> postprocess
12547 . . . ────────────> cgraph_finalize_function
12548 . . . <────────────
12551 . . . ──────────────────> (end of
12552 . . . . │ langhook_parse_file)
12554 . . . . (various code)
12557 . . . <───────────────── langhook:write_globals
12559 . . . │ (jit_langhook_write_globals)
12562 . . . ──────────────────> finalize_compilation_unit
12564 . . . . (the middle─end and backend)
12566 . . <───────────────────────────── end of toplev::main
12568 . . V───────────────────────> toplev::finalize
12569 . . . . │ (purge internal state)
12570 . . <──────────────────────── end of toplev::finalize
12572 . . │ Convert assembler to DSO ("fake.so")
12574 . . │ Load DSO (dlopen "fake.so")
12576 . . │ RELEASE MUTEX .
12578 . . │ end of playback::context::compile ()
12580 . . │ playback::context dtor
12582 . . │ Normally we cleanup the tempdir here:
12583 . . │ ("fake.so" is unlinked from the
12584 . . │ filesystem at this point)
12585 . . │ If the client code requested debuginfo, the
12586 . . │ cleanup happens later (in gcc_jit_result_release)
12587 . . │ to make it easier on the debugger (see PR jit/64206)
12590 . . │ end of recording::context::compile ()
12591 <─────────────────────────── . .
12593 V . . gcc_jit_result_get_code .
12594 ──────────────────────────> . .
12595 . . │ dlsym () within loaded DSO
12596 <─────────────────────────── . .
12599 │ Call it . . . .
12600 ───────────────> . . .
12603 <─────────────── . . .
12607 V . . gcc_jit_result_release .
12608 ──────────────────────────> . .
12609 . . │ dlclose () the loaded DSO
12610 . . │ (code becomes uncallable)
12612 . . │ If the client code requested debuginfo, then
12613 . . │ cleanup of the tempdir was delayed.
12614 . . │ If that was the case, clean it up now.
12615 <─────────────────────────── . .
12624 Here is a high-level summary from @code{jit-common.h}:
12628 In order to allow jit objects to be usable outside of a compile
12629 whilst working with the existing structure of GCC's code the
12630 C API is implemented in terms of a gcc::jit::recording::context,
12631 which records the calls made to it.
12633 When a gcc_jit_context is compiled, the recording context creates a
12634 playback context. The playback context invokes the bulk of the GCC
12635 code, and within the "frontend" parsing hook, plays back the recorded
12636 API calls, creating GCC tree objects.
12638 So there are two parallel families of classes: those relating to
12639 recording, and those relating to playback:
12645 Visibility: recording objects are exposed back to client code,
12646 whereas playback objects are internal to the library.
12649 Lifetime: recording objects have a lifetime equal to that of the
12650 recording context that created them, whereas playback objects only
12651 exist within the frontend hook.
12654 Memory allocation: recording objects are allocated by the recording
12655 context, and automatically freed by it when the context is released,
12656 whereas playback objects are allocated within the GC heap, and
12657 garbage-collected; they can own GC-references.
12660 Integration with rest of GCC: recording objects are unrelated to the
12661 rest of GCC, whereas playback objects are wrappers around "tree"
12662 instances. Hence you can't ask a recording rvalue or lvalue what its
12663 type is, whereas you can for a playback rvalue of lvalue (since it
12664 can work with the underlying GCC tree nodes).
12667 Instancing: There can be multiple recording contexts "alive" at once
12668 (albeit it only one compiling at once), whereas there can only be one
12669 playback context alive at one time (since it interacts with the GC).
12672 Ultimately if GCC could support multiple GC heaps and contexts, and
12673 finer-grained initialization, then this recording vs playback
12674 distinction could be eliminated.
12676 During a playback, we associate objects from the recording with
12677 their counterparts during this playback. For simplicity, we store this
12678 within the recording objects, as @code{void *m_playback_obj}, casting it to
12679 the appropriate playback object subclass. For these casts to make
12680 sense, the two class hierarchies need to have the same structure.
12682 Note that the playback objects that @code{m_playback_obj} points to are
12683 GC-allocated, but the recording objects don't own references:
12684 these associations only exist within a part of the code where
12685 the GC doesn't collect, and are set back to NULL before the GC can
12688 @anchor{internals/index example-of-log-file}@anchor{55}
12689 Another way to understand the structure of the code is to enable logging,
12690 via @pxref{54,,gcc_jit_context_set_logfile()}. Here is an example of a log
12691 generated via this call:
12694 JIT: entering: gcc_jit_context_set_str_option
12695 JIT: exiting: gcc_jit_context_set_str_option
12696 JIT: entering: gcc_jit_context_set_int_option
12697 JIT: exiting: gcc_jit_context_set_int_option
12698 JIT: entering: gcc_jit_context_set_bool_option
12699 JIT: exiting: gcc_jit_context_set_bool_option
12700 JIT: entering: gcc_jit_context_set_bool_option
12701 JIT: exiting: gcc_jit_context_set_bool_option
12702 JIT: entering: gcc_jit_context_set_bool_option
12703 JIT: exiting: gcc_jit_context_set_bool_option
12704 JIT: entering: gcc_jit_context_set_bool_option
12705 JIT: exiting: gcc_jit_context_set_bool_option
12706 JIT: entering: gcc_jit_context_set_bool_option
12707 JIT: exiting: gcc_jit_context_set_bool_option
12708 JIT: entering: gcc_jit_context_get_type
12709 JIT: exiting: gcc_jit_context_get_type
12710 JIT: entering: gcc_jit_context_get_type
12711 JIT: exiting: gcc_jit_context_get_type
12712 JIT: entering: gcc_jit_context_new_param
12713 JIT: exiting: gcc_jit_context_new_param
12714 JIT: entering: gcc_jit_context_new_function
12715 JIT: exiting: gcc_jit_context_new_function
12716 JIT: entering: gcc_jit_context_new_param
12717 JIT: exiting: gcc_jit_context_new_param
12718 JIT: entering: gcc_jit_context_get_type
12719 JIT: exiting: gcc_jit_context_get_type
12720 JIT: entering: gcc_jit_context_new_function
12721 JIT: exiting: gcc_jit_context_new_function
12722 JIT: entering: gcc_jit_context_new_string_literal
12723 JIT: exiting: gcc_jit_context_new_string_literal
12724 JIT: entering: gcc_jit_function_new_block
12725 JIT: exiting: gcc_jit_function_new_block
12726 JIT: entering: gcc_jit_block_add_comment
12727 JIT: exiting: gcc_jit_block_add_comment
12728 JIT: entering: gcc_jit_context_new_call
12729 JIT: exiting: gcc_jit_context_new_call
12730 JIT: entering: gcc_jit_block_add_eval
12731 JIT: exiting: gcc_jit_block_add_eval
12732 JIT: entering: gcc_jit_block_end_with_void_return
12733 JIT: exiting: gcc_jit_block_end_with_void_return
12734 JIT: entering: gcc_jit_context_compile
12735 JIT: compiling ctxt: 0x1283e20
12736 JIT: entering: gcc::jit::result* gcc::jit::recording::context::compile()
12737 JIT: entering: void gcc::jit::recording::context::validate()
12738 JIT: exiting: void gcc::jit::recording::context::validate()
12739 JIT: entering: gcc::jit::playback::context::context(gcc::jit::recording::context*)
12740 JIT: exiting: gcc::jit::playback::context::context(gcc::jit::recording::context*)
12741 JIT: entering: gcc::jit::result* gcc::jit::playback::context::compile()
12742 JIT: entering: gcc::jit::tempdir::tempdir(gcc::jit::logger*, int)
12743 JIT: exiting: gcc::jit::tempdir::tempdir(gcc::jit::logger*, int)
12744 JIT: entering: bool gcc::jit::tempdir::create()
12745 JIT: m_path_template: /tmp/libgccjit-XXXXXX
12746 JIT: m_path_tempdir: /tmp/libgccjit-CKq1M9
12747 JIT: exiting: bool gcc::jit::tempdir::create()
12748 JIT: entering: void gcc::jit::playback::context::make_fake_args(vec<char*>*, const char*, vec<gcc::jit::recording::requested_dump>*)
12749 JIT: exiting: void gcc::jit::playback::context::make_fake_args(vec<char*>*, const char*, vec<gcc::jit::recording::requested_dump>*)
12750 JIT: entering: void gcc::jit::playback::context::acquire_mutex()
12751 JIT: exiting: void gcc::jit::playback::context::acquire_mutex()
12752 JIT: entering: toplev::main
12753 JIT: argv[0]: ./test-hello-world.c.exe
12754 JIT: argv[1]: /tmp/libgccjit-CKq1M9/fake.c
12755 JIT: argv[2]: -fPIC
12758 JIT: argv[5]: -quiet
12759 JIT: argv[6]: --param
12760 JIT: argv[7]: ggc-min-expand=0
12761 JIT: argv[8]: --param
12762 JIT: argv[9]: ggc-min-heapsize=0
12763 JIT: entering: bool jit_langhook_init()
12764 JIT: exiting: bool jit_langhook_init()
12765 JIT: entering: void gcc::jit::playback::context::replay()
12766 JIT: entering: void gcc::jit::recording::context::replay_into(gcc::jit::replayer*)
12767 JIT: exiting: void gcc::jit::recording::context::replay_into(gcc::jit::replayer*)
12768 JIT: entering: void gcc::jit::recording::context::disassociate_from_playback()
12769 JIT: exiting: void gcc::jit::recording::context::disassociate_from_playback()
12770 JIT: entering: void gcc::jit::playback::context::handle_locations()
12771 JIT: exiting: void gcc::jit::playback::context::handle_locations()
12772 JIT: entering: void gcc::jit::playback::function::build_stmt_list()
12773 JIT: exiting: void gcc::jit::playback::function::build_stmt_list()
12774 JIT: entering: void gcc::jit::playback::function::build_stmt_list()
12775 JIT: exiting: void gcc::jit::playback::function::build_stmt_list()
12776 JIT: entering: void gcc::jit::playback::function::postprocess()
12777 JIT: exiting: void gcc::jit::playback::function::postprocess()
12778 JIT: entering: void gcc::jit::playback::function::postprocess()
12779 JIT: exiting: void gcc::jit::playback::function::postprocess()
12780 JIT: exiting: void gcc::jit::playback::context::replay()
12781 JIT: entering: void jit_langhook_write_globals()
12782 JIT: exiting: void jit_langhook_write_globals()
12783 JIT: exiting: toplev::main
12784 JIT: entering: void gcc::jit::playback::context::extract_any_requested_dumps(vec<gcc::jit::recording::requested_dump>*)
12785 JIT: exiting: void gcc::jit::playback::context::extract_any_requested_dumps(vec<gcc::jit::recording::requested_dump>*)
12786 JIT: entering: toplev::finalize
12787 JIT: exiting: toplev::finalize
12788 JIT: entering: void gcc::jit::playback::context::convert_to_dso(const char*)
12789 JIT: argv[0]: x86_64-unknown-linux-gnu-gcc-5.0.0
12790 JIT: argv[1]: -shared
12791 JIT: argv[2]: /tmp/libgccjit-CKq1M9/fake.s
12793 JIT: argv[4]: /tmp/libgccjit-CKq1M9/fake.so
12794 JIT: argv[5]: -fno-use-linker-plugin
12795 JIT: argv[6]: (null)
12796 JIT: exiting: void gcc::jit::playback::context::convert_to_dso(const char*)
12797 JIT: entering: gcc::jit::result* gcc::jit::playback::context::dlopen_built_dso()
12798 JIT: GCC_JIT_BOOL_OPTION_DEBUGINFO was set: handing over tempdir to jit::result
12799 JIT: entering: gcc::jit::result::result(gcc::jit::logger*, void*, gcc::jit::tempdir*)
12800 JIT: exiting: gcc::jit::result::result(gcc::jit::logger*, void*, gcc::jit::tempdir*)
12801 JIT: exiting: gcc::jit::result* gcc::jit::playback::context::dlopen_built_dso()
12802 JIT: entering: void gcc::jit::playback::context::release_mutex()
12803 JIT: exiting: void gcc::jit::playback::context::release_mutex()
12804 JIT: exiting: gcc::jit::result* gcc::jit::playback::context::compile()
12805 JIT: entering: gcc::jit::playback::context::~context()
12806 JIT: exiting: gcc::jit::playback::context::~context()
12807 JIT: exiting: gcc::jit::result* gcc::jit::recording::context::compile()
12808 JIT: gcc_jit_context_compile: returning (gcc_jit_result *)0x12f75d0
12809 JIT: exiting: gcc_jit_context_compile
12810 JIT: entering: gcc_jit_result_get_code
12811 JIT: locating fnname: hello_world
12812 JIT: entering: void* gcc::jit::result::get_code(const char*)
12813 JIT: exiting: void* gcc::jit::result::get_code(const char*)
12814 JIT: gcc_jit_result_get_code: returning (void *)0x7ff6b8cd87f0
12815 JIT: exiting: gcc_jit_result_get_code
12816 JIT: entering: gcc_jit_context_release
12817 JIT: deleting ctxt: 0x1283e20
12818 JIT: entering: gcc::jit::recording::context::~context()
12819 JIT: exiting: gcc::jit::recording::context::~context()
12820 JIT: exiting: gcc_jit_context_release
12821 JIT: entering: gcc_jit_result_release
12822 JIT: deleting result: 0x12f75d0
12823 JIT: entering: virtual gcc::jit::result::~result()
12824 JIT: entering: gcc::jit::tempdir::~tempdir()
12825 JIT: unlinking .s file: /tmp/libgccjit-CKq1M9/fake.s
12826 JIT: unlinking .so file: /tmp/libgccjit-CKq1M9/fake.so
12827 JIT: removing tempdir: /tmp/libgccjit-CKq1M9
12828 JIT: exiting: gcc::jit::tempdir::~tempdir()
12829 JIT: exiting: virtual gcc::jit::result::~result()
12830 JIT: exiting: gcc_jit_result_release
12831 JIT: gcc::jit::logger::~logger()
12837 @node Indices and tables,Index,Internals,Top
12838 @anchor{index indices-and-tables}@anchor{18c}
12839 @unnumbered Indices and tables
12857 @c The Sphinx C domain appears to lack explicit support for enum values,
12858 @c so I've been using :c:macro: for them.
12860 @c See http://sphinx-doc.org/domains.html#the-c-domain
12862 @node Index,,Indices and tables,Top