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 20150113), January 13, 2015
26 Copyright @copyright{} 2014-2015 Free Software Foundation, Inc.
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-2015 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-2015 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::
324 Running the test suite
326 * Running under valgrind::
332 @node Tutorial,Topic Reference,Top,Top
333 @anchor{intro/index libgccjit}@anchor{1}@anchor{intro/index doc}@anchor{2}@anchor{intro/index tutorial}@anchor{3}
337 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
338 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
340 @c This is free software: you can redistribute it and/or modify it
341 @c under the terms of the GNU General Public License as published by
342 @c the Free Software Foundation, either version 3 of the License, or
343 @c (at your option) any later version.
345 @c This program is distributed in the hope that it will be useful, but
346 @c WITHOUT ANY WARRANTY; without even the implied warranty of
347 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
348 @c General Public License for more details.
350 @c You should have received a copy of the GNU General Public License
351 @c along with this program. If not, see
352 @c <http://www.gnu.org/licenses/>.
355 * Tutorial part 1; "Hello world": Tutorial part 1 "Hello world".
356 * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function.
357 * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables.
358 * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter.
362 @node Tutorial part 1 "Hello world",Tutorial part 2 Creating a trivial machine code function,,Tutorial
363 @anchor{intro/tutorial01 doc}@anchor{4}@anchor{intro/tutorial01 tutorial-part-1-hello-world}@anchor{5}
364 @section Tutorial part 1: "Hello world"
367 Before we look at the details of the API, let's look at building and
368 running programs that use the library.
370 Here's a toy "hello world" program that uses the library to synthesize
371 a call to @cite{printf} and uses it to write a message to stdout.
373 Don't worry about the content of the program for now; we'll cover
374 the details in later parts of this tutorial.
379 /* Smoketest example for libgccjit.so
380 Copyright (C) 2014-2015 Free Software Foundation, Inc.
382 This file is part of GCC.
384 GCC is free software; you can redistribute it and/or modify it
385 under the terms of the GNU General Public License as published by
386 the Free Software Foundation; either version 3, or (at your option)
389 GCC is distributed in the hope that it will be useful, but
390 WITHOUT ANY WARRANTY; without even the implied warranty of
391 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
392 General Public License for more details.
394 You should have received a copy of the GNU General Public License
395 along with GCC; see the file COPYING3. If not see
396 <http://www.gnu.org/licenses/>. */
398 #include <libgccjit.h>
404 create_code (gcc_jit_context *ctxt)
406 /* Let's try to inject the equivalent of:
408 greet (const char *name)
410 printf ("hello %s\n", name);
413 gcc_jit_type *void_type =
414 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_VOID);
415 gcc_jit_type *const_char_ptr_type =
416 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_CONST_CHAR_PTR);
417 gcc_jit_param *param_name =
418 gcc_jit_context_new_param (ctxt, NULL, const_char_ptr_type, "name");
419 gcc_jit_function *func =
420 gcc_jit_context_new_function (ctxt, NULL,
421 GCC_JIT_FUNCTION_EXPORTED,
427 gcc_jit_param *param_format =
428 gcc_jit_context_new_param (ctxt, NULL, const_char_ptr_type, "format");
429 gcc_jit_function *printf_func =
430 gcc_jit_context_new_function (ctxt, NULL,
431 GCC_JIT_FUNCTION_IMPORTED,
432 gcc_jit_context_get_type (
433 ctxt, GCC_JIT_TYPE_INT),
437 gcc_jit_rvalue *args[2];
438 args[0] = gcc_jit_context_new_string_literal (ctxt, "hello %s\n");
439 args[1] = gcc_jit_param_as_rvalue (param_name);
441 gcc_jit_block *block = gcc_jit_function_new_block (func, NULL);
443 gcc_jit_block_add_eval (
445 gcc_jit_context_new_call (ctxt,
449 gcc_jit_block_end_with_void_return (block, NULL);
453 main (int argc, char **argv)
455 gcc_jit_context *ctxt;
456 gcc_jit_result *result;
458 /* Get a "context" object for working with the library. */
459 ctxt = gcc_jit_context_acquire ();
462 fprintf (stderr, "NULL ctxt");
466 /* Set some options on the context.
467 Let's see the code being generated, in assembler form. */
468 gcc_jit_context_set_bool_option (
470 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
473 /* Populate the context. */
476 /* Compile the code. */
477 result = gcc_jit_context_compile (ctxt);
480 fprintf (stderr, "NULL result");
484 /* Extract the generated code from "result". */
485 typedef void (*fn_type) (const char *);
487 (fn_type)gcc_jit_result_get_code (result, "greet");
490 fprintf (stderr, "NULL greet");
494 /* Now call the generated function: */
498 gcc_jit_context_release (ctxt);
499 gcc_jit_result_release (result);
508 Copy the above to @cite{tut01-hello-world.c}.
510 Assuming you have the jit library installed, build the test program
515 tut01-hello-world.c \
516 -o tut01-hello-world \
522 You should then be able to run the built program:
525 $ ./tut01-hello-world
531 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
532 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
534 @c This is free software: you can redistribute it and/or modify it
535 @c under the terms of the GNU General Public License as published by
536 @c the Free Software Foundation, either version 3 of the License, or
537 @c (at your option) any later version.
539 @c This program is distributed in the hope that it will be useful, but
540 @c WITHOUT ANY WARRANTY; without even the implied warranty of
541 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
542 @c General Public License for more details.
544 @c You should have received a copy of the GNU General Public License
545 @c along with this program. If not, see
546 @c <http://www.gnu.org/licenses/>.
548 @node Tutorial part 2 Creating a trivial machine code function,Tutorial part 3 Loops and variables,Tutorial part 1 "Hello world",Tutorial
549 @anchor{intro/tutorial02 doc}@anchor{6}@anchor{intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{7}
550 @section Tutorial part 2: Creating a trivial machine code function
553 Consider this C function:
564 How can we construct this at run-time using libgccjit?
566 First we need to include the relevant header:
569 #include <libgccjit.h>
574 All state associated with compilation is associated with a
575 @pxref{8,,gcc_jit_context *}.
577 Create one using @pxref{9,,gcc_jit_context_acquire()}:
580 gcc_jit_context *ctxt;
581 ctxt = gcc_jit_context_acquire ();
586 The JIT library has a system of types. It is statically-typed: every
587 expression is of a specific type, fixed at compile-time. In our example,
588 all of the expressions are of the C @cite{int} type, so let's obtain this from
589 the context, as a @pxref{a,,gcc_jit_type *}, using
590 @pxref{b,,gcc_jit_context_get_type()}:
593 gcc_jit_type *int_type =
594 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
599 @pxref{a,,gcc_jit_type *} is an example of a "contextual" object: every
600 entity in the API is associated with a @pxref{8,,gcc_jit_context *}.
602 Memory management is easy: all such "contextual" objects are automatically
603 cleaned up for you when the context is released, using
604 @pxref{c,,gcc_jit_context_release()}:
607 gcc_jit_context_release (ctxt);
612 so you don't need to manually track and cleanup all objects, just the
615 Although the API is C-based, there is a form of class hierarchy, which
633 There are casting methods for upcasting from subclasses to parent classes.
634 For example, @pxref{d,,gcc_jit_type_as_object()}:
637 gcc_jit_object *obj = gcc_jit_type_as_object (int_type);
642 One thing you can do with a @pxref{e,,gcc_jit_object *} is
643 to ask it for a human-readable description, using
644 @pxref{f,,gcc_jit_object_get_debug_string()}:
647 printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj));
652 giving this text on stdout:
660 This is invaluable when debugging.
662 Let's create the function. To do so, we first need to construct
663 its single parameter, specifying its type and giving it a name,
664 using @pxref{10,,gcc_jit_context_new_param()}:
667 gcc_jit_param *param_i =
668 gcc_jit_context_new_param (ctxt, NULL, int_type, "i");
673 Now we can create the function, using
674 @pxref{11,,gcc_jit_context_new_function()}:
677 gcc_jit_function *func =
678 gcc_jit_context_new_function (ctxt, NULL,
679 GCC_JIT_FUNCTION_EXPORTED,
688 To define the code within the function, we must create basic blocks
689 containing statements.
691 Every basic block contains a list of statements, eventually terminated
692 by a statement that either returns, or jumps to another basic block.
694 Our function has no control-flow, so we just need one basic block:
697 gcc_jit_block *block = gcc_jit_function_new_block (func, NULL);
702 Our basic block is relatively simple: it immediately terminates by
703 returning the value of an expression.
705 We can build the expression using @pxref{12,,gcc_jit_context_new_binary_op()}:
708 gcc_jit_rvalue *expr =
709 gcc_jit_context_new_binary_op (
711 GCC_JIT_BINARY_OP_MULT, int_type,
712 gcc_jit_param_as_rvalue (param_i),
713 gcc_jit_param_as_rvalue (param_i));
718 A @pxref{13,,gcc_jit_rvalue *} is another example of a
719 @pxref{e,,gcc_jit_object *} subclass. We can upcast it using
720 @pxref{14,,gcc_jit_rvalue_as_object()} and as before print it with
721 @pxref{f,,gcc_jit_object_get_debug_string()}.
724 printf ("expr: %s\n",
725 gcc_jit_object_get_debug_string (
726 gcc_jit_rvalue_as_object (expr)));
739 Creating the expression in itself doesn't do anything; we have to add
740 this expression to a statement within the block. In this case, we use it
741 to build a return statement, which terminates the basic block:
744 gcc_jit_block_end_with_return (block, NULL, expr);
749 OK, we've populated the context. We can now compile it using
750 @pxref{15,,gcc_jit_context_compile()}:
753 gcc_jit_result *result;
754 result = gcc_jit_context_compile (ctxt);
759 and get a @pxref{16,,gcc_jit_result *}.
761 At this point we're done with the context; we can release it:
764 gcc_jit_context_release (ctxt);
769 We can now use @pxref{17,,gcc_jit_result_get_code()} to look up a specific
770 machine code routine within the result, in this case, the function we
774 void *fn_ptr = gcc_jit_result_get_code (result, "square");
777 fprintf (stderr, "NULL fn_ptr");
784 We can now cast the pointer to an appropriate function pointer type, and
788 typedef int (*fn_type) (int);
789 fn_type square = (fn_type)fn_ptr;
790 printf ("result: %d", square (5));
801 Once we're done with the code, we can release the result:
804 gcc_jit_result_release (result);
809 We can't call @code{square} anymore once we've released @code{result}.
818 @node Error-handling,Options,,Tutorial part 2 Creating a trivial machine code function
819 @anchor{intro/tutorial02 error-handling}@anchor{18}
820 @subsection Error-handling
823 Various kinds of errors are possible when using the API, such as
824 mismatched types in an assignment. You can only compile and get code
825 from a context if no errors occur.
827 Errors are printed on stderr; they typically contain the name of the API
828 entrypoint where the error occurred, and pertinent information on the
832 ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *)
837 The API is designed to cope with errors without crashing, so you can get
838 away with having a single error-handling check in your code:
841 void *fn_ptr = gcc_jit_result_get_code (result, "square");
844 fprintf (stderr, "NULL fn_ptr");
851 For more information, see the @pxref{19,,error-handling guide}
852 within the Topic eference.
854 @node Options,Full example,Error-handling,Tutorial part 2 Creating a trivial machine code function
855 @anchor{intro/tutorial02 options}@anchor{1a}
859 To get more information on what's going on, you can set debugging flags
860 on the context using @pxref{1b,,gcc_jit_context_set_bool_option()}.
862 @c (I'm deliberately not mentioning
863 @c :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE` here since I think
864 @c it's probably more of use to implementors than to users)
866 Setting @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE} will dump a
867 C-like representation to stderr when you compile (GCC's "GIMPLE"
871 gcc_jit_context_set_bool_option (
873 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE,
875 result = gcc_jit_context_compile (ctxt);
881 square (signed int i)
893 We can see the generated machine code in assembler form (on stderr) by
894 setting @pxref{1d,,GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE} on the context
898 gcc_jit_context_set_bool_option (
900 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
902 result = gcc_jit_context_compile (ctxt);
911 .type square, @@function
916 .cfi_def_cfa_offset 16
919 .cfi_def_cfa_register 6
929 .size square, .-square
930 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
931 .section .note.GNU-stack,"",@@progbits
936 By default, no optimizations are performed, the equivalent of GCC's
937 @cite{-O0} option. We can turn things up to e.g. @cite{-O3} by calling
938 @pxref{1e,,gcc_jit_context_set_int_option()} with
939 @pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
942 gcc_jit_context_set_int_option (
944 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL,
955 .type square, @@function
965 .size square, .-square
966 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
967 .section .note.GNU-stack,"",@@progbits
972 Naturally this has only a small effect on such a trivial function.
974 @node Full example,,Options,Tutorial part 2 Creating a trivial machine code function
975 @anchor{intro/tutorial02 full-example}@anchor{20}
976 @subsection Full example
979 Here's what the above looks like as a complete program:
984 /* Usage example for libgccjit.so
985 Copyright (C) 2014-2015 Free Software Foundation, Inc.
987 This file is part of GCC.
989 GCC is free software; you can redistribute it and/or modify it
990 under the terms of the GNU General Public License as published by
991 the Free Software Foundation; either version 3, or (at your option)
994 GCC is distributed in the hope that it will be useful, but
995 WITHOUT ANY WARRANTY; without even the implied warranty of
996 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
997 General Public License for more details.
999 You should have received a copy of the GNU General Public License
1000 along with GCC; see the file COPYING3. If not see
1001 <http://www.gnu.org/licenses/>. */
1003 #include <libgccjit.h>
1009 create_code (gcc_jit_context *ctxt)
1011 /* Let's try to inject the equivalent of:
1018 gcc_jit_type *int_type =
1019 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
1020 gcc_jit_param *param_i =
1021 gcc_jit_context_new_param (ctxt, NULL, int_type, "i");
1022 gcc_jit_function *func =
1023 gcc_jit_context_new_function (ctxt, NULL,
1024 GCC_JIT_FUNCTION_EXPORTED,
1030 gcc_jit_block *block = gcc_jit_function_new_block (func, NULL);
1032 gcc_jit_rvalue *expr =
1033 gcc_jit_context_new_binary_op (
1035 GCC_JIT_BINARY_OP_MULT, int_type,
1036 gcc_jit_param_as_rvalue (param_i),
1037 gcc_jit_param_as_rvalue (param_i));
1039 gcc_jit_block_end_with_return (block, NULL, expr);
1043 main (int argc, char **argv)
1045 gcc_jit_context *ctxt = NULL;
1046 gcc_jit_result *result = NULL;
1048 /* Get a "context" object for working with the library. */
1049 ctxt = gcc_jit_context_acquire ();
1052 fprintf (stderr, "NULL ctxt");
1056 /* Set some options on the context.
1057 Let's see the code being generated, in assembler form. */
1058 gcc_jit_context_set_bool_option (
1060 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
1063 /* Populate the context. */
1066 /* Compile the code. */
1067 result = gcc_jit_context_compile (ctxt);
1070 fprintf (stderr, "NULL result");
1074 /* We're done with the context; we can release it: */
1075 gcc_jit_context_release (ctxt);
1078 /* Extract the generated code from "result". */
1079 void *fn_ptr = gcc_jit_result_get_code (result, "square");
1082 fprintf (stderr, "NULL fn_ptr");
1086 typedef int (*fn_type) (int);
1087 fn_type square = (fn_type)fn_ptr;
1088 printf ("result: %d\n", square (5));
1092 gcc_jit_context_release (ctxt);
1094 gcc_jit_result_release (result);
1103 Building and running it:
1111 # Run the built program:
1118 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
1119 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
1121 @c This is free software: you can redistribute it and/or modify it
1122 @c under the terms of the GNU General Public License as published by
1123 @c the Free Software Foundation, either version 3 of the License, or
1124 @c (at your option) any later version.
1126 @c This program is distributed in the hope that it will be useful, but
1127 @c WITHOUT ANY WARRANTY; without even the implied warranty of
1128 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1129 @c General Public License for more details.
1131 @c You should have received a copy of the GNU General Public License
1132 @c along with this program. If not, see
1133 @c <http://www.gnu.org/licenses/>.
1135 @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
1136 @anchor{intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{21}@anchor{intro/tutorial03 doc}@anchor{22}
1137 @section Tutorial part 3: Loops and variables
1140 Consider this C function:
1145 int loop_test (int n)
1148 for (int i = 0; i < n; i++)
1157 This example demonstrates some more features of libgccjit, with local
1158 variables and a loop.
1160 To break this down into libgccjit terms, it's usually easier to reword
1161 the @cite{for} loop as a @cite{while} loop, giving:
1166 int loop_test (int n)
1182 Here's what the final control flow graph will look like:
1189 @image{sum-of-squares1,,,image of a control flow graph,png}
1195 As before, we include the libgccjit header and make a
1196 @pxref{8,,gcc_jit_context *}.
1199 #include <libgccjit.h>
1203 gcc_jit_context *ctxt;
1204 ctxt = gcc_jit_context_acquire ();
1209 The function works with the C @cite{int} type:
1212 gcc_jit_type *the_type =
1213 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
1214 gcc_jit_type *return_type = the_type;
1219 though we could equally well make it work on, say, @cite{double}:
1222 gcc_jit_type *the_type =
1223 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_DOUBLE);
1228 Let's build the function:
1232 gcc_jit_context_new_param (ctxt, NULL, the_type, "n");
1233 gcc_jit_param *params[1] = @{n@};
1234 gcc_jit_function *func =
1235 gcc_jit_context_new_function (ctxt, NULL,
1236 GCC_JIT_FUNCTION_EXPORTED,
1245 * Expressions; lvalues and rvalues: Expressions lvalues and rvalues.
1247 * Visualizing the control flow graph::
1248 * Full example: Full example<2>.
1252 @node Expressions lvalues and rvalues,Control flow,,Tutorial part 3 Loops and variables
1253 @anchor{intro/tutorial03 expressions-lvalues-and-rvalues}@anchor{23}
1254 @subsection Expressions: lvalues and rvalues
1257 The base class of expression is the @pxref{13,,gcc_jit_rvalue *},
1258 representing an expression that can be on the @emph{right}-hand side of
1259 an assignment: a value that can be computed somehow, and assigned
1260 @emph{to} a storage area (such as a variable). It has a specific
1261 @pxref{a,,gcc_jit_type *}.
1263 Anothe important class is @pxref{24,,gcc_jit_lvalue *}.
1264 A @pxref{24,,gcc_jit_lvalue *}. is something that can of the @emph{left}-hand
1265 side of an assignment: a storage area (such as a variable).
1267 In other words, every assignment can be thought of as:
1275 Note that @pxref{24,,gcc_jit_lvalue *} is a subclass of
1276 @pxref{13,,gcc_jit_rvalue *}, where in an assignment of the form:
1279 LVALUE_A = LVALUE_B;
1284 the @cite{LVALUE_B} implies reading the current value of that storage
1285 area, assigning it into the @cite{LVALUE_A}.
1287 So far the only expressions we've seen are @cite{i * i}:
1290 gcc_jit_rvalue *expr =
1291 gcc_jit_context_new_binary_op (
1293 GCC_JIT_BINARY_OP_MULT, int_type,
1294 gcc_jit_param_as_rvalue (param_i),
1295 gcc_jit_param_as_rvalue (param_i));
1300 which is a @pxref{13,,gcc_jit_rvalue *}, and the various function
1301 parameters: @cite{param_i} and @cite{param_n}, instances of
1302 @pxref{25,,gcc_jit_param *}, which is a subclass of
1303 @pxref{24,,gcc_jit_lvalue *} (and, in turn, of @pxref{13,,gcc_jit_rvalue *}):
1304 we can both read from and write to function parameters within the
1307 Our new example has a couple of local variables. We create them by
1308 calling @pxref{26,,gcc_jit_function_new_local()}, supplying a type and a
1314 gcc_jit_function_new_local (func, NULL, the_type, "i");
1315 gcc_jit_lvalue *sum =
1316 gcc_jit_function_new_local (func, NULL, the_type, "sum");
1321 These are instances of @pxref{24,,gcc_jit_lvalue *} - they can be read from
1324 Note that there is no precanned way to create @emph{and} initialize a variable
1333 Instead, having added the local to the function, we have to separately add
1334 an assignment of @cite{0} to @cite{local_i} at the beginning of the function.
1336 @node Control flow,Visualizing the control flow graph,Expressions lvalues and rvalues,Tutorial part 3 Loops and variables
1337 @anchor{intro/tutorial03 control-flow}@anchor{27}
1338 @subsection Control flow
1341 This function has a loop, so we need to build some basic blocks to
1342 handle the control flow. In this case, we need 4 blocks:
1348 before the loop (initializing the locals)
1351 the conditional at the top of the loop (comparing @cite{i < n})
1354 the body of the loop
1357 after the loop terminates (@cite{return sum})
1360 so we create these as @pxref{28,,gcc_jit_block *} instances within the
1361 @pxref{29,,gcc_jit_function *}:
1364 gcc_jit_block *b_initial =
1365 gcc_jit_function_new_block (func, "initial");
1366 gcc_jit_block *b_loop_cond =
1367 gcc_jit_function_new_block (func, "loop_cond");
1368 gcc_jit_block *b_loop_body =
1369 gcc_jit_function_new_block (func, "loop_body");
1370 gcc_jit_block *b_after_loop =
1371 gcc_jit_function_new_block (func, "after_loop");
1376 We now populate each block with statements.
1378 The entry block @cite{b_initial} consists of initializations followed by a jump
1379 to the conditional. We assign @cite{0} to @cite{i} and to @cite{sum}, using
1380 @pxref{2a,,gcc_jit_block_add_assignment()} to add
1381 an assignment statement, and using @pxref{2b,,gcc_jit_context_zero()} to get
1382 the constant value @cite{0} for the relevant type for the right-hand side of
1387 gcc_jit_block_add_assignment (
1390 gcc_jit_context_zero (ctxt, the_type));
1393 gcc_jit_block_add_assignment (
1396 gcc_jit_context_zero (ctxt, the_type));
1401 We can then terminate the entry block by jumping to the conditional:
1404 gcc_jit_block_end_with_jump (b_initial, NULL, b_loop_cond);
1409 The conditional block is equivalent to the line @cite{while (i < n)} from our
1410 C example. It contains a single statement: a conditional, which jumps to
1411 one of two destination blocks depending on a boolean
1412 @pxref{13,,gcc_jit_rvalue *}, in this case the comparison of @cite{i} and @cite{n}.
1413 We build the comparison using @pxref{2c,,gcc_jit_context_new_comparison()}:
1416 gcc_jit_rvalue *guard =
1417 gcc_jit_context_new_comparison (
1419 GCC_JIT_COMPARISON_GE,
1420 gcc_jit_lvalue_as_rvalue (i),
1421 gcc_jit_param_as_rvalue (n));
1426 and can then use this to add @cite{b_loop_cond}'s sole statement, via
1427 @pxref{2d,,gcc_jit_block_end_with_conditional()}:
1430 gcc_jit_block_end_with_conditional (b_loop_cond, NULL, guard);
1435 Next, we populate the body of the loop.
1437 The C statement @cite{sum += i * i;} is an assignment operation, where an
1438 lvalue is modified "in-place". We use
1439 @pxref{2e,,gcc_jit_block_add_assignment_op()} to handle these operations:
1443 gcc_jit_block_add_assignment_op (
1446 GCC_JIT_BINARY_OP_PLUS,
1447 gcc_jit_context_new_binary_op (
1449 GCC_JIT_BINARY_OP_MULT, the_type,
1450 gcc_jit_lvalue_as_rvalue (i),
1451 gcc_jit_lvalue_as_rvalue (i)));
1456 The @cite{i++} can be thought of as @cite{i += 1}, and can thus be handled in
1457 a similar way. We use @pxref{2f,,gcc_jit_context_one()} to get the constant
1458 value @cite{1} (for the relevant type) for the right-hand side
1463 gcc_jit_block_add_assignment_op (
1466 GCC_JIT_BINARY_OP_PLUS,
1467 gcc_jit_context_one (ctxt, the_type));
1474 For numeric constants other than 0 or 1, we could use
1475 @pxref{30,,gcc_jit_context_new_rvalue_from_int()} and
1476 @pxref{31,,gcc_jit_context_new_rvalue_from_double()}.
1480 The loop body completes by jumping back to the conditional:
1483 gcc_jit_block_end_with_jump (b_loop_body, NULL, b_loop_cond);
1488 Finally, we populate the @cite{b_after_loop} block, reached when the loop
1489 conditional is false. We want to generate the equivalent of:
1497 so the block is just one statement:
1501 gcc_jit_block_end_with_return (
1504 gcc_jit_lvalue_as_rvalue (sum));
1511 You can intermingle block creation with statement creation,
1512 but given that the terminator statements generally include references
1513 to other blocks, I find it's clearer to create all the blocks,
1514 @emph{then} all the statements.
1518 We've finished populating the function. As before, we can now compile it
1522 gcc_jit_result *result;
1523 result = gcc_jit_context_compile (ctxt);
1525 typedef int (*loop_test_fn_type) (int);
1526 loop_test_fn_type loop_test =
1527 (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
1530 printf ("result: %d", loop_test (10));
1541 @node Visualizing the control flow graph,Full example<2>,Control flow,Tutorial part 3 Loops and variables
1542 @anchor{intro/tutorial03 visualizing-the-control-flow-graph}@anchor{32}
1543 @subsection Visualizing the control flow graph
1546 You can see the control flow graph of a function using
1547 @pxref{33,,gcc_jit_function_dump_to_dot()}:
1550 gcc_jit_function_dump_to_dot (func, "/tmp/sum-of-squares.dot");
1555 giving a .dot file in GraphViz format.
1557 You can convert this to an image using @cite{dot}:
1560 $ dot -Tpng /tmp/sum-of-squares.dot -o /tmp/sum-of-squares.png
1565 or use a viewer (my preferred one is xdot.py; see
1566 @indicateurl{https://github.com/jrfonseca/xdot.py}; on Fedora you can
1567 install it with @cite{yum install python-xdot}):
1574 @image{sum-of-squares1,,,image of a control flow graph,png}
1580 @node Full example<2>,,Visualizing the control flow graph,Tutorial part 3 Loops and variables
1581 @anchor{intro/tutorial03 full-example}@anchor{34}
1582 @subsection Full example
1588 /* Usage example for libgccjit.so
1589 Copyright (C) 2014-2015 Free Software Foundation, Inc.
1591 This file is part of GCC.
1593 GCC is free software; you can redistribute it and/or modify it
1594 under the terms of the GNU General Public License as published by
1595 the Free Software Foundation; either version 3, or (at your option)
1598 GCC is distributed in the hope that it will be useful, but
1599 WITHOUT ANY WARRANTY; without even the implied warranty of
1600 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1601 General Public License for more details.
1603 You should have received a copy of the GNU General Public License
1604 along with GCC; see the file COPYING3. If not see
1605 <http://www.gnu.org/licenses/>. */
1607 #include <libgccjit.h>
1613 create_code (gcc_jit_context *ctxt)
1616 Simple sum-of-squares, to test conditionals and looping
1618 int loop_test (int n)
1622 for (i = 0; i < n ; i ++)
1628 gcc_jit_type *the_type =
1629 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
1630 gcc_jit_type *return_type = the_type;
1633 gcc_jit_context_new_param (ctxt, NULL, the_type, "n");
1634 gcc_jit_param *params[1] = @{n@};
1635 gcc_jit_function *func =
1636 gcc_jit_context_new_function (ctxt, NULL,
1637 GCC_JIT_FUNCTION_EXPORTED,
1644 gcc_jit_function_new_local (func, NULL, the_type, "i");
1645 gcc_jit_lvalue *sum =
1646 gcc_jit_function_new_local (func, NULL, the_type, "sum");
1648 gcc_jit_block *b_initial =
1649 gcc_jit_function_new_block (func, "initial");
1650 gcc_jit_block *b_loop_cond =
1651 gcc_jit_function_new_block (func, "loop_cond");
1652 gcc_jit_block *b_loop_body =
1653 gcc_jit_function_new_block (func, "loop_body");
1654 gcc_jit_block *b_after_loop =
1655 gcc_jit_function_new_block (func, "after_loop");
1658 gcc_jit_block_add_assignment (
1661 gcc_jit_context_zero (ctxt, the_type));
1664 gcc_jit_block_add_assignment (
1667 gcc_jit_context_zero (ctxt, the_type));
1669 gcc_jit_block_end_with_jump (b_initial, NULL, b_loop_cond);
1672 gcc_jit_block_end_with_conditional (
1674 gcc_jit_context_new_comparison (
1676 GCC_JIT_COMPARISON_GE,
1677 gcc_jit_lvalue_as_rvalue (i),
1678 gcc_jit_param_as_rvalue (n)),
1683 gcc_jit_block_add_assignment_op (
1686 GCC_JIT_BINARY_OP_PLUS,
1687 gcc_jit_context_new_binary_op (
1689 GCC_JIT_BINARY_OP_MULT, the_type,
1690 gcc_jit_lvalue_as_rvalue (i),
1691 gcc_jit_lvalue_as_rvalue (i)));
1694 gcc_jit_block_add_assignment_op (
1697 GCC_JIT_BINARY_OP_PLUS,
1698 gcc_jit_context_one (ctxt, the_type));
1700 gcc_jit_block_end_with_jump (b_loop_body, NULL, b_loop_cond);
1703 gcc_jit_block_end_with_return (
1706 gcc_jit_lvalue_as_rvalue (sum));
1710 main (int argc, char **argv)
1712 gcc_jit_context *ctxt = NULL;
1713 gcc_jit_result *result = NULL;
1715 /* Get a "context" object for working with the library. */
1716 ctxt = gcc_jit_context_acquire ();
1719 fprintf (stderr, "NULL ctxt");
1723 /* Set some options on the context.
1724 Let's see the code being generated, in assembler form. */
1725 gcc_jit_context_set_bool_option (
1727 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
1730 /* Populate the context. */
1733 /* Compile the code. */
1734 result = gcc_jit_context_compile (ctxt);
1737 fprintf (stderr, "NULL result");
1741 /* Extract the generated code from "result". */
1742 typedef int (*loop_test_fn_type) (int);
1743 loop_test_fn_type loop_test =
1744 (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
1747 fprintf (stderr, "NULL loop_test");
1751 /* Run the generated code. */
1752 int val = loop_test (10);
1753 printf("loop_test returned: %d\n", val);
1756 gcc_jit_context_release (ctxt);
1757 gcc_jit_result_release (result);
1766 Building and running it:
1770 tut03-sum-of-squares.c \
1771 -o tut03-sum-of-squares \
1774 # Run the built program:
1775 $ ./tut03-sum-of-squares
1776 loop_test returned: 285
1781 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
1782 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
1784 @c This is free software: you can redistribute it and/or modify it
1785 @c under the terms of the GNU General Public License as published by
1786 @c the Free Software Foundation, either version 3 of the License, or
1787 @c (at your option) any later version.
1789 @c This program is distributed in the hope that it will be useful, but
1790 @c WITHOUT ANY WARRANTY; without even the implied warranty of
1791 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1792 @c General Public License for more details.
1794 @c You should have received a copy of the GNU General Public License
1795 @c along with this program. If not, see
1796 @c <http://www.gnu.org/licenses/>.
1798 @node Tutorial part 4 Adding JIT-compilation to a toy interpreter,,Tutorial part 3 Loops and variables,Tutorial
1799 @anchor{intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{35}@anchor{intro/tutorial04 doc}@anchor{36}
1800 @section Tutorial part 4: Adding JIT-compilation to a toy interpreter
1803 In this example we construct a "toy" interpreter, and add JIT-compilation
1807 * Our toy interpreter::
1808 * Compiling to machine code::
1809 * Setting things up::
1810 * Populating the function::
1811 * Verifying the control flow graph::
1812 * Compiling the context::
1813 * Single-stepping through the generated code::
1814 * Examining the generated code::
1815 * Putting it all together::
1816 * Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?.
1820 @node Our toy interpreter,Compiling to machine code,,Tutorial part 4 Adding JIT-compilation to a toy interpreter
1821 @anchor{intro/tutorial04 our-toy-interpreter}@anchor{37}
1822 @subsection Our toy interpreter
1825 It's a stack-based interpreter, and is intended as a (very simple) example
1826 of the kind of bytecode interpreter seen in dynamic languages such as
1829 For the sake of simplicity, our toy virtual machine is very limited:
1837 The only data type is @cite{int}
1840 It can only work on one function at a time (so that the only
1841 function call that can be made is to recurse).
1844 Functions can only take one parameter.
1847 Functions have a stack of @cite{int} values.
1850 We'll implement function call within the interpreter by calling a
1851 function in our implementation, rather than implementing our own
1855 The parser is only good enough to get the examples to work.
1859 Naturally, a real interpreter would be much more complicated that this.
1861 The following operations are supported:
1864 @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx}
1887 Duplicate top of stack.
1903 Swap top two elements
1920 Add the top two elements
1937 Likewise, but subtract.
1953 Likewise, but multiply.
1970 elements on the stack
1971 and push a nonzero/zero
1988 Recurse, passing the top
2006 Return the top of the
2019 PUSH_CONST @cite{arg}
2035 JUMP_ABS_IF_TRUE @cite{arg}
2039 Pop; if top of stack was
2054 Programs can be interpreted, disassembled, and compiled to machine code.
2056 The interpreter reads @code{.toy} scripts. Here's what a simple recursive
2057 factorial program looks like, the script @code{factorial.toy}.
2058 The parser ignores lines beginning with a @cite{#}.
2063 # Simple recursive factorial implementation, roughly equivalent to:
2065 # int factorial (int arg)
2069 # return arg * factorial (arg - 1)
2081 # stack: [arg, arg, 2]
2085 # stack: [arg, (arg < 2)]
2097 # stack: [arg, arg, 1]
2101 # stack: [arg, (arg - 1)
2105 # stack: [arg, factorial(arg - 1)]
2109 # stack: [arg * factorial(arg - 1)]
2119 The interpreter is a simple infinite loop with a big @code{switch} statement
2120 based on what the next opcode is:
2127 toyvm_function_interpret (toyvm_function *fn, int arg, FILE *trace)
2130 #define PUSH(ARG) (toyvm_frame_push (&frame, (ARG)))
2131 #define POP(ARG) (toyvm_frame_pop (&frame))
2133 frame.frm_function = fn;
2135 frame.frm_cur_depth = 0;
2143 assert (frame.frm_pc < fn->fn_num_ops);
2144 op = &fn->fn_ops[frame.frm_pc++];
2148 toyvm_frame_dump_stack (&frame, trace);
2149 toyvm_function_disassemble_op (fn, op, frame.frm_pc, trace);
2152 switch (op->op_opcode)
2154 /* Ops taking no operand. */
2174 case BINARY_SUBTRACT:
2186 case BINARY_COMPARE_LT:
2194 x = toyvm_function_interpret (fn, x, trace);
2201 /* Ops taking an operand. */
2203 PUSH (op->op_operand);
2206 case JUMP_ABS_IF_TRUE:
2209 frame.frm_pc = op->op_operand;
2213 assert (0); /* unknown opcode */
2215 @} /* end of switch on opcode */
2216 @} /* end of while loop */
2228 @node Compiling to machine code,Setting things up,Our toy interpreter,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2229 @anchor{intro/tutorial04 compiling-to-machine-code}@anchor{38}
2230 @subsection Compiling to machine code
2233 We want to generate machine code that can be cast to this type and
2234 then directly executed in-process:
2239 typedef int (*toyvm_compiled_code) (int);
2247 The lifetime of the code is tied to that of a @pxref{16,,gcc_jit_result *}.
2248 We'll handle this by bundling them up in a structure, so that we can
2249 clean them up together by calling @pxref{39,,gcc_jit_result_release()}:
2255 struct toyvm_compiled_function
2257 gcc_jit_result *cf_jit_result;
2258 toyvm_compiled_code cf_code;
2267 Our compiler isn't very sophisticated; it takes the implementation of
2268 each opcode above, and maps it directly to the operations supported by
2271 How should we handle the stack? In theory we could calculate what the
2272 stack depth will be at each opcode, and optimize away the stack
2273 manipulation "by hand". We'll see below that libgccjit is able to do
2274 this for us, so we'll implement stack manipulation
2275 in a direct way, by creating a @code{stack} array and @code{stack_depth}
2276 variables, local within the generated function, equivalent to this C code:
2280 int stack[MAX_STACK_DEPTH];
2285 We'll also have local variables @code{x} and @code{y} for use when implementing
2286 the opcodes, equivalent to this:
2295 This means our compiler has the following state:
2301 struct compilation_state
2303 gcc_jit_context *ctxt;
2305 gcc_jit_type *int_type;
2306 gcc_jit_type *bool_type;
2307 gcc_jit_type *stack_type; /* int[MAX_STACK_DEPTH] */
2309 gcc_jit_rvalue *const_one;
2311 gcc_jit_function *fn;
2312 gcc_jit_param *param_arg;
2313 gcc_jit_lvalue *stack;
2314 gcc_jit_lvalue *stack_depth;
2318 gcc_jit_location *op_locs[MAX_OPS];
2319 gcc_jit_block *initial_block;
2320 gcc_jit_block *op_blocks[MAX_OPS];
2330 @node Setting things up,Populating the function,Compiling to machine code,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2331 @anchor{intro/tutorial04 setting-things-up}@anchor{3a}
2332 @subsection Setting things up
2335 First we create our types:
2341 gcc_jit_context_get_type (state.ctxt, GCC_JIT_TYPE_INT);
2343 gcc_jit_context_get_type (state.ctxt, GCC_JIT_TYPE_BOOL);
2345 gcc_jit_context_new_array_type (state.ctxt, NULL,
2346 state.int_type, MAX_STACK_DEPTH);
2354 along with extracting a useful @cite{int} constant:
2359 state.const_one = gcc_jit_context_one (state.ctxt, state.int_type);
2367 We'll implement push and pop in terms of the @code{stack} array and
2368 @code{stack_depth}. Here are helper functions for adding statements to
2369 a block, implementing pushing and popping values:
2376 add_push (compilation_state *state,
2377 gcc_jit_block *block,
2378 gcc_jit_rvalue *rvalue,
2379 gcc_jit_location *loc)
2381 /* stack[stack_depth] = RVALUE */
2382 gcc_jit_block_add_assignment (
2385 /* stack[stack_depth] */
2386 gcc_jit_context_new_array_access (
2389 gcc_jit_lvalue_as_rvalue (state->stack),
2390 gcc_jit_lvalue_as_rvalue (state->stack_depth)),
2393 /* "stack_depth++;". */
2394 gcc_jit_block_add_assignment_op (
2398 GCC_JIT_BINARY_OP_PLUS,
2403 add_pop (compilation_state *state,
2404 gcc_jit_block *block,
2405 gcc_jit_lvalue *lvalue,
2406 gcc_jit_location *loc)
2408 /* "--stack_depth;". */
2409 gcc_jit_block_add_assignment_op (
2413 GCC_JIT_BINARY_OP_MINUS,
2416 /* "LVALUE = stack[stack_depth];". */
2417 gcc_jit_block_add_assignment (
2421 /* stack[stack_depth] */
2422 gcc_jit_lvalue_as_rvalue (
2423 gcc_jit_context_new_array_access (
2426 gcc_jit_lvalue_as_rvalue (state->stack),
2427 gcc_jit_lvalue_as_rvalue (state->stack_depth))));
2436 We will support single-stepping through the generated code in the
2437 debugger, so we need to create @pxref{3b,,gcc_jit_location} instances, one
2438 per operation in the source code. These will reference the lines of
2439 e.g. @code{factorial.toy}.
2444 for (pc = 0; pc < fn->fn_num_ops; pc++)
2446 toyvm_op *op = &fn->fn_ops[pc];
2448 state.op_locs[pc] = gcc_jit_context_new_location (state.ctxt,
2460 Let's create the function itself. As usual, we create its parameter
2461 first, then use the parameter to create the function:
2467 gcc_jit_context_new_param (state.ctxt, state.op_locs[0],
2468 state.int_type, "arg");
2470 gcc_jit_context_new_function (state.ctxt,
2472 GCC_JIT_FUNCTION_EXPORTED,
2475 1, &state.param_arg, 0);
2483 We create the locals within the function.
2489 gcc_jit_function_new_local (state.fn, NULL,
2490 state.stack_type, "stack");
2492 gcc_jit_function_new_local (state.fn, NULL,
2493 state.int_type, "stack_depth");
2495 gcc_jit_function_new_local (state.fn, NULL,
2496 state.int_type, "x");
2498 gcc_jit_function_new_local (state.fn, NULL,
2499 state.int_type, "y");
2507 @node Populating the function,Verifying the control flow graph,Setting things up,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2508 @anchor{intro/tutorial04 populating-the-function}@anchor{3c}
2509 @subsection Populating the function
2512 There's some one-time initialization, and the API treats the first block
2513 you create as the entrypoint of the function, so we need to create that
2519 state.initial_block = gcc_jit_function_new_block (state.fn, "initial");
2527 We can now create blocks for each of the operations. Most of these will
2528 be consolidated into larger blocks when the optimizer runs.
2533 for (pc = 0; pc < fn->fn_num_ops; pc++)
2536 sprintf (buf, "instr%i", pc);
2537 state.op_blocks[pc] = gcc_jit_function_new_block (state.fn, buf);
2546 Now that we have a block it can jump to when it's done, we can populate
2553 /* "stack_depth = 0;". */
2554 gcc_jit_block_add_assignment (
2555 state.initial_block,
2558 gcc_jit_context_zero (state.ctxt, state.int_type));
2560 /* "PUSH (arg);". */
2562 state.initial_block,
2563 gcc_jit_param_as_rvalue (state.param_arg),
2566 /* ...and jump to insn 0. */
2567 gcc_jit_block_end_with_jump (state.initial_block,
2569 state.op_blocks[0]);
2577 We can now populate the blocks for the individual operations. We loop
2578 through them, adding instructions to their blocks:
2583 for (pc = 0; pc < fn->fn_num_ops; pc++)
2585 gcc_jit_location *loc = state.op_locs[pc];
2587 gcc_jit_block *block = state.op_blocks[pc];
2588 gcc_jit_block *next_block = (pc < fn->fn_num_ops
2589 ? state.op_blocks[pc + 1]
2593 op = &fn->fn_ops[pc];
2601 We're going to have another big @code{switch} statement for implementing
2602 the opcodes, this time for compiling them, rather than interpreting
2603 them. It's helpful to have macros for implementing push and pop, so that
2604 we can make the @code{switch} statement that's coming up look as much as
2605 possible like the one above within the interpreter:
2609 #define X_EQUALS_POP()\
2610 add_pop (&state, block, state.x, loc)
2611 #define Y_EQUALS_POP()\
2612 add_pop (&state, block, state.y, loc)
2613 #define PUSH_RVALUE(RVALUE)\
2614 add_push (&state, block, (RVALUE), loc)
2616 PUSH_RVALUE (gcc_jit_lvalue_as_rvalue (state.x))
2618 PUSH_RVALUE (gcc_jit_lvalue_as_rvalue (state.y))
2627 A particularly clever implementation would have an @emph{identical}
2628 @code{switch} statement shared by the interpreter and the compiler, with
2629 some preprocessor "magic". We're not doing that here, for the sake
2634 When I first implemented this compiler, I accidentally missed an edit
2635 when copying and pasting the @code{Y_EQUALS_POP} macro, so that popping the
2636 stack into @code{y} instead erroneously assigned it to @code{x}, leaving @code{y}
2639 To track this kind of thing down, we can use
2640 @pxref{3d,,gcc_jit_block_add_comment()} to add descriptive comments
2641 to the internal representation. This is invaluable when looking through
2642 the generated IR for, say @code{factorial}:
2648 gcc_jit_block_add_comment (block, loc, opcode_names[op->op_opcode]);
2656 We can now write the big @code{switch} statement that implements the
2657 individual opcodes, populating the relevant block with statements:
2663 switch (op->op_opcode)
2682 gcc_jit_context_new_binary_op (
2685 GCC_JIT_BINARY_OP_PLUS,
2687 gcc_jit_lvalue_as_rvalue (state.x),
2688 gcc_jit_lvalue_as_rvalue (state.y)));
2691 case BINARY_SUBTRACT:
2695 gcc_jit_context_new_binary_op (
2698 GCC_JIT_BINARY_OP_MINUS,
2700 gcc_jit_lvalue_as_rvalue (state.x),
2701 gcc_jit_lvalue_as_rvalue (state.y)));
2708 gcc_jit_context_new_binary_op (
2711 GCC_JIT_BINARY_OP_MULT,
2713 gcc_jit_lvalue_as_rvalue (state.x),
2714 gcc_jit_lvalue_as_rvalue (state.y)));
2717 case BINARY_COMPARE_LT:
2721 /* cast of bool to int */
2722 gcc_jit_context_new_cast (
2725 /* (x < y) as a bool */
2726 gcc_jit_context_new_comparison (
2729 GCC_JIT_COMPARISON_LT,
2730 gcc_jit_lvalue_as_rvalue (state.x),
2731 gcc_jit_lvalue_as_rvalue (state.y)),
2738 gcc_jit_rvalue *arg = gcc_jit_lvalue_as_rvalue (state.x);
2740 gcc_jit_context_new_call (
2750 gcc_jit_block_end_with_return (
2753 gcc_jit_lvalue_as_rvalue (state.x));
2756 /* Ops taking an operand. */
2759 gcc_jit_context_new_rvalue_from_int (
2765 case JUMP_ABS_IF_TRUE:
2767 gcc_jit_block_end_with_conditional (
2771 gcc_jit_context_new_cast (
2774 gcc_jit_lvalue_as_rvalue (state.x),
2776 state.op_blocks[op->op_operand], /* on_true */
2777 next_block); /* on_false */
2782 @} /* end of switch on opcode */
2790 Every block must be terminated, via a call to one of the
2791 @code{gcc_jit_block_end_with_} entrypoints. This has been done for two
2792 of the opcodes, but we need to do it for the other ones, by jumping
2798 if (op->op_opcode != JUMP_ABS_IF_TRUE
2799 && op->op_opcode != RETURN)
2800 gcc_jit_block_end_with_jump (
2811 This is analogous to simply incrementing the program counter.
2813 @node Verifying the control flow graph,Compiling the context,Populating the function,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2814 @anchor{intro/tutorial04 verifying-the-control-flow-graph}@anchor{3e}
2815 @subsection Verifying the control flow graph
2818 Having finished looping over the blocks, the context is complete.
2820 As before, we can verify that the control flow and statements are sane by
2821 using @pxref{33,,gcc_jit_function_dump_to_dot()}:
2824 gcc_jit_function_dump_to_dot (state.fn, "/tmp/factorial.dot");
2829 and viewing the result. Note how the label names, comments, and
2830 variable names show up in the dump, to make it easier to spot
2831 errors in our compiler.
2838 @image{factorial1,,,image of a control flow graph,png}
2844 @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
2845 @anchor{intro/tutorial04 compiling-the-context}@anchor{3f}
2846 @subsection Compiling the context
2849 Having finished looping over the blocks and populating them with
2850 statements, the context is complete.
2852 We can now compile it, and extract machine code from the result:
2857 gcc_jit_result *jit_result = gcc_jit_context_compile (state.ctxt);
2858 gcc_jit_context_release (state.ctxt);
2860 toyvm_compiled_function *toyvm_result =
2861 (toyvm_compiled_function *)calloc (1, sizeof (toyvm_compiled_function));
2864 fprintf (stderr, "out of memory allocating toyvm_compiled_function\n");
2865 gcc_jit_result_release (jit_result);
2869 toyvm_result->cf_jit_result = jit_result;
2870 toyvm_result->cf_code =
2871 (toyvm_compiled_code)gcc_jit_result_get_code (jit_result,
2876 return toyvm_result;
2881 #define CHECK_NON_NULL(PTR) \
2883 if ((PTR) != NULL) \
2885 pass ("%s: %s is non-null", test, #PTR); \
2889 fail ("%s: %s is NULL", test, #PTR); \
2894 #define CHECK_VALUE(ACTUAL, EXPECTED) \
2896 if ((ACTUAL) == (EXPECTED)) \
2898 pass ("%s: actual: %s == expected: %s", test, #ACTUAL, #EXPECTED); \
2902 fail ("%s: actual: %s != expected: %s", test, #ACTUAL, #EXPECTED); \
2903 fprintf (stderr, "incorrect value\n"); \
2909 test_script (const char *scripts_dir, const char *script_name, int input,
2910 int expected_result)
2914 int interpreted_result;
2915 toyvm_compiled_function *compiled_fn;
2916 toyvm_compiled_code code;
2917 int compiled_result;
2919 snprintf (test, sizeof (test), "toyvm.c: %s", script_name);
2921 script_path = (char *)malloc (strlen (scripts_dir)
2922 + strlen (script_name) + 1);
2923 CHECK_NON_NULL (script_path);
2924 sprintf (script_path, "%s%s", scripts_dir, script_name);
2926 fn = toyvm_function_parse (script_path, script_name);
2927 CHECK_NON_NULL (fn);
2929 interpreted_result = toyvm_function_interpret (fn, input, NULL);
2930 CHECK_VALUE (interpreted_result, expected_result);
2932 compiled_fn = toyvm_function_compile (fn);
2933 CHECK_NON_NULL (compiled_fn);
2935 code = (toyvm_compiled_code)compiled_fn->cf_code;
2936 CHECK_NON_NULL (code);
2938 compiled_result = code (input);
2939 CHECK_VALUE (compiled_result, expected_result);
2941 gcc_jit_result_release (compiled_fn->cf_jit_result);
2947 #define PATH_TO_SCRIPTS ("/jit/docs/examples/tut04-toyvm/")
2955 snprintf (test, sizeof (test), "toyvm.c");
2957 /* We need to locate the test scripts.
2958 Rely on "srcdir" being set in the environment. */
2960 srcdir = getenv ("srcdir");
2961 CHECK_NON_NULL (srcdir);
2963 scripts_dir = (char *)malloc (strlen (srcdir) + strlen(PATH_TO_SCRIPTS)
2965 CHECK_NON_NULL (scripts_dir);
2966 sprintf (scripts_dir, "%s%s", srcdir, PATH_TO_SCRIPTS);
2968 test_script (scripts_dir, "factorial.toy", 10, 3628800);
2969 test_script (scripts_dir, "fibonacci.toy", 10, 55);
2975 main (int argc, char **argv)
2977 const char *filename = NULL;
2978 toyvm_function *fn = NULL;
2980 /* If called with no args, assume we're being run by the test suite. */
2990 "%s FILENAME INPUT: Parse and run a .toy file\n",
2996 fn = toyvm_function_parse (filename, filename);
3001 toyvm_function_disassemble (fn, stdout);
3003 printf ("interpreter result: %d\n",
3004 toyvm_function_interpret (fn, atoi (argv[2]), NULL));
3006 /* JIT-compilation. */
3007 toyvm_compiled_function *compiled_fn
3008 = toyvm_function_compile (fn);
3010 toyvm_compiled_code code = compiled_fn->cf_code;
3011 printf ("compiler result: %d\n",
3012 code (atoi (argv[2])));
3014 gcc_jit_result_release (compiled_fn->cf_jit_result);
3025 We can now run the result:
3030 toyvm_compiled_function *compiled_fn
3031 = toyvm_function_compile (fn);
3033 toyvm_compiled_code code = compiled_fn->cf_code;
3034 printf ("compiler result: %d\n",
3035 code (atoi (argv[2])));
3037 gcc_jit_result_release (compiled_fn->cf_jit_result);
3046 @node Single-stepping through the generated code,Examining the generated code,Compiling the context,Tutorial part 4 Adding JIT-compilation to a toy interpreter
3047 @anchor{intro/tutorial04 single-stepping-through-the-generated-code}@anchor{40}
3048 @subsection Single-stepping through the generated code
3051 It's possible to debug the generated code. To do this we need to both:
3059 Set up source code locations for our statements, so that we can
3060 meaningfully step through the code. We did this above by
3061 calling @pxref{41,,gcc_jit_context_new_location()} and using the
3065 Enable the generation of debugging information, by setting
3066 @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
3067 @pxref{8,,gcc_jit_context} via
3068 @pxref{1b,,gcc_jit_context_set_bool_option()}:
3071 gcc_jit_context_set_bool_option (
3073 GCC_JIT_BOOL_OPTION_DEBUGINFO,
3081 Having done this, we can put a breakpoint on the generated function:
3084 $ gdb --args ./toyvm factorial.toy 10
3085 (gdb) break factorial
3086 Function "factorial" not defined.
3087 Make breakpoint pending on future shared library load? (y or [n]) y
3088 Breakpoint 1 (factorial) pending.
3090 Breakpoint 1, factorial (arg=10) at factorial.toy:14
3096 We've set up location information, which references @code{factorial.toy}.
3097 This allows us to use e.g. @code{list} to see where we are in the script:
3107 15 # stack: [arg, arg]
3115 and to step through the function, examining the data:
3121 22 BINARY_COMPARE_LT
3123 $5 = @{10, 10, 2, 0, -7152, 32767, 0, 0@}
3124 (gdb) print stack_depth
3130 You'll see that the parts of the @code{stack} array that haven't been
3131 touched yet are uninitialized.
3135 Turning on optimizations may lead to unpredictable results when
3136 stepping through the generated code: the execution may appear to
3137 "jump around" the source code. This is analogous to turning up the
3138 optimization level in a regular compiler.
3142 @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
3143 @anchor{intro/tutorial04 examining-the-generated-code}@anchor{43}
3144 @subsection Examining the generated code
3147 How good is the optimized code?
3149 We can turn up optimizations, by calling
3150 @pxref{1e,,gcc_jit_context_set_int_option()} with
3151 @pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
3154 gcc_jit_context_set_int_option (
3156 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL,
3162 One of GCC's internal representations is called "gimple". A dump of the
3163 initial gimple representation of the code can be seen by setting:
3166 gcc_jit_context_set_bool_option (ctxt,
3167 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE,
3173 With optimization on and source locations displayed, this gives:
3175 @c We'll use "c" for gimple dumps
3178 factorial (signed int arg)
3180 <unnamed type> D.80;
3188 signed int stack_depth;
3189 signed int stack[8];
3195 stack[stack_depth] = arg;
3196 stack_depth = stack_depth + 1;
3200 stack_depth = stack_depth + -1;
3201 x = stack[stack_depth];
3202 stack[stack_depth] = x;
3203 stack_depth = stack_depth + 1;
3204 stack[stack_depth] = x;
3205 stack_depth = stack_depth + 1;
3209 stack[stack_depth] = 2;
3210 stack_depth = stack_depth + 1;
3218 You can see the generated machine code in assembly form via:
3221 gcc_jit_context_set_bool_option (
3223 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
3225 result = gcc_jit_context_compile (ctxt);
3230 which shows that (on this x86_64 box) the compiler has unrolled the loop
3231 and is using MMX instructions to perform several multiplications
3240 .type factorial, @@function
3243 .file 1 "factorial.toy"
3254 leal 0(,%rcx,4), %esi
3260 movl %eax, -16(%rsp)
3262 movd -16(%rsp), %xmm0
3263 movl %edi, -16(%rsp)
3264 movl %eax, -12(%rsp)
3265 movd -16(%rsp), %xmm1
3267 movl %edx, -16(%rsp)
3268 movd -12(%rsp), %xmm4
3269 movd -16(%rsp), %xmm6
3270 punpckldq %xmm4, %xmm0
3271 movdqa .LC1(%rip), %xmm4
3272 punpckldq %xmm6, %xmm1
3273 punpcklqdq %xmm0, %xmm1
3274 movdqa .LC0(%rip), %xmm0
3276 # etc - edited for brevity
3281 This is clearly overkill for a function that will likely overflow the
3282 @code{int} type before the vectorization is worthwhile - but then again, this
3285 Turning down the optimization level to 2:
3288 gcc_jit_context_set_int_option (
3290 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL,
3296 yields this code, which is simple enough to quote in its entirety:
3303 .type factorial, @@function
3332 .size factorial, .-factorial
3333 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-%@{gcc_release@})"
3334 .section .note.GNU-stack,"",@@progbits
3339 Note that the stack pushing and popping have been eliminated, as has the
3340 recursive call (in favor of an iteration).
3342 @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
3343 @anchor{intro/tutorial04 putting-it-all-together}@anchor{44}
3344 @subsection Putting it all together
3347 The complete example can be seen in the source tree at
3348 @code{gcc/jit/docs/examples/tut04-toyvm/toyvm.c}
3350 along with a Makefile and a couple of sample .toy scripts:
3354 drwxrwxr-x. 2 david david 4096 Sep 19 17:46 .
3355 drwxrwxr-x. 3 david david 4096 Sep 19 15:26 ..
3356 -rw-rw-r--. 1 david david 615 Sep 19 12:43 factorial.toy
3357 -rw-rw-r--. 1 david david 834 Sep 19 13:08 fibonacci.toy
3358 -rw-rw-r--. 1 david david 238 Sep 19 14:22 Makefile
3359 -rw-rw-r--. 1 david david 16457 Sep 19 17:07 toyvm.c
3362 g++ -Wall -g -o toyvm toyvm.c -lgccjit
3364 $ ./toyvm factorial.toy 10
3365 interpreter result: 3628800
3366 compiler result: 3628800
3368 $ ./toyvm fibonacci.toy 10
3369 interpreter result: 55
3375 @node Behind the curtain How does our code get optimized?,,Putting it all together,Tutorial part 4 Adding JIT-compilation to a toy interpreter
3376 @anchor{intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{45}
3377 @subsection Behind the curtain: How does our code get optimized?
3380 Our example is done, but you may be wondering about exactly how the
3381 compiler turned what we gave it into the machine code seen above.
3383 We can examine what the compiler is doing in detail by setting:
3386 gcc_jit_context_set_bool_option (state.ctxt,
3387 GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING,
3389 gcc_jit_context_set_bool_option (state.ctxt,
3390 GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES,
3396 This will dump detailed information about the compiler's state to a
3397 directory under @code{/tmp}, and keep it from being cleaned up.
3399 The precise names and their formats of these files is subject to change.
3400 Higher optimization levels lead to more files.
3401 Here's what I saw (edited for brevity; there were almost 200 files):
3404 intermediate files written to /tmp/libgccjit-KPQbGw
3405 $ ls /tmp/libgccjit-KPQbGw/
3407 fake.c.000i.type-inheritance
3409 fake.c.007t.omplower
3413 fake.c.014i.visibility
3414 fake.c.015i.early_local_cleanups
3421 The gimple code is converted into Static Single Assignment form,
3422 with annotations for use when generating the debuginfo:
3425 $ less /tmp/libgccjit-KPQbGw/fake.c.016t.ssa
3431 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3433 factorial (signed int arg)
3435 signed int stack[8];
3436 signed int stack_depth;
3448 # DEBUG stack_depth => stack_depth_3
3449 stack[stack_depth_3] = arg_5(D);
3450 stack_depth_7 = stack_depth_3 + 1;
3451 # DEBUG stack_depth => stack_depth_7
3452 # DEBUG instr0 => NULL
3453 # DEBUG /* DUP */ => NULL
3454 stack_depth_8 = stack_depth_7 + -1;
3455 # DEBUG stack_depth => stack_depth_8
3456 x_9 = stack[stack_depth_8];
3458 stack[stack_depth_8] = x_9;
3459 stack_depth_11 = stack_depth_8 + 1;
3460 # DEBUG stack_depth => stack_depth_11
3461 stack[stack_depth_11] = x_9;
3462 stack_depth_13 = stack_depth_11 + 1;
3463 # DEBUG stack_depth => stack_depth_13
3464 # DEBUG instr1 => NULL
3465 # DEBUG /* PUSH_CONST */ => NULL
3466 stack[stack_depth_13] = 2;
3468 /* etc; edited for brevity */
3473 We can perhaps better see the code by turning off
3474 @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to suppress all those @code{DEBUG}
3478 $ less /tmp/libgccjit-1Hywc0/fake.c.016t.ssa
3484 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3486 factorial (signed int arg)
3488 signed int stack[8];
3489 signed int stack_depth;
3501 stack[stack_depth_3] = arg_5(D);
3502 stack_depth_7 = stack_depth_3 + 1;
3503 stack_depth_8 = stack_depth_7 + -1;
3504 x_9 = stack[stack_depth_8];
3505 stack[stack_depth_8] = x_9;
3506 stack_depth_11 = stack_depth_8 + 1;
3507 stack[stack_depth_11] = x_9;
3508 stack_depth_13 = stack_depth_11 + 1;
3509 stack[stack_depth_13] = 2;
3510 stack_depth_15 = stack_depth_13 + 1;
3511 stack_depth_16 = stack_depth_15 + -1;
3512 y_17 = stack[stack_depth_16];
3513 stack_depth_18 = stack_depth_16 + -1;
3514 x_19 = stack[stack_depth_18];
3516 _21 = (signed int) _20;
3517 stack[stack_depth_18] = _21;
3518 stack_depth_23 = stack_depth_18 + 1;
3519 stack_depth_24 = stack_depth_23 + -1;
3520 x_25 = stack[stack_depth_24];
3522 goto <bb 4> (instr9);
3524 goto <bb 3> (instr4);
3528 stack_depth_26 = stack_depth_24 + -1;
3529 x_27 = stack[stack_depth_26];
3530 stack[stack_depth_26] = x_27;
3531 stack_depth_29 = stack_depth_26 + 1;
3532 stack[stack_depth_29] = x_27;
3533 stack_depth_31 = stack_depth_29 + 1;
3534 stack[stack_depth_31] = 1;
3535 stack_depth_33 = stack_depth_31 + 1;
3536 stack_depth_34 = stack_depth_33 + -1;
3537 y_35 = stack[stack_depth_34];
3538 stack_depth_36 = stack_depth_34 + -1;
3539 x_37 = stack[stack_depth_36];
3541 stack[stack_depth_36] = _38;
3542 stack_depth_40 = stack_depth_36 + 1;
3543 stack_depth_41 = stack_depth_40 + -1;
3544 x_42 = stack[stack_depth_41];
3545 _44 = factorial (x_42);
3546 stack[stack_depth_41] = _44;
3547 stack_depth_46 = stack_depth_41 + 1;
3548 stack_depth_47 = stack_depth_46 + -1;
3549 y_48 = stack[stack_depth_47];
3550 stack_depth_49 = stack_depth_47 + -1;
3551 x_50 = stack[stack_depth_49];
3553 stack[stack_depth_49] = _51;
3554 stack_depth_53 = stack_depth_49 + 1;
3556 # stack_depth_1 = PHI <stack_depth_24(2), stack_depth_53(3)>
3559 stack_depth_54 = stack_depth_1 + -1;
3560 x_55 = stack[stack_depth_54];
3562 stack =@{v@} @{CLOBBER@};
3570 Note in the above how all the @pxref{28,,gcc_jit_block} instances we
3571 created have been consolidated into just 3 blocks in GCC's internal
3572 representation: @code{initial}, @code{instr4} and @code{instr9}.
3575 * Optimizing away stack manipulation::
3576 * Elimination of tail recursion::
3580 @node Optimizing away stack manipulation,Elimination of tail recursion,,Behind the curtain How does our code get optimized?
3581 @anchor{intro/tutorial04 optimizing-away-stack-manipulation}@anchor{46}
3582 @subsubsection Optimizing away stack manipulation
3585 Recall our simple implementation of stack operations. Let's examine
3586 how the stack operations are optimized away.
3588 After a pass of constant-propagation, the depth of the stack at each
3589 opcode can be determined at compile-time:
3592 $ less /tmp/libgccjit-1Hywc0/fake.c.021t.ccp1
3598 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3600 factorial (signed int arg)
3602 signed int stack[8];
3603 signed int stack_depth;
3613 stack[0] = arg_5(D);
3621 _21 = (signed int) _20;
3625 goto <bb 4> (instr9);
3627 goto <bb 3> (instr4);
3640 _44 = factorial (x_42);
3651 stack =@{v@} @{CLOBBER@};
3659 Note how, in the above, all those @code{stack_depth} values are now just
3660 constants: we're accessing specific stack locations at each opcode.
3662 The "esra" pass ("Early Scalar Replacement of Aggregates") breaks
3663 out our "stack" array into individual elements:
3666 $ less /tmp/libgccjit-1Hywc0/fake.c.024t.esra
3672 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3674 Created a replacement for stack offset: 0, size: 32: stack$0
3675 Created a replacement for stack offset: 32, size: 32: stack$1
3676 Created a replacement for stack offset: 64, size: 32: stack$2
3678 Symbols to be put in SSA form
3679 @{ D.89 D.90 D.91 @}
3680 Incremental SSA update started at block: 0
3681 Number of blocks in CFG: 5
3682 Number of blocks to update: 4 ( 80%)
3685 factorial (signed int arg)
3690 signed int stack[8];
3691 signed int stack_depth;
3701 stack$0_45 = arg_5(D);
3709 _21 = (signed int) _20;
3713 goto <bb 4> (instr9);
3715 goto <bb 3> (instr4);
3728 _44 = factorial (x_42);
3735 # stack$0_52 = PHI <stack$0_39(2), stack$0_1(3)>
3740 stack =@{v@} @{CLOBBER@};
3748 Hence at this point, all those pushes and pops of the stack are now
3749 simply assignments to specific temporary variables.
3751 After some copy propagation, the stack manipulation has been completely
3755 $ less /tmp/libgccjit-1Hywc0/fake.c.026t.copyprop1
3761 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3763 factorial (signed int arg)
3768 signed int stack[8];
3769 signed int stack_depth;
3779 stack$0_39 = arg_5(D);
3780 _20 = arg_5(D) <= 1;
3781 _21 = (signed int) _20;
3783 goto <bb 4> (instr9);
3785 goto <bb 3> (instr4);
3789 _38 = arg_5(D) + -1;
3790 _44 = factorial (_38);
3791 _51 = arg_5(D) * _44;
3794 # stack$0_52 = PHI <arg_5(D)(2), _51(3)>
3797 stack =@{v@} @{CLOBBER@};
3805 Later on, another pass finally eliminated @code{stack_depth} local and the
3806 unused parts of the @cite{stack`} array altogether:
3809 $ less /tmp/libgccjit-1Hywc0/fake.c.036t.release_ssa
3815 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3817 Released 44 names, 314.29%, removed 44 holes
3818 factorial (signed int arg)
3821 signed int mult_acc_1;
3825 signed int mul_tmp_10;
3826 signed int mult_acc_11;
3827 signed int mult_acc_13;
3829 # arg_9 = PHI <arg_8(D)(0)>
3830 # mult_acc_13 = PHI <1(0)>
3834 # arg_4 = PHI <arg_9(2), _7(3)>
3835 # mult_acc_1 = PHI <mult_acc_13(2), mult_acc_11(3)>
3837 _6 = (signed int) _5;
3839 goto <bb 4> (instr9);
3841 goto <bb 3> (instr4);
3846 mult_acc_11 = mult_acc_1 * arg_4;
3849 # stack$0_12 = PHI <arg_4(5)>
3852 mul_tmp_10 = mult_acc_1 * stack$0_12;
3860 @node Elimination of tail recursion,,Optimizing away stack manipulation,Behind the curtain How does our code get optimized?
3861 @anchor{intro/tutorial04 elimination-of-tail-recursion}@anchor{47}
3862 @subsubsection Elimination of tail recursion
3865 Another significant optimization is the detection that the call to
3866 @code{factorial} is tail recursion, which can be eliminated in favor of
3870 $ less /tmp/libgccjit-1Hywc0/fake.c.030t.tailr1
3876 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3879 Symbols to be put in SSA form
3881 Incremental SSA update started at block: 0
3882 Number of blocks in CFG: 5
3883 Number of blocks to update: 4 ( 80%)
3886 factorial (signed int arg)
3891 signed int stack[8];
3892 signed int stack_depth;
3895 signed int mult_acc_1;
3899 signed int mul_tmp_44;
3900 signed int mult_acc_51;
3902 # arg_5 = PHI <arg_39(D)(0), _38(3)>
3903 # mult_acc_1 = PHI <1(0), mult_acc_51(3)>
3906 _21 = (signed int) _20;
3908 goto <bb 4> (instr9);
3910 goto <bb 3> (instr4);
3915 mult_acc_51 = mult_acc_1 * arg_5;
3916 goto <bb 2> (initial);
3918 # stack$0_52 = PHI <arg_5(2)>
3921 stack =@{v@} @{CLOBBER@};
3922 mul_tmp_44 = mult_acc_1 * stack$0_52;
3930 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
3931 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
3933 @c This is free software: you can redistribute it and/or modify it
3934 @c under the terms of the GNU General Public License as published by
3935 @c the Free Software Foundation, either version 3 of the License, or
3936 @c (at your option) any later version.
3938 @c This program is distributed in the hope that it will be useful, but
3939 @c WITHOUT ANY WARRANTY; without even the implied warranty of
3940 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
3941 @c General Public License for more details.
3943 @c You should have received a copy of the GNU General Public License
3944 @c along with this program. If not, see
3945 @c <http://www.gnu.org/licenses/>.
3947 @node Topic Reference,C++ bindings for libgccjit,Tutorial,Top
3948 @anchor{topics/index doc}@anchor{48}@anchor{topics/index topic-reference}@anchor{49}
3949 @chapter Topic Reference
3952 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
3953 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
3955 @c This is free software: you can redistribute it and/or modify it
3956 @c under the terms of the GNU General Public License as published by
3957 @c the Free Software Foundation, either version 3 of the License, or
3958 @c (at your option) any later version.
3960 @c This program is distributed in the hope that it will be useful, but
3961 @c WITHOUT ANY WARRANTY; without even the implied warranty of
3962 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
3963 @c General Public License for more details.
3965 @c You should have received a copy of the GNU General Public License
3966 @c along with this program. If not, see
3967 @c <http://www.gnu.org/licenses/>.
3970 * Compilation contexts::
3974 * Creating and using functions::
3975 * Source Locations::
3976 * Compilation results::
3978 Compilation contexts
3980 * Lifetime-management::
3982 * Error-handling: Error-handling<2>.
3984 * Options: Options<2>.
3995 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile.
3996 * Structures and unions::
4002 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions.
4006 * Simple expressions::
4007 * Unary Operations::
4008 * Binary Operations::
4015 * Global variables::
4017 Creating and using functions
4031 @node Compilation contexts,Objects,,Topic Reference
4032 @anchor{topics/contexts compilation-contexts}@anchor{4a}@anchor{topics/contexts doc}@anchor{4b}
4033 @section Compilation contexts
4036 @geindex gcc_jit_context (C type)
4037 @anchor{topics/contexts gcc_jit_context}@anchor{8}
4038 @deffn {C Type} gcc_jit_context
4041 The top-level of the API is the @pxref{8,,gcc_jit_context} type.
4043 A @pxref{8,,gcc_jit_context} instance encapsulates the state of a
4046 You can set up options on it, and add types, functions and code.
4047 Invoking @pxref{15,,gcc_jit_context_compile()} on it gives you a
4048 @pxref{16,,gcc_jit_result}.
4051 * Lifetime-management::
4053 * Error-handling: Error-handling<2>.
4055 * Options: Options<2>.
4059 @node Lifetime-management,Thread-safety,,Compilation contexts
4060 @anchor{topics/contexts lifetime-management}@anchor{4c}
4061 @subsection Lifetime-management
4064 Contexts are the unit of lifetime-management within the API: objects
4065 have their lifetime bounded by the context they are created within, and
4066 cleanup of such objects is done for you when the context is released.
4068 @geindex gcc_jit_context_acquire (C function)
4069 @anchor{topics/contexts gcc_jit_context_acquire}@anchor{9}
4070 @deffn {C Function} gcc_jit_context *gcc_jit_context_acquire (void)
4072 This function acquires a new @pxref{e,,gcc_jit_object *} instance,
4073 which is independent of any others that may be present within this
4077 @geindex gcc_jit_context_release (C function)
4078 @anchor{topics/contexts gcc_jit_context_release}@anchor{c}
4079 @deffn {C Function} void gcc_jit_context_release (gcc_jit_context@w{ }*ctxt)
4081 This function releases all resources associated with the given context.
4082 Both the context itself and all of its @pxref{e,,gcc_jit_object *}
4083 instances are cleaned up. It should be called exactly once on a given
4086 It is invalid to use the context or any of its "contextual" objects
4090 gcc_jit_context_release (ctxt);
4096 @geindex gcc_jit_context_new_child_context (C function)
4097 @anchor{topics/contexts gcc_jit_context_new_child_context}@anchor{4d}
4098 @deffn {C Function} gcc_jit_context * gcc_jit_context_new_child_context (gcc_jit_context@w{ }*parent_ctxt)
4100 Given an existing JIT context, create a child context.
4102 The child inherits a copy of all option-settings from the parent.
4104 The child can reference objects created within the parent, but not
4107 The lifetime of the child context must be bounded by that of the
4108 parent: you should release a child context before releasing the parent
4111 If you use a function from a parent context within a child context,
4112 you have to compile the parent context before you can compile the
4113 child context, and the gcc_jit_result of the parent context must
4114 outlive the gcc_jit_result of the child context.
4116 This allows caching of shared initializations. For example, you could
4117 create types and declarations of global functions in a parent context
4118 once within a process, and then create child contexts whenever a
4119 function or loop becomes hot. Each such child context can be used for
4120 JIT-compiling just one function or loop, but can reference types
4121 and helper functions created within the parent context.
4123 Contexts can be arbitrarily nested, provided the above rules are
4124 followed, but it's probably not worth going above 2 or 3 levels, and
4125 there will likely be a performance hit for such nesting.
4128 @node Thread-safety,Error-handling<2>,Lifetime-management,Compilation contexts
4129 @anchor{topics/contexts thread-safety}@anchor{4e}
4130 @subsection Thread-safety
4133 Instances of @pxref{8,,gcc_jit_context *} created via
4134 @pxref{9,,gcc_jit_context_acquire()} are independent from each other:
4135 only one thread may use a given context at once, but multiple threads
4136 could each have their own contexts without needing locks.
4138 Contexts created via @pxref{4d,,gcc_jit_context_new_child_context()} are
4139 related to their parent context. They can be partitioned by their
4140 ultimate ancestor into independent "family trees". Only one thread
4141 within a process may use a given "family tree" of such contexts at once,
4142 and if you're using multiple threads you should provide your own locking
4143 around entire such context partitions.
4145 @node Error-handling<2>,Debugging,Thread-safety,Compilation contexts
4146 @anchor{topics/contexts error-handling}@anchor{19}@anchor{topics/contexts id1}@anchor{4f}
4147 @subsection Error-handling
4150 Various kinds of errors are possible when using the API, such as
4151 mismatched types in an assignment. You can only compile and get code from
4152 a context if no errors occur.
4154 Errors are printed on stderr and can be queried using
4155 @pxref{50,,gcc_jit_context_get_first_error()}.
4157 They typically contain the name of the API entrypoint where the error
4158 occurred, and pertinent information on the problem:
4161 ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *)
4166 In general, if an error occurs when using an API entrypoint, the
4167 entrypoint returns NULL. You don't have to check everywhere for NULL
4168 results, since the API handles a NULL being passed in for any
4169 argument by issuing another error. This typically leads to a cascade of
4170 followup error messages, but is safe (albeit verbose). The first error
4171 message is usually the one to pay attention to, since it is likely to
4172 be responsible for all of the rest:
4174 @geindex gcc_jit_context_get_first_error (C function)
4175 @anchor{topics/contexts gcc_jit_context_get_first_error}@anchor{50}
4176 @deffn {C Function} const char * gcc_jit_context_get_first_error (gcc_jit_context@w{ }*ctxt)
4178 Returns the first error message that occurred on the context.
4180 The returned string is valid for the rest of the lifetime of the
4183 If no errors occurred, this will be NULL.
4186 If you are wrapping the C API for a higher-level language that supports
4187 exception-handling, you may instead by interested in the last error that
4188 occurred on the context, so that you can embed this in an exception:
4190 @geindex gcc_jit_context_get_last_error (C function)
4191 @anchor{topics/contexts gcc_jit_context_get_last_error}@anchor{51}
4192 @deffn {C Function} const char * gcc_jit_context_get_last_error (gcc_jit_context@w{ }*ctxt)
4194 Returns the last error message that occurred on the context.
4196 The returned string is valid for the rest of the lifetime of the
4199 If no errors occurred, this will be NULL.
4202 @node Debugging,Options<2>,Error-handling<2>,Compilation contexts
4203 @anchor{topics/contexts debugging}@anchor{52}
4204 @subsection Debugging
4207 @geindex gcc_jit_context_dump_to_file (C function)
4208 @anchor{topics/contexts gcc_jit_context_dump_to_file}@anchor{53}
4209 @deffn {C Function} void gcc_jit_context_dump_to_file (gcc_jit_context@w{ }*ctxt, const char@w{ }*path, int@w{ }update_locations)
4211 To help with debugging: dump a C-like representation to the given path,
4212 describing what's been set up on the context.
4214 If "update_locations" is true, then also set up @pxref{3b,,gcc_jit_location}
4215 information throughout the context, pointing at the dump file as if it
4216 were a source file. This may be of use in conjunction with
4217 @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to allow stepping through the
4221 @geindex gcc_jit_context_set_logfile (C function)
4222 @anchor{topics/contexts gcc_jit_context_set_logfile}@anchor{54}
4223 @deffn {C Function} void gcc_jit_context_set_logfile (gcc_jit_context@w{ }*ctxt, FILE@w{ }*logfile, int@w{ }flags, int@w{ }verbosity)
4225 To help with debugging; enable ongoing logging of the context's
4226 activity to the given file.
4228 For example, the following will enable logging to stderr.
4231 gcc_jit_context_set_logfile (ctxt, stderr, 0, 0);
4236 Examples of information logged include:
4245 the various steps involved within compilation
4248 activity on any @pxref{16,,gcc_jit_result} instances created by
4252 activity within any child contexts
4255 An example of a log can be seen @pxref{55,,here},
4256 though the precise format and kinds of information logged is subject
4259 The caller remains responsible for closing @cite{logfile}, and it must not
4260 be closed until all users are released. In particular, note that
4261 child contexts and @pxref{16,,gcc_jit_result} instances created by
4262 the context will use the logfile.
4264 There may a performance cost for logging.
4266 You can turn off logging on @cite{ctxt} by passing @cite{NULL} for @cite{logfile}.
4267 Doing so only affects the context; it does not affect child contexts
4268 or @pxref{16,,gcc_jit_result} instances already created by
4271 The parameters "flags" and "verbosity" are reserved for future
4272 expansion, and must be zero for now.
4275 To contrast the above: @pxref{53,,gcc_jit_context_dump_to_file()} dumps the
4276 current state of a context to the given path, whereas
4277 @pxref{54,,gcc_jit_context_set_logfile()} enables on-going logging of
4278 future activies on a context to the given @cite{FILE *}.
4280 @geindex gcc_jit_context_dump_reproducer_to_file (C function)
4281 @anchor{topics/contexts gcc_jit_context_dump_reproducer_to_file}@anchor{56}
4282 @deffn {C Function} void gcc_jit_context_dump_reproducer_to_file (gcc_jit_context@w{ }*ctxt, const char@w{ }*path)
4284 Write C source code into @cite{path} that can be compiled into a
4285 self-contained executable (i.e. with libgccjit as the only dependency).
4286 The generated code will attempt to replay the API calls that have been
4287 made into the given context.
4289 This may be useful when debugging the library or client code, for
4290 reducing a complicated recipe for reproducing a bug into a simpler
4291 form. For example, consider client code that parses some source file
4292 into some internal representation, and then walks this IR, calling into
4293 libgccjit. If this encounters a bug, a call to
4294 @cite{gcc_jit_context_dump_reproducer_to_file} will write out C code for
4295 a much simpler executable that performs the equivalent calls into
4296 libgccjit, without needing the client code and its data.
4298 Typically you need to supply @code{-Wno-unused-variable} when
4299 compiling the generated file (since the result of each API call is
4300 assigned to a unique variable within the generated C source, and not
4301 all are necessarily then used).
4304 @geindex gcc_jit_context_enable_dump (C function)
4305 @anchor{topics/contexts gcc_jit_context_enable_dump}@anchor{57}
4306 @deffn {C Function} void gcc_jit_context_enable_dump (gcc_jit_context@w{ }*ctxt, const char@w{ }*dumpname, char@w{ }**out_ptr)
4308 Enable the dumping of a specific set of internal state from the
4309 compilation, capturing the result in-memory as a buffer.
4311 Parameter "dumpname" corresponds to the equivalent gcc command-line
4312 option, without the "-fdump-" prefix.
4313 For example, to get the equivalent of @code{-fdump-tree-vrp1},
4314 supply @code{"tree-vrp1"}:
4317 static char *dump_vrp1;
4320 create_code (gcc_jit_context *ctxt)
4322 gcc_jit_context_enable_dump (ctxt, "tree-vrp1", &dump_vrp1);
4323 /* (other API calls omitted for brevity) */
4329 The context directly stores the dumpname as a @code{(const char *)}, so
4330 the passed string must outlive the context.
4332 @pxref{15,,gcc_jit_context_compile()} will capture the dump as a
4333 dynamically-allocated buffer, writing it to @code{*out_ptr}.
4335 The caller becomes responsible for calling:
4343 each time that @pxref{15,,gcc_jit_context_compile()} is called.
4344 @code{*out_ptr} will be written to, either with the address of a buffer,
4345 or with @code{NULL} if an error occurred.
4349 This API entrypoint is likely to be less stable than the others.
4350 In particular, both the precise dumpnames, and the format and content
4351 of the dumps are subject to change.
4353 It exists primarily for writing the library's own test suite.
4358 @node Options<2>,,Debugging,Compilation contexts
4359 @anchor{topics/contexts options}@anchor{58}
4370 @node String Options,Boolean options,,Options<2>
4371 @anchor{topics/contexts string-options}@anchor{59}
4372 @subsubsection String Options
4375 @geindex gcc_jit_context_set_str_option (C function)
4376 @anchor{topics/contexts gcc_jit_context_set_str_option}@anchor{5a}
4377 @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)
4379 Set a string option of the context.
4381 @geindex gcc_jit_str_option (C type)
4382 @anchor{topics/contexts gcc_jit_str_option}@anchor{5b}
4383 @deffn {C Type} enum gcc_jit_str_option
4386 There is currently just one string option:
4388 @geindex GCC_JIT_STR_OPTION_PROGNAME (C macro)
4389 @anchor{topics/contexts GCC_JIT_STR_OPTION_PROGNAME}@anchor{5c}
4390 @deffn {C Macro} GCC_JIT_STR_OPTION_PROGNAME
4392 The name of the program, for use as a prefix when printing error
4393 messages to stderr. If @cite{NULL}, or default, "libgccjit.so" is used.
4397 @node Boolean options,Integer options,String Options,Options<2>
4398 @anchor{topics/contexts boolean-options}@anchor{5d}
4399 @subsubsection Boolean options
4402 @geindex gcc_jit_context_set_bool_option (C function)
4403 @anchor{topics/contexts gcc_jit_context_set_bool_option}@anchor{1b}
4404 @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)
4406 Set a boolean option of the context.
4407 Zero is "false" (the default), non-zero is "true".
4409 @geindex gcc_jit_bool_option (C type)
4410 @anchor{topics/contexts gcc_jit_bool_option}@anchor{5e}
4411 @deffn {C Type} enum gcc_jit_bool_option
4414 @geindex GCC_JIT_BOOL_OPTION_DEBUGINFO (C macro)
4415 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_DEBUGINFO}@anchor{42}
4416 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DEBUGINFO
4418 If true, @pxref{15,,gcc_jit_context_compile()} will attempt to do the right
4419 thing so that if you attach a debugger to the process, it will
4420 be able to inspect variables and step through your code.
4422 Note that you can't step through code unless you set up source
4423 location information for the code (by creating and passing in
4424 @pxref{3b,,gcc_jit_location} instances).
4427 @geindex GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE (C macro)
4428 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}@anchor{5f}
4429 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE
4431 If true, @pxref{15,,gcc_jit_context_compile()} will dump its initial
4432 "tree" representation of your code to stderr (before any
4435 Here's some sample output (from the @cite{square} example):
4438 <statement_list 0x7f4875a62cc0
4439 type <void_type 0x7f4875a64bd0 VOID
4440 align 8 symtab 0 alias set -1 canonical type 0x7f4875a64bd0
4441 pointer_to_this <pointer_type 0x7f4875a64c78>>
4442 side-effects head 0x7f4875a761e0 tail 0x7f4875a761f8 stmts 0x7f4875a62d20 0x7f4875a62d00
4444 stmt <label_expr 0x7f4875a62d20 type <void_type 0x7f4875a64bd0>
4446 arg 0 <label_decl 0x7f4875a79080 entry type <void_type 0x7f4875a64bd0>
4447 VOID file (null) line 0 col 0
4448 align 1 context <function_decl 0x7f4875a77500 square>>>
4449 stmt <return_expr 0x7f4875a62d00
4450 type <integer_type 0x7f4875a645e8 public SI
4451 size <integer_cst 0x7f4875a623a0 constant 32>
4452 unit size <integer_cst 0x7f4875a623c0 constant 4>
4453 align 32 symtab 0 alias set -1 canonical type 0x7f4875a645e8 precision 32 min <integer_cst 0x7f4875a62340 -2147483648> max <integer_cst 0x7f4875a62360 2147483647>
4454 pointer_to_this <pointer_type 0x7f4875a6b348>>
4456 arg 0 <modify_expr 0x7f4875a72a78 type <integer_type 0x7f4875a645e8>
4457 side-effects arg 0 <result_decl 0x7f4875a7a000 D.54>
4458 arg 1 <mult_expr 0x7f4875a72a50 type <integer_type 0x7f4875a645e8>
4459 arg 0 <parm_decl 0x7f4875a79000 i> arg 1 <parm_decl 0x7f4875a79000 i>>>>>
4465 @geindex GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE (C macro)
4466 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE}@anchor{1c}
4467 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE
4469 If true, @pxref{15,,gcc_jit_context_compile()} will dump the "gimple"
4470 representation of your code to stderr, before any optimizations
4471 are performed. The dump resembles C code:
4474 square (signed int i)
4487 @geindex GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE (C macro)
4488 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE}@anchor{1d}
4489 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE
4491 If true, @pxref{15,,gcc_jit_context_compile()} will dump the final
4492 generated code to stderr, in the form of assembly language:
4498 .type square, @@function
4503 .cfi_def_cfa_offset 16
4506 .cfi_def_cfa_register 6
4510 imull -4(%rbp), %eax
4516 .size square, .-square
4517 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.1-%@{gcc_release@})"
4518 .section .note.GNU-stack,"",@@progbits
4524 @geindex GCC_JIT_BOOL_OPTION_DUMP_SUMMARY (C macro)
4525 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_SUMMARY}@anchor{60}
4526 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_SUMMARY
4528 If true, @pxref{15,,gcc_jit_context_compile()} will print information to stderr
4529 on the actions it is performing, followed by a profile showing
4530 the time taken and memory usage of each phase.
4533 @geindex GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING (C macro)
4534 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING}@anchor{61}
4535 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING
4537 If true, @pxref{15,,gcc_jit_context_compile()} will dump copious
4538 amount of information on what it's doing to various
4539 files within a temporary directory. Use
4540 @pxref{62,,GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES} (see below) to
4541 see the results. The files are intended to be human-readable,
4542 but the exact files and their formats are subject to change.
4545 @geindex GCC_JIT_BOOL_OPTION_SELFCHECK_GC (C macro)
4546 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_SELFCHECK_GC}@anchor{63}
4547 @deffn {C Macro} GCC_JIT_BOOL_OPTION_SELFCHECK_GC
4549 If true, libgccjit will aggressively run its garbage collector, to
4550 shake out bugs (greatly slowing down the compile). This is likely
4551 to only be of interest to developers @emph{of} the library. It is
4552 used when running the selftest suite.
4555 @geindex GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES (C macro)
4556 @anchor{topics/contexts GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES}@anchor{62}
4557 @deffn {C Macro} GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES
4559 If true, the @pxref{8,,gcc_jit_context} will not clean up intermediate files
4560 written to the filesystem, and will display their location on stderr.
4564 @node Integer options,,Boolean options,Options<2>
4565 @anchor{topics/contexts integer-options}@anchor{64}
4566 @subsubsection Integer options
4569 @geindex gcc_jit_context_set_int_option (C function)
4570 @anchor{topics/contexts gcc_jit_context_set_int_option}@anchor{1e}
4571 @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)
4573 Set an integer option of the context.
4575 @geindex gcc_jit_int_option (C type)
4576 @anchor{topics/contexts gcc_jit_int_option}@anchor{65}
4577 @deffn {C Type} enum gcc_jit_int_option
4580 There is currently just one integer option:
4582 @geindex GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL (C macro)
4583 @anchor{topics/contexts GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}@anchor{1f}
4584 @deffn {C Macro} GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL
4586 How much to optimize the code.
4588 Valid values are 0-3, corresponding to GCC's command-line options
4591 The default value is 0 (unoptimized).
4595 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
4596 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
4598 @c This is free software: you can redistribute it and/or modify it
4599 @c under the terms of the GNU General Public License as published by
4600 @c the Free Software Foundation, either version 3 of the License, or
4601 @c (at your option) any later version.
4603 @c This program is distributed in the hope that it will be useful, but
4604 @c WITHOUT ANY WARRANTY; without even the implied warranty of
4605 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4606 @c General Public License for more details.
4608 @c You should have received a copy of the GNU General Public License
4609 @c along with this program. If not, see
4610 @c <http://www.gnu.org/licenses/>.
4612 @node Objects,Types,Compilation contexts,Topic Reference
4613 @anchor{topics/objects objects}@anchor{66}@anchor{topics/objects doc}@anchor{67}
4617 @geindex gcc_jit_object (C type)
4618 @anchor{topics/objects gcc_jit_object}@anchor{e}
4619 @deffn {C Type} gcc_jit_object
4622 Almost every entity in the API (with the exception of
4623 @pxref{8,,gcc_jit_context *} and @pxref{16,,gcc_jit_result *}) is a
4624 "contextual" object, a @pxref{e,,gcc_jit_object *}
4634 is associated with a @pxref{8,,gcc_jit_context *}.
4637 is automatically cleaned up for you when its context is released so
4638 you don't need to manually track and cleanup all objects, just the
4643 Although the API is C-based, there is a form of class hierarchy, which
4661 There are casting methods for upcasting from subclasses to parent classes.
4662 For example, @pxref{d,,gcc_jit_type_as_object()}:
4665 gcc_jit_object *obj = gcc_jit_type_as_object (int_type);
4670 The object "base class" has the following operations:
4672 @geindex gcc_jit_object_get_context (C function)
4673 @anchor{topics/objects gcc_jit_object_get_context}@anchor{68}
4674 @deffn {C Function} gcc_jit_context *gcc_jit_object_get_context (gcc_jit_object@w{ }*obj)
4676 Which context is "obj" within?
4679 @geindex gcc_jit_object_get_debug_string (C function)
4680 @anchor{topics/objects gcc_jit_object_get_debug_string}@anchor{f}
4681 @deffn {C Function} const char *gcc_jit_object_get_debug_string (gcc_jit_object@w{ }*obj)
4683 Generate a human-readable description for the given object.
4688 printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj));
4693 might give this text on stdout:
4703 If you call this on an object, the @cite{const char *} buffer is allocated
4704 and generated on the first call for that object, and the buffer will
4705 have the same lifetime as the object i.e. it will exist until the
4706 object's context is released.
4711 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
4712 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
4714 @c This is free software: you can redistribute it and/or modify it
4715 @c under the terms of the GNU General Public License as published by
4716 @c the Free Software Foundation, either version 3 of the License, or
4717 @c (at your option) any later version.
4719 @c This program is distributed in the hope that it will be useful, but
4720 @c WITHOUT ANY WARRANTY; without even the implied warranty of
4721 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4722 @c General Public License for more details.
4724 @c You should have received a copy of the GNU General Public License
4725 @c along with this program. If not, see
4726 @c <http://www.gnu.org/licenses/>.
4728 @node Types,Expressions,Objects,Topic Reference
4729 @anchor{topics/types doc}@anchor{69}@anchor{topics/types types}@anchor{6a}
4733 @geindex gcc_jit_type (C type)
4734 @anchor{topics/types gcc_jit_type}@anchor{a}
4735 @deffn {C Type} gcc_jit_type
4737 gcc_jit_type represents a type within the library.
4740 @geindex gcc_jit_type_as_object (C function)
4741 @anchor{topics/types gcc_jit_type_as_object}@anchor{d}
4742 @deffn {C Function} gcc_jit_object *gcc_jit_type_as_object (gcc_jit_type@w{ }*type)
4744 Upcast a type to an object.
4747 Types can be created in several ways:
4753 fundamental types can be accessed using
4754 @pxref{b,,gcc_jit_context_get_type()}:
4757 gcc_jit_type *int_type = gcc_jit_context_get_type (GCC_JIT_TYPE_INT);
4762 See @pxref{b,,gcc_jit_context_get_type()} for the available types.
4765 derived types can be accessed by using functions such as
4766 @pxref{6b,,gcc_jit_type_get_pointer()} and @pxref{6c,,gcc_jit_type_get_const()}:
4769 gcc_jit_type *const_int_star = gcc_jit_type_get_pointer (gcc_jit_type_get_const (int_type));
4770 gcc_jit_type *int_const_star = gcc_jit_type_get_const (gcc_jit_type_get_pointer (int_type));
4776 by creating structures (see below).
4781 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile.
4782 * Structures and unions::
4786 @node Standard types,Pointers const and volatile,,Types
4787 @anchor{topics/types standard-types}@anchor{6d}
4788 @subsection Standard types
4791 @geindex gcc_jit_context_get_type (C function)
4792 @anchor{topics/types gcc_jit_context_get_type}@anchor{b}
4793 @deffn {C Function} gcc_jit_type *gcc_jit_context_get_type (gcc_jit_context@w{ }*ctxt, enum gcc_jit_types@w{ }type_)
4795 Access a specific type. The available types are:
4798 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
4801 @cite{enum gcc_jit_types} value
4809 @code{GCC_JIT_TYPE_VOID}
4813 C's @code{void} type.
4817 @code{GCC_JIT_TYPE_VOID_PTR}
4825 @code{GCC_JIT_TYPE_BOOL}
4829 C++'s @code{bool} type; also C99's
4830 @code{_Bool} type, aka @code{bool} if
4835 @code{GCC_JIT_TYPE_CHAR}
4839 C's @code{char} (of some signedness)
4843 @code{GCC_JIT_TYPE_SIGNED_CHAR}
4847 C's @code{signed char}
4851 @code{GCC_JIT_TYPE_UNSIGNED_CHAR}
4855 C's @code{unsigned char}
4859 @code{GCC_JIT_TYPE_SHORT}
4863 C's @code{short} (signed)
4867 @code{GCC_JIT_TYPE_UNSIGNED_SHORT}
4871 C's @code{unsigned short}
4875 @code{GCC_JIT_TYPE_INT}
4879 C's @code{int} (signed)
4883 @code{GCC_JIT_TYPE_UNSIGNED_INT}
4887 C's @code{unsigned int}
4891 @code{GCC_JIT_TYPE_LONG}
4895 C's @code{long} (signed)
4899 @code{GCC_JIT_TYPE_UNSIGNED_LONG}
4903 C's @code{unsigned long}
4907 @code{GCC_JIT_TYPE_LONG_LONG}
4911 C99's @code{long long} (signed)
4915 @code{GCC_JIT_TYPE_UNSIGNED_LONG_LONG}
4919 C99's @code{unsigned long long}
4923 @code{GCC_JIT_TYPE_FLOAT}
4929 @code{GCC_JIT_TYPE_DOUBLE}
4935 @code{GCC_JIT_TYPE_LONG_DOUBLE}
4941 @code{GCC_JIT_TYPE_CONST_CHAR_PTR}
4945 C type: @code{(const char *)}
4949 @code{GCC_JIT_TYPE_SIZE_T}
4953 C's @code{size_t} type
4957 @code{GCC_JIT_TYPE_FILE_PTR}
4961 C type: @code{(FILE *)}
4965 @code{GCC_JIT_TYPE_COMPLEX_FLOAT}
4969 C99's @code{_Complex float}
4973 @code{GCC_JIT_TYPE_COMPLEX_DOUBLE}
4977 C99's @code{_Complex double}
4981 @code{GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE}
4985 C99's @code{_Complex long double}
4991 @geindex gcc_jit_context_get_int_type (C function)
4992 @anchor{topics/types gcc_jit_context_get_int_type}@anchor{6e}
4993 @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)
4995 Access the integer type of the given size.
4998 @node Pointers const and volatile,Structures and unions,Standard types,Types
4999 @anchor{topics/types pointers-const-and-volatile}@anchor{6f}
5000 @subsection Pointers, @cite{const}, and @cite{volatile}
5003 @geindex gcc_jit_type_get_pointer (C function)
5004 @anchor{topics/types gcc_jit_type_get_pointer}@anchor{6b}
5005 @deffn {C Function} gcc_jit_type *gcc_jit_type_get_pointer (gcc_jit_type@w{ }*type)
5007 Given type "T", get type "T*".
5010 @geindex gcc_jit_type_get_const (C function)
5011 @anchor{topics/types gcc_jit_type_get_const}@anchor{6c}
5012 @deffn {C Function} gcc_jit_type *gcc_jit_type_get_const (gcc_jit_type@w{ }*type)
5014 Given type "T", get type "const T".
5017 @geindex gcc_jit_type_get_volatile (C function)
5018 @anchor{topics/types gcc_jit_type_get_volatile}@anchor{70}
5019 @deffn {C Function} gcc_jit_type *gcc_jit_type_get_volatile (gcc_jit_type@w{ }*type)
5021 Given type "T", get type "volatile T".
5024 @geindex gcc_jit_context_new_array_type (C function)
5025 @anchor{topics/types gcc_jit_context_new_array_type}@anchor{71}
5026 @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)
5028 Given type "T", get type "T[N]" (for a constant N).
5031 @node Structures and unions,,Pointers const and volatile,Types
5032 @anchor{topics/types structures-and-unions}@anchor{72}
5033 @subsection Structures and unions
5036 @geindex gcc_jit_struct (C type)
5037 @anchor{topics/types gcc_jit_struct}@anchor{73}
5038 @deffn {C Type} gcc_jit_struct
5041 A compound type analagous to a C @cite{struct}.
5043 @geindex gcc_jit_field (C type)
5044 @anchor{topics/types gcc_jit_field}@anchor{74}
5045 @deffn {C Type} gcc_jit_field
5048 A field within a @pxref{73,,gcc_jit_struct}.
5050 You can model C @cite{struct} types by creating @pxref{73,,gcc_jit_struct *} and
5051 @pxref{74,,gcc_jit_field} instances, in either order:
5057 by creating the fields, then the structure. For example, to model:
5060 struct coord @{double x; double y; @};
5068 gcc_jit_field *field_x =
5069 gcc_jit_context_new_field (ctxt, NULL, double_type, "x");
5070 gcc_jit_field *field_y =
5071 gcc_jit_context_new_field (ctxt, NULL, double_type, "y");
5072 gcc_jit_field *fields[2] = @{field_x, field_y@};
5073 gcc_jit_struct *coord =
5074 gcc_jit_context_new_struct_type (ctxt, NULL, "coord", 2, fields);
5080 by creating the structure, then populating it with fields, typically
5081 to allow modelling self-referential structs such as:
5084 struct node @{ int m_hash; struct node *m_next; @};
5092 gcc_jit_type *node =
5093 gcc_jit_context_new_opaque_struct (ctxt, NULL, "node");
5094 gcc_jit_type *node_ptr =
5095 gcc_jit_type_get_pointer (node);
5096 gcc_jit_field *field_hash =
5097 gcc_jit_context_new_field (ctxt, NULL, int_type, "m_hash");
5098 gcc_jit_field *field_next =
5099 gcc_jit_context_new_field (ctxt, NULL, node_ptr, "m_next");
5100 gcc_jit_field *fields[2] = @{field_hash, field_next@};
5101 gcc_jit_struct_set_fields (node, NULL, 2, fields);
5107 @geindex gcc_jit_context_new_field (C function)
5108 @anchor{topics/types gcc_jit_context_new_field}@anchor{75}
5109 @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)
5111 Construct a new field, with the given type and name.
5114 @geindex gcc_jit_field_as_object (C function)
5115 @anchor{topics/types gcc_jit_field_as_object}@anchor{76}
5116 @deffn {C Function} gcc_jit_object * gcc_jit_field_as_object (gcc_jit_field@w{ }*field)
5118 Upcast from field to object.
5121 @geindex gcc_jit_context_new_struct_type (C function)
5122 @anchor{topics/types gcc_jit_context_new_struct_type}@anchor{77}
5123 @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)
5127 Construct a new struct type, with the given name and fields.
5131 @geindex gcc_jit_context_new_opaque_struct (C function)
5132 @anchor{topics/types gcc_jit_context_new_opaque_struct}@anchor{78}
5133 @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)
5135 Construct a new struct type, with the given name, but without
5136 specifying the fields. The fields can be omitted (in which case the
5137 size of the struct is not known), or later specified using
5138 @pxref{79,,gcc_jit_struct_set_fields()}.
5141 @geindex gcc_jit_struct_as_type (C function)
5142 @anchor{topics/types gcc_jit_struct_as_type}@anchor{7a}
5143 @deffn {C Function} gcc_jit_type * gcc_jit_struct_as_type (gcc_jit_struct@w{ }*struct_type)
5145 Upcast from struct to type.
5148 @geindex gcc_jit_struct_set_fields (C function)
5149 @anchor{topics/types gcc_jit_struct_set_fields}@anchor{79}
5150 @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)
5152 Populate the fields of a formerly-opaque struct type.
5154 This can only be called once on a given struct type.
5157 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
5158 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
5160 @c This is free software: you can redistribute it and/or modify it
5161 @c under the terms of the GNU General Public License as published by
5162 @c the Free Software Foundation, either version 3 of the License, or
5163 @c (at your option) any later version.
5165 @c This program is distributed in the hope that it will be useful, but
5166 @c WITHOUT ANY WARRANTY; without even the implied warranty of
5167 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5168 @c General Public License for more details.
5170 @c You should have received a copy of the GNU General Public License
5171 @c along with this program. If not, see
5172 @c <http://www.gnu.org/licenses/>.
5174 @node Expressions,Creating and using functions,Types,Topic Reference
5175 @anchor{topics/expressions expressions}@anchor{7b}@anchor{topics/expressions doc}@anchor{7c}
5176 @section Expressions
5182 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions.
5186 * Simple expressions::
5187 * Unary Operations::
5188 * Binary Operations::
5195 * Global variables::
5200 @node Rvalues,Lvalues,,Expressions
5201 @anchor{topics/expressions rvalues}@anchor{7d}
5205 @geindex gcc_jit_rvalue (C type)
5206 @anchor{topics/expressions gcc_jit_rvalue}@anchor{13}
5207 @deffn {C Type} gcc_jit_rvalue
5210 A @pxref{13,,gcc_jit_rvalue *} is an expression that can be computed.
5212 It can be simple, e.g.:
5220 an integer value e.g. @cite{0} or @cite{42}
5223 a string literal e.g. @cite{"Hello world"}
5226 a variable e.g. @cite{i}. These are also lvalues (see below).
5238 a unary expression e.g. @cite{!cond}
5241 a binary expression e.g. @cite{(a + b)}
5244 a function call e.g. @cite{get_distance (&player_ship@comma{} &target)}
5251 Every rvalue has an associated type, and the API will check to ensure
5252 that types match up correctly (otherwise the context will emit an error).
5254 @geindex gcc_jit_rvalue_get_type (C function)
5255 @anchor{topics/expressions gcc_jit_rvalue_get_type}@anchor{7e}
5256 @deffn {C Function} gcc_jit_type *gcc_jit_rvalue_get_type (gcc_jit_rvalue@w{ }*rvalue)
5258 Get the type of this rvalue.
5261 @geindex gcc_jit_rvalue_as_object (C function)
5262 @anchor{topics/expressions gcc_jit_rvalue_as_object}@anchor{14}
5263 @deffn {C Function} gcc_jit_object *gcc_jit_rvalue_as_object (gcc_jit_rvalue@w{ }*rvalue)
5265 Upcast the given rvalue to be an object.
5269 * Simple expressions::
5270 * Unary Operations::
5271 * Binary Operations::
5278 @node Simple expressions,Unary Operations,,Rvalues
5279 @anchor{topics/expressions simple-expressions}@anchor{7f}
5280 @subsubsection Simple expressions
5283 @geindex gcc_jit_context_new_rvalue_from_int (C function)
5284 @anchor{topics/expressions gcc_jit_context_new_rvalue_from_int}@anchor{30}
5285 @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)
5287 Given a numeric type (integer or floating point), build an rvalue for
5288 the given constant @code{int} value.
5291 @geindex gcc_jit_context_new_rvalue_from_long (C function)
5292 @anchor{topics/expressions gcc_jit_context_new_rvalue_from_long}@anchor{80}
5293 @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)
5295 Given a numeric type (integer or floating point), build an rvalue for
5296 the given constant @code{long} value.
5299 @geindex gcc_jit_context_zero (C function)
5300 @anchor{topics/expressions gcc_jit_context_zero}@anchor{2b}
5301 @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type)
5303 Given a numeric type (integer or floating point), get the rvalue for
5304 zero. Essentially this is just a shortcut for:
5307 gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 0)
5313 @geindex gcc_jit_context_one (C function)
5314 @anchor{topics/expressions gcc_jit_context_one}@anchor{2f}
5315 @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_one (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type)
5317 Given a numeric type (integer or floating point), get the rvalue for
5318 zero. Essentially this is just a shortcut for:
5321 gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 1)
5327 @geindex gcc_jit_context_new_rvalue_from_double (C function)
5328 @anchor{topics/expressions gcc_jit_context_new_rvalue_from_double}@anchor{31}
5329 @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)
5331 Given a numeric type (integer or floating point), build an rvalue for
5332 the given constant @code{double} value.
5335 @geindex gcc_jit_context_new_rvalue_from_ptr (C function)
5336 @anchor{topics/expressions gcc_jit_context_new_rvalue_from_ptr}@anchor{81}
5337 @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)
5339 Given a pointer type, build an rvalue for the given address.
5342 @geindex gcc_jit_context_null (C function)
5343 @anchor{topics/expressions gcc_jit_context_null}@anchor{82}
5344 @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_null (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*pointer_type)
5346 Given a pointer type, build an rvalue for @code{NULL}. Essentially this
5347 is just a shortcut for:
5350 gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL)
5356 @geindex gcc_jit_context_new_string_literal (C function)
5357 @anchor{topics/expressions gcc_jit_context_new_string_literal}@anchor{83}
5358 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_string_literal (gcc_jit_context@w{ }*ctxt, const char@w{ }*value)
5360 Generate an rvalue for the given NIL-terminated string, of type
5361 @code{GCC_JIT_TYPE_CONST_CHAR_PTR}.
5364 @node Unary Operations,Binary Operations,Simple expressions,Rvalues
5365 @anchor{topics/expressions unary-operations}@anchor{84}
5366 @subsubsection Unary Operations
5369 @geindex gcc_jit_context_new_unary_op (C function)
5370 @anchor{topics/expressions gcc_jit_context_new_unary_op}@anchor{85}
5371 @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)
5373 Build a unary operation out of an input rvalue.
5376 @geindex gcc_jit_unary_op (C type)
5377 @anchor{topics/expressions gcc_jit_unary_op}@anchor{86}
5378 @deffn {C Type} enum gcc_jit_unary_op
5381 The available unary operations are:
5384 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx}
5395 @pxref{87,,GCC_JIT_UNARY_OP_MINUS}
5403 @pxref{88,,GCC_JIT_UNARY_OP_BITWISE_NEGATE}
5411 @pxref{89,,GCC_JIT_UNARY_OP_LOGICAL_NEGATE}
5419 @pxref{8a,,GCC_JIT_UNARY_OP_ABS}
5428 @geindex GCC_JIT_UNARY_OP_MINUS (C macro)
5429 @anchor{topics/expressions GCC_JIT_UNARY_OP_MINUS}@anchor{87}
5430 @deffn {C Macro} GCC_JIT_UNARY_OP_MINUS
5432 Negate an arithmetic value; analogous to:
5443 @geindex GCC_JIT_UNARY_OP_BITWISE_NEGATE (C macro)
5444 @anchor{topics/expressions GCC_JIT_UNARY_OP_BITWISE_NEGATE}@anchor{88}
5445 @deffn {C Macro} GCC_JIT_UNARY_OP_BITWISE_NEGATE
5447 Bitwise negation of an integer value (one's complement); analogous
5459 @geindex GCC_JIT_UNARY_OP_LOGICAL_NEGATE (C macro)
5460 @anchor{topics/expressions GCC_JIT_UNARY_OP_LOGICAL_NEGATE}@anchor{89}
5461 @deffn {C Macro} GCC_JIT_UNARY_OP_LOGICAL_NEGATE
5463 Logical negation of an arithmetic or pointer value; analogous to:
5474 @geindex GCC_JIT_UNARY_OP_ABS (C macro)
5475 @anchor{topics/expressions GCC_JIT_UNARY_OP_ABS}@anchor{8a}
5476 @deffn {C Macro} GCC_JIT_UNARY_OP_ABS
5478 Absolute value of an arithmetic expression; analogous to:
5489 @node Binary Operations,Comparisons,Unary Operations,Rvalues
5490 @anchor{topics/expressions binary-operations}@anchor{8b}
5491 @subsubsection Binary Operations
5494 @geindex gcc_jit_context_new_binary_op (C function)
5495 @anchor{topics/expressions gcc_jit_context_new_binary_op}@anchor{12}
5496 @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)
5498 Build a binary operation out of two constituent rvalues.
5501 @geindex gcc_jit_binary_op (C type)
5502 @anchor{topics/expressions gcc_jit_binary_op}@anchor{8c}
5503 @deffn {C Type} enum gcc_jit_binary_op
5506 The available binary operations are:
5509 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx}
5520 @pxref{8d,,GCC_JIT_BINARY_OP_PLUS}
5528 @code{GCC_JIT_BINARY_OP_MINUS}
5536 @pxref{8e,,GCC_JIT_BINARY_OP_MULT}
5544 @pxref{8f,,GCC_JIT_BINARY_OP_DIVIDE}
5552 @pxref{90,,GCC_JIT_BINARY_OP_MODULO}
5560 @pxref{91,,GCC_JIT_BINARY_OP_BITWISE_AND}
5568 @pxref{92,,GCC_JIT_BINARY_OP_BITWISE_XOR}
5576 @pxref{93,,GCC_JIT_BINARY_OP_BITWISE_OR}
5584 @pxref{94,,GCC_JIT_BINARY_OP_LOGICAL_AND}
5592 @pxref{95,,GCC_JIT_BINARY_OP_LOGICAL_OR}
5600 @pxref{96,,GCC_JIT_BINARY_OP_LSHIFT}
5608 @pxref{97,,GCC_JIT_BINARY_OP_RSHIFT}
5617 @geindex GCC_JIT_BINARY_OP_PLUS (C macro)
5618 @anchor{topics/expressions GCC_JIT_BINARY_OP_PLUS}@anchor{8d}
5619 @deffn {C Macro} GCC_JIT_BINARY_OP_PLUS
5621 Addition of arithmetic values; analogous to:
5631 For pointer addition, use @pxref{98,,gcc_jit_context_new_array_access()}.
5635 @deffn {C Macro} GCC_JIT_BINARY_OP_MINUS`
5637 Subtraction of arithmetic values; analogous to:
5648 @geindex GCC_JIT_BINARY_OP_MULT (C macro)
5649 @anchor{topics/expressions GCC_JIT_BINARY_OP_MULT}@anchor{8e}
5650 @deffn {C Macro} GCC_JIT_BINARY_OP_MULT
5652 Multiplication of a pair of arithmetic values; analogous to:
5663 @geindex GCC_JIT_BINARY_OP_DIVIDE (C macro)
5664 @anchor{topics/expressions GCC_JIT_BINARY_OP_DIVIDE}@anchor{8f}
5665 @deffn {C Macro} GCC_JIT_BINARY_OP_DIVIDE
5667 Quotient of division of arithmetic values; analogous to:
5677 The result type affects the kind of division: if the result type is
5678 integer-based, then the result is truncated towards zero, whereas
5679 a floating-point result type indicates floating-point division.
5682 @geindex GCC_JIT_BINARY_OP_MODULO (C macro)
5683 @anchor{topics/expressions GCC_JIT_BINARY_OP_MODULO}@anchor{90}
5684 @deffn {C Macro} GCC_JIT_BINARY_OP_MODULO
5686 Remainder of division of arithmetic values; analogous to:
5697 @geindex GCC_JIT_BINARY_OP_BITWISE_AND (C macro)
5698 @anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_AND}@anchor{91}
5699 @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_AND
5701 Bitwise AND; analogous to:
5712 @geindex GCC_JIT_BINARY_OP_BITWISE_XOR (C macro)
5713 @anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_XOR}@anchor{92}
5714 @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_XOR
5716 Bitwise exclusive OR; analogous to:
5727 @geindex GCC_JIT_BINARY_OP_BITWISE_OR (C macro)
5728 @anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_OR}@anchor{93}
5729 @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_OR
5731 Bitwise inclusive OR; analogous to:
5742 @geindex GCC_JIT_BINARY_OP_LOGICAL_AND (C macro)
5743 @anchor{topics/expressions GCC_JIT_BINARY_OP_LOGICAL_AND}@anchor{94}
5744 @deffn {C Macro} GCC_JIT_BINARY_OP_LOGICAL_AND
5746 Logical AND; analogous to:
5749 (EXPR_A) && (EXPR_B)
5757 @geindex GCC_JIT_BINARY_OP_LOGICAL_OR (C macro)
5758 @anchor{topics/expressions GCC_JIT_BINARY_OP_LOGICAL_OR}@anchor{95}
5759 @deffn {C Macro} GCC_JIT_BINARY_OP_LOGICAL_OR
5761 Logical OR; analogous to:
5764 (EXPR_A) || (EXPR_B)
5772 @geindex GCC_JIT_BINARY_OP_LSHIFT (C macro)
5773 @anchor{topics/expressions GCC_JIT_BINARY_OP_LSHIFT}@anchor{96}
5774 @deffn {C Macro} GCC_JIT_BINARY_OP_LSHIFT
5776 Left shift; analogous to:
5779 (EXPR_A) << (EXPR_B)
5787 @geindex GCC_JIT_BINARY_OP_RSHIFT (C macro)
5788 @anchor{topics/expressions GCC_JIT_BINARY_OP_RSHIFT}@anchor{97}
5789 @deffn {C Macro} GCC_JIT_BINARY_OP_RSHIFT
5791 Right shift; analogous to:
5794 (EXPR_A) >> (EXPR_B)
5802 @node Comparisons,Function calls,Binary Operations,Rvalues
5803 @anchor{topics/expressions comparisons}@anchor{99}
5804 @subsubsection Comparisons
5807 @geindex gcc_jit_context_new_comparison (C function)
5808 @anchor{topics/expressions gcc_jit_context_new_comparison}@anchor{2c}
5809 @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)
5811 Build a boolean rvalue out of the comparison of two other rvalues.
5814 @geindex gcc_jit_comparison (C type)
5815 @anchor{topics/expressions gcc_jit_comparison}@anchor{9a}
5816 @deffn {C Type} enum gcc_jit_comparison
5820 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx}
5831 @code{GCC_JIT_COMPARISON_EQ}
5839 @code{GCC_JIT_COMPARISON_NE}
5847 @code{GCC_JIT_COMPARISON_LT}
5855 @code{GCC_JIT_COMPARISON_LE}
5863 @code{GCC_JIT_COMPARISON_GT}
5871 @code{GCC_JIT_COMPARISON_GE}
5880 @node Function calls,Type-coercion,Comparisons,Rvalues
5881 @anchor{topics/expressions function-calls}@anchor{9b}
5882 @subsubsection Function calls
5885 @geindex gcc_jit_context_new_call (C function)
5886 @anchor{topics/expressions gcc_jit_context_new_call}@anchor{9c}
5887 @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)
5889 Given a function and the given table of argument rvalues, construct a
5890 call to the function, with the result as an rvalue.
5894 @pxref{9c,,gcc_jit_context_new_call()} merely builds a
5895 @pxref{13,,gcc_jit_rvalue} i.e. an expression that can be evaluated,
5896 perhaps as part of a more complicated expression.
5897 The call @emph{won't} happen unless you add a statement to a function
5898 that evaluates the expression.
5900 For example, if you want to call a function and discard the result
5901 (or to call a function with @code{void} return type), use
5902 @pxref{9d,,gcc_jit_block_add_eval()}:
5905 /* Add "(void)printf (arg0, arg1);". */
5906 gcc_jit_block_add_eval (
5908 gcc_jit_context_new_call (
5920 @node Type-coercion,,Function calls,Rvalues
5921 @anchor{topics/expressions type-coercion}@anchor{9e}
5922 @subsubsection Type-coercion
5925 @geindex gcc_jit_context_new_cast (C function)
5926 @anchor{topics/expressions gcc_jit_context_new_cast}@anchor{9f}
5927 @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)
5929 Given an rvalue of T, construct another rvalue of another type.
5931 Currently only a limited set of conversions are possible:
5945 P* <-> Q*, for pointer types P and Q
5950 @node Lvalues,Working with pointers structs and unions,Rvalues,Expressions
5951 @anchor{topics/expressions lvalues}@anchor{a0}
5955 @geindex gcc_jit_lvalue (C type)
5956 @anchor{topics/expressions gcc_jit_lvalue}@anchor{24}
5957 @deffn {C Type} gcc_jit_lvalue
5960 An lvalue is something that can of the @emph{left}-hand side of an assignment:
5961 a storage area (such as a variable). It is also usable as an rvalue,
5962 where the rvalue is computed by reading from the storage area.
5964 @geindex gcc_jit_lvalue_as_object (C function)
5965 @anchor{topics/expressions gcc_jit_lvalue_as_object}@anchor{a1}
5966 @deffn {C Function} gcc_jit_object * gcc_jit_lvalue_as_object (gcc_jit_lvalue@w{ }*lvalue)
5968 Upcast an lvalue to be an object.
5971 @geindex gcc_jit_lvalue_as_rvalue (C function)
5972 @anchor{topics/expressions gcc_jit_lvalue_as_rvalue}@anchor{a2}
5973 @deffn {C Function} gcc_jit_rvalue * gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue@w{ }*lvalue)
5975 Upcast an lvalue to be an rvalue.
5978 @geindex gcc_jit_lvalue_get_address (C function)
5979 @anchor{topics/expressions gcc_jit_lvalue_get_address}@anchor{a3}
5980 @deffn {C Function} gcc_jit_rvalue * gcc_jit_lvalue_get_address (gcc_jit_lvalue@w{ }*lvalue, gcc_jit_location@w{ }*loc)
5982 Take the address of an lvalue; analogous to:
5994 * Global variables::
5998 @node Global variables,,,Lvalues
5999 @anchor{topics/expressions global-variables}@anchor{a4}
6000 @subsubsection Global variables
6003 @geindex gcc_jit_context_new_global (C function)
6004 @anchor{topics/expressions gcc_jit_context_new_global}@anchor{a5}
6005 @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)
6007 Add a new global variable of the given type and name to the context.
6009 The "kind" parameter determines the visibility of the "global" outside
6010 of the @pxref{16,,gcc_jit_result}:
6012 @geindex gcc_jit_global_kind (C type)
6013 @anchor{topics/expressions gcc_jit_global_kind}@anchor{a6}
6014 @deffn {C Type} enum gcc_jit_global_kind
6017 @geindex GCC_JIT_GLOBAL_EXPORTED (C macro)
6018 @anchor{topics/expressions GCC_JIT_GLOBAL_EXPORTED}@anchor{a7}
6019 @deffn {C Macro} GCC_JIT_GLOBAL_EXPORTED
6021 Global is defined by the client code and is visible
6022 by name outside of this JIT context via
6023 @pxref{a8,,gcc_jit_result_get_global()} (and this value is required for
6024 the global to be accessible via that entrypoint).
6027 @geindex GCC_JIT_GLOBAL_INTERNAL (C macro)
6028 @anchor{topics/expressions GCC_JIT_GLOBAL_INTERNAL}@anchor{a9}
6029 @deffn {C Macro} GCC_JIT_GLOBAL_INTERNAL
6031 Global is defined by the client code, but is invisible
6032 outside of it. Analogous to a "static" global within a .c file.
6033 Specifically, the variable will only be visible within this
6034 context and within child contexts.
6037 @geindex GCC_JIT_GLOBAL_IMPORTED (C macro)
6038 @anchor{topics/expressions GCC_JIT_GLOBAL_IMPORTED}@anchor{aa}
6039 @deffn {C Macro} GCC_JIT_GLOBAL_IMPORTED
6041 Global is not defined by the client code; we're merely
6042 referring to it. Analogous to using an "extern" global from a
6047 @node Working with pointers structs and unions,,Lvalues,Expressions
6048 @anchor{topics/expressions working-with-pointers-structs-and-unions}@anchor{ab}
6049 @subsection Working with pointers, structs and unions
6052 @geindex gcc_jit_rvalue_dereference (C function)
6053 @anchor{topics/expressions gcc_jit_rvalue_dereference}@anchor{ac}
6054 @deffn {C Function} gcc_jit_lvalue * gcc_jit_rvalue_dereference (gcc_jit_rvalue@w{ }*rvalue, gcc_jit_location@w{ }*loc)
6056 Given an rvalue of pointer type @code{T *}, dereferencing the pointer,
6057 getting an lvalue of type @code{T}. Analogous to:
6068 Field access is provided separately for both lvalues and rvalues.
6070 @geindex gcc_jit_lvalue_access_field (C function)
6071 @anchor{topics/expressions gcc_jit_lvalue_access_field}@anchor{ad}
6072 @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)
6074 Given an lvalue of struct or union type, access the given field,
6075 getting an lvalue of the field's type. Analogous to:
6086 @geindex gcc_jit_rvalue_access_field (C function)
6087 @anchor{topics/expressions gcc_jit_rvalue_access_field}@anchor{ae}
6088 @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)
6090 Given an rvalue of struct or union type, access the given field
6091 as an rvalue. Analogous to:
6102 @geindex gcc_jit_rvalue_dereference_field (C function)
6103 @anchor{topics/expressions gcc_jit_rvalue_dereference_field}@anchor{af}
6104 @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)
6106 Given an rvalue of pointer type @code{T *} where T is of struct or union
6107 type, access the given field as an lvalue. Analogous to:
6115 in C, itself equivalent to @code{(*EXPR).FIELD}.
6118 @geindex gcc_jit_context_new_array_access (C function)
6119 @anchor{topics/expressions gcc_jit_context_new_array_access}@anchor{98}
6120 @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)
6122 Given an rvalue of pointer type @code{T *}, get at the element @cite{T} at
6123 the given index, using standard C array indexing rules i.e. each
6124 increment of @code{index} corresponds to @code{sizeof(T)} bytes.
6133 in C (or, indeed, to @code{PTR + INDEX}).
6136 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
6137 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
6139 @c This is free software: you can redistribute it and/or modify it
6140 @c under the terms of the GNU General Public License as published by
6141 @c the Free Software Foundation, either version 3 of the License, or
6142 @c (at your option) any later version.
6144 @c This program is distributed in the hope that it will be useful, but
6145 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6146 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6147 @c General Public License for more details.
6149 @c You should have received a copy of the GNU General Public License
6150 @c along with this program. If not, see
6151 @c <http://www.gnu.org/licenses/>.
6153 @node Creating and using functions,Source Locations,Expressions,Topic Reference
6154 @anchor{topics/functions doc}@anchor{b0}@anchor{topics/functions creating-and-using-functions}@anchor{b1}
6155 @section Creating and using functions
6166 @node Params,Functions,,Creating and using functions
6167 @anchor{topics/functions params}@anchor{b2}
6171 @geindex gcc_jit_param (C type)
6172 @anchor{topics/functions gcc_jit_param}@anchor{25}
6173 @deffn {C Type} gcc_jit_param
6175 A @cite{gcc_jit_param} represents a parameter to a function.
6178 @geindex gcc_jit_context_new_param (C function)
6179 @anchor{topics/functions gcc_jit_context_new_param}@anchor{10}
6180 @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)
6182 In preparation for creating a function, create a new parameter of the
6183 given type and name.
6186 Parameters are lvalues, and thus are also rvalues (and objects), so the
6187 following upcasts are available:
6189 @geindex gcc_jit_param_as_lvalue (C function)
6190 @anchor{topics/functions gcc_jit_param_as_lvalue}@anchor{b3}
6191 @deffn {C Function} gcc_jit_lvalue * gcc_jit_param_as_lvalue (gcc_jit_param@w{ }*param)
6193 Upcasting from param to lvalue.
6196 @geindex gcc_jit_param_as_rvalue (C function)
6197 @anchor{topics/functions gcc_jit_param_as_rvalue}@anchor{b4}
6198 @deffn {C Function} gcc_jit_rvalue * gcc_jit_param_as_rvalue (gcc_jit_param@w{ }*param)
6200 Upcasting from param to rvalue.
6203 @geindex gcc_jit_param_as_object (C function)
6204 @anchor{topics/functions gcc_jit_param_as_object}@anchor{b5}
6205 @deffn {C Function} gcc_jit_object * gcc_jit_param_as_object (gcc_jit_param@w{ }*param)
6207 Upcasting from param to object.
6210 @node Functions,Blocks,Params,Creating and using functions
6211 @anchor{topics/functions functions}@anchor{b6}
6212 @subsection Functions
6215 @geindex gcc_jit_function (C type)
6216 @anchor{topics/functions gcc_jit_function}@anchor{29}
6217 @deffn {C Type} gcc_jit_function
6219 A @cite{gcc_jit_function} represents a function - either one that we're
6220 creating ourselves, or one that we're referencing.
6223 @geindex gcc_jit_context_new_function (C function)
6224 @anchor{topics/functions gcc_jit_context_new_function}@anchor{11}
6225 @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)
6227 Create a gcc_jit_function with the given name and parameters.
6229 @geindex gcc_jit_function_kind (C type)
6230 @anchor{topics/functions gcc_jit_function_kind}@anchor{b7}
6231 @deffn {C Type} enum gcc_jit_function_kind
6234 This enum controls the kind of function created, and has the following
6239 @geindex GCC_JIT_FUNCTION_EXPORTED (C macro)
6240 @anchor{topics/functions GCC_JIT_FUNCTION_EXPORTED}@anchor{b8}
6241 @deffn {C Macro} GCC_JIT_FUNCTION_EXPORTED
6243 Function is defined by the client code and visible
6244 by name outside of the JIT.
6246 This value is required if you want to extract machine code
6247 for this function from a @pxref{16,,gcc_jit_result} via
6248 @pxref{17,,gcc_jit_result_get_code()}.
6251 @geindex GCC_JIT_FUNCTION_INTERNAL (C macro)
6252 @anchor{topics/functions GCC_JIT_FUNCTION_INTERNAL}@anchor{b9}
6253 @deffn {C Macro} GCC_JIT_FUNCTION_INTERNAL
6255 Function is defined by the client code, but is invisible
6256 outside of the JIT. Analogous to a "static" function.
6259 @geindex GCC_JIT_FUNCTION_IMPORTED (C macro)
6260 @anchor{topics/functions GCC_JIT_FUNCTION_IMPORTED}@anchor{ba}
6261 @deffn {C Macro} GCC_JIT_FUNCTION_IMPORTED
6263 Function is not defined by the client code; we're merely
6264 referring to it. Analogous to using an "extern" function from a
6268 @geindex GCC_JIT_FUNCTION_ALWAYS_INLINE (C macro)
6269 @anchor{topics/functions GCC_JIT_FUNCTION_ALWAYS_INLINE}@anchor{bb}
6270 @deffn {C Macro} GCC_JIT_FUNCTION_ALWAYS_INLINE
6272 Function is only ever inlined into other functions, and is
6273 invisible outside of the JIT.
6275 Analogous to prefixing with @code{inline} and adding
6276 @code{__attribute__((always_inline))}
6278 Inlining will only occur when the optimization level is
6279 above 0; when optimization is off, this is essentially the
6280 same as GCC_JIT_FUNCTION_INTERNAL.
6285 @geindex gcc_jit_context_get_builtin_function (C function)
6286 @anchor{topics/functions gcc_jit_context_get_builtin_function}@anchor{bc}
6287 @deffn {C Function} gcc_jit_function *gcc_jit_context_get_builtin_function (gcc_jit_context@w{ }*ctxt, const char@w{ }*name)
6290 @geindex gcc_jit_function_as_object (C function)
6291 @anchor{topics/functions gcc_jit_function_as_object}@anchor{bd}
6292 @deffn {C Function} gcc_jit_object * gcc_jit_function_as_object (gcc_jit_function@w{ }*func)
6294 Upcasting from function to object.
6297 @geindex gcc_jit_function_get_param (C function)
6298 @anchor{topics/functions gcc_jit_function_get_param}@anchor{be}
6299 @deffn {C Function} gcc_jit_param * gcc_jit_function_get_param (gcc_jit_function@w{ }*func, int@w{ }index)
6301 Get the param of the given index (0-based).
6304 @geindex gcc_jit_function_dump_to_dot (C function)
6305 @anchor{topics/functions gcc_jit_function_dump_to_dot}@anchor{33}
6306 @deffn {C Function} void gcc_jit_function_dump_to_dot (gcc_jit_function@w{ }*func, const char@w{ }*path)
6308 Emit the function in graphviz format to the given path.
6311 @geindex gcc_jit_function_new_local (C function)
6312 @anchor{topics/functions gcc_jit_function_new_local}@anchor{26}
6313 @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)
6315 Create a new local variable within the function, of the given type and
6319 @node Blocks,Statements,Functions,Creating and using functions
6320 @anchor{topics/functions blocks}@anchor{bf}
6324 @geindex gcc_jit_block (C type)
6325 @anchor{topics/functions gcc_jit_block}@anchor{28}
6326 @deffn {C Type} gcc_jit_block
6328 A @cite{gcc_jit_block} represents a basic block within a function i.e. a
6329 sequence of statements with a single entry point and a single exit
6332 The first basic block that you create within a function will
6335 Each basic block that you create within a function must be
6336 terminated, either with a conditional, a jump, or a return.
6338 It's legal to have multiple basic blocks that return within
6342 @geindex gcc_jit_function_new_block (C function)
6343 @anchor{topics/functions gcc_jit_function_new_block}@anchor{c0}
6344 @deffn {C Function} gcc_jit_block * gcc_jit_function_new_block (gcc_jit_function@w{ }*func, const char@w{ }*name)
6346 Create a basic block of the given name. The name may be NULL, but
6347 providing meaningful names is often helpful when debugging: it may
6348 show up in dumps of the internal representation, and in error
6352 @geindex gcc_jit_block_as_object (C function)
6353 @anchor{topics/functions gcc_jit_block_as_object}@anchor{c1}
6354 @deffn {C Function} gcc_jit_object * gcc_jit_block_as_object (gcc_jit_block@w{ }*block)
6356 Upcast from block to object.
6359 @geindex gcc_jit_block_get_function (C function)
6360 @anchor{topics/functions gcc_jit_block_get_function}@anchor{c2}
6361 @deffn {C Function} gcc_jit_function * gcc_jit_block_get_function (gcc_jit_block@w{ }*block)
6363 Which function is this block within?
6366 @node Statements,,Blocks,Creating and using functions
6367 @anchor{topics/functions statements}@anchor{c3}
6368 @subsection Statements
6371 @geindex gcc_jit_block_add_eval (C function)
6372 @anchor{topics/functions gcc_jit_block_add_eval}@anchor{9d}
6373 @deffn {C Function} void gcc_jit_block_add_eval (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*rvalue)
6375 Add evaluation of an rvalue, discarding the result
6376 (e.g. a function call that "returns" void).
6378 This is equivalent to this C code:
6387 @geindex gcc_jit_block_add_assignment (C function)
6388 @anchor{topics/functions gcc_jit_block_add_assignment}@anchor{2a}
6389 @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)
6391 Add evaluation of an rvalue, assigning the result to the given
6394 This is roughly equivalent to this C code:
6403 @geindex gcc_jit_block_add_assignment_op (C function)
6404 @anchor{topics/functions gcc_jit_block_add_assignment_op}@anchor{2e}
6405 @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)
6407 Add evaluation of an rvalue, using the result to modify an
6410 This is analogous to "+=" and friends:
6424 gcc_jit_block_add_assignment_op (
6427 GCC_JIT_BINARY_OP_PLUS,
6428 gcc_jit_context_one (ctxt, int_type));
6434 @geindex gcc_jit_block_add_comment (C function)
6435 @anchor{topics/functions gcc_jit_block_add_comment}@anchor{3d}
6436 @deffn {C Function} void gcc_jit_block_add_comment (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, const char@w{ }*text)
6438 Add a no-op textual comment to the internal representation of the
6439 code. It will be optimized away, but will be visible in the dumps
6440 seen via @pxref{5f,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}
6441 and @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE},
6442 and thus may be of use when debugging how your project's internal
6443 representation gets converted to the libgccjit IR.
6446 @geindex gcc_jit_block_end_with_conditional (C function)
6447 @anchor{topics/functions gcc_jit_block_end_with_conditional}@anchor{2d}
6448 @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)
6450 Terminate a block by adding evaluation of an rvalue, branching on the
6451 result to the appropriate successor block.
6453 This is roughly equivalent to this C code:
6464 block, boolval, on_true, and on_false must be non-NULL.
6467 @geindex gcc_jit_block_end_with_jump (C function)
6468 @anchor{topics/functions gcc_jit_block_end_with_jump}@anchor{c4}
6469 @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)
6471 Terminate a block by adding a jump to the given target block.
6473 This is roughly equivalent to this C code:
6482 @geindex gcc_jit_block_end_with_return (C function)
6483 @anchor{topics/functions gcc_jit_block_end_with_return}@anchor{c5}
6484 @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)
6486 Terminate a block by adding evaluation of an rvalue, returning the value.
6488 This is roughly equivalent to this C code:
6497 @geindex gcc_jit_block_end_with_void_return (C function)
6498 @anchor{topics/functions gcc_jit_block_end_with_void_return}@anchor{c6}
6499 @deffn {C Function} void gcc_jit_block_end_with_void_return (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc)
6501 Terminate a block by adding a valueless return, for use within a function
6502 with "void" return type.
6504 This is equivalent to this C code:
6513 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
6514 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
6516 @c This is free software: you can redistribute it and/or modify it
6517 @c under the terms of the GNU General Public License as published by
6518 @c the Free Software Foundation, either version 3 of the License, or
6519 @c (at your option) any later version.
6521 @c This program is distributed in the hope that it will be useful, but
6522 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6523 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6524 @c General Public License for more details.
6526 @c You should have received a copy of the GNU General Public License
6527 @c along with this program. If not, see
6528 @c <http://www.gnu.org/licenses/>.
6530 @node Source Locations,Compilation results,Creating and using functions,Topic Reference
6531 @anchor{topics/locations source-locations}@anchor{c7}@anchor{topics/locations doc}@anchor{c8}
6532 @section Source Locations
6535 @geindex gcc_jit_location (C type)
6536 @anchor{topics/locations gcc_jit_location}@anchor{3b}
6537 @deffn {C Type} gcc_jit_location
6539 A @cite{gcc_jit_location} encapsulates a source code location, so that
6540 you can (optionally) associate locations in your language with
6541 statements in the JIT-compiled code, allowing the debugger to
6542 single-step through your language.
6544 @cite{gcc_jit_location} instances are optional: you can always pass NULL to
6545 any API entrypoint accepting one.
6547 You can construct them using @pxref{41,,gcc_jit_context_new_location()}.
6549 You need to enable @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
6550 @pxref{8,,gcc_jit_context} for these locations to actually be usable by
6554 gcc_jit_context_set_bool_option (
6556 GCC_JIT_BOOL_OPTION_DEBUGINFO,
6563 @geindex gcc_jit_context_new_location (C function)
6564 @anchor{topics/locations gcc_jit_context_new_location}@anchor{41}
6565 @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)
6567 Create a @cite{gcc_jit_location} instance representing the given source
6576 @node Faking it,,,Source Locations
6577 @anchor{topics/locations faking-it}@anchor{c9}
6578 @subsection Faking it
6581 If you don't have source code for your internal representation, but need
6582 to debug, you can generate a C-like representation of the functions in
6583 your context using @pxref{53,,gcc_jit_context_dump_to_file()}:
6586 gcc_jit_context_dump_to_file (ctxt, "/tmp/something.c",
6587 1 /* update_locations */);
6592 This will dump C-like code to the given path. If the @cite{update_locations}
6593 argument is true, this will also set up @cite{gcc_jit_location} information
6594 throughout the context, pointing at the dump file as if it were a source
6595 file, giving you @emph{something} you can step through in the debugger.
6597 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
6598 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
6600 @c This is free software: you can redistribute it and/or modify it
6601 @c under the terms of the GNU General Public License as published by
6602 @c the Free Software Foundation, either version 3 of the License, or
6603 @c (at your option) any later version.
6605 @c This program is distributed in the hope that it will be useful, but
6606 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6607 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6608 @c General Public License for more details.
6610 @c You should have received a copy of the GNU General Public License
6611 @c along with this program. If not, see
6612 @c <http://www.gnu.org/licenses/>.
6614 @node Compilation results,,Source Locations,Topic Reference
6615 @anchor{topics/results compilation-results}@anchor{ca}@anchor{topics/results doc}@anchor{cb}
6616 @section Compilation results
6619 @geindex gcc_jit_result (C type)
6620 @anchor{topics/results gcc_jit_result}@anchor{16}
6621 @deffn {C Type} gcc_jit_result
6623 A @cite{gcc_jit_result} encapsulates the result of compiling a context,
6624 and the lifetimes of any machine code functions or globals that are
6628 @geindex gcc_jit_context_compile (C function)
6629 @anchor{topics/results gcc_jit_context_compile}@anchor{15}
6630 @deffn {C Function} gcc_jit_result * gcc_jit_context_compile (gcc_jit_context@w{ }*ctxt)
6632 This calls into GCC and builds the code, returning a
6633 @cite{gcc_jit_result *}.
6635 If this is non-NULL, the caller becomes responsible for
6636 calling @pxref{39,,gcc_jit_result_release()} on it once they're done
6640 @geindex gcc_jit_result_get_code (C function)
6641 @anchor{topics/results gcc_jit_result_get_code}@anchor{17}
6642 @deffn {C Function} void * gcc_jit_result_get_code (gcc_jit_result@w{ }*result, const char@w{ }*funcname)
6644 Locate a given function within the built machine code.
6646 Functions are looked up by name. For this to succeed, a function
6647 with a name matching @cite{funcname} must have been created on
6648 @cite{result}'s context (or a parent context) via a call to
6649 @pxref{11,,gcc_jit_context_new_function()} with @cite{kind}
6650 @pxref{b8,,GCC_JIT_FUNCTION_EXPORTED}:
6653 gcc_jit_context_new_function (ctxt,
6654 any_location, /* or NULL */
6655 /* Required for func to be visible to
6656 gcc_jit_result_get_code: */
6657 GCC_JIT_FUNCTION_EXPORTED,
6659 /* Must string-compare equal: */
6666 If such a function is not found (or @cite{result} or @cite{funcname} are
6667 @code{NULL}), an error message will be emitted on stderr and
6668 @code{NULL} will be returned.
6670 If the function is found, the result will need to be cast to a
6671 function pointer of the correct type before it can be called.
6673 Note that the resulting machine code becomes invalid after
6674 @pxref{39,,gcc_jit_result_release()} is called on the
6675 @pxref{16,,gcc_jit_result *}; attempting to call it after that may lead
6676 to a segmentation fault.
6679 @geindex gcc_jit_result_get_global (C function)
6680 @anchor{topics/results gcc_jit_result_get_global}@anchor{a8}
6681 @deffn {C Function} void * gcc_jit_result_get_global (gcc_jit_result@w{ }*result, const char@w{ }*name)
6683 Locate a given global within the built machine code.
6685 Globals are looked up by name. For this to succeed, a global
6686 with a name matching @cite{name} must have been created on
6687 @cite{result}'s context (or a parent context) via a call to
6688 @pxref{a5,,gcc_jit_context_new_global()} with @cite{kind}
6689 @pxref{a7,,GCC_JIT_GLOBAL_EXPORTED}.
6691 If the global is found, the result will need to be cast to a
6692 pointer of the correct type before it can be called.
6694 This is a @emph{pointer} to the global, so e.g. for an @code{int} this is
6697 For example, given an @code{int foo;} created this way:
6700 gcc_jit_lvalue *exported_global =
6701 gcc_jit_context_new_global (ctxt,
6702 any_location, /* or NULL */
6703 GCC_JIT_GLOBAL_EXPORTED,
6710 we can access it like this:
6714 (int *)gcc_jit_result_get_global (result, "foo");
6719 If such a global is not found (or @cite{result} or @cite{name} are
6720 @code{NULL}), an error message will be emitted on stderr and
6721 @code{NULL} will be returned.
6723 Note that the resulting address becomes invalid after
6724 @pxref{39,,gcc_jit_result_release()} is called on the
6725 @pxref{16,,gcc_jit_result *}; attempting to use it after that may lead
6726 to a segmentation fault.
6729 @geindex gcc_jit_result_release (C function)
6730 @anchor{topics/results gcc_jit_result_release}@anchor{39}
6731 @deffn {C Function} void gcc_jit_result_release (gcc_jit_result@w{ }*result)
6733 Once we're done with the code, this unloads the built .so file.
6734 This cleans up the result; after calling this, it's no longer
6735 valid to use the result, or any code or globals that were obtained
6736 by calling @pxref{17,,gcc_jit_result_get_code()} or
6737 @pxref{a8,,gcc_jit_result_get_global()} on it.
6740 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
6741 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
6743 @c This is free software: you can redistribute it and/or modify it
6744 @c under the terms of the GNU General Public License as published by
6745 @c the Free Software Foundation, either version 3 of the License, or
6746 @c (at your option) any later version.
6748 @c This program is distributed in the hope that it will be useful, but
6749 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6750 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6751 @c General Public License for more details.
6753 @c You should have received a copy of the GNU General Public License
6754 @c along with this program. If not, see
6755 @c <http://www.gnu.org/licenses/>.
6757 @node C++ bindings for libgccjit,Internals,Topic Reference,Top
6758 @anchor{cp/index c-bindings-for-libgccjit}@anchor{cc}@anchor{cp/index doc}@anchor{cd}
6759 @chapter C++ bindings for libgccjit
6762 This document describes the C++ bindings to
6763 libgccjit@footnote{http://gcc.gnu.org/wiki/JIT}, an API for embedding GCC
6764 inside programs and libraries.
6766 The C++ bindings consist of a single header file @code{libgccjit++.h}.
6768 This is a collection of "thin" wrapper classes around the C API.
6769 Everything is an inline function, implemented in terms of the C API,
6770 so there is nothing extra to link against.
6772 Note that libgccjit is currently of "Alpha" quality;
6773 the APIs are not yet set in stone, and they shouldn't be used in
6778 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
6779 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
6781 @c This is free software: you can redistribute it and/or modify it
6782 @c under the terms of the GNU General Public License as published by
6783 @c the Free Software Foundation, either version 3 of the License, or
6784 @c (at your option) any later version.
6786 @c This program is distributed in the hope that it will be useful, but
6787 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6788 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6789 @c General Public License for more details.
6791 @c You should have received a copy of the GNU General Public License
6792 @c along with this program. If not, see
6793 @c <http://www.gnu.org/licenses/>.
6796 * Tutorial: Tutorial<2>.
6797 * Topic Reference: Topic Reference<2>.
6801 * Tutorial part 1; "Hello world": Tutorial part 1 "Hello world"<2>.
6802 * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>.
6803 * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>.
6804 * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>.
6806 Tutorial part 2: Creating a trivial machine code function
6808 * Options: Options<3>.
6809 * Full example: Full example<3>.
6811 Tutorial part 3: Loops and variables
6813 * Expressions; lvalues and rvalues: Expressions lvalues and rvalues<2>.
6814 * Control flow: Control flow<2>.
6815 * Visualizing the control flow graph: Visualizing the control flow graph<2>.
6816 * Full example: Full example<4>.
6818 Tutorial part 4: Adding JIT-compilation to a toy interpreter
6820 * Our toy interpreter: Our toy interpreter<2>.
6821 * Compiling to machine code: Compiling to machine code<2>.
6822 * Setting things up: Setting things up<2>.
6823 * Populating the function: Populating the function<2>.
6824 * Verifying the control flow graph: Verifying the control flow graph<2>.
6825 * Compiling the context: Compiling the context<2>.
6826 * Single-stepping through the generated code: Single-stepping through the generated code<2>.
6827 * Examining the generated code: Examining the generated code<2>.
6828 * Putting it all together: Putting it all together<2>.
6829 * Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?<2>.
6831 Behind the curtain: How does our code get optimized?
6833 * Optimizing away stack manipulation: Optimizing away stack manipulation<2>.
6834 * Elimination of tail recursion: Elimination of tail recursion<2>.
6838 * Compilation contexts: Compilation contexts<2>.
6839 * Objects: Objects<2>.
6841 * Expressions: Expressions<2>.
6842 * Creating and using functions: Creating and using functions<2>.
6843 * Source Locations: Source Locations<2>.
6844 * Compilation results: Compilation results<2>.
6846 Compilation contexts
6848 * Lifetime-management: Lifetime-management<2>.
6849 * Thread-safety: Thread-safety<2>.
6850 * Error-handling: Error-handling<3>.
6851 * Debugging: Debugging<2>.
6852 * Options: Options<4>.
6856 * String Options: String Options<2>.
6857 * Boolean options: Boolean options<2>.
6858 * Integer options: Integer options<2>.
6862 * Standard types: Standard types<2>.
6863 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
6864 * Structures and unions: Structures and unions<2>.
6868 * Rvalues: Rvalues<2>.
6869 * Lvalues: Lvalues<2>.
6870 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
6874 * Simple expressions: Simple expressions<2>.
6875 * Unary Operations: Unary Operations<2>.
6876 * Binary Operations: Binary Operations<2>.
6877 * Comparisons: Comparisons<2>.
6878 * Function calls: Function calls<2>.
6879 * Type-coercion: Type-coercion<2>.
6883 * Global variables: Global variables<2>.
6885 Creating and using functions
6887 * Params: Params<2>.
6888 * Functions: Functions<2>.
6889 * Blocks: Blocks<2>.
6890 * Statements: Statements<2>.
6894 * Faking it: Faking it<2>.
6899 @node Tutorial<2>,Topic Reference<2>,,C++ bindings for libgccjit
6900 @anchor{cp/intro/index doc}@anchor{ce}@anchor{cp/intro/index tutorial}@anchor{cf}
6904 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
6905 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
6907 @c This is free software: you can redistribute it and/or modify it
6908 @c under the terms of the GNU General Public License as published by
6909 @c the Free Software Foundation, either version 3 of the License, or
6910 @c (at your option) any later version.
6912 @c This program is distributed in the hope that it will be useful, but
6913 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6914 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6915 @c General Public License for more details.
6917 @c You should have received a copy of the GNU General Public License
6918 @c along with this program. If not, see
6919 @c <http://www.gnu.org/licenses/>.
6922 * Tutorial part 1; "Hello world": Tutorial part 1 "Hello world"<2>.
6923 * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>.
6924 * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>.
6925 * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>.
6929 @node Tutorial part 1 "Hello world"<2>,Tutorial part 2 Creating a trivial machine code function<2>,,Tutorial<2>
6930 @anchor{cp/intro/tutorial01 doc}@anchor{d0}@anchor{cp/intro/tutorial01 tutorial-part-1-hello-world}@anchor{d1}
6931 @subsection Tutorial part 1: "Hello world"
6934 Before we look at the details of the API, let's look at building and
6935 running programs that use the library.
6937 Here's a toy "hello world" program that uses the library's C++ API to
6938 synthesize a call to @cite{printf} and uses it to write a message to stdout.
6940 Don't worry about the content of the program for now; we'll cover
6941 the details in later parts of this tutorial.
6946 /* Smoketest example for libgccjit.so C++ API
6947 Copyright (C) 2014-2015 Free Software Foundation, Inc.
6949 This file is part of GCC.
6951 GCC is free software; you can redistribute it and/or modify it
6952 under the terms of the GNU General Public License as published by
6953 the Free Software Foundation; either version 3, or (at your option)
6956 GCC is distributed in the hope that it will be useful, but
6957 WITHOUT ANY WARRANTY; without even the implied warranty of
6958 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6959 General Public License for more details.
6961 You should have received a copy of the GNU General Public License
6962 along with GCC; see the file COPYING3. If not see
6963 <http://www.gnu.org/licenses/>. */
6965 #include <libgccjit++.h>
6971 create_code (gccjit::context ctxt)
6973 /* Let's try to inject the equivalent of this C code:
6975 greet (const char *name)
6977 printf ("hello %s\n", name);
6980 gccjit::type void_type = ctxt.get_type (GCC_JIT_TYPE_VOID);
6981 gccjit::type const_char_ptr_type =
6982 ctxt.get_type (GCC_JIT_TYPE_CONST_CHAR_PTR);
6983 gccjit::param param_name =
6984 ctxt.new_param (const_char_ptr_type, "name");
6985 std::vector<gccjit::param> func_params;
6986 func_params.push_back (param_name);
6987 gccjit::function func =
6988 ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
6993 gccjit::param param_format =
6994 ctxt.new_param (const_char_ptr_type, "format");
6995 std::vector<gccjit::param> printf_params;
6996 printf_params.push_back (param_format);
6997 gccjit::function printf_func =
6998 ctxt.new_function (GCC_JIT_FUNCTION_IMPORTED,
6999 ctxt.get_type (GCC_JIT_TYPE_INT),
7003 gccjit::block block = func.new_block ();
7004 block.add_eval (ctxt.new_call (printf_func,
7005 ctxt.new_rvalue ("hello %s\n"),
7007 block.end_with_return ();
7011 main (int argc, char **argv)
7013 gccjit::context ctxt;
7014 gcc_jit_result *result;
7016 /* Get a "context" object for working with the library. */
7017 ctxt = gccjit::context::acquire ();
7019 /* Set some options on the context.
7020 Turn this on to see the code being generated, in assembler form. */
7021 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 0);
7023 /* Populate the context. */
7026 /* Compile the code. */
7027 result = ctxt.compile ();
7030 fprintf (stderr, "NULL result");
7036 /* Extract the generated code from "result". */
7037 typedef void (*fn_type) (const char *);
7039 (fn_type)gcc_jit_result_get_code (result, "greet");
7042 fprintf (stderr, "NULL greet");
7046 /* Now call the generated function: */
7050 gcc_jit_result_release (result);
7059 Copy the above to @cite{tut01-hello-world.cc}.
7061 Assuming you have the jit library installed, build the test program
7066 tut01-hello-world.cc \
7067 -o tut01-hello-world \
7073 You should then be able to run the built program:
7076 $ ./tut01-hello-world
7082 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
7083 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
7085 @c This is free software: you can redistribute it and/or modify it
7086 @c under the terms of the GNU General Public License as published by
7087 @c the Free Software Foundation, either version 3 of the License, or
7088 @c (at your option) any later version.
7090 @c This program is distributed in the hope that it will be useful, but
7091 @c WITHOUT ANY WARRANTY; without even the implied warranty of
7092 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
7093 @c General Public License for more details.
7095 @c You should have received a copy of the GNU General Public License
7096 @c along with this program. If not, see
7097 @c <http://www.gnu.org/licenses/>.
7099 @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>
7100 @anchor{cp/intro/tutorial02 doc}@anchor{d2}@anchor{cp/intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{d3}
7101 @subsection Tutorial part 2: Creating a trivial machine code function
7104 Consider this C function:
7115 How can we construct this at run-time using libgccjit's C++ API?
7117 First we need to include the relevant header:
7120 #include <libgccjit++.h>
7125 All state associated with compilation is associated with a
7126 @code{gccjit::context}, which is a thin C++ wrapper around the C API's
7127 @pxref{8,,gcc_jit_context *}.
7129 Create one using @pxref{d4,,gccjit;;context;;acquire()}:
7132 gccjit::context ctxt;
7133 ctxt = gccjit::context::acquire ();
7138 The JIT library has a system of types. It is statically-typed: every
7139 expression is of a specific type, fixed at compile-time. In our example,
7140 all of the expressions are of the C @cite{int} type, so let's obtain this from
7141 the context, as a @code{gccjit::type}, using
7142 @pxref{d5,,gccjit;;context;;get_type()}:
7145 gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
7150 @code{gccjit::type} is an example of a "contextual" object: every
7151 entity in the API is associated with a @code{gccjit::context}.
7153 Memory management is easy: all such "contextual" objects are automatically
7154 cleaned up for you when the context is released, using
7155 @pxref{d6,,gccjit;;context;;release()}:
7163 so you don't need to manually track and cleanup all objects, just the
7166 All of the C++ classes in the API are thin wrappers around pointers to
7169 The C++ class hierarchy within the @code{gccjit} namespace looks like this:
7186 One thing you can do with a @code{gccjit::object} is
7187 to ask it for a human-readable description as a @code{std::string}, using
7188 @pxref{d7,,gccjit;;object;;get_debug_string()}:
7191 printf ("obj: %s\n", obj.get_debug_string ().c_str ());
7196 giving this text on stdout:
7204 This is invaluable when debugging.
7206 Let's create the function. To do so, we first need to construct
7207 its single parameter, specifying its type and giving it a name,
7208 using @pxref{d8,,gccjit;;context;;new_param()}:
7211 gccjit::param param_i = ctxt.new_param (int_type, "i");
7216 and we can then make a vector of all of the params of the function,
7217 in this case just one:
7220 std::vector<gccjit::param> params;
7221 params.push_back (param_i);
7226 Now we can create the function, using
7227 @code{gccjit::context::new_function()}:
7230 gccjit::function func =
7231 ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
7240 To define the code within the function, we must create basic blocks
7241 containing statements.
7243 Every basic block contains a list of statements, eventually terminated
7244 by a statement that either returns, or jumps to another basic block.
7246 Our function has no control-flow, so we just need one basic block:
7249 gccjit::block block = func.new_block ();
7254 Our basic block is relatively simple: it immediately terminates by
7255 returning the value of an expression.
7257 We can build the expression using @pxref{d9,,gccjit;;context;;new_binary_op()}:
7260 gccjit::rvalue expr =
7261 ctxt.new_binary_op (
7262 GCC_JIT_BINARY_OP_MULT, int_type,
7268 A @code{gccjit::rvalue} is another example of a
7269 @code{gccjit::object} subclass. As before, we can print it with
7270 @pxref{d7,,gccjit;;object;;get_debug_string()}.
7273 printf ("expr: %s\n", expr.get_debug_string ().c_str ());
7286 Note that @code{gccjit::rvalue} provides numerous overloaded operators
7287 which can be used to dramatically reduce the amount of typing needed.
7288 We can build the above binary operation more directly with this one-liner:
7291 gccjit::rvalue expr = param_i * param_i;
7296 Creating the expression in itself doesn't do anything; we have to add
7297 this expression to a statement within the block. In this case, we use it
7298 to build a return statement, which terminates the basic block:
7301 block.end_with_return (expr);
7306 OK, we've populated the context. We can now compile it using
7307 @pxref{da,,gccjit;;context;;compile()}:
7310 gcc_jit_result *result;
7311 result = ctxt.compile ();
7316 and get a @pxref{16,,gcc_jit_result *}.
7318 We can now use @pxref{17,,gcc_jit_result_get_code()} to look up a specific
7319 machine code routine within the result, in this case, the function we
7323 void *fn_ptr = gcc_jit_result_get_code (result, "square");
7326 fprintf (stderr, "NULL fn_ptr");
7333 We can now cast the pointer to an appropriate function pointer type, and
7337 typedef int (*fn_type) (int);
7338 fn_type square = (fn_type)fn_ptr;
7339 printf ("result: %d", square (5));
7351 * Options: Options<3>.
7352 * Full example: Full example<3>.
7356 @node Options<3>,Full example<3>,,Tutorial part 2 Creating a trivial machine code function<2>
7357 @anchor{cp/intro/tutorial02 options}@anchor{db}
7358 @subsubsection Options
7361 To get more information on what's going on, you can set debugging flags
7362 on the context using @pxref{dc,,gccjit;;context;;set_bool_option()}.
7364 @c (I'm deliberately not mentioning
7365 @c :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE` here since I think
7366 @c it's probably more of use to implementors than to users)
7368 Setting @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE} will dump a
7369 C-like representation to stderr when you compile (GCC's "GIMPLE"
7373 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1);
7374 result = ctxt.compile ();
7380 square (signed int i)
7392 We can see the generated machine code in assembler form (on stderr) by
7393 setting @pxref{1d,,GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE} on the context
7397 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 1);
7398 result = ctxt.compile ();
7407 .type square, @@function
7412 .cfi_def_cfa_offset 16
7415 .cfi_def_cfa_register 6
7419 imull -4(%rbp), %eax
7425 .size square, .-square
7426 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
7427 .section .note.GNU-stack,"",@@progbits
7432 By default, no optimizations are performed, the equivalent of GCC's
7433 @cite{-O0} option. We can turn things up to e.g. @cite{-O3} by calling
7434 @pxref{dd,,gccjit;;context;;set_int_option()} with
7435 @pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
7438 ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3);
7448 .type square, @@function
7458 .size square, .-square
7459 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
7460 .section .note.GNU-stack,"",@@progbits
7465 Naturally this has only a small effect on such a trivial function.
7467 @node Full example<3>,,Options<3>,Tutorial part 2 Creating a trivial machine code function<2>
7468 @anchor{cp/intro/tutorial02 full-example}@anchor{de}
7469 @subsubsection Full example
7472 Here's what the above looks like as a complete program:
7477 /* Usage example for libgccjit.so's C++ API
7478 Copyright (C) 2014-2015 Free Software Foundation, Inc.
7480 This file is part of GCC.
7482 GCC is free software; you can redistribute it and/or modify it
7483 under the terms of the GNU General Public License as published by
7484 the Free Software Foundation; either version 3, or (at your option)
7487 GCC is distributed in the hope that it will be useful, but
7488 WITHOUT ANY WARRANTY; without even the implied warranty of
7489 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
7490 General Public License for more details.
7492 You should have received a copy of the GNU General Public License
7493 along with GCC; see the file COPYING3. If not see
7494 <http://www.gnu.org/licenses/>. */
7496 #include <libgccjit++.h>
7502 create_code (gccjit::context ctxt)
7504 /* Let's try to inject the equivalent of this C code:
7511 gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
7512 gccjit::param param_i = ctxt.new_param (int_type, "i");
7513 std::vector<gccjit::param> params;
7514 params.push_back (param_i);
7515 gccjit::function func = ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
7520 gccjit::block block = func.new_block ();
7522 gccjit::rvalue expr =
7523 ctxt.new_binary_op (GCC_JIT_BINARY_OP_MULT, int_type,
7526 block.end_with_return (expr);
7530 main (int argc, char **argv)
7532 /* Get a "context" object for working with the library. */
7533 gccjit::context ctxt = gccjit::context::acquire ();
7535 /* Set some options on the context.
7536 Turn this on to see the code being generated, in assembler form. */
7537 ctxt.set_bool_option (
7538 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
7541 /* Populate the context. */
7544 /* Compile the code. */
7545 gcc_jit_result *result = ctxt.compile ();
7547 /* We're done with the context; we can release it: */
7552 fprintf (stderr, "NULL result");
7556 /* Extract the generated code from "result". */
7557 void *fn_ptr = gcc_jit_result_get_code (result, "square");
7560 fprintf (stderr, "NULL fn_ptr");
7561 gcc_jit_result_release (result);
7565 typedef int (*fn_type) (int);
7566 fn_type square = (fn_type)fn_ptr;
7567 printf ("result: %d\n", square (5));
7569 gcc_jit_result_release (result);
7578 Building and running it:
7586 # Run the built program:
7593 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
7594 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
7596 @c This is free software: you can redistribute it and/or modify it
7597 @c under the terms of the GNU General Public License as published by
7598 @c the Free Software Foundation, either version 3 of the License, or
7599 @c (at your option) any later version.
7601 @c This program is distributed in the hope that it will be useful, but
7602 @c WITHOUT ANY WARRANTY; without even the implied warranty of
7603 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
7604 @c General Public License for more details.
7606 @c You should have received a copy of the GNU General Public License
7607 @c along with this program. If not, see
7608 @c <http://www.gnu.org/licenses/>.
7610 @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>
7611 @anchor{cp/intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{df}@anchor{cp/intro/tutorial03 doc}@anchor{e0}
7612 @subsection Tutorial part 3: Loops and variables
7615 Consider this C function:
7620 int loop_test (int n)
7623 for (int i = 0; i < n; i++)
7632 This example demonstrates some more features of libgccjit, with local
7633 variables and a loop.
7635 To break this down into libgccjit terms, it's usually easier to reword
7636 the @cite{for} loop as a @cite{while} loop, giving:
7641 int loop_test (int n)
7657 Here's what the final control flow graph will look like:
7664 @image{sum-of-squares,,,image of a control flow graph,png}
7670 As before, we include the libgccjit++ header and make a
7671 @code{gccjit::context}.
7674 #include <libgccjit++.h>
7678 gccjit::context ctxt;
7679 ctxt = gccjit::context::acquire ();
7684 The function works with the C @cite{int} type.
7686 In the previous tutorial we acquired this via
7689 gccjit::type the_type = ctxt.get_type (ctxt, GCC_JIT_TYPE_INT);
7694 though we could equally well make it work on, say, @cite{double}:
7697 gccjit::type the_type = ctxt.get_type (ctxt, GCC_JIT_TYPE_DOUBLE);
7702 For integer types we can use @code{gccjit::context::get_int_type}
7703 to directly bind a specific type:
7706 gccjit::type the_type = ctxt.get_int_type <int> ();
7711 Let's build the function:
7714 gcc_jit_param n = ctxt.new_param (the_type, "n");
7715 std::vector<gccjit::param> params;
7716 params.push_back (n);
7717 gccjit::function func =
7718 ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
7727 * Expressions; lvalues and rvalues: Expressions lvalues and rvalues<2>.
7728 * Control flow: Control flow<2>.
7729 * Visualizing the control flow graph: Visualizing the control flow graph<2>.
7730 * Full example: Full example<4>.
7734 @node Expressions lvalues and rvalues<2>,Control flow<2>,,Tutorial part 3 Loops and variables<2>
7735 @anchor{cp/intro/tutorial03 expressions-lvalues-and-rvalues}@anchor{e1}
7736 @subsubsection Expressions: lvalues and rvalues
7739 The base class of expression is the @code{gccjit::rvalue},
7740 representing an expression that can be on the @emph{right}-hand side of
7741 an assignment: a value that can be computed somehow, and assigned
7742 @emph{to} a storage area (such as a variable). It has a specific
7743 @code{gccjit::type}.
7745 Anothe important class is @code{gccjit::lvalue}.
7746 A @code{gccjit::lvalue}. is something that can of the @emph{left}-hand
7747 side of an assignment: a storage area (such as a variable).
7749 In other words, every assignment can be thought of as:
7757 Note that @code{gccjit::lvalue} is a subclass of
7758 @code{gccjit::rvalue}, where in an assignment of the form:
7761 LVALUE_A = LVALUE_B;
7766 the @cite{LVALUE_B} implies reading the current value of that storage
7767 area, assigning it into the @cite{LVALUE_A}.
7769 So far the only expressions we've seen are from the previous tutorial:
7775 the multiplication @cite{i * i}:
7781 gccjit::rvalue expr =
7782 ctxt.new_binary_op (
7783 GCC_JIT_BINARY_OP_MULT, int_type,
7786 /* Alternatively, using operator-overloading: */
7787 gccjit::rvalue expr = param_i * param_i;
7792 which is a @code{gccjit::rvalue}, and
7799 the various function parameters: @cite{param_i} and @cite{param_n}, instances of
7800 @code{gccjit::param}, which is a subclass of @code{gccjit::lvalue}
7801 (and, in turn, of @code{gccjit::rvalue}):
7802 we can both read from and write to function parameters within the
7806 Our new example has a new kind of expression: we have two local
7807 variables. We create them by calling
7808 @pxref{e2,,gccjit;;function;;new_local()}, supplying a type and a name:
7812 gccjit::lvalue i = func.new_local (the_type, "i");
7813 gccjit::lvalue sum = func.new_local (the_type, "sum");
7818 These are instances of @code{gccjit::lvalue} - they can be read from
7821 Note that there is no precanned way to create @emph{and} initialize a variable
7830 Instead, having added the local to the function, we have to separately add
7831 an assignment of @cite{0} to @cite{local_i} at the beginning of the function.
7833 @node Control flow<2>,Visualizing the control flow graph<2>,Expressions lvalues and rvalues<2>,Tutorial part 3 Loops and variables<2>
7834 @anchor{cp/intro/tutorial03 control-flow}@anchor{e3}
7835 @subsubsection Control flow
7838 This function has a loop, so we need to build some basic blocks to
7839 handle the control flow. In this case, we need 4 blocks:
7845 before the loop (initializing the locals)
7848 the conditional at the top of the loop (comparing @cite{i < n})
7851 the body of the loop
7854 after the loop terminates (@cite{return sum})
7857 so we create these as @code{gccjit::block} instances within the
7858 @code{gccjit::function}:
7861 gccjit::block b_initial = func.new_block ("initial");
7862 gccjit::block b_loop_cond = func.new_block ("loop_cond");
7863 gccjit::block b_loop_body = func.new_block ("loop_body");
7864 gccjit::block b_after_loop = func.new_block ("after_loop");
7869 We now populate each block with statements.
7871 The entry block @cite{b_initial} consists of initializations followed by a jump
7872 to the conditional. We assign @cite{0} to @cite{i} and to @cite{sum}, using
7873 @pxref{e4,,gccjit;;block;;add_assignment()} to add
7874 an assignment statement, and using @pxref{e5,,gccjit;;context;;zero()} to get
7875 the constant value @cite{0} for the relevant type for the right-hand side of
7880 b_initial.add_assignment (sum, ctxt.zero (the_type));
7883 b_initial.add_assignment (i, ctxt.zero (the_type));
7888 We can then terminate the entry block by jumping to the conditional:
7891 b_initial.end_with_jump (b_loop_cond);
7896 The conditional block is equivalent to the line @cite{while (i < n)} from our
7897 C example. It contains a single statement: a conditional, which jumps to
7898 one of two destination blocks depending on a boolean
7899 @code{gccjit::rvalue}, in this case the comparison of @cite{i} and @cite{n}.
7901 We could build the comparison using @pxref{e6,,gccjit;;context;;new_comparison()}:
7904 gccjit::rvalue guard =
7905 ctxt.new_comparison (GCC_JIT_COMPARISON_GE,
7911 and can then use this to add @cite{b_loop_cond}'s sole statement, via
7912 @pxref{e7,,gccjit;;block;;end_with_conditional()}:
7915 b_loop_cond.end_with_conditional (guard);
7920 However @code{gccjit::rvalue} has overloaded operators for this, so we
7921 express the conditional as
7924 gccjit::rvalue guard = (i >= n);
7929 and hence write the block more concisely as:
7932 b_loop_cond.end_with_conditional (
7940 Next, we populate the body of the loop.
7942 The C statement @cite{sum += i * i;} is an assignment operation, where an
7943 lvalue is modified "in-place". We use
7944 @pxref{e8,,gccjit;;block;;add_assignment_op()} to handle these operations:
7948 b_loop_body.add_assignment_op (sum,
7949 GCC_JIT_BINARY_OP_PLUS,
7955 The @cite{i++} can be thought of as @cite{i += 1}, and can thus be handled in
7956 a similar way. We use @pxref{2f,,gcc_jit_context_one()} to get the constant
7957 value @cite{1} (for the relevant type) for the right-hand side
7962 b_loop_body.add_assignment_op (i,
7963 GCC_JIT_BINARY_OP_PLUS,
7964 ctxt.one (the_type));
7971 For numeric constants other than 0 or 1, we could use
7972 @pxref{e9,,gccjit;;context;;new_rvalue()}, which has overloads
7973 for both @code{int} and @code{double}.
7977 The loop body completes by jumping back to the conditional:
7980 b_loop_body.end_with_jump (b_loop_cond);
7985 Finally, we populate the @cite{b_after_loop} block, reached when the loop
7986 conditional is false. We want to generate the equivalent of:
7994 so the block is just one statement:
7998 b_after_loop.end_with_return (sum);
8005 You can intermingle block creation with statement creation,
8006 but given that the terminator statements generally include references
8007 to other blocks, I find it's clearer to create all the blocks,
8008 @emph{then} all the statements.
8012 We've finished populating the function. As before, we can now compile it
8016 gcc_jit_result *result;
8017 result = ctxt.compile ();
8023 fprintf (stderr, "NULL result");
8027 typedef int (*loop_test_fn_type) (int);
8028 loop_test_fn_type loop_test =
8029 (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
8032 fprintf (stderr, "NULL loop_test");
8033 gcc_jit_result_release (result);
8036 printf ("result: %d", loop_test (10));
8047 @node Visualizing the control flow graph<2>,Full example<4>,Control flow<2>,Tutorial part 3 Loops and variables<2>
8048 @anchor{cp/intro/tutorial03 visualizing-the-control-flow-graph}@anchor{ea}
8049 @subsubsection Visualizing the control flow graph
8052 You can see the control flow graph of a function using
8053 @pxref{eb,,gccjit;;function;;dump_to_dot()}:
8056 func.dump_to_dot ("/tmp/sum-of-squares.dot");
8061 giving a .dot file in GraphViz format.
8063 You can convert this to an image using @cite{dot}:
8066 $ dot -Tpng /tmp/sum-of-squares.dot -o /tmp/sum-of-squares.png
8071 or use a viewer (my preferred one is xdot.py; see
8072 @indicateurl{https://github.com/jrfonseca/xdot.py}; on Fedora you can
8073 install it with @cite{yum install python-xdot}):
8080 @image{sum-of-squares,,,image of a control flow graph,png}
8086 @node Full example<4>,,Visualizing the control flow graph<2>,Tutorial part 3 Loops and variables<2>
8087 @anchor{cp/intro/tutorial03 full-example}@anchor{ec}
8088 @subsubsection Full example
8094 /* Usage example for libgccjit.so's C++ API
8095 Copyright (C) 2014-2015 Free Software Foundation, Inc.
8097 This file is part of GCC.
8099 GCC is free software; you can redistribute it and/or modify it
8100 under the terms of the GNU General Public License as published by
8101 the Free Software Foundation; either version 3, or (at your option)
8104 GCC is distributed in the hope that it will be useful, but
8105 WITHOUT ANY WARRANTY; without even the implied warranty of
8106 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
8107 General Public License for more details.
8109 You should have received a copy of the GNU General Public License
8110 along with GCC; see the file COPYING3. If not see
8111 <http://www.gnu.org/licenses/>. */
8113 #include <libgccjit++.h>
8119 create_code (gccjit::context ctxt)
8122 Simple sum-of-squares, to test conditionals and looping
8124 int loop_test (int n)
8128 for (i = 0; i < n ; i ++)
8134 gccjit::type the_type = ctxt.get_int_type <int> ();
8135 gccjit::type return_type = the_type;
8137 gccjit::param n = ctxt.new_param (the_type, "n");
8138 std::vector<gccjit::param> params;
8139 params.push_back (n);
8140 gccjit::function func =
8141 ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
8147 gccjit::lvalue i = func.new_local (the_type, "i");
8148 gccjit::lvalue sum = func.new_local (the_type, "sum");
8150 gccjit::block b_initial = func.new_block ("initial");
8151 gccjit::block b_loop_cond = func.new_block ("loop_cond");
8152 gccjit::block b_loop_body = func.new_block ("loop_body");
8153 gccjit::block b_after_loop = func.new_block ("after_loop");
8156 b_initial.add_assignment (sum, ctxt.zero (the_type));
8159 b_initial.add_assignment (i, ctxt.zero (the_type));
8161 b_initial.end_with_jump (b_loop_cond);
8164 b_loop_cond.end_with_conditional (
8170 b_loop_body.add_assignment_op (sum,
8171 GCC_JIT_BINARY_OP_PLUS,
8175 b_loop_body.add_assignment_op (i,
8176 GCC_JIT_BINARY_OP_PLUS,
8177 ctxt.one (the_type));
8179 b_loop_body.end_with_jump (b_loop_cond);
8182 b_after_loop.end_with_return (sum);
8186 main (int argc, char **argv)
8188 gccjit::context ctxt;
8189 gcc_jit_result *result = NULL;
8191 /* Get a "context" object for working with the library. */
8192 ctxt = gccjit::context::acquire ();
8194 /* Set some options on the context.
8195 Turn this on to see the code being generated, in assembler form. */
8196 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
8199 /* Populate the context. */
8202 /* Compile the code. */
8203 result = ctxt.compile ();
8209 fprintf (stderr, "NULL result");
8213 /* Extract the generated code from "result". */
8214 typedef int (*loop_test_fn_type) (int);
8215 loop_test_fn_type loop_test =
8216 (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
8219 fprintf (stderr, "NULL loop_test");
8220 gcc_jit_result_release (result);
8224 /* Run the generated code. */
8225 int val = loop_test (10);
8226 printf("loop_test returned: %d\n", val);
8228 gcc_jit_result_release (result);
8237 Building and running it:
8241 tut03-sum-of-squares.cc \
8242 -o tut03-sum-of-squares \
8245 # Run the built program:
8246 $ ./tut03-sum-of-squares
8247 loop_test returned: 285
8252 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
8253 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
8255 @c This is free software: you can redistribute it and/or modify it
8256 @c under the terms of the GNU General Public License as published by
8257 @c the Free Software Foundation, either version 3 of the License, or
8258 @c (at your option) any later version.
8260 @c This program is distributed in the hope that it will be useful, but
8261 @c WITHOUT ANY WARRANTY; without even the implied warranty of
8262 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
8263 @c General Public License for more details.
8265 @c You should have received a copy of the GNU General Public License
8266 @c along with this program. If not, see
8267 @c <http://www.gnu.org/licenses/>.
8269 @node Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>,,Tutorial part 3 Loops and variables<2>,Tutorial<2>
8270 @anchor{cp/intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{ed}@anchor{cp/intro/tutorial04 doc}@anchor{ee}
8271 @subsection Tutorial part 4: Adding JIT-compilation to a toy interpreter
8274 In this example we construct a "toy" interpreter, and add JIT-compilation
8278 * Our toy interpreter: Our toy interpreter<2>.
8279 * Compiling to machine code: Compiling to machine code<2>.
8280 * Setting things up: Setting things up<2>.
8281 * Populating the function: Populating the function<2>.
8282 * Verifying the control flow graph: Verifying the control flow graph<2>.
8283 * Compiling the context: Compiling the context<2>.
8284 * Single-stepping through the generated code: Single-stepping through the generated code<2>.
8285 * Examining the generated code: Examining the generated code<2>.
8286 * Putting it all together: Putting it all together<2>.
8287 * Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?<2>.
8291 @node Our toy interpreter<2>,Compiling to machine code<2>,,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
8292 @anchor{cp/intro/tutorial04 our-toy-interpreter}@anchor{ef}
8293 @subsubsection Our toy interpreter
8296 It's a stack-based interpreter, and is intended as a (very simple) example
8297 of the kind of bytecode interpreter seen in dynamic languages such as
8300 For the sake of simplicity, our toy virtual machine is very limited:
8308 The only data type is @cite{int}
8311 It can only work on one function at a time (so that the only
8312 function call that can be made is to recurse).
8315 Functions can only take one parameter.
8318 Functions have a stack of @cite{int} values.
8321 We'll implement function call within the interpreter by calling a
8322 function in our implementation, rather than implementing our own
8326 The parser is only good enough to get the examples to work.
8330 Naturally, a real interpreter would be much more complicated that this.
8332 The following operations are supported:
8335 @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx}
8358 Duplicate top of stack.
8374 Swap top two elements
8391 Add the top two elements
8408 Likewise, but subtract.
8424 Likewise, but multiply.
8441 elements on the stack
8442 and push a nonzero/zero
8459 Recurse, passing the top
8477 Return the top of the
8490 PUSH_CONST @cite{arg}
8506 JUMP_ABS_IF_TRUE @cite{arg}
8510 Pop; if top of stack was
8525 Programs can be interpreted, disassembled, and compiled to machine code.
8527 The interpreter reads @code{.toy} scripts. Here's what a simple recursive
8528 factorial program looks like, the script @code{factorial.toy}.
8529 The parser ignores lines beginning with a @cite{#}.
8534 # Simple recursive factorial implementation, roughly equivalent to:
8536 # int factorial (int arg)
8540 # return arg * factorial (arg - 1)
8552 # stack: [arg, arg, 2]
8556 # stack: [arg, (arg < 2)]
8568 # stack: [arg, arg, 1]
8572 # stack: [arg, (arg - 1)
8576 # stack: [arg, factorial(arg - 1)]
8580 # stack: [arg * factorial(arg - 1)]
8590 The interpreter is a simple infinite loop with a big @code{switch} statement
8591 based on what the next opcode is:
8598 toyvm_function::interpret (int arg, FILE *trace)
8601 #define PUSH(ARG) (frame.push (ARG))
8602 #define POP(ARG) (frame.pop ())
8604 frame.frm_function = this;
8606 frame.frm_cur_depth = 0;
8614 assert (frame.frm_pc < fn_num_ops);
8615 op = &fn_ops[frame.frm_pc++];
8619 frame.dump_stack (trace);
8620 disassemble_op (op, frame.frm_pc, trace);
8623 switch (op->op_opcode)
8625 /* Ops taking no operand. */
8645 case BINARY_SUBTRACT:
8657 case BINARY_COMPARE_LT:
8665 x = interpret (x, trace);
8672 /* Ops taking an operand. */
8674 PUSH (op->op_operand);
8677 case JUMP_ABS_IF_TRUE:
8680 frame.frm_pc = op->op_operand;
8684 assert (0); /* unknown opcode */
8686 @} /* end of switch on opcode */
8687 @} /* end of while loop */
8699 @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>
8700 @anchor{cp/intro/tutorial04 compiling-to-machine-code}@anchor{f0}
8701 @subsubsection Compiling to machine code
8704 We want to generate machine code that can be cast to this type and
8705 then directly executed in-process:
8710 typedef int (*toyvm_compiled_func) (int);
8718 Our compiler isn't very sophisticated; it takes the implementation of
8719 each opcode above, and maps it directly to the operations supported by
8722 How should we handle the stack? In theory we could calculate what the
8723 stack depth will be at each opcode, and optimize away the stack
8724 manipulation "by hand". We'll see below that libgccjit is able to do
8725 this for us, so we'll implement stack manipulation
8726 in a direct way, by creating a @code{stack} array and @code{stack_depth}
8727 variables, local within the generated function, equivalent to this C code:
8731 int stack[MAX_STACK_DEPTH];
8736 We'll also have local variables @code{x} and @code{y} for use when implementing
8737 the opcodes, equivalent to this:
8746 This means our compiler has the following state:
8752 toyvm_function &toyvmfn;
8754 gccjit::context ctxt;
8756 gccjit::type int_type;
8757 gccjit::type bool_type;
8758 gccjit::type stack_type; /* int[MAX_STACK_DEPTH] */
8760 gccjit::rvalue const_one;
8762 gccjit::function fn;
8763 gccjit::param param_arg;
8764 gccjit::lvalue stack;
8765 gccjit::lvalue stack_depth;
8769 gccjit::location op_locs[MAX_OPS];
8770 gccjit::block initial_block;
8771 gccjit::block op_blocks[MAX_OPS];
8779 @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>
8780 @anchor{cp/intro/tutorial04 setting-things-up}@anchor{f1}
8781 @subsubsection Setting things up
8784 First we create our types:
8791 compilation_state::create_types ()
8794 int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
8795 bool_type = ctxt.get_type (GCC_JIT_TYPE_BOOL);
8796 stack_type = ctxt.new_array_type (int_type, MAX_STACK_DEPTH);
8804 along with extracting a useful @cite{int} constant:
8809 const_one = ctxt.one (int_type);
8819 We'll implement push and pop in terms of the @code{stack} array and
8820 @code{stack_depth}. Here are helper functions for adding statements to
8821 a block, implementing pushing and popping values:
8828 compilation_state::add_push (gccjit::block block,
8829 gccjit::rvalue rvalue,
8830 gccjit::location loc)
8832 /* stack[stack_depth] = RVALUE */
8833 block.add_assignment (
8834 /* stack[stack_depth] */
8835 ctxt.new_array_access (
8842 /* "stack_depth++;". */
8843 block.add_assignment_op (
8845 GCC_JIT_BINARY_OP_PLUS,
8851 compilation_state::add_pop (gccjit::block block,
8852 gccjit::lvalue lvalue,
8853 gccjit::location loc)
8855 /* "--stack_depth;". */
8856 block.add_assignment_op (
8858 GCC_JIT_BINARY_OP_MINUS,
8862 /* "LVALUE = stack[stack_depth];". */
8863 block.add_assignment (
8865 /* stack[stack_depth] */
8866 ctxt.new_array_access (stack,
8878 We will support single-stepping through the generated code in the
8879 debugger, so we need to create @code{gccjit::location} instances, one
8880 per operation in the source code. These will reference the lines of
8881 e.g. @code{factorial.toy}.
8888 compilation_state::create_locations ()
8890 for (int pc = 0; pc < toyvmfn.fn_num_ops; pc++)
8892 toyvm_op *op = &toyvmfn.fn_ops[pc];
8894 op_locs[pc] = ctxt.new_location (toyvmfn.fn_filename,
8906 Let's create the function itself. As usual, we create its parameter
8907 first, then use the parameter to create the function:
8914 compilation_state::create_function (const char *funcname)
8916 std::vector <gccjit::param> params;
8917 param_arg = ctxt.new_param (int_type, "arg", op_locs[0]);
8918 params.push_back (param_arg);
8919 fn = ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
8931 We create the locals within the function.
8936 stack = fn.new_local (stack_type, "stack");
8937 stack_depth = fn.new_local (int_type, "stack_depth");
8938 x = fn.new_local (int_type, "x");
8939 y = fn.new_local (int_type, "y");
8947 @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>
8948 @anchor{cp/intro/tutorial04 populating-the-function}@anchor{f2}
8949 @subsubsection Populating the function
8952 There's some one-time initialization, and the API treats the first block
8953 you create as the entrypoint of the function, so we need to create that
8959 initial_block = fn.new_block ("initial");
8967 We can now create blocks for each of the operations. Most of these will
8968 be consolidated into larger blocks when the optimizer runs.
8973 for (int pc = 0; pc < toyvmfn.fn_num_ops; pc++)
8976 sprintf (buf, "instr%i", pc);
8977 op_blocks[pc] = fn.new_block (buf);
8986 Now that we have a block it can jump to when it's done, we can populate
8993 /* "stack_depth = 0;". */
8994 initial_block.add_assignment (stack_depth,
8995 ctxt.zero (int_type),
8998 /* "PUSH (arg);". */
8999 add_push (initial_block,
9003 /* ...and jump to insn 0. */
9004 initial_block.end_with_jump (op_blocks[0],
9013 We can now populate the blocks for the individual operations. We loop
9014 through them, adding instructions to their blocks:
9019 for (int pc = 0; pc < toyvmfn.fn_num_ops; pc++)
9021 gccjit::location loc = op_locs[pc];
9023 gccjit::block block = op_blocks[pc];
9024 gccjit::block next_block = (pc < toyvmfn.fn_num_ops
9029 op = &toyvmfn.fn_ops[pc];
9037 We're going to have another big @code{switch} statement for implementing
9038 the opcodes, this time for compiling them, rather than interpreting
9039 them. It's helpful to have macros for implementing push and pop, so that
9040 we can make the @code{switch} statement that's coming up look as much as
9041 possible like the one above within the interpreter:
9045 #define X_EQUALS_POP()\
9046 add_pop (block, x, loc)
9047 #define Y_EQUALS_POP()\
9048 add_pop (block, y, loc)
9049 #define PUSH_RVALUE(RVALUE)\
9050 add_push (block, (RVALUE), loc)
9063 A particularly clever implementation would have an @emph{identical}
9064 @code{switch} statement shared by the interpreter and the compiler, with
9065 some preprocessor "magic". We're not doing that here, for the sake
9070 When I first implemented this compiler, I accidentally missed an edit
9071 when copying and pasting the @code{Y_EQUALS_POP} macro, so that popping the
9072 stack into @code{y} instead erroneously assigned it to @code{x}, leaving @code{y}
9075 To track this kind of thing down, we can use
9076 @pxref{f3,,gccjit;;block;;add_comment()} to add descriptive comments
9077 to the internal representation. This is invaluable when looking through
9078 the generated IR for, say @code{factorial}:
9084 block.add_comment (opcode_names[op->op_opcode], loc);
9092 We can now write the big @code{switch} statement that implements the
9093 individual opcodes, populating the relevant block with statements:
9099 switch (op->op_opcode)
9118 ctxt.new_binary_op (
9119 GCC_JIT_BINARY_OP_PLUS,
9125 case BINARY_SUBTRACT:
9129 ctxt.new_binary_op (
9130 GCC_JIT_BINARY_OP_MINUS,
9140 ctxt.new_binary_op (
9141 GCC_JIT_BINARY_OP_MULT,
9147 case BINARY_COMPARE_LT:
9151 /* cast of bool to int */
9153 /* (x < y) as a bool */
9154 ctxt.new_comparison (
9155 GCC_JIT_COMPARISON_LT,
9175 block.end_with_return (x, loc);
9178 /* Ops taking an operand. */
9181 ctxt.new_rvalue (int_type, op->op_operand));
9184 case JUMP_ABS_IF_TRUE:
9186 block.end_with_conditional (
9188 ctxt.new_cast (x, bool_type, loc),
9189 op_blocks[op->op_operand], /* on_true */
9190 next_block, /* on_false */
9196 @} /* end of switch on opcode */
9204 Every block must be terminated, via a call to one of the
9205 @code{gccjit::block::end_with_} entrypoints. This has been done for two
9206 of the opcodes, but we need to do it for the other ones, by jumping
9212 if (op->op_opcode != JUMP_ABS_IF_TRUE
9213 && op->op_opcode != RETURN)
9214 block.end_with_jump (next_block, loc);
9222 This is analogous to simply incrementing the program counter.
9224 @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>
9225 @anchor{cp/intro/tutorial04 verifying-the-control-flow-graph}@anchor{f4}
9226 @subsubsection Verifying the control flow graph
9229 Having finished looping over the blocks, the context is complete.
9231 As before, we can verify that the control flow and statements are sane by
9232 using @pxref{eb,,gccjit;;function;;dump_to_dot()}:
9235 fn.dump_to_dot ("/tmp/factorial.dot");
9240 and viewing the result. Note how the label names, comments, and
9241 variable names show up in the dump, to make it easier to spot
9242 errors in our compiler.
9249 @image{factorial,,,image of a control flow graph,png}
9255 @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>
9256 @anchor{cp/intro/tutorial04 compiling-the-context}@anchor{f5}
9257 @subsubsection Compiling the context
9260 Having finished looping over the blocks and populating them with
9261 statements, the context is complete.
9263 We can now compile it, and extract machine code from the result:
9268 gcc_jit_result *result = state.compile ();
9270 return (toyvm_compiled_func)gcc_jit_result_get_code (result, funcname);
9277 We can now run the result:
9282 toyvm_compiled_func code = fn->compile ();
9283 printf ("compiler result: %d\n",
9284 code (atoi (argv[2])));
9292 @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>
9293 @anchor{cp/intro/tutorial04 single-stepping-through-the-generated-code}@anchor{f6}
9294 @subsubsection Single-stepping through the generated code
9297 It's possible to debug the generated code. To do this we need to both:
9305 Set up source code locations for our statements, so that we can
9306 meaningfully step through the code. We did this above by
9307 calling @pxref{f7,,gccjit;;context;;new_location()} and using the
9311 Enable the generation of debugging information, by setting
9312 @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
9313 @code{gccjit::context} via
9314 @pxref{dc,,gccjit;;context;;set_bool_option()}:
9317 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1);
9324 Having done this, we can put a breakpoint on the generated function:
9327 $ gdb --args ./toyvm factorial.toy 10
9328 (gdb) break factorial
9329 Function "factorial" not defined.
9330 Make breakpoint pending on future shared library load? (y or [n]) y
9331 Breakpoint 1 (factorial) pending.
9333 Breakpoint 1, factorial (arg=10) at factorial.toy:14
9339 We've set up location information, which references @code{factorial.toy}.
9340 This allows us to use e.g. @code{list} to see where we are in the script:
9350 15 # stack: [arg, arg]
9358 and to step through the function, examining the data:
9364 22 BINARY_COMPARE_LT
9366 $5 = @{10, 10, 2, 0, -7152, 32767, 0, 0@}
9367 (gdb) print stack_depth
9373 You'll see that the parts of the @code{stack} array that haven't been
9374 touched yet are uninitialized.
9378 Turning on optimizations may lead to unpredictable results when
9379 stepping through the generated code: the execution may appear to
9380 "jump around" the source code. This is analogous to turning up the
9381 optimization level in a regular compiler.
9385 @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>
9386 @anchor{cp/intro/tutorial04 examining-the-generated-code}@anchor{f8}
9387 @subsubsection Examining the generated code
9390 How good is the optimized code?
9392 We can turn up optimizations, by calling
9393 @pxref{dd,,gccjit;;context;;set_int_option()} with
9394 @pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
9397 ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3);
9402 One of GCC's internal representations is called "gimple". A dump of the
9403 initial gimple representation of the code can be seen by setting:
9406 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1);
9411 With optimization on and source locations displayed, this gives:
9413 @c We'll use "c" for gimple dumps
9416 factorial (signed int arg)
9418 <unnamed type> D.80;
9426 signed int stack_depth;
9427 signed int stack[8];
9433 stack[stack_depth] = arg;
9434 stack_depth = stack_depth + 1;
9438 stack_depth = stack_depth + -1;
9439 x = stack[stack_depth];
9440 stack[stack_depth] = x;
9441 stack_depth = stack_depth + 1;
9442 stack[stack_depth] = x;
9443 stack_depth = stack_depth + 1;
9447 stack[stack_depth] = 2;
9448 stack_depth = stack_depth + 1;
9456 You can see the generated machine code in assembly form via:
9459 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 1);
9460 result = ctxt.compile ();
9465 which shows that (on this x86_64 box) the compiler has unrolled the loop
9466 and is using MMX instructions to perform several multiplications
9475 .type factorial, @@function
9478 .file 1 "factorial.toy"
9489 leal 0(,%rcx,4), %esi
9495 movl %eax, -16(%rsp)
9497 movd -16(%rsp), %xmm0
9498 movl %edi, -16(%rsp)
9499 movl %eax, -12(%rsp)
9500 movd -16(%rsp), %xmm1
9502 movl %edx, -16(%rsp)
9503 movd -12(%rsp), %xmm4
9504 movd -16(%rsp), %xmm6
9505 punpckldq %xmm4, %xmm0
9506 movdqa .LC1(%rip), %xmm4
9507 punpckldq %xmm6, %xmm1
9508 punpcklqdq %xmm0, %xmm1
9509 movdqa .LC0(%rip), %xmm0
9511 # etc - edited for brevity
9516 This is clearly overkill for a function that will likely overflow the
9517 @code{int} type before the vectorization is worthwhile - but then again, this
9520 Turning down the optimization level to 2:
9523 ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 2);
9528 yields this code, which is simple enough to quote in its entirety:
9535 .type factorial, @@function
9564 .size factorial, .-factorial
9565 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-%@{gcc_release@})"
9566 .section .note.GNU-stack,"",@@progbits
9571 Note that the stack pushing and popping have been eliminated, as has the
9572 recursive call (in favor of an iteration).
9574 @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>
9575 @anchor{cp/intro/tutorial04 putting-it-all-together}@anchor{f9}
9576 @subsubsection Putting it all together
9579 The complete example can be seen in the source tree at
9580 @code{gcc/jit/docs/examples/tut04-toyvm/toyvm.cc}
9582 along with a Makefile and a couple of sample .toy scripts:
9586 drwxrwxr-x. 2 david david 4096 Sep 19 17:46 .
9587 drwxrwxr-x. 3 david david 4096 Sep 19 15:26 ..
9588 -rw-rw-r--. 1 david david 615 Sep 19 12:43 factorial.toy
9589 -rw-rw-r--. 1 david david 834 Sep 19 13:08 fibonacci.toy
9590 -rw-rw-r--. 1 david david 238 Sep 19 14:22 Makefile
9591 -rw-rw-r--. 1 david david 16457 Sep 19 17:07 toyvm.cc
9594 g++ -Wall -g -o toyvm toyvm.cc -lgccjit
9596 $ ./toyvm factorial.toy 10
9597 interpreter result: 3628800
9598 compiler result: 3628800
9600 $ ./toyvm fibonacci.toy 10
9601 interpreter result: 55
9607 @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>
9608 @anchor{cp/intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{fa}
9609 @subsubsection Behind the curtain: How does our code get optimized?
9612 Our example is done, but you may be wondering about exactly how the
9613 compiler turned what we gave it into the machine code seen above.
9615 We can examine what the compiler is doing in detail by setting:
9618 state.ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING, 1);
9619 state.ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES, 1);
9624 This will dump detailed information about the compiler's state to a
9625 directory under @code{/tmp}, and keep it from being cleaned up.
9627 The precise names and their formats of these files is subject to change.
9628 Higher optimization levels lead to more files.
9629 Here's what I saw (edited for brevity; there were almost 200 files):
9632 intermediate files written to /tmp/libgccjit-KPQbGw
9633 $ ls /tmp/libgccjit-KPQbGw/
9635 fake.c.000i.type-inheritance
9637 fake.c.007t.omplower
9641 fake.c.014i.visibility
9642 fake.c.015i.early_local_cleanups
9649 The gimple code is converted into Static Single Assignment form,
9650 with annotations for use when generating the debuginfo:
9653 $ less /tmp/libgccjit-KPQbGw/fake.c.016t.ssa
9659 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
9661 factorial (signed int arg)
9663 signed int stack[8];
9664 signed int stack_depth;
9676 # DEBUG stack_depth => stack_depth_3
9677 stack[stack_depth_3] = arg_5(D);
9678 stack_depth_7 = stack_depth_3 + 1;
9679 # DEBUG stack_depth => stack_depth_7
9680 # DEBUG instr0 => NULL
9681 # DEBUG /* DUP */ => NULL
9682 stack_depth_8 = stack_depth_7 + -1;
9683 # DEBUG stack_depth => stack_depth_8
9684 x_9 = stack[stack_depth_8];
9686 stack[stack_depth_8] = x_9;
9687 stack_depth_11 = stack_depth_8 + 1;
9688 # DEBUG stack_depth => stack_depth_11
9689 stack[stack_depth_11] = x_9;
9690 stack_depth_13 = stack_depth_11 + 1;
9691 # DEBUG stack_depth => stack_depth_13
9692 # DEBUG instr1 => NULL
9693 # DEBUG /* PUSH_CONST */ => NULL
9694 stack[stack_depth_13] = 2;
9696 /* etc; edited for brevity */
9701 We can perhaps better see the code by turning off
9702 @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to suppress all those @code{DEBUG}
9706 $ less /tmp/libgccjit-1Hywc0/fake.c.016t.ssa
9712 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
9714 factorial (signed int arg)
9716 signed int stack[8];
9717 signed int stack_depth;
9729 stack[stack_depth_3] = arg_5(D);
9730 stack_depth_7 = stack_depth_3 + 1;
9731 stack_depth_8 = stack_depth_7 + -1;
9732 x_9 = stack[stack_depth_8];
9733 stack[stack_depth_8] = x_9;
9734 stack_depth_11 = stack_depth_8 + 1;
9735 stack[stack_depth_11] = x_9;
9736 stack_depth_13 = stack_depth_11 + 1;
9737 stack[stack_depth_13] = 2;
9738 stack_depth_15 = stack_depth_13 + 1;
9739 stack_depth_16 = stack_depth_15 + -1;
9740 y_17 = stack[stack_depth_16];
9741 stack_depth_18 = stack_depth_16 + -1;
9742 x_19 = stack[stack_depth_18];
9744 _21 = (signed int) _20;
9745 stack[stack_depth_18] = _21;
9746 stack_depth_23 = stack_depth_18 + 1;
9747 stack_depth_24 = stack_depth_23 + -1;
9748 x_25 = stack[stack_depth_24];
9750 goto <bb 4> (instr9);
9752 goto <bb 3> (instr4);
9756 stack_depth_26 = stack_depth_24 + -1;
9757 x_27 = stack[stack_depth_26];
9758 stack[stack_depth_26] = x_27;
9759 stack_depth_29 = stack_depth_26 + 1;
9760 stack[stack_depth_29] = x_27;
9761 stack_depth_31 = stack_depth_29 + 1;
9762 stack[stack_depth_31] = 1;
9763 stack_depth_33 = stack_depth_31 + 1;
9764 stack_depth_34 = stack_depth_33 + -1;
9765 y_35 = stack[stack_depth_34];
9766 stack_depth_36 = stack_depth_34 + -1;
9767 x_37 = stack[stack_depth_36];
9769 stack[stack_depth_36] = _38;
9770 stack_depth_40 = stack_depth_36 + 1;
9771 stack_depth_41 = stack_depth_40 + -1;
9772 x_42 = stack[stack_depth_41];
9773 _44 = factorial (x_42);
9774 stack[stack_depth_41] = _44;
9775 stack_depth_46 = stack_depth_41 + 1;
9776 stack_depth_47 = stack_depth_46 + -1;
9777 y_48 = stack[stack_depth_47];
9778 stack_depth_49 = stack_depth_47 + -1;
9779 x_50 = stack[stack_depth_49];
9781 stack[stack_depth_49] = _51;
9782 stack_depth_53 = stack_depth_49 + 1;
9784 # stack_depth_1 = PHI <stack_depth_24(2), stack_depth_53(3)>
9787 stack_depth_54 = stack_depth_1 + -1;
9788 x_55 = stack[stack_depth_54];
9790 stack =@{v@} @{CLOBBER@};
9798 Note in the above how all the @code{gccjit::block} instances we
9799 created have been consolidated into just 3 blocks in GCC's internal
9800 representation: @code{initial}, @code{instr4} and @code{instr9}.
9803 * Optimizing away stack manipulation: Optimizing away stack manipulation<2>.
9804 * Elimination of tail recursion: Elimination of tail recursion<2>.
9808 @node Optimizing away stack manipulation<2>,Elimination of tail recursion<2>,,Behind the curtain How does our code get optimized?<2>
9809 @anchor{cp/intro/tutorial04 optimizing-away-stack-manipulation}@anchor{fb}
9810 @subsubsection Optimizing away stack manipulation
9813 Recall our simple implementation of stack operations. Let's examine
9814 how the stack operations are optimized away.
9816 After a pass of constant-propagation, the depth of the stack at each
9817 opcode can be determined at compile-time:
9820 $ less /tmp/libgccjit-1Hywc0/fake.c.021t.ccp1
9826 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
9828 factorial (signed int arg)
9830 signed int stack[8];
9831 signed int stack_depth;
9841 stack[0] = arg_5(D);
9849 _21 = (signed int) _20;
9853 goto <bb 4> (instr9);
9855 goto <bb 3> (instr4);
9868 _44 = factorial (x_42);
9879 stack =@{v@} @{CLOBBER@};
9887 Note how, in the above, all those @code{stack_depth} values are now just
9888 constants: we're accessing specific stack locations at each opcode.
9890 The "esra" pass ("Early Scalar Replacement of Aggregates") breaks
9891 out our "stack" array into individual elements:
9894 $ less /tmp/libgccjit-1Hywc0/fake.c.024t.esra
9900 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
9902 Created a replacement for stack offset: 0, size: 32: stack$0
9903 Created a replacement for stack offset: 32, size: 32: stack$1
9904 Created a replacement for stack offset: 64, size: 32: stack$2
9906 Symbols to be put in SSA form
9907 @{ D.89 D.90 D.91 @}
9908 Incremental SSA update started at block: 0
9909 Number of blocks in CFG: 5
9910 Number of blocks to update: 4 ( 80%)
9913 factorial (signed int arg)
9918 signed int stack[8];
9919 signed int stack_depth;
9929 stack$0_45 = arg_5(D);
9937 _21 = (signed int) _20;
9941 goto <bb 4> (instr9);
9943 goto <bb 3> (instr4);
9956 _44 = factorial (x_42);
9963 # stack$0_52 = PHI <stack$0_39(2), stack$0_1(3)>
9968 stack =@{v@} @{CLOBBER@};
9976 Hence at this point, all those pushes and pops of the stack are now
9977 simply assignments to specific temporary variables.
9979 After some copy propagation, the stack manipulation has been completely
9983 $ less /tmp/libgccjit-1Hywc0/fake.c.026t.copyprop1
9989 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
9991 factorial (signed int arg)
9996 signed int stack[8];
9997 signed int stack_depth;
10000 <unnamed type> _20;
10007 stack$0_39 = arg_5(D);
10008 _20 = arg_5(D) <= 1;
10009 _21 = (signed int) _20;
10011 goto <bb 4> (instr9);
10013 goto <bb 3> (instr4);
10017 _38 = arg_5(D) + -1;
10018 _44 = factorial (_38);
10019 _51 = arg_5(D) * _44;
10022 # stack$0_52 = PHI <arg_5(D)(2), _51(3)>
10025 stack =@{v@} @{CLOBBER@};
10033 Later on, another pass finally eliminated @code{stack_depth} local and the
10034 unused parts of the @cite{stack`} array altogether:
10037 $ less /tmp/libgccjit-1Hywc0/fake.c.036t.release_ssa
10043 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
10045 Released 44 names, 314.29%, removed 44 holes
10046 factorial (signed int arg)
10048 signed int stack$0;
10049 signed int mult_acc_1;
10053 signed int mul_tmp_10;
10054 signed int mult_acc_11;
10055 signed int mult_acc_13;
10057 # arg_9 = PHI <arg_8(D)(0)>
10058 # mult_acc_13 = PHI <1(0)>
10062 # arg_4 = PHI <arg_9(2), _7(3)>
10063 # mult_acc_1 = PHI <mult_acc_13(2), mult_acc_11(3)>
10065 _6 = (signed int) _5;
10067 goto <bb 4> (instr9);
10069 goto <bb 3> (instr4);
10074 mult_acc_11 = mult_acc_1 * arg_4;
10077 # stack$0_12 = PHI <arg_4(5)>
10080 mul_tmp_10 = mult_acc_1 * stack$0_12;
10088 @node Elimination of tail recursion<2>,,Optimizing away stack manipulation<2>,Behind the curtain How does our code get optimized?<2>
10089 @anchor{cp/intro/tutorial04 elimination-of-tail-recursion}@anchor{fc}
10090 @subsubsection Elimination of tail recursion
10093 Another significant optimization is the detection that the call to
10094 @code{factorial} is tail recursion, which can be eliminated in favor of
10098 $ less /tmp/libgccjit-1Hywc0/fake.c.030t.tailr1
10104 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
10107 Symbols to be put in SSA form
10109 Incremental SSA update started at block: 0
10110 Number of blocks in CFG: 5
10111 Number of blocks to update: 4 ( 80%)
10114 factorial (signed int arg)
10116 signed int stack$2;
10117 signed int stack$1;
10118 signed int stack$0;
10119 signed int stack[8];
10120 signed int stack_depth;
10123 signed int mult_acc_1;
10124 <unnamed type> _20;
10127 signed int mul_tmp_44;
10128 signed int mult_acc_51;
10130 # arg_5 = PHI <arg_39(D)(0), _38(3)>
10131 # mult_acc_1 = PHI <1(0), mult_acc_51(3)>
10134 _21 = (signed int) _20;
10136 goto <bb 4> (instr9);
10138 goto <bb 3> (instr4);
10143 mult_acc_51 = mult_acc_1 * arg_5;
10144 goto <bb 2> (initial);
10146 # stack$0_52 = PHI <arg_5(2)>
10149 stack =@{v@} @{CLOBBER@};
10150 mul_tmp_44 = mult_acc_1 * stack$0_52;
10158 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
10159 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
10161 @c This is free software: you can redistribute it and/or modify it
10162 @c under the terms of the GNU General Public License as published by
10163 @c the Free Software Foundation, either version 3 of the License, or
10164 @c (at your option) any later version.
10166 @c This program is distributed in the hope that it will be useful, but
10167 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10168 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10169 @c General Public License for more details.
10171 @c You should have received a copy of the GNU General Public License
10172 @c along with this program. If not, see
10173 @c <http://www.gnu.org/licenses/>.
10175 @node Topic Reference<2>,,Tutorial<2>,C++ bindings for libgccjit
10176 @anchor{cp/topics/index doc}@anchor{fd}@anchor{cp/topics/index topic-reference}@anchor{fe}
10177 @section Topic Reference
10180 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
10181 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
10183 @c This is free software: you can redistribute it and/or modify it
10184 @c under the terms of the GNU General Public License as published by
10185 @c the Free Software Foundation, either version 3 of the License, or
10186 @c (at your option) any later version.
10188 @c This program is distributed in the hope that it will be useful, but
10189 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10190 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10191 @c General Public License for more details.
10193 @c You should have received a copy of the GNU General Public License
10194 @c along with this program. If not, see
10195 @c <http://www.gnu.org/licenses/>.
10198 * Compilation contexts: Compilation contexts<2>.
10199 * Objects: Objects<2>.
10201 * Expressions: Expressions<2>.
10202 * Creating and using functions: Creating and using functions<2>.
10203 * Source Locations: Source Locations<2>.
10204 * Compilation results: Compilation results<2>.
10206 Compilation contexts
10208 * Lifetime-management: Lifetime-management<2>.
10209 * Thread-safety: Thread-safety<2>.
10210 * Error-handling: Error-handling<3>.
10211 * Debugging: Debugging<2>.
10212 * Options: Options<4>.
10216 * String Options: String Options<2>.
10217 * Boolean options: Boolean options<2>.
10218 * Integer options: Integer options<2>.
10222 * Standard types: Standard types<2>.
10223 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
10224 * Structures and unions: Structures and unions<2>.
10228 * Rvalues: Rvalues<2>.
10229 * Lvalues: Lvalues<2>.
10230 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
10234 * Simple expressions: Simple expressions<2>.
10235 * Unary Operations: Unary Operations<2>.
10236 * Binary Operations: Binary Operations<2>.
10237 * Comparisons: Comparisons<2>.
10238 * Function calls: Function calls<2>.
10239 * Type-coercion: Type-coercion<2>.
10243 * Global variables: Global variables<2>.
10245 Creating and using functions
10247 * Params: Params<2>.
10248 * Functions: Functions<2>.
10249 * Blocks: Blocks<2>.
10250 * Statements: Statements<2>.
10254 * Faking it: Faking it<2>.
10259 @node Compilation contexts<2>,Objects<2>,,Topic Reference<2>
10260 @anchor{cp/topics/contexts compilation-contexts}@anchor{ff}@anchor{cp/topics/contexts doc}@anchor{100}
10261 @subsection Compilation contexts
10264 @geindex gccjit;;context (C++ class)
10265 @anchor{cp/topics/contexts gccjit context}@anchor{101}
10266 @deffn {C++ Class} gccjit::context
10269 The top-level of the C++ API is the @pxref{101,,gccjit;;context} type.
10271 A @pxref{101,,gccjit;;context} instance encapsulates the state of a
10274 You can set up options on it, and add types, functions and code.
10275 Invoking @pxref{da,,gccjit;;context;;compile()} on it gives you a
10276 @pxref{16,,gcc_jit_result *}.
10278 It is a thin wrapper around the C API's @pxref{8,,gcc_jit_context *}.
10281 * Lifetime-management: Lifetime-management<2>.
10282 * Thread-safety: Thread-safety<2>.
10283 * Error-handling: Error-handling<3>.
10284 * Debugging: Debugging<2>.
10285 * Options: Options<4>.
10289 @node Lifetime-management<2>,Thread-safety<2>,,Compilation contexts<2>
10290 @anchor{cp/topics/contexts lifetime-management}@anchor{102}
10291 @subsubsection Lifetime-management
10294 Contexts are the unit of lifetime-management within the API: objects
10295 have their lifetime bounded by the context they are created within, and
10296 cleanup of such objects is done for you when the context is released.
10298 @geindex gccjit;;context;;acquire (C++ function)
10299 @anchor{cp/topics/contexts gccjit context acquire}@anchor{d4}
10300 @deffn {C++ Function} gccjit::context gccjit::context::acquire ()
10302 This function acquires a new @pxref{101,,gccjit;;context} instance,
10303 which is independent of any others that may be present within this
10307 @geindex gccjit;;context;;release (C++ function)
10308 @anchor{cp/topics/contexts gccjit context release}@anchor{d6}
10309 @deffn {C++ Function} void gccjit::context::release ()
10311 This function releases all resources associated with the given context.
10312 Both the context itself and all of its @code{gccjit::object *}
10313 instances are cleaned up. It should be called exactly once on a given
10316 It is invalid to use the context or any of its "contextual" objects
10317 after calling this.
10326 @geindex gccjit;;context;;new_child_context (C++ function)
10327 @anchor{cp/topics/contexts gccjit context new_child_context}@anchor{103}
10328 @deffn {C++ Function} gccjit::context gccjit::context::new_child_context ()
10330 Given an existing JIT context, create a child context.
10332 The child inherits a copy of all option-settings from the parent.
10334 The child can reference objects created within the parent, but not
10337 The lifetime of the child context must be bounded by that of the
10338 parent: you should release a child context before releasing the parent
10341 If you use a function from a parent context within a child context,
10342 you have to compile the parent context before you can compile the
10343 child context, and the gccjit::result of the parent context must
10344 outlive the gccjit::result of the child context.
10346 This allows caching of shared initializations. For example, you could
10347 create types and declarations of global functions in a parent context
10348 once within a process, and then create child contexts whenever a
10349 function or loop becomes hot. Each such child context can be used for
10350 JIT-compiling just one function or loop, but can reference types
10351 and helper functions created within the parent context.
10353 Contexts can be arbitrarily nested, provided the above rules are
10354 followed, but it's probably not worth going above 2 or 3 levels, and
10355 there will likely be a performance hit for such nesting.
10358 @node Thread-safety<2>,Error-handling<3>,Lifetime-management<2>,Compilation contexts<2>
10359 @anchor{cp/topics/contexts thread-safety}@anchor{104}
10360 @subsubsection Thread-safety
10363 Instances of @pxref{101,,gccjit;;context} created via
10364 @pxref{d4,,gccjit;;context;;acquire()} are independent from each other:
10365 only one thread may use a given context at once, but multiple threads
10366 could each have their own contexts without needing locks.
10368 Contexts created via @pxref{103,,gccjit;;context;;new_child_context()} are
10369 related to their parent context. They can be partitioned by their
10370 ultimate ancestor into independent "family trees". Only one thread
10371 within a process may use a given "family tree" of such contexts at once,
10372 and if you're using multiple threads you should provide your own locking
10373 around entire such context partitions.
10375 @node Error-handling<3>,Debugging<2>,Thread-safety<2>,Compilation contexts<2>
10376 @anchor{cp/topics/contexts error-handling}@anchor{105}
10377 @subsubsection Error-handling
10380 @c FIXME: How does error-handling work for C++ API?
10382 You can only compile and get code from a context if no errors occur.
10384 In general, if an error occurs when using an API entrypoint, it returns
10385 NULL. You don't have to check everywhere for NULL results, since the
10386 API gracefully handles a NULL being passed in for any argument.
10388 Errors are printed on stderr and can be queried using
10389 @pxref{106,,gccjit;;context;;get_first_error()}.
10391 @geindex gccjit;;context;;get_first_error (C++ function)
10392 @anchor{cp/topics/contexts gccjit context get_first_error__gccjit contextP}@anchor{106}
10393 @deffn {C++ Function} const char* gccjit::context::get_first_error (gccjit::context* ctxt)
10395 Returns the first error message that occurred on the context.
10397 The returned string is valid for the rest of the lifetime of the
10400 If no errors occurred, this will be NULL.
10403 @node Debugging<2>,Options<4>,Error-handling<3>,Compilation contexts<2>
10404 @anchor{cp/topics/contexts debugging}@anchor{107}
10405 @subsubsection Debugging
10408 @geindex gccjit;;context;;dump_to_file (C++ function)
10409 @anchor{cp/topics/contexts gccjit context dump_to_file__ssCR i}@anchor{108}
10410 @deffn {C++ Function} void gccjit::context::dump_to_file (const std::string& path, int update_locations)
10412 To help with debugging: dump a C-like representation to the given path,
10413 describing what's been set up on the context.
10415 If "update_locations" is true, then also set up @pxref{109,,gccjit;;location}
10416 information throughout the context, pointing at the dump file as if it
10417 were a source file. This may be of use in conjunction with
10418 @code{GCCJIT::BOOL_OPTION_DEBUGINFO} to allow stepping through the
10419 code in a debugger.
10422 @geindex gccjit;;context;;dump_reproducer_to_file (C++ function)
10423 @anchor{cp/topics/contexts gccjit context dump_reproducer_to_file__gcc_jit_contextP cCP}@anchor{10a}
10424 @deffn {C++ Function} void gccjit::context::dump_reproducer_to_file (gcc_jit_context* ctxt, const char* path)
10426 This is a thin wrapper around the C API
10427 @pxref{56,,gcc_jit_context_dump_reproducer_to_file()}, and hence works the
10430 Note that the generated source is C code, not C++; this might be of use
10431 for seeing what the C++ bindings are doing at the C level.
10434 @node Options<4>,,Debugging<2>,Compilation contexts<2>
10435 @anchor{cp/topics/contexts options}@anchor{10b}
10436 @subsubsection Options
10440 * String Options: String Options<2>.
10441 * Boolean options: Boolean options<2>.
10442 * Integer options: Integer options<2>.
10446 @node String Options<2>,Boolean options<2>,,Options<4>
10447 @anchor{cp/topics/contexts string-options}@anchor{10c}
10448 @subsubsection String Options
10451 @geindex gccjit;;context;;set_str_option (C++ function)
10452 @anchor{cp/topics/contexts gccjit context set_str_option__enum cCP}@anchor{10d}
10453 @deffn {C++ Function} void gccjit::context::set_str_option (enum gcc_jit_str_option, const char* value)
10455 Set a string option of the context.
10457 This is a thin wrapper around the C API
10458 @pxref{5a,,gcc_jit_context_set_str_option()}; the options have the same
10462 @node Boolean options<2>,Integer options<2>,String Options<2>,Options<4>
10463 @anchor{cp/topics/contexts boolean-options}@anchor{10e}
10464 @subsubsection Boolean options
10467 @geindex gccjit;;context;;set_bool_option (C++ function)
10468 @anchor{cp/topics/contexts gccjit context set_bool_option__enum i}@anchor{dc}
10469 @deffn {C++ Function} void gccjit::context::set_bool_option (enum gcc_jit_bool_option, int value)
10471 Set a boolean option of the context.
10473 This is a thin wrapper around the C API
10474 @pxref{1b,,gcc_jit_context_set_bool_option()}; the options have the same
10478 @node Integer options<2>,,Boolean options<2>,Options<4>
10479 @anchor{cp/topics/contexts integer-options}@anchor{10f}
10480 @subsubsection Integer options
10483 @geindex gccjit;;context;;set_int_option (C++ function)
10484 @anchor{cp/topics/contexts gccjit context set_int_option__enum i}@anchor{dd}
10485 @deffn {C++ Function} void gccjit::context::set_int_option (enum gcc_jit_int_option, int value)
10487 Set an integer option of the context.
10489 This is a thin wrapper around the C API
10490 @pxref{1e,,gcc_jit_context_set_int_option()}; the options have the same
10494 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
10495 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
10497 @c This is free software: you can redistribute it and/or modify it
10498 @c under the terms of the GNU General Public License as published by
10499 @c the Free Software Foundation, either version 3 of the License, or
10500 @c (at your option) any later version.
10502 @c This program is distributed in the hope that it will be useful, but
10503 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10504 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10505 @c General Public License for more details.
10507 @c You should have received a copy of the GNU General Public License
10508 @c along with this program. If not, see
10509 @c <http://www.gnu.org/licenses/>.
10511 @node Objects<2>,Types<2>,Compilation contexts<2>,Topic Reference<2>
10512 @anchor{cp/topics/objects objects}@anchor{110}@anchor{cp/topics/objects doc}@anchor{111}
10513 @subsection Objects
10516 @geindex gccjit;;object (C++ class)
10517 @anchor{cp/topics/objects gccjit object}@anchor{112}
10518 @deffn {C++ Class} gccjit::object
10521 Almost every entity in the API (with the exception of
10522 @pxref{101,,gccjit;;context} and @pxref{16,,gcc_jit_result *}) is a
10523 "contextual" object, a @pxref{112,,gccjit;;object}.
10533 is associated with a @pxref{101,,gccjit;;context}.
10536 is automatically cleaned up for you when its context is released so
10537 you don't need to manually track and cleanup all objects, just the
10542 The C++ class hierarchy within the @code{gccjit} namespace looks like this:
10559 The @pxref{112,,gccjit;;object} base class has the following operations:
10561 @geindex gccjit;;object;;get_context (C++ function)
10562 @anchor{cp/topics/objects gccjit object get_contextC}@anchor{113}
10563 @deffn {C++ Function} gccjit::context gccjit::object::get_context () const
10565 Which context is the obj within?
10568 @geindex gccjit;;object;;get_debug_string (C++ function)
10569 @anchor{cp/topics/objects gccjit object get_debug_stringC}@anchor{d7}
10570 @deffn {C++ Function} std::string gccjit::object::get_debug_string () const
10572 Generate a human-readable description for the given object.
10577 printf ("obj: %s\n", obj.get_debug_string ().c_str ());
10582 might give this text on stdout:
10585 obj: 4.0 * (float)i
10591 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
10592 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
10594 @c This is free software: you can redistribute it and/or modify it
10595 @c under the terms of the GNU General Public License as published by
10596 @c the Free Software Foundation, either version 3 of the License, or
10597 @c (at your option) any later version.
10599 @c This program is distributed in the hope that it will be useful, but
10600 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10601 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10602 @c General Public License for more details.
10604 @c You should have received a copy of the GNU General Public License
10605 @c along with this program. If not, see
10606 @c <http://www.gnu.org/licenses/>.
10608 @node Types<2>,Expressions<2>,Objects<2>,Topic Reference<2>
10609 @anchor{cp/topics/types doc}@anchor{114}@anchor{cp/topics/types types}@anchor{115}
10613 @geindex gccjit;;type (C++ class)
10614 @anchor{cp/topics/types gccjit type}@anchor{116}
10615 @deffn {C++ Class} gccjit::type
10617 gccjit::type represents a type within the library. It is a subclass
10618 of @pxref{112,,gccjit;;object}.
10621 Types can be created in several ways:
10627 fundamental types can be accessed using
10628 @pxref{d5,,gccjit;;context;;get_type()}:
10631 gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
10636 or using the @code{gccjit::context::get_int_type} template:
10639 gccjit::type t = ctxt.get_int_type <unsigned short> ();
10644 See @pxref{b,,gcc_jit_context_get_type()} for the available types.
10647 derived types can be accessed by using functions such as
10648 @pxref{117,,gccjit;;type;;get_pointer()} and @pxref{118,,gccjit;;type;;get_const()}:
10651 gccjit::type const_int_star = int_type.get_const ().get_pointer ();
10652 gccjit::type int_const_star = int_type.get_pointer ().get_const ();
10658 by creating structures (see below).
10662 * Standard types: Standard types<2>.
10663 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
10664 * Structures and unions: Structures and unions<2>.
10668 @node Standard types<2>,Pointers const and volatile<2>,,Types<2>
10669 @anchor{cp/topics/types standard-types}@anchor{119}
10670 @subsubsection Standard types
10673 @geindex gccjit;;context;;get_type (C++ function)
10674 @anchor{cp/topics/types gccjit context get_type__enum}@anchor{d5}
10675 @deffn {C++ Function} gccjit::type gccjit::context::get_type (enum gcc_jit_types)
10677 Access a specific type. This is a thin wrapper around
10678 @pxref{b,,gcc_jit_context_get_type()}; the parameter has the same meaning.
10681 @geindex gccjit;;context;;get_int_type (C++ function)
10682 @anchor{cp/topics/types gccjit context get_int_type__s i}@anchor{11a}
10683 @deffn {C++ Function} gccjit::type gccjit::context::get_int_type (size_t num_bytes, int is_signed)
10685 Access the integer type of the given size.
10688 @geindex gccjit;;context;;get_int_type<T> (C++ function)
10689 @anchor{cp/topics/types gccjit context get_int_type T}@anchor{11b}
10690 @deffn {C++ Function} gccjit::type gccjit::context::get_int_type<T> ()
10692 Access the given integer type. For example, you could map the
10693 @code{unsigned short} type into a gccjit::type via:
10696 gccjit::type t = ctxt.get_int_type <unsigned short> ();
10702 @node Pointers const and volatile<2>,Structures and unions<2>,Standard types<2>,Types<2>
10703 @anchor{cp/topics/types pointers-const-and-volatile}@anchor{11c}
10704 @subsubsection Pointers, @cite{const}, and @cite{volatile}
10707 @geindex gccjit;;type;;get_pointer (C++ function)
10708 @anchor{cp/topics/types gccjit type get_pointer}@anchor{117}
10709 @deffn {C++ Function} gccjit::type gccjit::type::get_pointer ()
10711 Given type "T", get type "T*".
10714 @c FIXME: get_const doesn't seem to exist
10716 @geindex gccjit;;type;;get_const (C++ function)
10717 @anchor{cp/topics/types gccjit type get_const}@anchor{118}
10718 @deffn {C++ Function} gccjit::type gccjit::type::get_const ()
10720 Given type "T", get type "const T".
10723 @geindex gccjit;;type;;get_volatile (C++ function)
10724 @anchor{cp/topics/types gccjit type get_volatile}@anchor{11d}
10725 @deffn {C++ Function} gccjit::type gccjit::type::get_volatile ()
10727 Given type "T", get type "volatile T".
10730 @geindex gccjit;;context;;new_array_type (C++ function)
10731 @anchor{cp/topics/types gccjit context new_array_type__gccjit type i gccjit location}@anchor{11e}
10732 @deffn {C++ Function} gccjit::type gccjit::context::new_array_type (gccjit::type element_type, int num_elements, gccjit::location loc)
10734 Given type "T", get type "T[N]" (for a constant N).
10735 Param "loc" is optional.
10738 @node Structures and unions<2>,,Pointers const and volatile<2>,Types<2>
10739 @anchor{cp/topics/types structures-and-unions}@anchor{11f}
10740 @subsubsection Structures and unions
10743 @geindex gccjit;;struct_ (C++ class)
10744 @anchor{cp/topics/types gccjit struct_}@anchor{120}
10745 @deffn {C++ Class} gccjit::struct_
10748 A compound type analagous to a C @cite{struct}.
10750 @pxref{120,,gccjit;;struct_} is a subclass of @pxref{116,,gccjit;;type} (and thus
10751 of @pxref{112,,gccjit;;object} in turn).
10753 @geindex gccjit;;field (C++ class)
10754 @anchor{cp/topics/types gccjit field}@anchor{121}
10755 @deffn {C++ Class} gccjit::field
10758 A field within a @pxref{120,,gccjit;;struct_}.
10760 @pxref{121,,gccjit;;field} is a subclass of @pxref{112,,gccjit;;object}.
10762 You can model C @cite{struct} types by creating @pxref{120,,gccjit;;struct_} and
10763 @pxref{121,,gccjit;;field} instances, in either order:
10769 by creating the fields, then the structure. For example, to model:
10772 struct coord @{double x; double y; @};
10780 gccjit::field field_x = ctxt.new_field (double_type, "x");
10781 gccjit::field field_y = ctxt.new_field (double_type, "y");
10782 std::vector fields;
10783 fields.push_back (field_x);
10784 fields.push_back (field_y);
10785 gccjit::struct_ coord = ctxt.new_struct_type ("coord", fields);
10791 by creating the structure, then populating it with fields, typically
10792 to allow modelling self-referential structs such as:
10795 struct node @{ int m_hash; struct node *m_next; @};
10803 gccjit::struct_ node = ctxt.new_opaque_struct_type ("node");
10804 gccjit::type node_ptr = node.get_pointer ();
10805 gccjit::field field_hash = ctxt.new_field (int_type, "m_hash");
10806 gccjit::field field_next = ctxt.new_field (node_ptr, "m_next");
10807 std::vector fields;
10808 fields.push_back (field_hash);
10809 fields.push_back (field_next);
10810 node.set_fields (fields);
10816 @c FIXME: the above API doesn't seem to exist yet
10818 @geindex gccjit;;context;;new_field (C++ function)
10819 @anchor{cp/topics/types gccjit context new_field__gccjit type cCP gccjit location}@anchor{122}
10820 @deffn {C++ Function} gccjit::field gccjit::context::new_field (gccjit::type type, const char* name, gccjit::location loc)
10822 Construct a new field, with the given type and name.
10825 @geindex gccjit;;context;;new_struct_type (C++ function)
10826 @anchor{cp/topics/types gccjit context new_struct_type__ssCR std vector field R gccjit location}@anchor{123}
10827 @deffn {C++ Function} gccjit::struct_ gccjit::context::new_struct_type (const std::string& name, std::vector<field>& fields, gccjit::location loc)
10831 Construct a new struct type, with the given name and fields.
10835 @geindex gccjit;;context;;new_opaque_struct (C++ function)
10836 @anchor{cp/topics/types gccjit context new_opaque_struct__ssCR gccjit location}@anchor{124}
10837 @deffn {C++ Function} gccjit::struct_ gccjit::context::new_opaque_struct (const std::string& name, gccjit::location loc)
10839 Construct a new struct type, with the given name, but without
10840 specifying the fields. The fields can be omitted (in which case the
10841 size of the struct is not known), or later specified using
10842 @pxref{79,,gcc_jit_struct_set_fields()}.
10845 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
10846 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
10848 @c This is free software: you can redistribute it and/or modify it
10849 @c under the terms of the GNU General Public License as published by
10850 @c the Free Software Foundation, either version 3 of the License, or
10851 @c (at your option) any later version.
10853 @c This program is distributed in the hope that it will be useful, but
10854 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10855 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10856 @c General Public License for more details.
10858 @c You should have received a copy of the GNU General Public License
10859 @c along with this program. If not, see
10860 @c <http://www.gnu.org/licenses/>.
10862 @node Expressions<2>,Creating and using functions<2>,Types<2>,Topic Reference<2>
10863 @anchor{cp/topics/expressions expressions}@anchor{125}@anchor{cp/topics/expressions doc}@anchor{126}
10864 @subsection Expressions
10868 * Rvalues: Rvalues<2>.
10869 * Lvalues: Lvalues<2>.
10870 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
10874 * Simple expressions: Simple expressions<2>.
10875 * Unary Operations: Unary Operations<2>.
10876 * Binary Operations: Binary Operations<2>.
10877 * Comparisons: Comparisons<2>.
10878 * Function calls: Function calls<2>.
10879 * Type-coercion: Type-coercion<2>.
10883 * Global variables: Global variables<2>.
10888 @node Rvalues<2>,Lvalues<2>,,Expressions<2>
10889 @anchor{cp/topics/expressions rvalues}@anchor{127}
10890 @subsubsection Rvalues
10893 @geindex gccjit;;rvalue (C++ class)
10894 @anchor{cp/topics/expressions gccjit rvalue}@anchor{128}
10895 @deffn {C++ Class} gccjit::rvalue
10898 A @pxref{128,,gccjit;;rvalue} is an expression that can be computed. It is a
10899 subclass of @pxref{112,,gccjit;;object}, and is a thin wrapper around
10900 @pxref{13,,gcc_jit_rvalue *} from the C API.
10902 It can be simple, e.g.:
10910 an integer value e.g. @cite{0} or @cite{42}
10913 a string literal e.g. @cite{"Hello world"}
10916 a variable e.g. @cite{i}. These are also lvalues (see below).
10928 a unary expression e.g. @cite{!cond}
10931 a binary expression e.g. @cite{(a + b)}
10934 a function call e.g. @cite{get_distance (&player_ship@comma{} &target)}
10941 Every rvalue has an associated type, and the API will check to ensure
10942 that types match up correctly (otherwise the context will emit an error).
10944 @geindex gccjit;;rvalue;;get_type (C++ function)
10945 @anchor{cp/topics/expressions gccjit rvalue get_type}@anchor{129}
10946 @deffn {C++ Function} gccjit::type gccjit::rvalue::get_type ()
10948 Get the type of this rvalue.
10952 * Simple expressions: Simple expressions<2>.
10953 * Unary Operations: Unary Operations<2>.
10954 * Binary Operations: Binary Operations<2>.
10955 * Comparisons: Comparisons<2>.
10956 * Function calls: Function calls<2>.
10957 * Type-coercion: Type-coercion<2>.
10961 @node Simple expressions<2>,Unary Operations<2>,,Rvalues<2>
10962 @anchor{cp/topics/expressions simple-expressions}@anchor{12a}
10963 @subsubsection Simple expressions
10966 @geindex gccjit;;context;;new_rvalue (C++ function)
10967 @anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type iC}@anchor{e9}
10968 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, int value) const
10970 Given a numeric type (integer or floating point), build an rvalue for
10971 the given constant @code{int} value.
10974 @geindex gccjit;;context;;new_rvalue (C++ function)
10975 @anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type lC}@anchor{12b}
10976 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, long value) const
10978 Given a numeric type (integer or floating point), build an rvalue for
10979 the given constant @code{long} value.
10982 @geindex gccjit;;context;;zero (C++ function)
10983 @anchor{cp/topics/expressions gccjit context zero__gccjit typeC}@anchor{e5}
10984 @deffn {C++ Function} gccjit::rvalue gccjit::context::zero (gccjit::type numeric_type) const
10986 Given a numeric type (integer or floating point), get the rvalue for
10987 zero. Essentially this is just a shortcut for:
10990 ctxt.new_rvalue (numeric_type, 0)
10996 @geindex gccjit;;context;;one (C++ function)
10997 @anchor{cp/topics/expressions gccjit context one__gccjit typeC}@anchor{12c}
10998 @deffn {C++ Function} gccjit::rvalue gccjit::context::one (gccjit::type numeric_type) const
11000 Given a numeric type (integer or floating point), get the rvalue for
11001 zero. Essentially this is just a shortcut for:
11004 ctxt.new_rvalue (numeric_type, 1)
11010 @geindex gccjit;;context;;new_rvalue (C++ function)
11011 @anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type doubleC}@anchor{12d}
11012 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, double value) const
11014 Given a numeric type (integer or floating point), build an rvalue for
11015 the given constant @code{double} value.
11018 @geindex gccjit;;context;;new_rvalue (C++ function)
11019 @anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type voidPC}@anchor{12e}
11020 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type pointer_type, void* value) const
11022 Given a pointer type, build an rvalue for the given address.
11025 @geindex gccjit;;context;;new_rvalue (C++ function)
11026 @anchor{cp/topics/expressions gccjit context new_rvalue__ssCRC}@anchor{12f}
11027 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (const std::string& value) const
11029 Generate an rvalue of type @code{GCC_JIT_TYPE_CONST_CHAR_PTR} for
11030 the given string. This is akin to a string literal.
11033 @node Unary Operations<2>,Binary Operations<2>,Simple expressions<2>,Rvalues<2>
11034 @anchor{cp/topics/expressions unary-operations}@anchor{130}
11035 @subsubsection Unary Operations
11038 @geindex gccjit;;context;;new_unary_op (C++ function)
11039 @anchor{cp/topics/expressions gccjit context new_unary_op__enum gccjit type gccjit rvalue gccjit location}@anchor{131}
11040 @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)
11042 Build a unary operation out of an input rvalue.
11044 Parameter @code{loc} is optional.
11046 This is a thin wrapper around the C API's
11047 @pxref{85,,gcc_jit_context_new_unary_op()} and the available unary
11048 operations are documented there.
11051 There are shorter ways to spell the various specific kinds of unary
11054 @geindex gccjit;;context;;new_minus (C++ function)
11055 @anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit location}@anchor{132}
11056 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
11058 Negate an arithmetic value; for example:
11061 gccjit::rvalue negpi = ctxt.new_minus (t_double, pi);
11066 builds the equivalent of this C expression:
11075 @geindex new_bitwise_negate (C++ function)
11076 @anchor{cp/topics/expressions new_bitwise_negate__gccjit type gccjit rvalue gccjit location}@anchor{133}
11077 @deffn {C++ Function} gccjit::rvalue new_bitwise_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
11079 Bitwise negation of an integer value (one's complement); for example:
11082 gccjit::rvalue mask = ctxt.new_bitwise_negate (t_int, a);
11087 builds the equivalent of this C expression:
11096 @geindex new_logical_negate (C++ function)
11097 @anchor{cp/topics/expressions new_logical_negate__gccjit type gccjit rvalue gccjit location}@anchor{134}
11098 @deffn {C++ Function} gccjit::rvalue new_logical_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
11100 Logical negation of an arithmetic or pointer value; for example:
11103 gccjit::rvalue guard = ctxt.new_logical_negate (t_bool, cond);
11108 builds the equivalent of this C expression:
11117 The most concise way to spell them is with overloaded operators:
11119 @geindex operator- (C++ function)
11120 @anchor{cp/topics/expressions sub-operator__gccjit rvalue}@anchor{135}
11121 @deffn {C++ Function} gccjit::rvalue operator- (gccjit::rvalue a)
11124 gccjit::rvalue negpi = -pi;
11130 @geindex operator~ (C++ function)
11131 @anchor{cp/topics/expressions inv-operator__gccjit rvalue}@anchor{136}
11132 @deffn {C++ Function} gccjit::rvalue operator~ (gccjit::rvalue a)
11135 gccjit::rvalue mask = ~a;
11141 @geindex operator! (C++ function)
11142 @anchor{cp/topics/expressions not-operator__gccjit rvalue}@anchor{137}
11143 @deffn {C++ Function} gccjit::rvalue operator! (gccjit::rvalue a)
11146 gccjit::rvalue guard = !cond;
11152 @node Binary Operations<2>,Comparisons<2>,Unary Operations<2>,Rvalues<2>
11153 @anchor{cp/topics/expressions binary-operations}@anchor{138}
11154 @subsubsection Binary Operations
11157 @geindex gccjit;;context;;new_binary_op (C++ function)
11158 @anchor{cp/topics/expressions gccjit context new_binary_op__enum gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{d9}
11159 @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)
11161 Build a binary operation out of two constituent rvalues.
11163 Parameter @code{loc} is optional.
11165 This is a thin wrapper around the C API's
11166 @pxref{12,,gcc_jit_context_new_binary_op()} and the available binary
11167 operations are documented there.
11170 There are shorter ways to spell the various specific kinds of binary
11173 @geindex gccjit;;context;;new_plus (C++ function)
11174 @anchor{cp/topics/expressions gccjit context new_plus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{139}
11175 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_plus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11178 @geindex gccjit;;context;;new_minus (C++ function)
11179 @anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{13a}
11180 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11183 @geindex gccjit;;context;;new_mult (C++ function)
11184 @anchor{cp/topics/expressions gccjit context new_mult__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{13b}
11185 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_mult (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11188 @geindex gccjit;;context;;new_divide (C++ function)
11189 @anchor{cp/topics/expressions gccjit context new_divide__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{13c}
11190 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_divide (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11193 @geindex gccjit;;context;;new_modulo (C++ function)
11194 @anchor{cp/topics/expressions gccjit context new_modulo__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{13d}
11195 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_modulo (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11198 @geindex gccjit;;context;;new_bitwise_and (C++ function)
11199 @anchor{cp/topics/expressions gccjit context new_bitwise_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{13e}
11200 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11203 @geindex gccjit;;context;;new_bitwise_xor (C++ function)
11204 @anchor{cp/topics/expressions gccjit context new_bitwise_xor__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{13f}
11205 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_xor (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11208 @geindex gccjit;;context;;new_bitwise_or (C++ function)
11209 @anchor{cp/topics/expressions gccjit context new_bitwise_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{140}
11210 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11213 @geindex gccjit;;context;;new_logical_and (C++ function)
11214 @anchor{cp/topics/expressions gccjit context new_logical_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{141}
11215 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_logical_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11218 @geindex gccjit;;context;;new_logical_or (C++ function)
11219 @anchor{cp/topics/expressions gccjit context new_logical_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{142}
11220 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_logical_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11223 The most concise way to spell them is with overloaded operators:
11225 @geindex operator+ (C++ function)
11226 @anchor{cp/topics/expressions add-operator__gccjit rvalue gccjit rvalue}@anchor{143}
11227 @deffn {C++ Function} gccjit::rvalue operator+ (gccjit::rvalue a, gccjit::rvalue b)
11230 gccjit::rvalue sum = a + b;
11236 @geindex operator- (C++ function)
11237 @anchor{cp/topics/expressions sub-operator__gccjit rvalue gccjit rvalue}@anchor{144}
11238 @deffn {C++ Function} gccjit::rvalue operator- (gccjit::rvalue a, gccjit::rvalue b)
11241 gccjit::rvalue diff = a - b;
11247 @geindex operator* (C++ function)
11248 @anchor{cp/topics/expressions mul-operator__gccjit rvalue gccjit rvalue}@anchor{145}
11249 @deffn {C++ Function} gccjit::rvalue operator* (gccjit::rvalue a, gccjit::rvalue b)
11252 gccjit::rvalue prod = a * b;
11258 @geindex operator/ (C++ function)
11259 @anchor{cp/topics/expressions div-operator__gccjit rvalue gccjit rvalue}@anchor{146}
11260 @deffn {C++ Function} gccjit::rvalue operator/ (gccjit::rvalue a, gccjit::rvalue b)
11263 gccjit::rvalue result = a / b;
11269 @geindex operator% (C++ function)
11270 @anchor{cp/topics/expressions mod-operator__gccjit rvalue gccjit rvalue}@anchor{147}
11271 @deffn {C++ Function} gccjit::rvalue operator% (gccjit::rvalue a, gccjit::rvalue b)
11274 gccjit::rvalue mod = a % b;
11280 @geindex operator& (C++ function)
11281 @anchor{cp/topics/expressions and-operator__gccjit rvalue gccjit rvalue}@anchor{148}
11282 @deffn {C++ Function} gccjit::rvalue operator& (gccjit::rvalue a, gccjit::rvalue b)
11285 gccjit::rvalue x = a & b;
11291 @geindex operator^ (C++ function)
11292 @anchor{cp/topics/expressions xor-operator__gccjit rvalue gccjit rvalue}@anchor{149}
11293 @deffn {C++ Function} gccjit::rvalue operator^ (gccjit::rvalue a, gccjit::rvalue b)
11296 gccjit::rvalue x = a ^ b;
11302 @geindex operator| (C++ function)
11303 @anchor{cp/topics/expressions or-operator__gccjit rvalue gccjit rvalue}@anchor{14a}
11304 @deffn {C++ Function} gccjit::rvalue operator| (gccjit::rvalue a, gccjit::rvalue b)
11307 gccjit::rvalue x = a | b;
11313 @geindex operator&& (C++ function)
11314 @anchor{cp/topics/expressions sand-operator__gccjit rvalue gccjit rvalue}@anchor{14b}
11315 @deffn {C++ Function} gccjit::rvalue operator&& (gccjit::rvalue a, gccjit::rvalue b)
11318 gccjit::rvalue cond = a && b;
11324 @geindex operator|| (C++ function)
11325 @anchor{cp/topics/expressions sor-operator__gccjit rvalue gccjit rvalue}@anchor{14c}
11326 @deffn {C++ Function} gccjit::rvalue operator|| (gccjit::rvalue a, gccjit::rvalue b)
11329 gccjit::rvalue cond = a || b;
11335 These can of course be combined, giving a terse way to build compound
11341 gccjit::rvalue discriminant = (b * b) - (four * a * c);
11347 @node Comparisons<2>,Function calls<2>,Binary Operations<2>,Rvalues<2>
11348 @anchor{cp/topics/expressions comparisons}@anchor{14d}
11349 @subsubsection Comparisons
11352 @geindex gccjit;;context;;new_comparison (C++ function)
11353 @anchor{cp/topics/expressions gccjit context new_comparison__enum gccjit rvalue gccjit rvalue gccjit location}@anchor{e6}
11354 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_comparison (enum gcc_jit_comparison, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11356 Build a boolean rvalue out of the comparison of two other rvalues.
11358 Parameter @code{loc} is optional.
11360 This is a thin wrapper around the C API's
11361 @pxref{2c,,gcc_jit_context_new_comparison()} and the available kinds
11362 of comparison are documented there.
11365 There are shorter ways to spell the various specific kinds of binary
11368 @geindex gccjit;;context;;new_eq (C++ function)
11369 @anchor{cp/topics/expressions gccjit context new_eq__gccjit rvalue gccjit rvalue gccjit location}@anchor{14e}
11370 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_eq (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11373 @geindex gccjit;;context;;new_ne (C++ function)
11374 @anchor{cp/topics/expressions gccjit context new_ne__gccjit rvalue gccjit rvalue gccjit location}@anchor{14f}
11375 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_ne (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11378 @geindex gccjit;;context;;new_lt (C++ function)
11379 @anchor{cp/topics/expressions gccjit context new_lt__gccjit rvalue gccjit rvalue gccjit location}@anchor{150}
11380 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_lt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11383 @geindex gccjit;;context;;new_le (C++ function)
11384 @anchor{cp/topics/expressions gccjit context new_le__gccjit rvalue gccjit rvalue gccjit location}@anchor{151}
11385 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_le (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11388 @geindex gccjit;;context;;new_gt (C++ function)
11389 @anchor{cp/topics/expressions gccjit context new_gt__gccjit rvalue gccjit rvalue gccjit location}@anchor{152}
11390 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_gt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11393 @geindex gccjit;;context;;new_ge (C++ function)
11394 @anchor{cp/topics/expressions gccjit context new_ge__gccjit rvalue gccjit rvalue gccjit location}@anchor{153}
11395 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_ge (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
11398 The most concise way to spell them is with overloaded operators:
11400 @geindex operator== (C++ function)
11401 @anchor{cp/topics/expressions eq-operator__gccjit rvalue gccjit rvalue}@anchor{154}
11402 @deffn {C++ Function} gccjit::rvalue operator== (gccjit::rvalue a, gccjit::rvalue b)
11405 gccjit::rvalue cond = (a == ctxt.zero (t_int));
11411 @geindex operator!= (C++ function)
11412 @anchor{cp/topics/expressions neq-operator__gccjit rvalue gccjit rvalue}@anchor{155}
11413 @deffn {C++ Function} gccjit::rvalue operator!= (gccjit::rvalue a, gccjit::rvalue b)
11416 gccjit::rvalue cond = (i != j);
11422 @geindex operator< (C++ function)
11423 @anchor{cp/topics/expressions lt-operator__gccjit rvalue gccjit rvalue}@anchor{156}
11424 @deffn {C++ Function} gccjit::rvalue operator< (gccjit::rvalue a, gccjit::rvalue b)
11427 gccjit::rvalue cond = i < n;
11433 @geindex operator<= (C++ function)
11434 @anchor{cp/topics/expressions lte-operator__gccjit rvalue gccjit rvalue}@anchor{157}
11435 @deffn {C++ Function} gccjit::rvalue operator<= (gccjit::rvalue a, gccjit::rvalue b)
11438 gccjit::rvalue cond = i <= n;
11444 @geindex operator> (C++ function)
11445 @anchor{cp/topics/expressions gt-operator__gccjit rvalue gccjit rvalue}@anchor{158}
11446 @deffn {C++ Function} gccjit::rvalue operator> (gccjit::rvalue a, gccjit::rvalue b)
11449 gccjit::rvalue cond = (ch > limit);
11455 @geindex operator>= (C++ function)
11456 @anchor{cp/topics/expressions gte-operator__gccjit rvalue gccjit rvalue}@anchor{159}
11457 @deffn {C++ Function} gccjit::rvalue operator>= (gccjit::rvalue a, gccjit::rvalue b)
11460 gccjit::rvalue cond = (score >= ctxt.new_rvalue (t_int, 100));
11466 @c TODO: beyond this point
11468 @node Function calls<2>,Type-coercion<2>,Comparisons<2>,Rvalues<2>
11469 @anchor{cp/topics/expressions function-calls}@anchor{15a}
11470 @subsubsection Function calls
11473 @geindex gcc_jit_context_new_call (C++ function)
11474 @anchor{cp/topics/expressions gcc_jit_context_new_call__gcc_jit_contextP gcc_jit_locationP gcc_jit_functionP i gcc_jit_rvaluePP}@anchor{15b}
11475 @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)
11477 Given a function and the given table of argument rvalues, construct a
11478 call to the function, with the result as an rvalue.
11482 @code{gccjit::context::new_call()} merely builds a
11483 @pxref{128,,gccjit;;rvalue} i.e. an expression that can be evaluated,
11484 perhaps as part of a more complicated expression.
11485 The call @emph{won't} happen unless you add a statement to a function
11486 that evaluates the expression.
11488 For example, if you want to call a function and discard the result
11489 (or to call a function with @code{void} return type), use
11490 @pxref{15c,,gccjit;;block;;add_eval()}:
11493 /* Add "(void)printf (arg0, arg1);". */
11494 block.add_eval (ctxt.new_call (printf_func, arg0, arg1));
11502 @node Type-coercion<2>,,Function calls<2>,Rvalues<2>
11503 @anchor{cp/topics/expressions type-coercion}@anchor{15d}
11504 @subsubsection Type-coercion
11507 @geindex gccjit;;context;;new_cast (C++ function)
11508 @anchor{cp/topics/expressions gccjit context new_cast__gccjit rvalue gccjit type gccjit location}@anchor{15e}
11509 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_cast (gccjit::rvalue rvalue, gccjit::type type, gccjit::location loc)
11511 Given an rvalue of T, construct another rvalue of another type.
11513 Currently only a limited set of conversions are possible:
11527 P* <-> Q*, for pointer types P and Q
11532 @node Lvalues<2>,Working with pointers structs and unions<2>,Rvalues<2>,Expressions<2>
11533 @anchor{cp/topics/expressions lvalues}@anchor{15f}
11534 @subsubsection Lvalues
11537 @geindex gccjit;;lvalue (C++ class)
11538 @anchor{cp/topics/expressions gccjit lvalue}@anchor{160}
11539 @deffn {C++ Class} gccjit::lvalue
11542 An lvalue is something that can of the @emph{left}-hand side of an assignment:
11543 a storage area (such as a variable). It is a subclass of
11544 @pxref{128,,gccjit;;rvalue}, where the rvalue is computed by reading from the
11547 It iss a thin wrapper around @pxref{24,,gcc_jit_lvalue *} from the C API.
11549 @geindex gccjit;;lvalue;;get_address (C++ function)
11550 @anchor{cp/topics/expressions gccjit lvalue get_address__gccjit location}@anchor{161}
11551 @deffn {C++ Function} gccjit::rvalue gccjit::lvalue::get_address (gccjit::location loc)
11553 Take the address of an lvalue; analogous to:
11563 Parameter "loc" is optional.
11567 * Global variables: Global variables<2>.
11571 @node Global variables<2>,,,Lvalues<2>
11572 @anchor{cp/topics/expressions global-variables}@anchor{162}
11573 @subsubsection Global variables
11576 @geindex gccjit;;context;;new_global (C++ function)
11577 @anchor{cp/topics/expressions gccjit context new_global__enum gccjit type cCP gccjit location}@anchor{163}
11578 @deffn {C++ Function} gccjit::lvalue gccjit::context::new_global (enum gcc_jit_global_kind, gccjit::type type, const char* name, gccjit::location loc)
11580 Add a new global variable of the given type and name to the context.
11582 This is a thin wrapper around @pxref{a5,,gcc_jit_context_new_global()} from
11583 the C API; the "kind" parameter has the same meaning as there.
11586 @node Working with pointers structs and unions<2>,,Lvalues<2>,Expressions<2>
11587 @anchor{cp/topics/expressions working-with-pointers-structs-and-unions}@anchor{164}
11588 @subsubsection Working with pointers, structs and unions
11591 @geindex gccjit;;rvalue;;dereference (C++ function)
11592 @anchor{cp/topics/expressions gccjit rvalue dereference__gccjit location}@anchor{165}
11593 @deffn {C++ Function} gccjit::lvalue gccjit::rvalue::dereference (gccjit::location loc)
11595 Given an rvalue of pointer type @code{T *}, dereferencing the pointer,
11596 getting an lvalue of type @code{T}. Analogous to:
11606 Parameter "loc" is optional.
11609 If you don't need to specify the location, this can also be expressed using
11610 an overloaded operator:
11613 @deffn {C++ Function} gccjit::lvalue gccjit::rvalue::operator* ();
11616 gccjit::lvalue content = *ptr;
11622 Field access is provided separately for both lvalues and rvalues:
11624 @geindex gccjit;;lvalue;;access_field (C++ function)
11625 @anchor{cp/topics/expressions gccjit lvalue access_field__gccjit field gccjit location}@anchor{166}
11626 @deffn {C++ Function} gccjit::lvalue gccjit::lvalue::access_field (gccjit::field field, gccjit::location loc)
11628 Given an lvalue of struct or union type, access the given field,
11629 getting an lvalue of the field's type. Analogous to:
11632 (EXPR).field = ...;
11640 @geindex gccjit;;rvalue;;access_field (C++ function)
11641 @anchor{cp/topics/expressions gccjit rvalue access_field__gccjit field gccjit location}@anchor{167}
11642 @deffn {C++ Function} gccjit::rvalue gccjit::rvalue::access_field (gccjit::field field, gccjit::location loc)
11644 Given an rvalue of struct or union type, access the given field
11645 as an rvalue. Analogous to:
11656 @geindex gccjit;;rvalue;;dereference_field (C++ function)
11657 @anchor{cp/topics/expressions gccjit rvalue dereference_field__gccjit field gccjit location}@anchor{168}
11658 @deffn {C++ Function} gccjit::lvalue gccjit::rvalue::dereference_field (gccjit::field field, gccjit::location loc)
11660 Given an rvalue of pointer type @code{T *} where T is of struct or union
11661 type, access the given field as an lvalue. Analogous to:
11669 in C, itself equivalent to @code{(*EXPR).FIELD}.
11672 @geindex gccjit;;context;;new_array_access (C++ function)
11673 @anchor{cp/topics/expressions gccjit context new_array_access__gccjit rvalue gccjit rvalue gccjit location}@anchor{169}
11674 @deffn {C++ Function} gccjit::lvalue gccjit::context::new_array_access (gccjit::rvalue ptr, gccjit::rvalue index, gccjit::location loc)
11676 Given an rvalue of pointer type @code{T *}, get at the element @cite{T} at
11677 the given index, using standard C array indexing rules i.e. each
11678 increment of @code{index} corresponds to @code{sizeof(T)} bytes.
11687 in C (or, indeed, to @code{PTR + INDEX}).
11689 Parameter "loc" is optional.
11692 For array accesses where you don't need to specify a @pxref{109,,gccjit;;location},
11693 two overloaded operators are available:
11697 gccjit::lvalue gccjit::rvalue::operator[] (gccjit::rvalue index)
11700 gccjit::lvalue element = array[idx];
11705 gccjit::lvalue gccjit::rvalue::operator[] (int index)
11708 gccjit::lvalue element = array[0];
11714 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
11715 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
11717 @c This is free software: you can redistribute it and/or modify it
11718 @c under the terms of the GNU General Public License as published by
11719 @c the Free Software Foundation, either version 3 of the License, or
11720 @c (at your option) any later version.
11722 @c This program is distributed in the hope that it will be useful, but
11723 @c WITHOUT ANY WARRANTY; without even the implied warranty of
11724 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11725 @c General Public License for more details.
11727 @c You should have received a copy of the GNU General Public License
11728 @c along with this program. If not, see
11729 @c <http://www.gnu.org/licenses/>.
11731 @node Creating and using functions<2>,Source Locations<2>,Expressions<2>,Topic Reference<2>
11732 @anchor{cp/topics/functions doc}@anchor{16a}@anchor{cp/topics/functions creating-and-using-functions}@anchor{16b}
11733 @subsection Creating and using functions
11737 * Params: Params<2>.
11738 * Functions: Functions<2>.
11739 * Blocks: Blocks<2>.
11740 * Statements: Statements<2>.
11744 @node Params<2>,Functions<2>,,Creating and using functions<2>
11745 @anchor{cp/topics/functions params}@anchor{16c}
11746 @subsubsection Params
11749 @geindex gccjit;;param (C++ class)
11750 @anchor{cp/topics/functions gccjit param}@anchor{16d}
11751 @deffn {C++ Class} gccjit::param
11753 A @cite{gccjit::param} represents a parameter to a function.
11756 @geindex gccjit;;context;;new_param (C++ function)
11757 @anchor{cp/topics/functions gccjit context new_param__gccjit type cCP gccjit location}@anchor{d8}
11758 @deffn {C++ Function} gccjit::param gccjit::context::new_param (gccjit::type type, const char* name, gccjit::location loc)
11760 In preparation for creating a function, create a new parameter of the
11761 given type and name.
11764 @pxref{16d,,gccjit;;param} is a subclass of @pxref{160,,gccjit;;lvalue} (and thus
11765 of @pxref{128,,gccjit;;rvalue} and @pxref{112,,gccjit;;object}). It is a thin
11766 wrapper around the C API's @pxref{25,,gcc_jit_param *}.
11768 @node Functions<2>,Blocks<2>,Params<2>,Creating and using functions<2>
11769 @anchor{cp/topics/functions functions}@anchor{16e}
11770 @subsubsection Functions
11773 @geindex gccjit;;function (C++ class)
11774 @anchor{cp/topics/functions gccjit function}@anchor{16f}
11775 @deffn {C++ Class} gccjit::function
11777 A @cite{gccjit::function} represents a function - either one that we're
11778 creating ourselves, or one that we're referencing.
11782 @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) \
11784 Create a gcc_jit_function with the given name and parameters.
11786 Parameters "is_variadic" and "loc" are optional.
11788 This is a wrapper around the C API's @pxref{11,,gcc_jit_context_new_function()}.
11791 @geindex gccjit;;context;;get_builtin_function (C++ function)
11792 @anchor{cp/topics/functions gccjit context get_builtin_function__cCP}@anchor{170}
11793 @deffn {C++ Function} gccjit::function gccjit::context::get_builtin_function (const char* name)
11795 This is a wrapper around the C API's
11796 @pxref{bc,,gcc_jit_context_get_builtin_function()}.
11799 @geindex gccjit;;function;;get_param (C++ function)
11800 @anchor{cp/topics/functions gccjit function get_param__iC}@anchor{171}
11801 @deffn {C++ Function} gccjit::param gccjit::function::get_param (int index) const
11803 Get the param of the given index (0-based).
11806 @geindex gccjit;;function;;dump_to_dot (C++ function)
11807 @anchor{cp/topics/functions gccjit function dump_to_dot__cCP}@anchor{eb}
11808 @deffn {C++ Function} void gccjit::function::dump_to_dot (const char* path)
11810 Emit the function in graphviz format to the given path.
11813 @geindex gccjit;;function;;new_local (C++ function)
11814 @anchor{cp/topics/functions gccjit function new_local__gccjit type cCP gccjit location}@anchor{e2}
11815 @deffn {C++ Function} gccjit::lvalue gccjit::function::new_local (gccjit::type type, const char* name, gccjit::location loc)
11817 Create a new local variable within the function, of the given type and
11821 @node Blocks<2>,Statements<2>,Functions<2>,Creating and using functions<2>
11822 @anchor{cp/topics/functions blocks}@anchor{172}
11823 @subsubsection Blocks
11826 @geindex gccjit;;block (C++ class)
11827 @anchor{cp/topics/functions gccjit block}@anchor{173}
11828 @deffn {C++ Class} gccjit::block
11830 A @cite{gccjit::block} represents a basic block within a function i.e. a
11831 sequence of statements with a single entry point and a single exit
11834 @pxref{173,,gccjit;;block} is a subclass of @pxref{112,,gccjit;;object}.
11836 The first basic block that you create within a function will
11839 Each basic block that you create within a function must be
11840 terminated, either with a conditional, a jump, or a return.
11842 It's legal to have multiple basic blocks that return within
11846 @geindex gccjit;;function;;new_block (C++ function)
11847 @anchor{cp/topics/functions gccjit function new_block__cCP}@anchor{174}
11848 @deffn {C++ Function} gccjit::block gccjit::function::new_block (const char* name)
11850 Create a basic block of the given name. The name may be NULL, but
11851 providing meaningful names is often helpful when debugging: it may
11852 show up in dumps of the internal representation, and in error
11856 @node Statements<2>,,Blocks<2>,Creating and using functions<2>
11857 @anchor{cp/topics/functions statements}@anchor{175}
11858 @subsubsection Statements
11861 @geindex gccjit;;block;;add_eval (C++ function)
11862 @anchor{cp/topics/functions gccjit block add_eval__gccjit rvalue gccjit location}@anchor{15c}
11863 @deffn {C++ Function} void gccjit::block::add_eval (gccjit::rvalue rvalue, gccjit::location loc)
11865 Add evaluation of an rvalue, discarding the result
11866 (e.g. a function call that "returns" void).
11868 This is equivalent to this C code:
11877 @geindex gccjit;;block;;add_assignment (C++ function)
11878 @anchor{cp/topics/functions gccjit block add_assignment__gccjit lvalue gccjit rvalue gccjit location}@anchor{e4}
11879 @deffn {C++ Function} void gccjit::block::add_assignment (gccjit::lvalue lvalue, gccjit::rvalue rvalue, gccjit::location loc)
11881 Add evaluation of an rvalue, assigning the result to the given
11884 This is roughly equivalent to this C code:
11893 @geindex gccjit;;block;;add_assignment_op (C++ function)
11894 @anchor{cp/topics/functions gccjit block add_assignment_op__gccjit lvalue enum gccjit rvalue gccjit location}@anchor{e8}
11895 @deffn {C++ Function} void gccjit::block::add_assignment_op (gccjit::lvalue lvalue, enum gcc_jit_binary_op, gccjit::rvalue rvalue, gccjit::location loc)
11897 Add evaluation of an rvalue, using the result to modify an
11900 This is analogous to "+=" and friends:
11914 loop_body.add_assignment_op (
11916 GCC_JIT_BINARY_OP_PLUS,
11917 ctxt.one (int_type));
11923 @geindex gccjit;;block;;add_comment (C++ function)
11924 @anchor{cp/topics/functions gccjit block add_comment__cCP gccjit location}@anchor{f3}
11925 @deffn {C++ Function} void gccjit::block::add_comment (const char* text, gccjit::location loc)
11927 Add a no-op textual comment to the internal representation of the
11928 code. It will be optimized away, but will be visible in the dumps
11929 seen via @pxref{5f,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}
11930 and @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE},
11931 and thus may be of use when debugging how your project's internal
11932 representation gets converted to the libgccjit IR.
11934 Parameter "loc" is optional.
11937 @geindex gccjit;;block;;end_with_conditional (C++ function)
11938 @anchor{cp/topics/functions gccjit block end_with_conditional__gccjit rvalue gccjit block gccjit block gccjit location}@anchor{e7}
11939 @deffn {C++ Function} void gccjit::block::end_with_conditional (gccjit::rvalue boolval, gccjit::block on_true, gccjit::block on_false, gccjit::location loc)
11941 Terminate a block by adding evaluation of an rvalue, branching on the
11942 result to the appropriate successor block.
11944 This is roughly equivalent to this C code:
11955 block, boolval, on_true, and on_false must be non-NULL.
11958 @geindex gccjit;;block;;end_with_jump (C++ function)
11959 @anchor{cp/topics/functions gccjit block end_with_jump__gccjit block gccjit location}@anchor{176}
11960 @deffn {C++ Function} void gccjit::block::end_with_jump (gccjit::block target, gccjit::location loc)
11962 Terminate a block by adding a jump to the given target block.
11964 This is roughly equivalent to this C code:
11973 @geindex gccjit;;block;;end_with_return (C++ function)
11974 @anchor{cp/topics/functions gccjit block end_with_return__gccjit rvalue gccjit location}@anchor{177}
11975 @deffn {C++ Function} void gccjit::block::end_with_return (gccjit::rvalue rvalue, gccjit::location loc)
11979 Both params are optional.
11981 An rvalue must be provided for a function returning non-void, and
11982 must not be provided by a function "returning" @cite{void}.
11984 If an rvalue is provided, the block is terminated by evaluating the
11985 rvalue and returning the value.
11987 This is roughly equivalent to this C code:
11995 If an rvalue is not provided, the block is terminated by adding a
11996 valueless return, for use within a function with "void" return type.
11998 This is equivalent to this C code:
12007 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
12008 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
12010 @c This is free software: you can redistribute it and/or modify it
12011 @c under the terms of the GNU General Public License as published by
12012 @c the Free Software Foundation, either version 3 of the License, or
12013 @c (at your option) any later version.
12015 @c This program is distributed in the hope that it will be useful, but
12016 @c WITHOUT ANY WARRANTY; without even the implied warranty of
12017 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12018 @c General Public License for more details.
12020 @c You should have received a copy of the GNU General Public License
12021 @c along with this program. If not, see
12022 @c <http://www.gnu.org/licenses/>.
12024 @node Source Locations<2>,Compilation results<2>,Creating and using functions<2>,Topic Reference<2>
12025 @anchor{cp/topics/locations source-locations}@anchor{178}@anchor{cp/topics/locations doc}@anchor{179}
12026 @subsection Source Locations
12029 @geindex gccjit;;location (C++ class)
12030 @anchor{cp/topics/locations gccjit location}@anchor{109}
12031 @deffn {C++ Class} gccjit::location
12033 A @cite{gccjit::location} encapsulates a source code location, so that
12034 you can (optionally) associate locations in your language with
12035 statements in the JIT-compiled code, allowing the debugger to
12036 single-step through your language.
12038 @cite{gccjit::location} instances are optional: you can always omit them
12039 from any C++ API entrypoint accepting one.
12041 You can construct them using @pxref{f7,,gccjit;;context;;new_location()}.
12043 You need to enable @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
12044 @pxref{101,,gccjit;;context} for these locations to actually be usable by
12048 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1);
12054 @geindex gccjit;;context;;new_location (C++ function)
12055 @anchor{cp/topics/locations gccjit context new_location__cCP i i}@anchor{f7}
12056 @deffn {C++ Function} gccjit::location gccjit::context::new_location (const char* filename, int line, int column)
12058 Create a @cite{gccjit::location} instance representing the given source
12063 * Faking it: Faking it<2>.
12067 @node Faking it<2>,,,Source Locations<2>
12068 @anchor{cp/topics/locations faking-it}@anchor{17a}
12069 @subsubsection Faking it
12072 If you don't have source code for your internal representation, but need
12073 to debug, you can generate a C-like representation of the functions in
12074 your context using @pxref{108,,gccjit;;context;;dump_to_file()}:
12077 ctxt.dump_to_file ("/tmp/something.c",
12078 1 /* update_locations */);
12083 This will dump C-like code to the given path. If the @cite{update_locations}
12084 argument is true, this will also set up @cite{gccjit::location} information
12085 throughout the context, pointing at the dump file as if it were a source
12086 file, giving you @emph{something} you can step through in the debugger.
12088 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
12089 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
12091 @c This is free software: you can redistribute it and/or modify it
12092 @c under the terms of the GNU General Public License as published by
12093 @c the Free Software Foundation, either version 3 of the License, or
12094 @c (at your option) any later version.
12096 @c This program is distributed in the hope that it will be useful, but
12097 @c WITHOUT ANY WARRANTY; without even the implied warranty of
12098 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12099 @c General Public License for more details.
12101 @c You should have received a copy of the GNU General Public License
12102 @c along with this program. If not, see
12103 @c <http://www.gnu.org/licenses/>.
12105 @node Compilation results<2>,,Source Locations<2>,Topic Reference<2>
12106 @anchor{cp/topics/results compilation-results}@anchor{17b}@anchor{cp/topics/results doc}@anchor{17c}
12107 @subsection Compilation results
12110 @geindex gcc_jit_result (C++ type)
12111 @anchor{cp/topics/results gcc_jit_result}@anchor{17d}
12112 @deffn {C++ Type} gcc_jit_result
12114 A @cite{gcc_jit_result} encapsulates the result of compiling a context.
12117 @geindex gccjit;;context;;compile (C++ function)
12118 @anchor{cp/topics/results gccjit context compile}@anchor{da}
12119 @deffn {C++ Function} @pxref{17d,,gcc_jit_result*} gccjit::context::compile ()
12121 This calls into GCC and builds the code, returning a
12122 @cite{gcc_jit_result *}.
12125 @geindex gcc_jit_result_get_code (C++ function)
12126 @anchor{cp/topics/results gcc_jit_result_get_code__gcc_jit_resultP cCP}@anchor{17e}
12127 @deffn {C++ Function} void* gcc_jit_result_get_code (gcc_jit_result* result, const char* funcname)
12129 Locate a given function within the built machine code.
12130 This will need to be cast to a function pointer of the
12131 correct type before it can be called.
12134 @geindex gcc_jit_result_release (C++ function)
12135 @anchor{cp/topics/results gcc_jit_result_release__gcc_jit_resultP}@anchor{17f}
12136 @deffn {C++ Function} void gcc_jit_result_release (gcc_jit_result* result)
12138 Once we're done with the code, this unloads the built .so file.
12139 This cleans up the result; after calling this, it's no longer
12140 valid to use the result.
12143 @c Copyright (C) 2014-2015 Free Software Foundation, Inc.
12144 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
12146 @c This is free software: you can redistribute it and/or modify it
12147 @c under the terms of the GNU General Public License as published by
12148 @c the Free Software Foundation, either version 3 of the License, or
12149 @c (at your option) any later version.
12151 @c This program is distributed in the hope that it will be useful, but
12152 @c WITHOUT ANY WARRANTY; without even the implied warranty of
12153 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12154 @c General Public License for more details.
12156 @c You should have received a copy of the GNU General Public License
12157 @c along with this program. If not, see
12158 @c <http://www.gnu.org/licenses/>.
12160 @node Internals,Indices and tables,C++ bindings for libgccjit,Top
12161 @anchor{internals/index internals}@anchor{180}@anchor{internals/index doc}@anchor{181}
12166 * Working on the JIT library::
12167 * Running the test suite::
12168 * Environment variables::
12169 * Overview of code structure::
12174 @node Working on the JIT library,Running the test suite,,Internals
12175 @anchor{internals/index working-on-the-jit-library}@anchor{182}
12176 @section Working on the JIT library
12179 Having checked out the source code (to "src"), you can configure and build
12180 the JIT library like this:
12185 PREFIX=$(pwd)/install
12188 --enable-host-shared \
12189 --enable-languages=jit,c++ \
12190 --disable-bootstrap \
12191 --enable-checking=release \
12193 nice make -j4 # altering the "4" to however many cores you have
12198 This should build a libgccjit.so within jit/build/gcc:
12201 [build] $ file gcc/libgccjit.so*
12202 gcc/libgccjit.so: symbolic link to `libgccjit.so.0'
12203 gcc/libgccjit.so.0: symbolic link to `libgccjit.so.0.0.1'
12204 gcc/libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, not stripped
12209 Here's what those configuration options mean:
12211 @geindex command line option; --enable-host-shared
12212 @anchor{internals/index cmdoption--enable-host-shared}@anchor{183}
12213 @deffn {Option} --enable-host-shared
12215 Configuring with this option means that the compiler is built as
12216 position-independent code, which incurs a slight performance hit,
12217 but it necessary for a shared library.
12220 @geindex command line option; --enable-languages=jit@comma{}c++
12221 @anchor{internals/index cmdoption--enable-languages}@anchor{184}
12222 @deffn {Option} --enable-languages=jit,c++
12224 This specifies which frontends to build. The JIT library looks like
12225 a frontend to the rest of the code.
12227 The C++ portion of the JIT test suite requires the C++ frontend to be
12228 enabled at configure-time, or you may see errors like this when
12229 running the test suite:
12232 xgcc: error: /home/david/jit/src/gcc/testsuite/jit.dg/test-quadratic.cc: C++ compiler not installed on this system
12233 c++: error trying to exec 'cc1plus': execvp: No such file or directory
12239 @geindex command line option; --disable-bootstrap
12240 @anchor{internals/index cmdoption--disable-bootstrap}@anchor{185}
12241 @deffn {Option} --disable-bootstrap
12243 For hacking on the "jit" subdirectory, performing a full
12244 bootstrap can be overkill, since it's unused by a bootstrap. However,
12245 when submitting patches, you should remove this option, to ensure that
12246 the compiler can still bootstrap itself.
12249 @geindex command line option; --enable-checking=release
12250 @anchor{internals/index cmdoption--enable-checking}@anchor{186}
12251 @deffn {Option} --enable-checking=release
12253 The compile can perform extensive self-checking as it runs, useful when
12254 debugging, but slowing things down.
12256 For maximum speed, configure with @code{--enable-checking=release} to
12257 disable this self-checking.
12260 @node Running the test suite,Environment variables,Working on the JIT library,Internals
12261 @anchor{internals/index running-the-test-suite}@anchor{187}
12262 @section Running the test suite
12267 [gcc] $ make check-jit RUNTESTFLAGS="-v -v -v"
12272 A summary of the tests can then be seen in:
12275 jit/build/gcc/testsuite/jit/jit.sum
12280 and detailed logs in:
12283 jit/build/gcc/testsuite/jit/jit.log
12288 The test executables can be seen as:
12291 jit/build/gcc/testsuite/jit/*.exe
12296 which can be run independently.
12298 You can compile and run individual tests by passing "jit.exp=TESTNAME" to RUNTESTFLAGS e.g.:
12301 [gcc] $ make check-jit RUNTESTFLAGS="-v -v -v jit.exp=test-factorial.c"
12306 and once a test has been compiled, you can debug it directly:
12309 [gcc] $ PATH=.:$PATH \
12310 LD_LIBRARY_PATH=. \
12313 testsuite/jit/test-factorial.c.exe
12319 * Running under valgrind::
12323 @node Running under valgrind,,,Running the test suite
12324 @anchor{internals/index running-under-valgrind}@anchor{188}
12325 @subsection Running under valgrind
12328 The jit testsuite detects if RUN_UNDER_VALGRIND is present in the
12329 environment (with any value). If it is present, it runs the test client
12330 code under valgrind@footnote{http://valgrind.org},
12331 specifcally, the default
12332 memcheck@footnote{http://valgrind.org/docs/manual/mc-manual.html}
12334 --leak-check=full@footnote{http://valgrind.org/docs/manual/mc-manual.html#opt.leak-check}.
12336 It automatically parses the output from valgrind, injecting XFAIL results if
12337 any issues are found, or PASS results if the output is clean. The output
12338 is saved to @code{TESTNAME.exe.valgrind.txt}.
12340 For example, the following invocation verbosely runs the testcase
12341 @code{test-sum-of-squares.c} under valgrind, showing an issue:
12344 $ RUN_UNDER_VALGRIND= \
12346 RUNTESTFLAGS="-v -v -v jit.exp=test-sum-of-squares.c"
12348 (...verbose log contains detailed valgrind errors, if any...)
12350 === jit Summary ===
12352 # of expected passes 28
12353 # of expected failures 2
12355 $ less testsuite/jit/jit.sum
12356 (...other results...)
12357 XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.c.exe.valgrind.txt: definitely lost: 8 bytes in 1 blocks
12358 XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.c.exe.valgrind.txt: unsuppressed errors: 1
12359 (...other results...)
12361 $ less testsuite/jit/test-sum-of-squares.c.exe.valgrind.txt
12362 (...shows full valgrind report for this test case...)
12367 When running under valgrind, it's best to have configured gcc with
12368 @code{--enable-valgrind-annotations}, which automatically suppresses
12369 various known false positives.
12371 @node Environment variables,Overview of code structure,Running the test suite,Internals
12372 @anchor{internals/index environment-variables}@anchor{189}
12373 @section Environment variables
12376 When running client code against a locally-built libgccjit, three
12377 environment variables need to be set up:
12379 @geindex environment variable; LD_LIBRARY_PATH
12380 @anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{18a}
12381 @deffn {Environment Variable} LD_LIBRARY_PATH
12385 @cite{libgccjit.so} is dynamically linked into client code, so if running
12386 against a locally-built library, @code{LD_LIBRARY_PATH} needs to be set
12387 up appropriately. The library can be found within the "gcc"
12388 subdirectory of the build tree:
12392 $ file libgccjit.so*
12393 libgccjit.so: symbolic link to `libgccjit.so.0'
12394 libgccjit.so.0: symbolic link to `libgccjit.so.0.0.1'
12395 libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (GNU/Linux), dynamically linked, not stripped
12401 @geindex environment variable; PATH
12402 @anchor{internals/index envvar-PATH}@anchor{18b}
12403 @deffn {Environment Variable} PATH
12405 The library uses a driver executable for converting from .s assembler
12406 files to .so shared libraries. Specifically, it looks for a name
12408 @code{$@{target_noncanonical@}-gcc-$@{gcc_BASEVER@}$@{exeext@}}
12409 such as @code{x86_64-unknown-linux-gnu-gcc-5.0.0}.
12411 Hence @code{PATH} needs to include a directory where the library can
12412 locate this executable.
12414 The executable is normally installed to the installation bindir
12415 (e.g. /usr/bin), but a copy is also created within the "gcc"
12416 subdirectory of the build tree for running the testsuite, and for ease
12420 @geindex environment variable; LIBRARY_PATH
12421 @anchor{internals/index envvar-LIBRARY_PATH}@anchor{18c}
12422 @deffn {Environment Variable} LIBRARY_PATH
12424 The driver executable invokes the linker, and the latter needs to locate
12425 support libraries needed by the generated code, or you will see errors
12429 ld: cannot find crtbeginS.o: No such file or directory
12430 ld: cannot find -lgcc
12431 ld: cannot find -lgcc_s
12436 Hence if running directly from a locally-built copy (without installing),
12437 @code{LIBRARY_PATH} needs to contain the "gcc" subdirectory of the build
12441 For example, to run a binary that uses the library against a non-installed
12442 build of the library in LIBGCCJIT_BUILD_DIR you need an invocation of the
12443 client code like this, to preprend the dir to each of the environment
12447 $ LD_LIBRARY_PATH=$(LIBGCCJIT_BUILD_DIR):$(LD_LIBRARY_PATH) \
12448 PATH=$(LIBGCCJIT_BUILD_DIR):$(PATH) \
12449 LIBRARY_PATH=$(LIBGCCJIT_BUILD_DIR):$(LIBRARY_PATH) \
12456 @node Overview of code structure,Design notes,Environment variables,Internals
12457 @anchor{internals/index overview-of-code-structure}@anchor{18d}
12458 @section Overview of code structure
12465 @code{libgccjit.c} implements the API entrypoints. It performs error
12466 checking, then calls into classes of the gcc::jit::recording namespace
12467 within @code{jit-recording.c} and @code{jit-recording.h}.
12470 The gcc::jit::recording classes (within @code{jit-recording.c} and
12471 @code{jit-recording.h}) record the API calls that are made:
12477 /* Indentation indicates inheritance: */
12483 class function_type;
12484 class compound_type;
12505 When the context is compiled, the gcc::jit::playback classes (within
12506 @code{jit-playback.c} and @code{jit-playback.h}) replay the API calls
12507 within langhook:parse_file:
12513 /* Indentation indicates inheritance: */
12517 class compound_type;
12534 Client Code . Generated . libgccjit.so
12536 . . JIT API . JIT "Frontend". (libbackend.a)
12537 ....................................................................................
12539 ──────────────────────────> . .
12542 . . ──> libgccjit.c .
12543 . . │ (error-checking).
12545 . . ──> jit-recording.c
12546 . . (record API calls)
12547 . . <─────── .
12549 <─────────────────────────── . .
12552 V . . gcc_jit_context_compile .
12553 ──────────────────────────> . .
12554 . . │ start of recording::context::compile ()
12556 . . │ start of playback::context::compile ()
12557 . . │ (create tempdir) .
12559 . . │ ACQUIRE MUTEX .
12561 . . V───────────────────────> toplev::main (for now)
12563 . . . . (various code)
12566 . . . <───────────────── langhook:parse_file
12568 . . . │ (jit_langhook_parse_file)
12570 ..........................................│..................VVVVVVVVVVVVV...
12571 . . . │ . No GC in here
12572 . . . │ jit-playback.c
12573 . . . │ (playback of API calls)
12574 . . . ───────────────> creation of functions,
12575 . . . . types, expression trees
12576 . . . <──────────────── etc
12577 . . . │(handle_locations: add locations to
12578 . . . │ linemap and associate them with trees)
12580 . . . │ . No GC in here
12581 ..........................................│..................AAAAAAAAAAAAA...
12582 . . . │ for each function
12583 . . . ──> postprocess
12585 . . . ────────────> cgraph_finalize_function
12586 . . . <────────────
12589 . . . ──────────────────> (end of
12590 . . . . │ langhook_parse_file)
12592 . . . . (various code)
12595 . . . <───────────────── langhook:write_globals
12597 . . . │ (jit_langhook_write_globals)
12600 . . . ──────────────────> finalize_compilation_unit
12602 . . . . (the middle─end and backend)
12604 . . <───────────────────────────── end of toplev::main
12606 . . V───────────────────────> toplev::finalize
12607 . . . . │ (purge internal state)
12608 . . <──────────────────────── end of toplev::finalize
12610 . . │ Convert assembler to DSO ("fake.so")
12612 . . │ Load DSO (dlopen "fake.so")
12614 . . │ RELEASE MUTEX .
12616 . . │ end of playback::context::compile ()
12618 . . │ playback::context dtor
12620 . . │ Normally we cleanup the tempdir here:
12621 . . │ ("fake.so" is unlinked from the
12622 . . │ filesystem at this point)
12623 . . │ If the client code requested debuginfo, the
12624 . . │ cleanup happens later (in gcc_jit_result_release)
12625 . . │ to make it easier on the debugger (see PR jit/64206)
12628 . . │ end of recording::context::compile ()
12629 <─────────────────────────── . .
12631 V . . gcc_jit_result_get_code .
12632 ──────────────────────────> . .
12633 . . │ dlsym () within loaded DSO
12634 <─────────────────────────── . .
12637 │ Call it . . . .
12638 ───────────────> . . .
12641 <─────────────── . . .
12645 V . . gcc_jit_result_release .
12646 ──────────────────────────> . .
12647 . . │ dlclose () the loaded DSO
12648 . . │ (code becomes uncallable)
12650 . . │ If the client code requested debuginfo, then
12651 . . │ cleanup of the tempdir was delayed.
12652 . . │ If that was the case, clean it up now.
12653 <─────────────────────────── . .
12662 Here is a high-level summary from @code{jit-common.h}:
12666 In order to allow jit objects to be usable outside of a compile
12667 whilst working with the existing structure of GCC's code the
12668 C API is implemented in terms of a gcc::jit::recording::context,
12669 which records the calls made to it.
12671 When a gcc_jit_context is compiled, the recording context creates a
12672 playback context. The playback context invokes the bulk of the GCC
12673 code, and within the "frontend" parsing hook, plays back the recorded
12674 API calls, creating GCC tree objects.
12676 So there are two parallel families of classes: those relating to
12677 recording, and those relating to playback:
12683 Visibility: recording objects are exposed back to client code,
12684 whereas playback objects are internal to the library.
12687 Lifetime: recording objects have a lifetime equal to that of the
12688 recording context that created them, whereas playback objects only
12689 exist within the frontend hook.
12692 Memory allocation: recording objects are allocated by the recording
12693 context, and automatically freed by it when the context is released,
12694 whereas playback objects are allocated within the GC heap, and
12695 garbage-collected; they can own GC-references.
12698 Integration with rest of GCC: recording objects are unrelated to the
12699 rest of GCC, whereas playback objects are wrappers around "tree"
12700 instances. Hence you can't ask a recording rvalue or lvalue what its
12701 type is, whereas you can for a playback rvalue of lvalue (since it
12702 can work with the underlying GCC tree nodes).
12705 Instancing: There can be multiple recording contexts "alive" at once
12706 (albeit it only one compiling at once), whereas there can only be one
12707 playback context alive at one time (since it interacts with the GC).
12710 Ultimately if GCC could support multiple GC heaps and contexts, and
12711 finer-grained initialization, then this recording vs playback
12712 distinction could be eliminated.
12714 During a playback, we associate objects from the recording with
12715 their counterparts during this playback. For simplicity, we store this
12716 within the recording objects, as @code{void *m_playback_obj}, casting it to
12717 the appropriate playback object subclass. For these casts to make
12718 sense, the two class hierarchies need to have the same structure.
12720 Note that the playback objects that @code{m_playback_obj} points to are
12721 GC-allocated, but the recording objects don't own references:
12722 these associations only exist within a part of the code where
12723 the GC doesn't collect, and are set back to NULL before the GC can
12726 @anchor{internals/index example-of-log-file}@anchor{55}
12727 Another way to understand the structure of the code is to enable logging,
12728 via @pxref{54,,gcc_jit_context_set_logfile()}. Here is an example of a log
12729 generated via this call:
12732 JIT: entering: gcc_jit_context_set_str_option
12733 JIT: exiting: gcc_jit_context_set_str_option
12734 JIT: entering: gcc_jit_context_set_int_option
12735 JIT: exiting: gcc_jit_context_set_int_option
12736 JIT: entering: gcc_jit_context_set_bool_option
12737 JIT: exiting: gcc_jit_context_set_bool_option
12738 JIT: entering: gcc_jit_context_set_bool_option
12739 JIT: exiting: gcc_jit_context_set_bool_option
12740 JIT: entering: gcc_jit_context_set_bool_option
12741 JIT: exiting: gcc_jit_context_set_bool_option
12742 JIT: entering: gcc_jit_context_set_bool_option
12743 JIT: exiting: gcc_jit_context_set_bool_option
12744 JIT: entering: gcc_jit_context_set_bool_option
12745 JIT: exiting: gcc_jit_context_set_bool_option
12746 JIT: entering: gcc_jit_context_get_type
12747 JIT: exiting: gcc_jit_context_get_type
12748 JIT: entering: gcc_jit_context_get_type
12749 JIT: exiting: gcc_jit_context_get_type
12750 JIT: entering: gcc_jit_context_new_param
12751 JIT: exiting: gcc_jit_context_new_param
12752 JIT: entering: gcc_jit_context_new_function
12753 JIT: exiting: gcc_jit_context_new_function
12754 JIT: entering: gcc_jit_context_new_param
12755 JIT: exiting: gcc_jit_context_new_param
12756 JIT: entering: gcc_jit_context_get_type
12757 JIT: exiting: gcc_jit_context_get_type
12758 JIT: entering: gcc_jit_context_new_function
12759 JIT: exiting: gcc_jit_context_new_function
12760 JIT: entering: gcc_jit_context_new_string_literal
12761 JIT: exiting: gcc_jit_context_new_string_literal
12762 JIT: entering: gcc_jit_function_new_block
12763 JIT: exiting: gcc_jit_function_new_block
12764 JIT: entering: gcc_jit_block_add_comment
12765 JIT: exiting: gcc_jit_block_add_comment
12766 JIT: entering: gcc_jit_context_new_call
12767 JIT: exiting: gcc_jit_context_new_call
12768 JIT: entering: gcc_jit_block_add_eval
12769 JIT: exiting: gcc_jit_block_add_eval
12770 JIT: entering: gcc_jit_block_end_with_void_return
12771 JIT: exiting: gcc_jit_block_end_with_void_return
12772 JIT: entering: gcc_jit_context_compile
12773 JIT: compiling ctxt: 0x1283e20
12774 JIT: entering: gcc::jit::result* gcc::jit::recording::context::compile()
12775 JIT: entering: void gcc::jit::recording::context::validate()
12776 JIT: exiting: void gcc::jit::recording::context::validate()
12777 JIT: entering: gcc::jit::playback::context::context(gcc::jit::recording::context*)
12778 JIT: exiting: gcc::jit::playback::context::context(gcc::jit::recording::context*)
12779 JIT: entering: gcc::jit::result* gcc::jit::playback::context::compile()
12780 JIT: entering: gcc::jit::tempdir::tempdir(gcc::jit::logger*, int)
12781 JIT: exiting: gcc::jit::tempdir::tempdir(gcc::jit::logger*, int)
12782 JIT: entering: bool gcc::jit::tempdir::create()
12783 JIT: m_path_template: /tmp/libgccjit-XXXXXX
12784 JIT: m_path_tempdir: /tmp/libgccjit-CKq1M9
12785 JIT: exiting: bool gcc::jit::tempdir::create()
12786 JIT: entering: void gcc::jit::playback::context::make_fake_args(vec<char*>*, const char*, vec<gcc::jit::recording::requested_dump>*)
12787 JIT: exiting: void gcc::jit::playback::context::make_fake_args(vec<char*>*, const char*, vec<gcc::jit::recording::requested_dump>*)
12788 JIT: entering: void gcc::jit::playback::context::acquire_mutex()
12789 JIT: exiting: void gcc::jit::playback::context::acquire_mutex()
12790 JIT: entering: toplev::main
12791 JIT: argv[0]: ./test-hello-world.c.exe
12792 JIT: argv[1]: /tmp/libgccjit-CKq1M9/fake.c
12793 JIT: argv[2]: -fPIC
12796 JIT: argv[5]: -quiet
12797 JIT: argv[6]: --param
12798 JIT: argv[7]: ggc-min-expand=0
12799 JIT: argv[8]: --param
12800 JIT: argv[9]: ggc-min-heapsize=0
12801 JIT: entering: bool jit_langhook_init()
12802 JIT: exiting: bool jit_langhook_init()
12803 JIT: entering: void gcc::jit::playback::context::replay()
12804 JIT: entering: void gcc::jit::recording::context::replay_into(gcc::jit::replayer*)
12805 JIT: exiting: void gcc::jit::recording::context::replay_into(gcc::jit::replayer*)
12806 JIT: entering: void gcc::jit::recording::context::disassociate_from_playback()
12807 JIT: exiting: void gcc::jit::recording::context::disassociate_from_playback()
12808 JIT: entering: void gcc::jit::playback::context::handle_locations()
12809 JIT: exiting: void gcc::jit::playback::context::handle_locations()
12810 JIT: entering: void gcc::jit::playback::function::build_stmt_list()
12811 JIT: exiting: void gcc::jit::playback::function::build_stmt_list()
12812 JIT: entering: void gcc::jit::playback::function::build_stmt_list()
12813 JIT: exiting: void gcc::jit::playback::function::build_stmt_list()
12814 JIT: entering: void gcc::jit::playback::function::postprocess()
12815 JIT: exiting: void gcc::jit::playback::function::postprocess()
12816 JIT: entering: void gcc::jit::playback::function::postprocess()
12817 JIT: exiting: void gcc::jit::playback::function::postprocess()
12818 JIT: exiting: void gcc::jit::playback::context::replay()
12819 JIT: entering: void jit_langhook_write_globals()
12820 JIT: exiting: void jit_langhook_write_globals()
12821 JIT: exiting: toplev::main
12822 JIT: entering: void gcc::jit::playback::context::extract_any_requested_dumps(vec<gcc::jit::recording::requested_dump>*)
12823 JIT: exiting: void gcc::jit::playback::context::extract_any_requested_dumps(vec<gcc::jit::recording::requested_dump>*)
12824 JIT: entering: toplev::finalize
12825 JIT: exiting: toplev::finalize
12826 JIT: entering: void gcc::jit::playback::context::convert_to_dso(const char*)
12827 JIT: argv[0]: x86_64-unknown-linux-gnu-gcc-5.0.0
12828 JIT: argv[1]: -shared
12829 JIT: argv[2]: /tmp/libgccjit-CKq1M9/fake.s
12831 JIT: argv[4]: /tmp/libgccjit-CKq1M9/fake.so
12832 JIT: argv[5]: -fno-use-linker-plugin
12833 JIT: argv[6]: (null)
12834 JIT: exiting: void gcc::jit::playback::context::convert_to_dso(const char*)
12835 JIT: entering: gcc::jit::result* gcc::jit::playback::context::dlopen_built_dso()
12836 JIT: GCC_JIT_BOOL_OPTION_DEBUGINFO was set: handing over tempdir to jit::result
12837 JIT: entering: gcc::jit::result::result(gcc::jit::logger*, void*, gcc::jit::tempdir*)
12838 JIT: exiting: gcc::jit::result::result(gcc::jit::logger*, void*, gcc::jit::tempdir*)
12839 JIT: exiting: gcc::jit::result* gcc::jit::playback::context::dlopen_built_dso()
12840 JIT: entering: void gcc::jit::playback::context::release_mutex()
12841 JIT: exiting: void gcc::jit::playback::context::release_mutex()
12842 JIT: exiting: gcc::jit::result* gcc::jit::playback::context::compile()
12843 JIT: entering: gcc::jit::playback::context::~context()
12844 JIT: exiting: gcc::jit::playback::context::~context()
12845 JIT: exiting: gcc::jit::result* gcc::jit::recording::context::compile()
12846 JIT: gcc_jit_context_compile: returning (gcc_jit_result *)0x12f75d0
12847 JIT: exiting: gcc_jit_context_compile
12848 JIT: entering: gcc_jit_result_get_code
12849 JIT: locating fnname: hello_world
12850 JIT: entering: void* gcc::jit::result::get_code(const char*)
12851 JIT: exiting: void* gcc::jit::result::get_code(const char*)
12852 JIT: gcc_jit_result_get_code: returning (void *)0x7ff6b8cd87f0
12853 JIT: exiting: gcc_jit_result_get_code
12854 JIT: entering: gcc_jit_context_release
12855 JIT: deleting ctxt: 0x1283e20
12856 JIT: entering: gcc::jit::recording::context::~context()
12857 JIT: exiting: gcc::jit::recording::context::~context()
12858 JIT: exiting: gcc_jit_context_release
12859 JIT: entering: gcc_jit_result_release
12860 JIT: deleting result: 0x12f75d0
12861 JIT: entering: virtual gcc::jit::result::~result()
12862 JIT: entering: gcc::jit::tempdir::~tempdir()
12863 JIT: unlinking .s file: /tmp/libgccjit-CKq1M9/fake.s
12864 JIT: unlinking .so file: /tmp/libgccjit-CKq1M9/fake.so
12865 JIT: removing tempdir: /tmp/libgccjit-CKq1M9
12866 JIT: exiting: gcc::jit::tempdir::~tempdir()
12867 JIT: exiting: virtual gcc::jit::result::~result()
12868 JIT: exiting: gcc_jit_result_release
12869 JIT: gcc::jit::logger::~logger()
12875 @node Design notes,,Overview of code structure,Internals
12876 @anchor{internals/index design-notes}@anchor{18e}
12877 @section Design notes
12880 It should not be possible for client code to cause an internal compiler
12881 error. If this @emph{does} happen, the root cause should be isolated (perhaps
12882 using @pxref{56,,gcc_jit_context_dump_reproducer_to_file()}) and the cause
12883 should be rejected via additional checking. The checking ideally should
12884 be within the libgccjit API entrypoints in libgccjit.c, since this is as
12885 close as possible to the error; failing that, a good place is within
12886 @code{recording::context::validate ()} in jit-recording.c.
12888 @node Indices and tables,Index,Internals,Top
12889 @anchor{index indices-and-tables}@anchor{18f}
12890 @unnumbered Indices and tables
12908 @c The Sphinx C domain appears to lack explicit support for enum values,
12909 @c so I've been using :c:macro: for them.
12911 @c See http://sphinx-doc.org/domains.html#the-c-domain
12913 @node Index,,Indices and tables,Top