Debian Codegraph @

gcc/jit/docs/_build/texinfo/libgccjit.texi

raw
1 \input texinfo @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename libgccjit.info
4 @documentencoding UTF-8
5 @ifinfo
6 @*Generated by Sphinx 2.2.2.@*
7 @end ifinfo
8 @settitle libgccjit Documentation
9 @defindex ge
10 @paragraphindent 0
11 @exampleindent 4
12 @finalout
13 @dircategory Miscellaneous
14 @direntry
15 * libgccjit: (libgccjit.info). GCC-based Just In Time compiler library.
16 @end direntry
17
18 @definfoenclose strong,`,'
19 @definfoenclose emph,`,'
20 @c %**end of header
21
22 @copying
23 @quotation
24 libgccjit 12.0.1 (experimental 20220411), Apr 12, 2022
25
26 David Malcolm
27
28 Copyright @copyright{} 2014-2022 Free Software Foundation, Inc.
29 @end quotation
30
31 @end copying
32
33 @titlepage
34 @title libgccjit Documentation
35 @insertcopying
36 @end titlepage
37 @contents
38
39 @c %** start of user preamble
40
41 @c %** end of user preamble
42
43 @ifnottex
44 @node Top
45 @top libgccjit Documentation
46 @insertcopying
47 @end ifnottex
48
49 @c %**start of body
50 @anchor{index doc}@anchor{0}
51 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
52 @c Originally contributed by David Malcolm <[email protected]>
53 @c
54 @c This is free software: you can redistribute it and/or modify it
55 @c under the terms of the GNU General Public License as published by
56 @c the Free Software Foundation, either version 3 of the License, or
57 @c (at your option) any later version.
58 @c
59 @c This program is distributed in the hope that it will be useful, but
60 @c WITHOUT ANY WARRANTY; without even the implied warranty of
61 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
62 @c General Public License for more details.
63 @c
64 @c You should have received a copy of the GNU General Public License
65 @c along with this program. If not, see
66 @c <https://www.gnu.org/licenses/>.
67
68 This document describes libgccjit@footnote{https://gcc.gnu.org/wiki/JIT}, an API
69 for embedding GCC inside programs and libraries.
70
71 There are actually two APIs for the library:
72
73
74 @itemize *
75
76 @item
77 a pure C API: @code{libgccjit.h}
78
79 @item
80 a C++ wrapper API: @code{libgccjit++.h}. This is a collection of “thin”
81 wrapper classes around the C API, to save typing.
82 @end itemize
83
84 Contents:
85
86 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
87 @c Originally contributed by David Malcolm <[email protected]>
88 @c
89 @c This is free software: you can redistribute it and/or modify it
90 @c under the terms of the GNU General Public License as published by
91 @c the Free Software Foundation, either version 3 of the License, or
92 @c (at your option) any later version.
93 @c
94 @c This program is distributed in the hope that it will be useful, but
95 @c WITHOUT ANY WARRANTY; without even the implied warranty of
96 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
97 @c General Public License for more details.
98 @c
99 @c You should have received a copy of the GNU General Public License
100 @c along with this program. If not, see
101 @c <https://www.gnu.org/licenses/>.
102
103 @menu
104 * Tutorial::
105 * Topic Reference::
106 * C++ bindings for libgccjit::
107 * Internals::
108 * Indices and tables::
109 * Index::
110
111 @detailmenu
112 --- The Detailed Node Listing ---
113
114 Tutorial
115
116 * Tutorial part 1; “Hello world”: Tutorial part 1 “Hello world”.
117 * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function.
118 * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables.
119 * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter.
120 * Tutorial part 5; Implementing an Ahead-of-Time compiler: Tutorial part 5 Implementing an Ahead-of-Time compiler.
121
122 Tutorial part 2: Creating a trivial machine code function
123
124 * Error-handling::
125 * Options::
126 * Full example::
127
128 Tutorial part 3: Loops and variables
129
130 * Expressions; lvalues and rvalues: Expressions lvalues and rvalues.
131 * Control flow::
132 * Visualizing the control flow graph::
133 * Full example: Full example<2>.
134
135 Tutorial part 4: Adding JIT-compilation to a toy interpreter
136
137 * Our toy interpreter::
138 * Compiling to machine code::
139 * Setting things up::
140 * Populating the function::
141 * Verifying the control flow graph::
142 * Compiling the context::
143 * Single-stepping through the generated code::
144 * Examining the generated code::
145 * Putting it all together::
146 * Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?.
147
148 Behind the curtain: How does our code get optimized?
149
150 * Optimizing away stack manipulation::
151 * Elimination of tail recursion::
152
153 Tutorial part 5: Implementing an Ahead-of-Time compiler
154
155 * The “brainf” language::
156 * Converting a brainf script to libgccjit IR::
157 * Compiling a context to a file::
158 * Other forms of ahead-of-time-compilation::
159
160 Topic Reference
161
162 * Compilation contexts::
163 * Objects::
164 * Types::
165 * Expressions::
166 * Creating and using functions::
167 * Function pointers: Function pointers<2>.
168 * Source Locations::
169 * Compiling a context::
170 * ABI and API compatibility::
171 * Performance::
172 * Using Assembly Language with libgccjit::
173
174 Compilation contexts
175
176 * Lifetime-management::
177 * Thread-safety::
178 * Error-handling: Error-handling<2>.
179 * Debugging::
180 * Options: Options<2>.
181
182 Options
183
184 * String Options::
185 * Boolean options::
186 * Integer options::
187 * Additional command-line options::
188
189 Types
190
191 * Standard types::
192 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile.
193 * Vector types::
194 * Structures and unions::
195 * Function pointer types::
196 * Reflection API::
197
198 Expressions
199
200 * Rvalues::
201 * Lvalues::
202 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions.
203
204 Rvalues
205
206 * Simple expressions::
207 * Constructor expressions::
208 * Vector expressions::
209 * Unary Operations::
210 * Binary Operations::
211 * Comparisons::
212 * Function calls::
213 * Function pointers::
214 * Type-coercion::
215
216 Lvalues
217
218 * Global variables::
219
220 Creating and using functions
221
222 * Params::
223 * Functions::
224 * Blocks::
225 * Statements::
226
227 Source Locations
228
229 * Faking it::
230
231 Compiling a context
232
233 * In-memory compilation::
234 * Ahead-of-time compilation::
235
236 ABI and API compatibility
237
238 * Programmatically checking version::
239 * ABI symbol tags::
240
241 ABI symbol tags
242
243 * LIBGCCJIT_ABI_0::
244 * LIBGCCJIT_ABI_1::
245 * LIBGCCJIT_ABI_2::
246 * LIBGCCJIT_ABI_3::
247 * LIBGCCJIT_ABI_4::
248 * LIBGCCJIT_ABI_5::
249 * LIBGCCJIT_ABI_6::
250 * LIBGCCJIT_ABI_7::
251 * LIBGCCJIT_ABI_8::
252 * LIBGCCJIT_ABI_9::
253 * LIBGCCJIT_ABI_10::
254 * LIBGCCJIT_ABI_11::
255 * LIBGCCJIT_ABI_12::
256 * LIBGCCJIT_ABI_13::
257 * LIBGCCJIT_ABI_14::
258 * LIBGCCJIT_ABI_15::
259 * LIBGCCJIT_ABI_16::
260 * LIBGCCJIT_ABI_17::
261 * LIBGCCJIT_ABI_18::
262 * LIBGCCJIT_ABI_19::
263 * LIBGCCJIT_ABI_20::
264 * LIBGCCJIT_ABI_21::
265 * LIBGCCJIT_ABI_22::
266 * LIBGCCJIT_ABI_23::
267 * LIBGCCJIT_ABI_24::
268
269 Performance
270
271 * The timing API::
272
273 Using Assembly Language with libgccjit
274
275 * Adding assembler instructions within a function::
276 * Adding top-level assembler statements::
277
278 C++ bindings for libgccjit
279
280 * Tutorial: Tutorial<2>.
281 * Topic Reference: Topic Reference<2>.
282
283 Tutorial
284
285 * Tutorial part 1; “Hello world”: Tutorial part 1 “Hello world”<2>.
286 * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>.
287 * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>.
288 * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>.
289
290 Tutorial part 2: Creating a trivial machine code function
291
292 * Options: Options<3>.
293 * Full example: Full example<3>.
294
295 Tutorial part 3: Loops and variables
296
297 * Expressions; lvalues and rvalues: Expressions lvalues and rvalues<2>.
298 * Control flow: Control flow<2>.
299 * Visualizing the control flow graph: Visualizing the control flow graph<2>.
300 * Full example: Full example<4>.
301
302 Tutorial part 4: Adding JIT-compilation to a toy interpreter
303
304 * Our toy interpreter: Our toy interpreter<2>.
305 * Compiling to machine code: Compiling to machine code<2>.
306 * Setting things up: Setting things up<2>.
307 * Populating the function: Populating the function<2>.
308 * Verifying the control flow graph: Verifying the control flow graph<2>.
309 * Compiling the context: Compiling the context<2>.
310 * Single-stepping through the generated code: Single-stepping through the generated code<2>.
311 * Examining the generated code: Examining the generated code<2>.
312 * Putting it all together: Putting it all together<2>.
313 * Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?<2>.
314
315 Behind the curtain: How does our code get optimized?
316
317 * Optimizing away stack manipulation: Optimizing away stack manipulation<2>.
318 * Elimination of tail recursion: Elimination of tail recursion<2>.
319
320 Topic Reference
321
322 * Compilation contexts: Compilation contexts<2>.
323 * Objects: Objects<2>.
324 * Types: Types<2>.
325 * Expressions: Expressions<2>.
326 * Creating and using functions: Creating and using functions<2>.
327 * Source Locations: Source Locations<2>.
328 * Compiling a context: Compiling a context<2>.
329 * Using Assembly Language with libgccjit++::
330
331 Compilation contexts
332
333 * Lifetime-management: Lifetime-management<2>.
334 * Thread-safety: Thread-safety<2>.
335 * Error-handling: Error-handling<3>.
336 * Debugging: Debugging<2>.
337 * Options: Options<4>.
338
339 Options
340
341 * String Options: String Options<2>.
342 * Boolean options: Boolean options<2>.
343 * Integer options: Integer options<2>.
344 * Additional command-line options: Additional command-line options<2>.
345
346 Types
347
348 * Standard types: Standard types<2>.
349 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
350 * Vector types: Vector types<2>.
351 * Structures and unions: Structures and unions<2>.
352
353 Expressions
354
355 * Rvalues: Rvalues<2>.
356 * Lvalues: Lvalues<2>.
357 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
358
359 Rvalues
360
361 * Simple expressions: Simple expressions<2>.
362 * Vector expressions: Vector expressions<2>.
363 * Unary Operations: Unary Operations<2>.
364 * Binary Operations: Binary Operations<2>.
365 * Comparisons: Comparisons<2>.
366 * Function calls: Function calls<2>.
367 * Function pointers: Function pointers<3>.
368 * Type-coercion: Type-coercion<2>.
369
370 Lvalues
371
372 * Global variables: Global variables<2>.
373
374 Creating and using functions
375
376 * Params: Params<2>.
377 * Functions: Functions<2>.
378 * Blocks: Blocks<2>.
379 * Statements: Statements<2>.
380
381 Source Locations
382
383 * Faking it: Faking it<2>.
384
385 Compiling a context
386
387 * In-memory compilation: In-memory compilation<2>.
388 * Ahead-of-time compilation: Ahead-of-time compilation<2>.
389
390 Using Assembly Language with libgccjit++
391
392 * Adding assembler instructions within a function: Adding assembler instructions within a function<2>.
393 * Adding top-level assembler statements: Adding top-level assembler statements<2>.
394
395 Internals
396
397 * Working on the JIT library::
398 * Running the test suite::
399 * Environment variables::
400 * Packaging notes::
401 * Overview of code structure::
402 * Design notes::
403 * Submitting patches::
404
405 Running the test suite
406
407 * Running under valgrind::
408
409 @end detailmenu
410 @end menu
411
412 @node Tutorial,Topic Reference,Top,Top
413 @anchor{intro/index doc}@anchor{1}@anchor{intro/index libgccjit}@anchor{2}@anchor{intro/index tutorial}@anchor{3}
414 @chapter Tutorial
415
416
417 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
418 @c Originally contributed by David Malcolm <[email protected]>
419 @c
420 @c This is free software: you can redistribute it and/or modify it
421 @c under the terms of the GNU General Public License as published by
422 @c the Free Software Foundation, either version 3 of the License, or
423 @c (at your option) any later version.
424 @c
425 @c This program is distributed in the hope that it will be useful, but
426 @c WITHOUT ANY WARRANTY; without even the implied warranty of
427 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
428 @c General Public License for more details.
429 @c
430 @c You should have received a copy of the GNU General Public License
431 @c along with this program. If not, see
432 @c <https://www.gnu.org/licenses/>.
433
434 @menu
435 * Tutorial part 1; “Hello world”: Tutorial part 1 “Hello world”.
436 * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function.
437 * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables.
438 * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter.
439 * Tutorial part 5; Implementing an Ahead-of-Time compiler: Tutorial part 5 Implementing an Ahead-of-Time compiler.
440
441 @end menu
442
443 @node Tutorial part 1 “Hello world”,Tutorial part 2 Creating a trivial machine code function,,Tutorial
444 @anchor{intro/tutorial01 doc}@anchor{4}@anchor{intro/tutorial01 tutorial-part-1-hello-world}@anchor{5}
445 @section Tutorial part 1: “Hello world”
446
447
448 Before we look at the details of the API, let’s look at building and
449 running programs that use the library.
450
451 Here’s a toy “hello world” program that uses the library to synthesize
452 a call to @cite{printf} and uses it to write a message to stdout.
453
454 Don’t worry about the content of the program for now; we’ll cover
455 the details in later parts of this tutorial.
456
457 @quotation
458
459 @example
460 /* Smoketest example for libgccjit.so
461 Copyright (C) 2014-2022 Free Software Foundation, Inc.
462
463 This file is part of GCC.
464
465 GCC is free software; you can redistribute it and/or modify it
466 under the terms of the GNU General Public License as published by
467 the Free Software Foundation; either version 3, or (at your option)
468 any later version.
469
470 GCC is distributed in the hope that it will be useful, but
471 WITHOUT ANY WARRANTY; without even the implied warranty of
472 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
473 General Public License for more details.
474
475 You should have received a copy of the GNU General Public License
476 along with GCC; see the file COPYING3. If not see
477 <http://www.gnu.org/licenses/>. */
478
479 #include <libgccjit.h>
480
481 #include <stdlib.h>
482 #include <stdio.h>
483
484 static void
485 create_code (gcc_jit_context *ctxt)
486 @{
487 /* Let's try to inject the equivalent of:
488 void
489 greet (const char *name)
490 @{
491 printf ("hello %s\n", name);
492 @}
493 */
494 gcc_jit_type *void_type =
495 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_VOID);
496 gcc_jit_type *const_char_ptr_type =
497 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_CONST_CHAR_PTR);
498 gcc_jit_param *param_name =
499 gcc_jit_context_new_param (ctxt, NULL, const_char_ptr_type, "name");
500 gcc_jit_function *func =
501 gcc_jit_context_new_function (ctxt, NULL,
502 GCC_JIT_FUNCTION_EXPORTED,
503 void_type,
504 "greet",
505 1, &param_name,
506 0);
507
508 gcc_jit_param *param_format =
509 gcc_jit_context_new_param (ctxt, NULL, const_char_ptr_type, "format");
510 gcc_jit_function *printf_func =
511 gcc_jit_context_new_function (ctxt, NULL,
512 GCC_JIT_FUNCTION_IMPORTED,
513 gcc_jit_context_get_type (
514 ctxt, GCC_JIT_TYPE_INT),
515 "printf",
516 1, &param_format,
517 1);
518 gcc_jit_rvalue *args[2];
519 args[0] = gcc_jit_context_new_string_literal (ctxt, "hello %s\n");
520 args[1] = gcc_jit_param_as_rvalue (param_name);
521
522 gcc_jit_block *block = gcc_jit_function_new_block (func, NULL);
523
524 gcc_jit_block_add_eval (
525 block, NULL,
526 gcc_jit_context_new_call (ctxt,
527 NULL,
528 printf_func,
529 2, args));
530 gcc_jit_block_end_with_void_return (block, NULL);
531 @}
532
533 int
534 main (int argc, char **argv)
535 @{
536 gcc_jit_context *ctxt;
537 gcc_jit_result *result;
538
539 /* Get a "context" object for working with the library. */
540 ctxt = gcc_jit_context_acquire ();
541 if (!ctxt)
542 @{
543 fprintf (stderr, "NULL ctxt");
544 exit (1);
545 @}
546
547 /* Set some options on the context.
548 Let's see the code being generated, in assembler form. */
549 gcc_jit_context_set_bool_option (
550 ctxt,
551 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
552 0);
553
554 /* Populate the context. */
555 create_code (ctxt);
556
557 /* Compile the code. */
558 result = gcc_jit_context_compile (ctxt);
559 if (!result)
560 @{
561 fprintf (stderr, "NULL result");
562 exit (1);
563 @}
564
565 /* Extract the generated code from "result". */
566 typedef void (*fn_type) (const char *);
567 fn_type greet =
568 (fn_type)gcc_jit_result_get_code (result, "greet");
569 if (!greet)
570 @{
571 fprintf (stderr, "NULL greet");
572 exit (1);
573 @}
574
575 /* Now call the generated function: */
576 greet ("world");
577 fflush (stdout);
578
579 gcc_jit_context_release (ctxt);
580 gcc_jit_result_release (result);
581 return 0;
582 @}
583 @end example
584 @end quotation
585
586 Copy the above to @cite{tut01-hello-world.c}.
587
588 Assuming you have the jit library installed, build the test program
589 using:
590
591 @example
592 $ gcc \
593 tut01-hello-world.c \
594 -o tut01-hello-world \
595 -lgccjit
596 @end example
597
598 You should then be able to run the built program:
599
600 @example
601 $ ./tut01-hello-world
602 hello world
603 @end example
604
605 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
606 @c Originally contributed by David Malcolm <[email protected]>
607 @c
608 @c This is free software: you can redistribute it and/or modify it
609 @c under the terms of the GNU General Public License as published by
610 @c the Free Software Foundation, either version 3 of the License, or
611 @c (at your option) any later version.
612 @c
613 @c This program is distributed in the hope that it will be useful, but
614 @c WITHOUT ANY WARRANTY; without even the implied warranty of
615 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
616 @c General Public License for more details.
617 @c
618 @c You should have received a copy of the GNU General Public License
619 @c along with this program. If not, see
620 @c <https://www.gnu.org/licenses/>.
621
622 @node Tutorial part 2 Creating a trivial machine code function,Tutorial part 3 Loops and variables,Tutorial part 1 “Hello world”,Tutorial
623 @anchor{intro/tutorial02 doc}@anchor{6}@anchor{intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{7}
624 @section Tutorial part 2: Creating a trivial machine code function
625
626
627 Consider this C function:
628
629 @example
630 int square (int i)
631 @{
632 return i * i;
633 @}
634 @end example
635
636 How can we construct this at run-time using libgccjit?
637
638 First we need to include the relevant header:
639
640 @example
641 #include <libgccjit.h>
642 @end example
643
644 All state associated with compilation is associated with a
645 @ref{8,,gcc_jit_context *}.
646
647 Create one using @ref{9,,gcc_jit_context_acquire()}:
648
649 @example
650 gcc_jit_context *ctxt;
651 ctxt = gcc_jit_context_acquire ();
652 @end example
653
654 The JIT library has a system of types. It is statically-typed: every
655 expression is of a specific type, fixed at compile-time. In our example,
656 all of the expressions are of the C @cite{int} type, so let’s obtain this from
657 the context, as a @ref{a,,gcc_jit_type *}, using
658 @ref{b,,gcc_jit_context_get_type()}:
659
660 @example
661 gcc_jit_type *int_type =
662 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
663 @end example
664
665 @ref{a,,gcc_jit_type *} is an example of a “contextual” object: every
666 entity in the API is associated with a @ref{8,,gcc_jit_context *}.
667
668 Memory management is easy: all such “contextual” objects are automatically
669 cleaned up for you when the context is released, using
670 @ref{c,,gcc_jit_context_release()}:
671
672 @example
673 gcc_jit_context_release (ctxt);
674 @end example
675
676 so you don’t need to manually track and cleanup all objects, just the
677 contexts.
678
679 Although the API is C-based, there is a form of class hierarchy, which
680 looks like this:
681
682 @example
683 +- gcc_jit_object
684 +- gcc_jit_location
685 +- gcc_jit_type
686 +- gcc_jit_struct
687 +- gcc_jit_field
688 +- gcc_jit_function
689 +- gcc_jit_block
690 +- gcc_jit_rvalue
691 +- gcc_jit_lvalue
692 +- gcc_jit_param
693 @end example
694
695 There are casting methods for upcasting from subclasses to parent classes.
696 For example, @ref{d,,gcc_jit_type_as_object()}:
697
698 @example
699 gcc_jit_object *obj = gcc_jit_type_as_object (int_type);
700 @end example
701
702 One thing you can do with a @ref{e,,gcc_jit_object *} is
703 to ask it for a human-readable description, using
704 @ref{f,,gcc_jit_object_get_debug_string()}:
705
706 @example
707 printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj));
708 @end example
709
710 giving this text on stdout:
711
712 @example
713 obj: int
714 @end example
715
716 This is invaluable when debugging.
717
718 Let’s create the function. To do so, we first need to construct
719 its single parameter, specifying its type and giving it a name,
720 using @ref{10,,gcc_jit_context_new_param()}:
721
722 @example
723 gcc_jit_param *param_i =
724 gcc_jit_context_new_param (ctxt, NULL, int_type, "i");
725 @end example
726
727 Now we can create the function, using
728 @ref{11,,gcc_jit_context_new_function()}:
729
730 @example
731 gcc_jit_function *func =
732 gcc_jit_context_new_function (ctxt, NULL,
733 GCC_JIT_FUNCTION_EXPORTED,
734 int_type,
735 "square",
736 1, &param_i,
737 0);
738 @end example
739
740 To define the code within the function, we must create basic blocks
741 containing statements.
742
743 Every basic block contains a list of statements, eventually terminated
744 by a statement that either returns, or jumps to another basic block.
745
746 Our function has no control-flow, so we just need one basic block:
747
748 @example
749 gcc_jit_block *block = gcc_jit_function_new_block (func, NULL);
750 @end example
751
752 Our basic block is relatively simple: it immediately terminates by
753 returning the value of an expression.
754
755 We can build the expression using @ref{12,,gcc_jit_context_new_binary_op()}:
756
757 @example
758 gcc_jit_rvalue *expr =
759 gcc_jit_context_new_binary_op (
760 ctxt, NULL,
761 GCC_JIT_BINARY_OP_MULT, int_type,
762 gcc_jit_param_as_rvalue (param_i),
763 gcc_jit_param_as_rvalue (param_i));
764 @end example
765
766 A @ref{13,,gcc_jit_rvalue *} is another example of a
767 @ref{e,,gcc_jit_object *} subclass. We can upcast it using
768 @ref{14,,gcc_jit_rvalue_as_object()} and as before print it with
769 @ref{f,,gcc_jit_object_get_debug_string()}.
770
771 @example
772 printf ("expr: %s\n",
773 gcc_jit_object_get_debug_string (
774 gcc_jit_rvalue_as_object (expr)));
775 @end example
776
777 giving this output:
778
779 @example
780 expr: i * i
781 @end example
782
783 Creating the expression in itself doesn’t do anything; we have to add
784 this expression to a statement within the block. In this case, we use it
785 to build a return statement, which terminates the basic block:
786
787 @example
788 gcc_jit_block_end_with_return (block, NULL, expr);
789 @end example
790
791 OK, we’ve populated the context. We can now compile it using
792 @ref{15,,gcc_jit_context_compile()}:
793
794 @example
795 gcc_jit_result *result;
796 result = gcc_jit_context_compile (ctxt);
797 @end example
798
799 and get a @ref{16,,gcc_jit_result *}.
800
801 At this point we’re done with the context; we can release it:
802
803 @example
804 gcc_jit_context_release (ctxt);
805 @end example
806
807 We can now use @ref{17,,gcc_jit_result_get_code()} to look up a specific
808 machine code routine within the result, in this case, the function we
809 created above.
810
811 @example
812 void *fn_ptr = gcc_jit_result_get_code (result, "square");
813 if (!fn_ptr)
814 @{
815 fprintf (stderr, "NULL fn_ptr");
816 goto error;
817 @}
818 @end example
819
820 We can now cast the pointer to an appropriate function pointer type, and
821 then call it:
822
823 @example
824 typedef int (*fn_type) (int);
825 fn_type square = (fn_type)fn_ptr;
826 printf ("result: %d", square (5));
827 @end example
828
829 @example
830 result: 25
831 @end example
832
833 Once we’re done with the code, we can release the result:
834
835 @example
836 gcc_jit_result_release (result);
837 @end example
838
839 We can’t call @code{square} anymore once we’ve released @code{result}.
840
841 @menu
842 * Error-handling::
843 * Options::
844 * Full example::
845
846 @end menu
847
848 @node Error-handling,Options,,Tutorial part 2 Creating a trivial machine code function
849 @anchor{intro/tutorial02 error-handling}@anchor{18}
850 @subsection Error-handling
851
852
853 Various kinds of errors are possible when using the API, such as
854 mismatched types in an assignment. You can only compile and get code
855 from a context if no errors occur.
856
857 Errors are printed on stderr; they typically contain the name of the API
858 entrypoint where the error occurred, and pertinent information on the
859 problem:
860
861 @example
862 ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *)
863 @end example
864
865 The API is designed to cope with errors without crashing, so you can get
866 away with having a single error-handling check in your code:
867
868 @example
869 void *fn_ptr = gcc_jit_result_get_code (result, "square");
870 if (!fn_ptr)
871 @{
872 fprintf (stderr, "NULL fn_ptr");
873 goto error;
874 @}
875 @end example
876
877 For more information, see the @ref{19,,error-handling guide}
878 within the Topic eference.
879
880 @node Options,Full example,Error-handling,Tutorial part 2 Creating a trivial machine code function
881 @anchor{intro/tutorial02 options}@anchor{1a}
882 @subsection Options
883
884
885 To get more information on what’s going on, you can set debugging flags
886 on the context using @ref{1b,,gcc_jit_context_set_bool_option()}.
887
888 @c (I'm deliberately not mentioning
889 @c :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE` here since I think
890 @c it's probably more of use to implementors than to users)
891
892 Setting @ref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE} will dump a
893 C-like representation to stderr when you compile (GCC’s “GIMPLE”
894 representation):
895
896 @example
897 gcc_jit_context_set_bool_option (
898 ctxt,
899 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE,
900 1);
901 result = gcc_jit_context_compile (ctxt);
902 @end example
903
904 @example
905 square (signed int i)
906 @{
907 signed int D.260;
908
909 entry:
910 D.260 = i * i;
911 return D.260;
912 @}
913 @end example
914
915 We can see the generated machine code in assembler form (on stderr) by
916 setting @ref{1d,,GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE} on the context
917 before compiling:
918
919 @example
920 gcc_jit_context_set_bool_option (
921 ctxt,
922 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
923 1);
924 result = gcc_jit_context_compile (ctxt);
925 @end example
926
927 @example
928 .file "fake.c"
929 .text
930 .globl square
931 .type square, @@function
932 square:
933 .LFB6:
934 .cfi_startproc
935 pushq %rbp
936 .cfi_def_cfa_offset 16
937 .cfi_offset 6, -16
938 movq %rsp, %rbp
939 .cfi_def_cfa_register 6
940 movl %edi, -4(%rbp)
941 .L14:
942 movl -4(%rbp), %eax
943 imull -4(%rbp), %eax
944 popq %rbp
945 .cfi_def_cfa 7, 8
946 ret
947 .cfi_endproc
948 .LFE6:
949 .size square, .-square
950 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
951 .section .note.GNU-stack,"",@@progbits
952 @end example
953
954 By default, no optimizations are performed, the equivalent of GCC’s
955 @cite{-O0} option. We can turn things up to e.g. @cite{-O3} by calling
956 @ref{1e,,gcc_jit_context_set_int_option()} with
957 @ref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
958
959 @example
960 gcc_jit_context_set_int_option (
961 ctxt,
962 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL,
963 3);
964 @end example
965
966 @example
967 .file "fake.c"
968 .text
969 .p2align 4,,15
970 .globl square
971 .type square, @@function
972 square:
973 .LFB7:
974 .cfi_startproc
975 .L16:
976 movl %edi, %eax
977 imull %edi, %eax
978 ret
979 .cfi_endproc
980 .LFE7:
981 .size square, .-square
982 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
983 .section .note.GNU-stack,"",@@progbits
984 @end example
985
986 Naturally this has only a small effect on such a trivial function.
987
988 @node Full example,,Options,Tutorial part 2 Creating a trivial machine code function
989 @anchor{intro/tutorial02 full-example}@anchor{20}
990 @subsection Full example
991
992
993 Here’s what the above looks like as a complete program:
994
995 @quotation
996
997 @example
998 /* Usage example for libgccjit.so
999 Copyright (C) 2014-2022 Free Software Foundation, Inc.
1000
1001 This file is part of GCC.
1002
1003 GCC is free software; you can redistribute it and/or modify it
1004 under the terms of the GNU General Public License as published by
1005 the Free Software Foundation; either version 3, or (at your option)
1006 any later version.
1007
1008 GCC is distributed in the hope that it will be useful, but
1009 WITHOUT ANY WARRANTY; without even the implied warranty of
1010 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1011 General Public License for more details.
1012
1013 You should have received a copy of the GNU General Public License
1014 along with GCC; see the file COPYING3. If not see
1015 <http://www.gnu.org/licenses/>. */
1016
1017 #include <libgccjit.h>
1018
1019 #include <stdlib.h>
1020 #include <stdio.h>
1021
1022 void
1023 create_code (gcc_jit_context *ctxt)
1024 @{
1025 /* Let's try to inject the equivalent of:
1026
1027 int square (int i)
1028 @{
1029 return i * i;
1030 @}
1031 */
1032 gcc_jit_type *int_type =
1033 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
1034 gcc_jit_param *param_i =
1035 gcc_jit_context_new_param (ctxt, NULL, int_type, "i");
1036 gcc_jit_function *func =
1037 gcc_jit_context_new_function (ctxt, NULL,
1038 GCC_JIT_FUNCTION_EXPORTED,
1039 int_type,
1040 "square",
1041 1, &param_i,
1042 0);
1043
1044 gcc_jit_block *block = gcc_jit_function_new_block (func, NULL);
1045
1046 gcc_jit_rvalue *expr =
1047 gcc_jit_context_new_binary_op (
1048 ctxt, NULL,
1049 GCC_JIT_BINARY_OP_MULT, int_type,
1050 gcc_jit_param_as_rvalue (param_i),
1051 gcc_jit_param_as_rvalue (param_i));
1052
1053 gcc_jit_block_end_with_return (block, NULL, expr);
1054 @}
1055
1056 int
1057 main (int argc, char **argv)
1058 @{
1059 gcc_jit_context *ctxt = NULL;
1060 gcc_jit_result *result = NULL;
1061
1062 /* Get a "context" object for working with the library. */
1063 ctxt = gcc_jit_context_acquire ();
1064 if (!ctxt)
1065 @{
1066 fprintf (stderr, "NULL ctxt");
1067 goto error;
1068 @}
1069
1070 /* Set some options on the context.
1071 Let's see the code being generated, in assembler form. */
1072 gcc_jit_context_set_bool_option (
1073 ctxt,
1074 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
1075 0);
1076
1077 /* Populate the context. */
1078 create_code (ctxt);
1079
1080 /* Compile the code. */
1081 result = gcc_jit_context_compile (ctxt);
1082 if (!result)
1083 @{
1084 fprintf (stderr, "NULL result");
1085 goto error;
1086 @}
1087
1088 /* We're done with the context; we can release it: */
1089 gcc_jit_context_release (ctxt);
1090 ctxt = NULL;
1091
1092 /* Extract the generated code from "result". */
1093 void *fn_ptr = gcc_jit_result_get_code (result, "square");
1094 if (!fn_ptr)
1095 @{
1096 fprintf (stderr, "NULL fn_ptr");
1097 goto error;
1098 @}
1099
1100 typedef int (*fn_type) (int);
1101 fn_type square = (fn_type)fn_ptr;
1102 printf ("result: %d\n", square (5));
1103
1104 error:
1105 if (ctxt)
1106 gcc_jit_context_release (ctxt);
1107 if (result)
1108 gcc_jit_result_release (result);
1109 return 0;
1110 @}
1111 @end example
1112 @end quotation
1113
1114 Building and running it:
1115
1116 @example
1117 $ gcc \
1118 tut02-square.c \
1119 -o tut02-square \
1120 -lgccjit
1121
1122 # Run the built program:
1123 $ ./tut02-square
1124 result: 25
1125 @end example
1126
1127 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
1128 @c Originally contributed by David Malcolm <[email protected]>
1129 @c
1130 @c This is free software: you can redistribute it and/or modify it
1131 @c under the terms of the GNU General Public License as published by
1132 @c the Free Software Foundation, either version 3 of the License, or
1133 @c (at your option) any later version.
1134 @c
1135 @c This program is distributed in the hope that it will be useful, but
1136 @c WITHOUT ANY WARRANTY; without even the implied warranty of
1137 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1138 @c General Public License for more details.
1139 @c
1140 @c You should have received a copy of the GNU General Public License
1141 @c along with this program. If not, see
1142 @c <https://www.gnu.org/licenses/>.
1143
1144 @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
1145 @anchor{intro/tutorial03 doc}@anchor{21}@anchor{intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{22}
1146 @section Tutorial part 3: Loops and variables
1147
1148
1149 Consider this C function:
1150
1151 @quotation
1152
1153 @example
1154 int loop_test (int n)
1155 @{
1156 int sum = 0;
1157 for (int i = 0; i < n; i++)
1158 sum += i * i;
1159 return sum;
1160 @}
1161 @end example
1162 @end quotation
1163
1164 This example demonstrates some more features of libgccjit, with local
1165 variables and a loop.
1166
1167 To break this down into libgccjit terms, it’s usually easier to reword
1168 the @cite{for} loop as a @cite{while} loop, giving:
1169
1170 @quotation
1171
1172 @example
1173 int loop_test (int n)
1174 @{
1175 int sum = 0;
1176 int i = 0;
1177 while (i < n)
1178 @{
1179 sum += i * i;
1180 i++;
1181 @}
1182 return sum;
1183 @}
1184 @end example
1185 @end quotation
1186
1187 Here’s what the final control flow graph will look like:
1188
1189 @quotation
1190
1191
1192 @float Figure
1193
1194 @image{libgccjit-figures/sum-of-squares1,,,image of a control flow graph,png}
1195
1196 @end float
1197
1198 @end quotation
1199
1200 As before, we include the libgccjit header and make a
1201 @ref{8,,gcc_jit_context *}.
1202
1203 @example
1204 #include <libgccjit.h>
1205
1206 void test (void)
1207 @{
1208 gcc_jit_context *ctxt;
1209 ctxt = gcc_jit_context_acquire ();
1210 @end example
1211
1212 The function works with the C @cite{int} type:
1213
1214 @example
1215 gcc_jit_type *the_type =
1216 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
1217 gcc_jit_type *return_type = the_type;
1218 @end example
1219
1220 though we could equally well make it work on, say, @cite{double}:
1221
1222 @example
1223 gcc_jit_type *the_type =
1224 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_DOUBLE);
1225 @end example
1226
1227 Let’s build the function:
1228
1229 @example
1230 gcc_jit_param *n =
1231 gcc_jit_context_new_param (ctxt, NULL, the_type, "n");
1232 gcc_jit_param *params[1] = @{n@};
1233 gcc_jit_function *func =
1234 gcc_jit_context_new_function (ctxt, NULL,
1235 GCC_JIT_FUNCTION_EXPORTED,
1236 return_type,
1237 "loop_test",
1238 1, params, 0);
1239 @end example
1240
1241 @menu
1242 * Expressions; lvalues and rvalues: Expressions lvalues and rvalues.
1243 * Control flow::
1244 * Visualizing the control flow graph::
1245 * Full example: Full example<2>.
1246
1247 @end menu
1248
1249 @node Expressions lvalues and rvalues,Control flow,,Tutorial part 3 Loops and variables
1250 @anchor{intro/tutorial03 expressions-lvalues-and-rvalues}@anchor{23}
1251 @subsection Expressions: lvalues and rvalues
1252
1253
1254 The base class of expression is the @ref{13,,gcc_jit_rvalue *},
1255 representing an expression that can be on the @emph{right}-hand side of
1256 an assignment: a value that can be computed somehow, and assigned
1257 @emph{to} a storage area (such as a variable). It has a specific
1258 @ref{a,,gcc_jit_type *}.
1259
1260 Anothe important class is @ref{24,,gcc_jit_lvalue *}.
1261 A @ref{24,,gcc_jit_lvalue *}. is something that can of the @emph{left}-hand
1262 side of an assignment: a storage area (such as a variable).
1263
1264 In other words, every assignment can be thought of as:
1265
1266 @example
1267 LVALUE = RVALUE;
1268 @end example
1269
1270 Note that @ref{24,,gcc_jit_lvalue *} is a subclass of
1271 @ref{13,,gcc_jit_rvalue *}, where in an assignment of the form:
1272
1273 @example
1274 LVALUE_A = LVALUE_B;
1275 @end example
1276
1277 the @cite{LVALUE_B} implies reading the current value of that storage
1278 area, assigning it into the @cite{LVALUE_A}.
1279
1280 So far the only expressions we’ve seen are @cite{i * i}:
1281
1282 @example
1283 gcc_jit_rvalue *expr =
1284 gcc_jit_context_new_binary_op (
1285 ctxt, NULL,
1286 GCC_JIT_BINARY_OP_MULT, int_type,
1287 gcc_jit_param_as_rvalue (param_i),
1288 gcc_jit_param_as_rvalue (param_i));
1289 @end example
1290
1291 which is a @ref{13,,gcc_jit_rvalue *}, and the various function
1292 parameters: @cite{param_i} and @cite{param_n}, instances of
1293 @ref{25,,gcc_jit_param *}, which is a subclass of
1294 @ref{24,,gcc_jit_lvalue *} (and, in turn, of @ref{13,,gcc_jit_rvalue *}):
1295 we can both read from and write to function parameters within the
1296 body of a function.
1297
1298 Our new example has a couple of local variables. We create them by
1299 calling @ref{26,,gcc_jit_function_new_local()}, supplying a type and a
1300 name:
1301
1302 @example
1303 /* Build locals: */
1304 gcc_jit_lvalue *i =
1305 gcc_jit_function_new_local (func, NULL, the_type, "i");
1306 gcc_jit_lvalue *sum =
1307 gcc_jit_function_new_local (func, NULL, the_type, "sum");
1308 @end example
1309
1310 These are instances of @ref{24,,gcc_jit_lvalue *} - they can be read from
1311 and written to.
1312
1313 Note that there is no precanned way to create @emph{and} initialize a variable
1314 like in C:
1315
1316 @example
1317 int i = 0;
1318 @end example
1319
1320 Instead, having added the local to the function, we have to separately add
1321 an assignment of @cite{0} to @cite{local_i} at the beginning of the function.
1322
1323 @node Control flow,Visualizing the control flow graph,Expressions lvalues and rvalues,Tutorial part 3 Loops and variables
1324 @anchor{intro/tutorial03 control-flow}@anchor{27}
1325 @subsection Control flow
1326
1327
1328 This function has a loop, so we need to build some basic blocks to
1329 handle the control flow. In this case, we need 4 blocks:
1330
1331
1332 @enumerate
1333
1334 @item
1335 before the loop (initializing the locals)
1336
1337 @item
1338 the conditional at the top of the loop (comparing @cite{i < n})
1339
1340 @item
1341 the body of the loop
1342
1343 @item
1344 after the loop terminates (@cite{return sum})
1345 @end enumerate
1346
1347 so we create these as @ref{28,,gcc_jit_block *} instances within the
1348 @ref{29,,gcc_jit_function *}:
1349
1350 @example
1351 gcc_jit_block *b_initial =
1352 gcc_jit_function_new_block (func, "initial");
1353 gcc_jit_block *b_loop_cond =
1354 gcc_jit_function_new_block (func, "loop_cond");
1355 gcc_jit_block *b_loop_body =
1356 gcc_jit_function_new_block (func, "loop_body");
1357 gcc_jit_block *b_after_loop =
1358 gcc_jit_function_new_block (func, "after_loop");
1359 @end example
1360
1361 We now populate each block with statements.
1362
1363 The entry block @cite{b_initial} consists of initializations followed by a jump
1364 to the conditional. We assign @cite{0} to @cite{i} and to @cite{sum}, using
1365 @ref{2a,,gcc_jit_block_add_assignment()} to add
1366 an assignment statement, and using @ref{2b,,gcc_jit_context_zero()} to get
1367 the constant value @cite{0} for the relevant type for the right-hand side of
1368 the assignment:
1369
1370 @example
1371 /* sum = 0; */
1372 gcc_jit_block_add_assignment (
1373 b_initial, NULL,
1374 sum,
1375 gcc_jit_context_zero (ctxt, the_type));
1376
1377 /* i = 0; */
1378 gcc_jit_block_add_assignment (
1379 b_initial, NULL,
1380 i,
1381 gcc_jit_context_zero (ctxt, the_type));
1382 @end example
1383
1384 We can then terminate the entry block by jumping to the conditional:
1385
1386 @example
1387 gcc_jit_block_end_with_jump (b_initial, NULL, b_loop_cond);
1388 @end example
1389
1390 The conditional block is equivalent to the line @cite{while (i < n)} from our
1391 C example. It contains a single statement: a conditional, which jumps to
1392 one of two destination blocks depending on a boolean
1393 @ref{13,,gcc_jit_rvalue *}, in this case the comparison of @cite{i} and @cite{n}.
1394 We build the comparison using @ref{2c,,gcc_jit_context_new_comparison()}:
1395
1396 @example
1397 /* (i >= n) */
1398 gcc_jit_rvalue *guard =
1399 gcc_jit_context_new_comparison (
1400 ctxt, NULL,
1401 GCC_JIT_COMPARISON_GE,
1402 gcc_jit_lvalue_as_rvalue (i),
1403 gcc_jit_param_as_rvalue (n));
1404 @end example
1405
1406 and can then use this to add @cite{b_loop_cond}’s sole statement, via
1407 @ref{2d,,gcc_jit_block_end_with_conditional()}:
1408
1409 @example
1410 /* Equivalent to:
1411 if (guard)
1412 goto after_loop;
1413 else
1414 goto loop_body; */
1415 gcc_jit_block_end_with_conditional (
1416 b_loop_cond, NULL,
1417 guard,
1418 b_after_loop, /* on_true */
1419 b_loop_body); /* on_false */
1420 @end example
1421
1422 Next, we populate the body of the loop.
1423
1424 The C statement @cite{sum += i * i;} is an assignment operation, where an
1425 lvalue is modified “in-place”. We use
1426 @ref{2e,,gcc_jit_block_add_assignment_op()} to handle these operations:
1427
1428 @example
1429 /* sum += i * i */
1430 gcc_jit_block_add_assignment_op (
1431 b_loop_body, NULL,
1432 sum,
1433 GCC_JIT_BINARY_OP_PLUS,
1434 gcc_jit_context_new_binary_op (
1435 ctxt, NULL,
1436 GCC_JIT_BINARY_OP_MULT, the_type,
1437 gcc_jit_lvalue_as_rvalue (i),
1438 gcc_jit_lvalue_as_rvalue (i)));
1439 @end example
1440
1441 The @cite{i++} can be thought of as @cite{i += 1}, and can thus be handled in
1442 a similar way. We use @ref{2f,,gcc_jit_context_one()} to get the constant
1443 value @cite{1} (for the relevant type) for the right-hand side
1444 of the assignment.
1445
1446 @example
1447 /* i++ */
1448 gcc_jit_block_add_assignment_op (
1449 b_loop_body, NULL,
1450 i,
1451 GCC_JIT_BINARY_OP_PLUS,
1452 gcc_jit_context_one (ctxt, the_type));
1453 @end example
1454
1455 @cartouche
1456 @quotation Note
1457 For numeric constants other than 0 or 1, we could use
1458 @ref{30,,gcc_jit_context_new_rvalue_from_int()} and
1459 @ref{31,,gcc_jit_context_new_rvalue_from_double()}.
1460 @end quotation
1461 @end cartouche
1462
1463 The loop body completes by jumping back to the conditional:
1464
1465 @example
1466 gcc_jit_block_end_with_jump (b_loop_body, NULL, b_loop_cond);
1467 @end example
1468
1469 Finally, we populate the @cite{b_after_loop} block, reached when the loop
1470 conditional is false. We want to generate the equivalent of:
1471
1472 @example
1473 return sum;
1474 @end example
1475
1476 so the block is just one statement:
1477
1478 @example
1479 /* return sum */
1480 gcc_jit_block_end_with_return (
1481 b_after_loop,
1482 NULL,
1483 gcc_jit_lvalue_as_rvalue (sum));
1484 @end example
1485
1486 @cartouche
1487 @quotation Note
1488 You can intermingle block creation with statement creation,
1489 but given that the terminator statements generally include references
1490 to other blocks, I find it’s clearer to create all the blocks,
1491 @emph{then} all the statements.
1492 @end quotation
1493 @end cartouche
1494
1495 We’ve finished populating the function. As before, we can now compile it
1496 to machine code:
1497
1498 @example
1499 gcc_jit_result *result;
1500 result = gcc_jit_context_compile (ctxt);
1501
1502 typedef int (*loop_test_fn_type) (int);
1503 loop_test_fn_type loop_test =
1504 (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
1505 if (!loop_test)
1506 goto error;
1507 printf ("result: %d", loop_test (10));
1508 @end example
1509
1510 @example
1511 result: 285
1512 @end example
1513
1514 @node Visualizing the control flow graph,Full example<2>,Control flow,Tutorial part 3 Loops and variables
1515 @anchor{intro/tutorial03 visualizing-the-control-flow-graph}@anchor{32}
1516 @subsection Visualizing the control flow graph
1517
1518
1519 You can see the control flow graph of a function using
1520 @ref{33,,gcc_jit_function_dump_to_dot()}:
1521
1522 @example
1523 gcc_jit_function_dump_to_dot (func, "/tmp/sum-of-squares.dot");
1524 @end example
1525
1526 giving a .dot file in GraphViz format.
1527
1528 You can convert this to an image using @cite{dot}:
1529
1530 @example
1531 $ dot -Tpng /tmp/sum-of-squares.dot -o /tmp/sum-of-squares.png
1532 @end example
1533
1534 or use a viewer (my preferred one is xdot.py; see
1535 @indicateurl{https://github.com/jrfonseca/xdot.py}; on Fedora you can
1536 install it with @cite{yum install python-xdot}):
1537
1538 @quotation
1539
1540
1541 @float Figure
1542
1543 @image{libgccjit-figures/sum-of-squares1,,,image of a control flow graph,png}
1544
1545 @end float
1546
1547 @end quotation
1548
1549 @node Full example<2>,,Visualizing the control flow graph,Tutorial part 3 Loops and variables
1550 @anchor{intro/tutorial03 full-example}@anchor{34}
1551 @subsection Full example
1552
1553
1554 @quotation
1555
1556 @example
1557 /* Usage example for libgccjit.so
1558 Copyright (C) 2014-2022 Free Software Foundation, Inc.
1559
1560 This file is part of GCC.
1561
1562 GCC is free software; you can redistribute it and/or modify it
1563 under the terms of the GNU General Public License as published by
1564 the Free Software Foundation; either version 3, or (at your option)
1565 any later version.
1566
1567 GCC is distributed in the hope that it will be useful, but
1568 WITHOUT ANY WARRANTY; without even the implied warranty of
1569 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1570 General Public License for more details.
1571
1572 You should have received a copy of the GNU General Public License
1573 along with GCC; see the file COPYING3. If not see
1574 <http://www.gnu.org/licenses/>. */
1575
1576 #include <libgccjit.h>
1577
1578 #include <stdlib.h>
1579 #include <stdio.h>
1580
1581 void
1582 create_code (gcc_jit_context *ctxt)
1583 @{
1584 /*
1585 Simple sum-of-squares, to test conditionals and looping
1586
1587 int loop_test (int n)
1588 @{
1589 int i;
1590 int sum = 0;
1591 for (i = 0; i < n ; i ++)
1592 @{
1593 sum += i * i;
1594 @}
1595 return sum;
1596 */
1597 gcc_jit_type *the_type =
1598 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
1599 gcc_jit_type *return_type = the_type;
1600
1601 gcc_jit_param *n =
1602 gcc_jit_context_new_param (ctxt, NULL, the_type, "n");
1603 gcc_jit_param *params[1] = @{n@};
1604 gcc_jit_function *func =
1605 gcc_jit_context_new_function (ctxt, NULL,
1606 GCC_JIT_FUNCTION_EXPORTED,
1607 return_type,
1608 "loop_test",
1609 1, params, 0);
1610
1611 /* Build locals: */
1612 gcc_jit_lvalue *i =
1613 gcc_jit_function_new_local (func, NULL, the_type, "i");
1614 gcc_jit_lvalue *sum =
1615 gcc_jit_function_new_local (func, NULL, the_type, "sum");
1616
1617 gcc_jit_block *b_initial =
1618 gcc_jit_function_new_block (func, "initial");
1619 gcc_jit_block *b_loop_cond =
1620 gcc_jit_function_new_block (func, "loop_cond");
1621 gcc_jit_block *b_loop_body =
1622 gcc_jit_function_new_block (func, "loop_body");
1623 gcc_jit_block *b_after_loop =
1624 gcc_jit_function_new_block (func, "after_loop");
1625
1626 /* sum = 0; */
1627 gcc_jit_block_add_assignment (
1628 b_initial, NULL,
1629 sum,
1630 gcc_jit_context_zero (ctxt, the_type));
1631
1632 /* i = 0; */
1633 gcc_jit_block_add_assignment (
1634 b_initial, NULL,
1635 i,
1636 gcc_jit_context_zero (ctxt, the_type));
1637
1638 gcc_jit_block_end_with_jump (b_initial, NULL, b_loop_cond);
1639
1640 /* if (i >= n) */
1641 gcc_jit_block_end_with_conditional (
1642 b_loop_cond, NULL,
1643 gcc_jit_context_new_comparison (
1644 ctxt, NULL,
1645 GCC_JIT_COMPARISON_GE,
1646 gcc_jit_lvalue_as_rvalue (i),
1647 gcc_jit_param_as_rvalue (n)),
1648 b_after_loop,
1649 b_loop_body);
1650
1651 /* sum += i * i */
1652 gcc_jit_block_add_assignment_op (
1653 b_loop_body, NULL,
1654 sum,
1655 GCC_JIT_BINARY_OP_PLUS,
1656 gcc_jit_context_new_binary_op (
1657 ctxt, NULL,
1658 GCC_JIT_BINARY_OP_MULT, the_type,
1659 gcc_jit_lvalue_as_rvalue (i),
1660 gcc_jit_lvalue_as_rvalue (i)));
1661
1662 /* i++ */
1663 gcc_jit_block_add_assignment_op (
1664 b_loop_body, NULL,
1665 i,
1666 GCC_JIT_BINARY_OP_PLUS,
1667 gcc_jit_context_one (ctxt, the_type));
1668
1669 gcc_jit_block_end_with_jump (b_loop_body, NULL, b_loop_cond);
1670
1671 /* return sum */
1672 gcc_jit_block_end_with_return (
1673 b_after_loop,
1674 NULL,
1675 gcc_jit_lvalue_as_rvalue (sum));
1676 @}
1677
1678 int
1679 main (int argc, char **argv)
1680 @{
1681 gcc_jit_context *ctxt = NULL;
1682 gcc_jit_result *result = NULL;
1683
1684 /* Get a "context" object for working with the library. */
1685 ctxt = gcc_jit_context_acquire ();
1686 if (!ctxt)
1687 @{
1688 fprintf (stderr, "NULL ctxt");
1689 goto error;
1690 @}
1691
1692 /* Set some options on the context.
1693 Let's see the code being generated, in assembler form. */
1694 gcc_jit_context_set_bool_option (
1695 ctxt,
1696 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
1697 0);
1698
1699 /* Populate the context. */
1700 create_code (ctxt);
1701
1702 /* Compile the code. */
1703 result = gcc_jit_context_compile (ctxt);
1704 if (!result)
1705 @{
1706 fprintf (stderr, "NULL result");
1707 goto error;
1708 @}
1709
1710 /* Extract the generated code from "result". */
1711 typedef int (*loop_test_fn_type) (int);
1712 loop_test_fn_type loop_test =
1713 (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
1714 if (!loop_test)
1715 @{
1716 fprintf (stderr, "NULL loop_test");
1717 goto error;
1718 @}
1719
1720 /* Run the generated code. */
1721 int val = loop_test (10);
1722 printf("loop_test returned: %d\n", val);
1723
1724 error:
1725 gcc_jit_context_release (ctxt);
1726 gcc_jit_result_release (result);
1727 return 0;
1728 @}
1729 @end example
1730 @end quotation
1731
1732 Building and running it:
1733
1734 @example
1735 $ gcc \
1736 tut03-sum-of-squares.c \
1737 -o tut03-sum-of-squares \
1738 -lgccjit
1739
1740 # Run the built program:
1741 $ ./tut03-sum-of-squares
1742 loop_test returned: 285
1743 @end example
1744
1745 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
1746 @c Originally contributed by David Malcolm <[email protected]>
1747 @c
1748 @c This is free software: you can redistribute it and/or modify it
1749 @c under the terms of the GNU General Public License as published by
1750 @c the Free Software Foundation, either version 3 of the License, or
1751 @c (at your option) any later version.
1752 @c
1753 @c This program is distributed in the hope that it will be useful, but
1754 @c WITHOUT ANY WARRANTY; without even the implied warranty of
1755 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1756 @c General Public License for more details.
1757 @c
1758 @c You should have received a copy of the GNU General Public License
1759 @c along with this program. If not, see
1760 @c <https://www.gnu.org/licenses/>.
1761
1762 @node Tutorial part 4 Adding JIT-compilation to a toy interpreter,Tutorial part 5 Implementing an Ahead-of-Time compiler,Tutorial part 3 Loops and variables,Tutorial
1763 @anchor{intro/tutorial04 doc}@anchor{35}@anchor{intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{36}
1764 @section Tutorial part 4: Adding JIT-compilation to a toy interpreter
1765
1766
1767 In this example we construct a “toy” interpreter, and add JIT-compilation
1768 to it.
1769
1770 @menu
1771 * Our toy interpreter::
1772 * Compiling to machine code::
1773 * Setting things up::
1774 * Populating the function::
1775 * Verifying the control flow graph::
1776 * Compiling the context::
1777 * Single-stepping through the generated code::
1778 * Examining the generated code::
1779 * Putting it all together::
1780 * Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?.
1781
1782 @end menu
1783
1784 @node Our toy interpreter,Compiling to machine code,,Tutorial part 4 Adding JIT-compilation to a toy interpreter
1785 @anchor{intro/tutorial04 our-toy-interpreter}@anchor{37}
1786 @subsection Our toy interpreter
1787
1788
1789 It’s a stack-based interpreter, and is intended as a (very simple) example
1790 of the kind of bytecode interpreter seen in dynamic languages such as
1791 Python, Ruby etc.
1792
1793 For the sake of simplicity, our toy virtual machine is very limited:
1794
1795 @quotation
1796
1797
1798 @itemize *
1799
1800 @item
1801 The only data type is @cite{int}
1802
1803 @item
1804 It can only work on one function at a time (so that the only
1805 function call that can be made is to recurse).
1806
1807 @item
1808 Functions can only take one parameter.
1809
1810 @item
1811 Functions have a stack of @cite{int} values.
1812
1813 @item
1814 We’ll implement function call within the interpreter by calling a
1815 function in our implementation, rather than implementing our own
1816 frame stack.
1817
1818 @item
1819 The parser is only good enough to get the examples to work.
1820 @end itemize
1821 @end quotation
1822
1823 Naturally, a real interpreter would be much more complicated that this.
1824
1825 The following operations are supported:
1826
1827
1828 @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx}
1829 @headitem
1830
1831 Operation
1832
1833 @tab
1834
1835 Meaning
1836
1837 @tab
1838
1839 Old Stack
1840
1841 @tab
1842
1843 New Stack
1844
1845 @item
1846
1847 DUP
1848
1849 @tab
1850
1851 Duplicate top of stack.
1852
1853 @tab
1854
1855 @code{[..., x]}
1856
1857 @tab
1858
1859 @code{[..., x, x]}
1860
1861 @item
1862
1863 ROT
1864
1865 @tab
1866
1867 Swap top two elements
1868 of stack.
1869
1870 @tab
1871
1872 @code{[..., x, y]}
1873
1874 @tab
1875
1876 @code{[..., y, x]}
1877
1878 @item
1879
1880 BINARY_ADD
1881
1882 @tab
1883
1884 Add the top two elements
1885 on the stack.
1886
1887 @tab
1888
1889 @code{[..., x, y]}
1890
1891 @tab
1892
1893 @code{[..., (x+y)]}
1894
1895 @item
1896
1897 BINARY_SUBTRACT
1898
1899 @tab
1900
1901 Likewise, but subtract.
1902
1903 @tab
1904
1905 @code{[..., x, y]}
1906
1907 @tab
1908
1909 @code{[..., (x-y)]}
1910
1911 @item
1912
1913 BINARY_MULT
1914
1915 @tab
1916
1917 Likewise, but multiply.
1918
1919 @tab
1920
1921 @code{[..., x, y]}
1922
1923 @tab
1924
1925 @code{[..., (x*y)]}
1926
1927 @item
1928
1929 BINARY_COMPARE_LT
1930
1931 @tab
1932
1933 Compare the top two
1934 elements on the stack
1935 and push a nonzero/zero
1936 if (x<y).
1937
1938 @tab
1939
1940 @code{[..., x, y]}
1941
1942 @tab
1943
1944 @code{[..., (x<y)]}
1945
1946 @item
1947
1948 RECURSE
1949
1950 @tab
1951
1952 Recurse, passing the top
1953 of the stack, and
1954 popping the result.
1955
1956 @tab
1957
1958 @code{[..., x]}
1959
1960 @tab
1961
1962 @code{[..., fn(x)]}
1963
1964 @item
1965
1966 RETURN
1967
1968 @tab
1969
1970 Return the top of the
1971 stack.
1972
1973 @tab
1974
1975 @code{[x]}
1976
1977 @tab
1978
1979 @code{[]}
1980
1981 @item
1982
1983 PUSH_CONST @cite{arg}
1984
1985 @tab
1986
1987 Push an int const.
1988
1989 @tab
1990
1991 @code{[...]}
1992
1993 @tab
1994
1995 @code{[..., arg]}
1996
1997 @item
1998
1999 JUMP_ABS_IF_TRUE @cite{arg}
2000
2001 @tab
2002
2003 Pop; if top of stack was
2004 nonzero, jump to
2005 @code{arg}.
2006
2007 @tab
2008
2009 @code{[..., x]}
2010
2011 @tab
2012
2013 @code{[...]}
2014
2015 @end multitable
2016
2017
2018 Programs can be interpreted, disassembled, and compiled to machine code.
2019
2020 The interpreter reads @code{.toy} scripts. Here’s what a simple recursive
2021 factorial program looks like, the script @code{factorial.toy}.
2022 The parser ignores lines beginning with a @cite{#}.
2023
2024 @quotation
2025
2026 @example
2027 # Simple recursive factorial implementation, roughly equivalent to:
2028 #
2029 # int factorial (int arg)
2030 # @{
2031 # if (arg < 2)
2032 # return arg
2033 # return arg * factorial (arg - 1)
2034 # @}
2035
2036 # Initial state:
2037 # stack: [arg]
2038
2039 # 0:
2040 DUP
2041 # stack: [arg, arg]
2042
2043 # 1:
2044 PUSH_CONST 2
2045 # stack: [arg, arg, 2]
2046
2047 # 2:
2048 BINARY_COMPARE_LT
2049 # stack: [arg, (arg < 2)]
2050
2051 # 3:
2052 JUMP_ABS_IF_TRUE 9
2053 # stack: [arg]
2054
2055 # 4:
2056 DUP
2057 # stack: [arg, arg]
2058
2059 # 5:
2060 PUSH_CONST 1
2061 # stack: [arg, arg, 1]
2062
2063 # 6:
2064 BINARY_SUBTRACT
2065 # stack: [arg, (arg - 1)
2066
2067 # 7:
2068 RECURSE
2069 # stack: [arg, factorial(arg - 1)]
2070
2071 # 8:
2072 BINARY_MULT
2073 # stack: [arg * factorial(arg - 1)]
2074
2075 # 9:
2076 RETURN
2077 @end example
2078 @end quotation
2079
2080 The interpreter is a simple infinite loop with a big @code{switch} statement
2081 based on what the next opcode is:
2082
2083 @quotation
2084
2085 @example
2086
2087 static int
2088 toyvm_function_interpret (toyvm_function *fn, int arg, FILE *trace)
2089 @{
2090 toyvm_frame frame;
2091 #define PUSH(ARG) (toyvm_frame_push (&frame, (ARG)))
2092 #define POP(ARG) (toyvm_frame_pop (&frame))
2093
2094 frame.frm_function = fn;
2095 frame.frm_pc = 0;
2096 frame.frm_cur_depth = 0;
2097
2098 PUSH (arg);
2099
2100 while (1)
2101 @{
2102 toyvm_op *op;
2103 int x, y;
2104 assert (frame.frm_pc < fn->fn_num_ops);
2105 op = &fn->fn_ops[frame.frm_pc++];
2106
2107 if (trace)
2108 @{
2109 toyvm_frame_dump_stack (&frame, trace);
2110 toyvm_function_disassemble_op (fn, op, frame.frm_pc, trace);
2111 @}
2112
2113 switch (op->op_opcode)
2114 @{
2115 /* Ops taking no operand. */
2116 case DUP:
2117 x = POP ();
2118 PUSH (x);
2119 PUSH (x);
2120 break;
2121
2122 case ROT:
2123 y = POP ();
2124 x = POP ();
2125 PUSH (y);
2126 PUSH (x);
2127 break;
2128
2129 case BINARY_ADD:
2130 y = POP ();
2131 x = POP ();
2132 PUSH (x + y);
2133 break;
2134
2135 case BINARY_SUBTRACT:
2136 y = POP ();
2137 x = POP ();
2138 PUSH (x - y);
2139 break;
2140
2141 case BINARY_MULT:
2142 y = POP ();
2143 x = POP ();
2144 PUSH (x * y);
2145 break;
2146
2147 case BINARY_COMPARE_LT:
2148 y = POP ();
2149 x = POP ();
2150 PUSH (x < y);
2151 break;
2152
2153 case RECURSE:
2154 x = POP ();
2155 x = toyvm_function_interpret (fn, x, trace);
2156 PUSH (x);
2157 break;
2158
2159 case RETURN:
2160 return POP ();
2161
2162 /* Ops taking an operand. */
2163 case PUSH_CONST:
2164 PUSH (op->op_operand);
2165 break;
2166
2167 case JUMP_ABS_IF_TRUE:
2168 x = POP ();
2169 if (x)
2170 frame.frm_pc = op->op_operand;
2171 break;
2172
2173 default:
2174 assert (0); /* unknown opcode */
2175
2176 @} /* end of switch on opcode */
2177 @} /* end of while loop */
2178
2179 #undef PUSH
2180 #undef POP
2181 @}
2182
2183 @end example
2184 @end quotation
2185
2186 @node Compiling to machine code,Setting things up,Our toy interpreter,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2187 @anchor{intro/tutorial04 compiling-to-machine-code}@anchor{38}
2188 @subsection Compiling to machine code
2189
2190
2191 We want to generate machine code that can be cast to this type and
2192 then directly executed in-process:
2193
2194 @quotation
2195
2196 @example
2197 typedef int (*toyvm_compiled_code) (int);
2198
2199 @end example
2200 @end quotation
2201
2202 The lifetime of the code is tied to that of a @ref{16,,gcc_jit_result *}.
2203 We’ll handle this by bundling them up in a structure, so that we can
2204 clean them up together by calling @ref{39,,gcc_jit_result_release()}:
2205
2206 @quotation
2207
2208 @example
2209
2210 struct toyvm_compiled_function
2211 @{
2212 gcc_jit_result *cf_jit_result;
2213 toyvm_compiled_code cf_code;
2214 @};
2215
2216 @end example
2217 @end quotation
2218
2219 Our compiler isn’t very sophisticated; it takes the implementation of
2220 each opcode above, and maps it directly to the operations supported by
2221 the libgccjit API.
2222
2223 How should we handle the stack? In theory we could calculate what the
2224 stack depth will be at each opcode, and optimize away the stack
2225 manipulation “by hand”. We’ll see below that libgccjit is able to do
2226 this for us, so we’ll implement stack manipulation
2227 in a direct way, by creating a @code{stack} array and @code{stack_depth}
2228 variables, local within the generated function, equivalent to this C code:
2229
2230 @example
2231 int stack_depth;
2232 int stack[MAX_STACK_DEPTH];
2233 @end example
2234
2235 We’ll also have local variables @code{x} and @code{y} for use when implementing
2236 the opcodes, equivalent to this:
2237
2238 @example
2239 int x;
2240 int y;
2241 @end example
2242
2243 This means our compiler has the following state:
2244
2245 @quotation
2246
2247 @example
2248
2249 struct compilation_state
2250 @{
2251 gcc_jit_context *ctxt;
2252
2253 gcc_jit_type *int_type;
2254 gcc_jit_type *bool_type;
2255 gcc_jit_type *stack_type; /* int[MAX_STACK_DEPTH] */
2256
2257 gcc_jit_rvalue *const_one;
2258
2259 gcc_jit_function *fn;
2260 gcc_jit_param *param_arg;
2261 gcc_jit_lvalue *stack;
2262 gcc_jit_lvalue *stack_depth;
2263 gcc_jit_lvalue *x;
2264 gcc_jit_lvalue *y;
2265
2266 gcc_jit_location *op_locs[MAX_OPS];
2267 gcc_jit_block *initial_block;
2268 gcc_jit_block *op_blocks[MAX_OPS];
2269
2270 @};
2271
2272 @end example
2273 @end quotation
2274
2275 @node Setting things up,Populating the function,Compiling to machine code,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2276 @anchor{intro/tutorial04 setting-things-up}@anchor{3a}
2277 @subsection Setting things up
2278
2279
2280 First we create our types:
2281
2282 @quotation
2283
2284 @example
2285 state.int_type =
2286 gcc_jit_context_get_type (state.ctxt, GCC_JIT_TYPE_INT);
2287 state.bool_type =
2288 gcc_jit_context_get_type (state.ctxt, GCC_JIT_TYPE_BOOL);
2289 state.stack_type =
2290 gcc_jit_context_new_array_type (state.ctxt, NULL,
2291 state.int_type, MAX_STACK_DEPTH);
2292
2293 @end example
2294 @end quotation
2295
2296 along with extracting a useful @cite{int} constant:
2297
2298 @quotation
2299
2300 @example
2301 state.const_one = gcc_jit_context_one (state.ctxt, state.int_type);
2302
2303 @end example
2304 @end quotation
2305
2306 We’ll implement push and pop in terms of the @code{stack} array and
2307 @code{stack_depth}. Here are helper functions for adding statements to
2308 a block, implementing pushing and popping values:
2309
2310 @quotation
2311
2312 @example
2313
2314 static void
2315 add_push (compilation_state *state,
2316 gcc_jit_block *block,
2317 gcc_jit_rvalue *rvalue,
2318 gcc_jit_location *loc)
2319 @{
2320 /* stack[stack_depth] = RVALUE */
2321 gcc_jit_block_add_assignment (
2322 block,
2323 loc,
2324 /* stack[stack_depth] */
2325 gcc_jit_context_new_array_access (
2326 state->ctxt,
2327 loc,
2328 gcc_jit_lvalue_as_rvalue (state->stack),
2329 gcc_jit_lvalue_as_rvalue (state->stack_depth)),
2330 rvalue);
2331
2332 /* "stack_depth++;". */
2333 gcc_jit_block_add_assignment_op (
2334 block,
2335 loc,
2336 state->stack_depth,
2337 GCC_JIT_BINARY_OP_PLUS,
2338 state->const_one);
2339 @}
2340
2341 static void
2342 add_pop (compilation_state *state,
2343 gcc_jit_block *block,
2344 gcc_jit_lvalue *lvalue,
2345 gcc_jit_location *loc)
2346 @{
2347 /* "--stack_depth;". */
2348 gcc_jit_block_add_assignment_op (
2349 block,
2350 loc,
2351 state->stack_depth,
2352 GCC_JIT_BINARY_OP_MINUS,
2353 state->const_one);
2354
2355 /* "LVALUE = stack[stack_depth];". */
2356 gcc_jit_block_add_assignment (
2357 block,
2358 loc,
2359 lvalue,
2360 /* stack[stack_depth] */
2361 gcc_jit_lvalue_as_rvalue (
2362 gcc_jit_context_new_array_access (
2363 state->ctxt,
2364 loc,
2365 gcc_jit_lvalue_as_rvalue (state->stack),
2366 gcc_jit_lvalue_as_rvalue (state->stack_depth))));
2367 @}
2368
2369 @end example
2370 @end quotation
2371
2372 We will support single-stepping through the generated code in the
2373 debugger, so we need to create @ref{3b,,gcc_jit_location} instances, one
2374 per operation in the source code. These will reference the lines of
2375 e.g. @code{factorial.toy}.
2376
2377 @quotation
2378
2379 @example
2380 for (pc = 0; pc < fn->fn_num_ops; pc++)
2381 @{
2382 toyvm_op *op = &fn->fn_ops[pc];
2383
2384 state.op_locs[pc] = gcc_jit_context_new_location (state.ctxt,
2385 fn->fn_filename,
2386 op->op_linenum,
2387 0); /* column */
2388 @}
2389
2390 @end example
2391 @end quotation
2392
2393 Let’s create the function itself. As usual, we create its parameter
2394 first, then use the parameter to create the function:
2395
2396 @quotation
2397
2398 @example
2399 state.param_arg =
2400 gcc_jit_context_new_param (state.ctxt, state.op_locs[0],
2401 state.int_type, "arg");
2402 state.fn =
2403 gcc_jit_context_new_function (state.ctxt,
2404 state.op_locs[0],
2405 GCC_JIT_FUNCTION_EXPORTED,
2406 state.int_type,
2407 funcname,
2408 1, &state.param_arg, 0);
2409
2410 @end example
2411 @end quotation
2412
2413 We create the locals within the function.
2414
2415 @quotation
2416
2417 @example
2418 state.stack =
2419 gcc_jit_function_new_local (state.fn, NULL,
2420 state.stack_type, "stack");
2421 state.stack_depth =
2422 gcc_jit_function_new_local (state.fn, NULL,
2423 state.int_type, "stack_depth");
2424 state.x =
2425 gcc_jit_function_new_local (state.fn, NULL,
2426 state.int_type, "x");
2427 state.y =
2428 gcc_jit_function_new_local (state.fn, NULL,
2429 state.int_type, "y");
2430
2431 @end example
2432 @end quotation
2433
2434 @node Populating the function,Verifying the control flow graph,Setting things up,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2435 @anchor{intro/tutorial04 populating-the-function}@anchor{3c}
2436 @subsection Populating the function
2437
2438
2439 There’s some one-time initialization, and the API treats the first block
2440 you create as the entrypoint of the function, so we need to create that
2441 block first:
2442
2443 @quotation
2444
2445 @example
2446 state.initial_block = gcc_jit_function_new_block (state.fn, "initial");
2447
2448 @end example
2449 @end quotation
2450
2451 We can now create blocks for each of the operations. Most of these will
2452 be consolidated into larger blocks when the optimizer runs.
2453
2454 @quotation
2455
2456 @example
2457 for (pc = 0; pc < fn->fn_num_ops; pc++)
2458 @{
2459 char buf[100];
2460 sprintf (buf, "instr%i", pc);
2461 state.op_blocks[pc] = gcc_jit_function_new_block (state.fn, buf);
2462 @}
2463
2464 @end example
2465 @end quotation
2466
2467 Now that we have a block it can jump to when it’s done, we can populate
2468 the initial block:
2469
2470 @quotation
2471
2472 @example
2473
2474 /* "stack_depth = 0;". */
2475 gcc_jit_block_add_assignment (
2476 state.initial_block,
2477 state.op_locs[0],
2478 state.stack_depth,
2479 gcc_jit_context_zero (state.ctxt, state.int_type));
2480
2481 /* "PUSH (arg);". */
2482 add_push (&state,
2483 state.initial_block,
2484 gcc_jit_param_as_rvalue (state.param_arg),
2485 state.op_locs[0]);
2486
2487 /* ...and jump to insn 0. */
2488 gcc_jit_block_end_with_jump (state.initial_block,
2489 state.op_locs[0],
2490 state.op_blocks[0]);
2491
2492 @end example
2493 @end quotation
2494
2495 We can now populate the blocks for the individual operations. We loop
2496 through them, adding instructions to their blocks:
2497
2498 @quotation
2499
2500 @example
2501 for (pc = 0; pc < fn->fn_num_ops; pc++)
2502 @{
2503 gcc_jit_location *loc = state.op_locs[pc];
2504
2505 gcc_jit_block *block = state.op_blocks[pc];
2506 gcc_jit_block *next_block = (pc < fn->fn_num_ops
2507 ? state.op_blocks[pc + 1]
2508 : NULL);
2509
2510 toyvm_op *op;
2511 op = &fn->fn_ops[pc];
2512
2513 @end example
2514 @end quotation
2515
2516 We’re going to have another big @code{switch} statement for implementing
2517 the opcodes, this time for compiling them, rather than interpreting
2518 them. It’s helpful to have macros for implementing push and pop, so that
2519 we can make the @code{switch} statement that’s coming up look as much as
2520 possible like the one above within the interpreter:
2521
2522 @example
2523
2524 #define X_EQUALS_POP()\
2525 add_pop (&state, block, state.x, loc)
2526 #define Y_EQUALS_POP()\
2527 add_pop (&state, block, state.y, loc)
2528 #define PUSH_RVALUE(RVALUE)\
2529 add_push (&state, block, (RVALUE), loc)
2530 #define PUSH_X()\
2531 PUSH_RVALUE (gcc_jit_lvalue_as_rvalue (state.x))
2532 #define PUSH_Y() \
2533 PUSH_RVALUE (gcc_jit_lvalue_as_rvalue (state.y))
2534
2535 @end example
2536
2537 @cartouche
2538 @quotation Note
2539 A particularly clever implementation would have an @emph{identical}
2540 @code{switch} statement shared by the interpreter and the compiler, with
2541 some preprocessor “magic”. We’re not doing that here, for the sake
2542 of simplicity.
2543 @end quotation
2544 @end cartouche
2545
2546 When I first implemented this compiler, I accidentally missed an edit
2547 when copying and pasting the @code{Y_EQUALS_POP} macro, so that popping the
2548 stack into @code{y} instead erroneously assigned it to @code{x}, leaving @code{y}
2549 uninitialized.
2550
2551 To track this kind of thing down, we can use
2552 @ref{3d,,gcc_jit_block_add_comment()} to add descriptive comments
2553 to the internal representation. This is invaluable when looking through
2554 the generated IR for, say @code{factorial}:
2555
2556 @quotation
2557
2558 @example
2559
2560 gcc_jit_block_add_comment (block, loc, opcode_names[op->op_opcode]);
2561
2562 @end example
2563 @end quotation
2564
2565 We can now write the big @code{switch} statement that implements the
2566 individual opcodes, populating the relevant block with statements:
2567
2568 @quotation
2569
2570 @example
2571
2572 switch (op->op_opcode)
2573 @{
2574 case DUP:
2575 X_EQUALS_POP ();
2576 PUSH_X ();
2577 PUSH_X ();
2578 break;
2579
2580 case ROT:
2581 Y_EQUALS_POP ();
2582 X_EQUALS_POP ();
2583 PUSH_Y ();
2584 PUSH_X ();
2585 break;
2586
2587 case BINARY_ADD:
2588 Y_EQUALS_POP ();
2589 X_EQUALS_POP ();
2590 PUSH_RVALUE (
2591 gcc_jit_context_new_binary_op (
2592 state.ctxt,
2593 loc,
2594 GCC_JIT_BINARY_OP_PLUS,
2595 state.int_type,
2596 gcc_jit_lvalue_as_rvalue (state.x),
2597 gcc_jit_lvalue_as_rvalue (state.y)));
2598 break;
2599
2600 case BINARY_SUBTRACT:
2601 Y_EQUALS_POP ();
2602 X_EQUALS_POP ();
2603 PUSH_RVALUE (
2604 gcc_jit_context_new_binary_op (
2605 state.ctxt,
2606 loc,
2607 GCC_JIT_BINARY_OP_MINUS,
2608 state.int_type,
2609 gcc_jit_lvalue_as_rvalue (state.x),
2610 gcc_jit_lvalue_as_rvalue (state.y)));
2611 break;
2612
2613 case BINARY_MULT:
2614 Y_EQUALS_POP ();
2615 X_EQUALS_POP ();
2616 PUSH_RVALUE (
2617 gcc_jit_context_new_binary_op (
2618 state.ctxt,
2619 loc,
2620 GCC_JIT_BINARY_OP_MULT,
2621 state.int_type,
2622 gcc_jit_lvalue_as_rvalue (state.x),
2623 gcc_jit_lvalue_as_rvalue (state.y)));
2624 break;
2625
2626 case BINARY_COMPARE_LT:
2627 Y_EQUALS_POP ();
2628 X_EQUALS_POP ();
2629 PUSH_RVALUE (
2630 /* cast of bool to int */
2631 gcc_jit_context_new_cast (
2632 state.ctxt,
2633 loc,
2634 /* (x < y) as a bool */
2635 gcc_jit_context_new_comparison (
2636 state.ctxt,
2637 loc,
2638 GCC_JIT_COMPARISON_LT,
2639 gcc_jit_lvalue_as_rvalue (state.x),
2640 gcc_jit_lvalue_as_rvalue (state.y)),
2641 state.int_type));
2642 break;
2643
2644 case RECURSE:
2645 @{
2646 X_EQUALS_POP ();
2647 gcc_jit_rvalue *arg = gcc_jit_lvalue_as_rvalue (state.x);
2648 PUSH_RVALUE (
2649 gcc_jit_context_new_call (
2650 state.ctxt,
2651 loc,
2652 state.fn,
2653 1, &arg));
2654 break;
2655 @}
2656
2657 case RETURN:
2658 X_EQUALS_POP ();
2659 gcc_jit_block_end_with_return (
2660 block,
2661 loc,
2662 gcc_jit_lvalue_as_rvalue (state.x));
2663 break;
2664
2665 /* Ops taking an operand. */
2666 case PUSH_CONST:
2667 PUSH_RVALUE (
2668 gcc_jit_context_new_rvalue_from_int (
2669 state.ctxt,
2670 state.int_type,
2671 op->op_operand));
2672 break;
2673
2674 case JUMP_ABS_IF_TRUE:
2675 X_EQUALS_POP ();
2676 gcc_jit_block_end_with_conditional (
2677 block,
2678 loc,
2679 /* "(bool)x". */
2680 gcc_jit_context_new_cast (
2681 state.ctxt,
2682 loc,
2683 gcc_jit_lvalue_as_rvalue (state.x),
2684 state.bool_type),
2685 state.op_blocks[op->op_operand], /* on_true */
2686 next_block); /* on_false */
2687 break;
2688
2689 default:
2690 assert(0);
2691 @} /* end of switch on opcode */
2692
2693 @end example
2694 @end quotation
2695
2696 Every block must be terminated, via a call to one of the
2697 @code{gcc_jit_block_end_with_} entrypoints. This has been done for two
2698 of the opcodes, but we need to do it for the other ones, by jumping
2699 to the next block.
2700
2701 @quotation
2702
2703 @example
2704 if (op->op_opcode != JUMP_ABS_IF_TRUE
2705 && op->op_opcode != RETURN)
2706 gcc_jit_block_end_with_jump (
2707 block,
2708 loc,
2709 next_block);
2710
2711 @end example
2712 @end quotation
2713
2714 This is analogous to simply incrementing the program counter.
2715
2716 @node Verifying the control flow graph,Compiling the context,Populating the function,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2717 @anchor{intro/tutorial04 verifying-the-control-flow-graph}@anchor{3e}
2718 @subsection Verifying the control flow graph
2719
2720
2721 Having finished looping over the blocks, the context is complete.
2722
2723 As before, we can verify that the control flow and statements are sane by
2724 using @ref{33,,gcc_jit_function_dump_to_dot()}:
2725
2726 @example
2727 gcc_jit_function_dump_to_dot (state.fn, "/tmp/factorial.dot");
2728 @end example
2729
2730 and viewing the result. Note how the label names, comments, and
2731 variable names show up in the dump, to make it easier to spot
2732 errors in our compiler.
2733
2734 @quotation
2735
2736
2737 @float Figure
2738
2739 @image{libgccjit-figures/factorial1,,,image of a control flow graph,png}
2740
2741 @end float
2742
2743 @end quotation
2744
2745 @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
2746 @anchor{intro/tutorial04 compiling-the-context}@anchor{3f}
2747 @subsection Compiling the context
2748
2749
2750 Having finished looping over the blocks and populating them with
2751 statements, the context is complete.
2752
2753 We can now compile it, and extract machine code from the result:
2754
2755 @quotation
2756 @end quotation
2757
2758 We can now run the result:
2759
2760 @quotation
2761
2762 @example
2763 toyvm_compiled_function *compiled_fn
2764 = toyvm_function_compile (fn);
2765
2766 toyvm_compiled_code code = compiled_fn->cf_code;
2767 printf ("compiler result: %d\n",
2768 code (atoi (argv[2])));
2769
2770 gcc_jit_result_release (compiled_fn->cf_jit_result);
2771 free (compiled_fn);
2772
2773 @end example
2774 @end quotation
2775
2776 @node Single-stepping through the generated code,Examining the generated code,Compiling the context,Tutorial part 4 Adding JIT-compilation to a toy interpreter
2777 @anchor{intro/tutorial04 single-stepping-through-the-generated-code}@anchor{40}
2778 @subsection Single-stepping through the generated code
2779
2780
2781 It’s possible to debug the generated code. To do this we need to both:
2782
2783 @quotation
2784
2785
2786 @itemize *
2787
2788 @item
2789 Set up source code locations for our statements, so that we can
2790 meaningfully step through the code. We did this above by
2791 calling @ref{41,,gcc_jit_context_new_location()} and using the
2792 results.
2793
2794 @item
2795 Enable the generation of debugging information, by setting
2796 @ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
2797 @ref{8,,gcc_jit_context} via
2798 @ref{1b,,gcc_jit_context_set_bool_option()}:
2799
2800 @example
2801 gcc_jit_context_set_bool_option (
2802 ctxt,
2803 GCC_JIT_BOOL_OPTION_DEBUGINFO,
2804 1);
2805 @end example
2806 @end itemize
2807 @end quotation
2808
2809 Having done this, we can put a breakpoint on the generated function:
2810
2811 @example
2812 $ gdb --args ./toyvm factorial.toy 10
2813 (gdb) break factorial
2814 Function "factorial" not defined.
2815 Make breakpoint pending on future shared library load? (y or [n]) y
2816 Breakpoint 1 (factorial) pending.
2817 (gdb) run
2818 Breakpoint 1, factorial (arg=10) at factorial.toy:14
2819 14 DUP
2820 @end example
2821
2822 We’ve set up location information, which references @code{factorial.toy}.
2823 This allows us to use e.g. @code{list} to see where we are in the script:
2824
2825 @example
2826 (gdb) list
2827 9
2828 10 # Initial state:
2829 11 # stack: [arg]
2830 12
2831 13 # 0:
2832 14 DUP
2833 15 # stack: [arg, arg]
2834 16
2835 17 # 1:
2836 18 PUSH_CONST 2
2837 @end example
2838
2839 and to step through the function, examining the data:
2840
2841 @example
2842 (gdb) n
2843 18 PUSH_CONST 2
2844 (gdb) n
2845 22 BINARY_COMPARE_LT
2846 (gdb) print stack
2847 $5 = @{10, 10, 2, 0, -7152, 32767, 0, 0@}
2848 (gdb) print stack_depth
2849 $6 = 3
2850 @end example
2851
2852 You’ll see that the parts of the @code{stack} array that haven’t been
2853 touched yet are uninitialized.
2854
2855 @cartouche
2856 @quotation Note
2857 Turning on optimizations may lead to unpredictable results when
2858 stepping through the generated code: the execution may appear to
2859 “jump around” the source code. This is analogous to turning up the
2860 optimization level in a regular compiler.
2861 @end quotation
2862 @end cartouche
2863
2864 @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
2865 @anchor{intro/tutorial04 examining-the-generated-code}@anchor{43}
2866 @subsection Examining the generated code
2867
2868
2869 How good is the optimized code?
2870
2871 We can turn up optimizations, by calling
2872 @ref{1e,,gcc_jit_context_set_int_option()} with
2873 @ref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
2874
2875 @example
2876 gcc_jit_context_set_int_option (
2877 ctxt,
2878 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL,
2879 3);
2880 @end example
2881
2882 One of GCC’s internal representations is called “gimple”. A dump of the
2883 initial gimple representation of the code can be seen by setting:
2884
2885 @example
2886 gcc_jit_context_set_bool_option (ctxt,
2887 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE,
2888 1);
2889 @end example
2890
2891 With optimization on and source locations displayed, this gives:
2892
2893 @c We'll use "c" for gimple dumps
2894
2895 @example
2896 factorial (signed int arg)
2897 @{
2898 <unnamed type> D.80;
2899 signed int D.81;
2900 signed int D.82;
2901 signed int D.83;
2902 signed int D.84;
2903 signed int D.85;
2904 signed int y;
2905 signed int x;
2906 signed int stack_depth;
2907 signed int stack[8];
2908
2909 try
2910 @{
2911 initial:
2912 stack_depth = 0;
2913 stack[stack_depth] = arg;
2914 stack_depth = stack_depth + 1;
2915 goto instr0;
2916 instr0:
2917 /* DUP */:
2918 stack_depth = stack_depth + -1;
2919 x = stack[stack_depth];
2920 stack[stack_depth] = x;
2921 stack_depth = stack_depth + 1;
2922 stack[stack_depth] = x;
2923 stack_depth = stack_depth + 1;
2924 goto instr1;
2925 instr1:
2926 /* PUSH_CONST */:
2927 stack[stack_depth] = 2;
2928 stack_depth = stack_depth + 1;
2929 goto instr2;
2930
2931 /* etc */
2932 @end example
2933
2934 You can see the generated machine code in assembly form via:
2935
2936 @example
2937 gcc_jit_context_set_bool_option (
2938 ctxt,
2939 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
2940 1);
2941 result = gcc_jit_context_compile (ctxt);
2942 @end example
2943
2944 which shows that (on this x86_64 box) the compiler has unrolled the loop
2945 and is using MMX instructions to perform several multiplications
2946 simultaneously:
2947
2948 @example
2949 .file "fake.c"
2950 .text
2951 .Ltext0:
2952 .p2align 4,,15
2953 .globl factorial
2954 .type factorial, @@function
2955 factorial:
2956 .LFB0:
2957 .file 1 "factorial.toy"
2958 .loc 1 14 0
2959 .cfi_startproc
2960 .LVL0:
2961 .L2:
2962 .loc 1 26 0
2963 cmpl $1, %edi
2964 jle .L13
2965 leal -1(%rdi), %edx
2966 movl %edx, %ecx
2967 shrl $2, %ecx
2968 leal 0(,%rcx,4), %esi
2969 testl %esi, %esi
2970 je .L14
2971 cmpl $9, %edx
2972 jbe .L14
2973 leal -2(%rdi), %eax
2974 movl %eax, -16(%rsp)
2975 leal -3(%rdi), %eax
2976 movd -16(%rsp), %xmm0
2977 movl %edi, -16(%rsp)
2978 movl %eax, -12(%rsp)
2979 movd -16(%rsp), %xmm1
2980 xorl %eax, %eax
2981 movl %edx, -16(%rsp)
2982 movd -12(%rsp), %xmm4
2983 movd -16(%rsp), %xmm6
2984 punpckldq %xmm4, %xmm0
2985 movdqa .LC1(%rip), %xmm4
2986 punpckldq %xmm6, %xmm1
2987 punpcklqdq %xmm0, %xmm1
2988 movdqa .LC0(%rip), %xmm0
2989 jmp .L5
2990 # etc - edited for brevity
2991 @end example
2992
2993 This is clearly overkill for a function that will likely overflow the
2994 @code{int} type before the vectorization is worthwhile - but then again, this
2995 is a toy example.
2996
2997 Turning down the optimization level to 2:
2998
2999 @example
3000 gcc_jit_context_set_int_option (
3001 ctxt,
3002 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL,
3003 3);
3004 @end example
3005
3006 yields this code, which is simple enough to quote in its entirety:
3007
3008 @example
3009 .file "fake.c"
3010 .text
3011 .p2align 4,,15
3012 .globl factorial
3013 .type factorial, @@function
3014 factorial:
3015 .LFB0:
3016 .cfi_startproc
3017 .L2:
3018 cmpl $1, %edi
3019 jle .L8
3020 movl $1, %edx
3021 jmp .L4
3022 .p2align 4,,10
3023 .p2align 3
3024 .L6:
3025 movl %eax, %edi
3026 .L4:
3027 .L5:
3028 leal -1(%rdi), %eax
3029 imull %edi, %edx
3030 cmpl $1, %eax
3031 jne .L6
3032 .L3:
3033 .L7:
3034 imull %edx, %eax
3035 ret
3036 .L8:
3037 movl %edi, %eax
3038 movl $1, %edx
3039 jmp .L7
3040 .cfi_endproc
3041 .LFE0:
3042 .size factorial, .-factorial
3043 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-%@{gcc_release@})"
3044 .section .note.GNU-stack,"",@@progbits
3045 @end example
3046
3047 Note that the stack pushing and popping have been eliminated, as has the
3048 recursive call (in favor of an iteration).
3049
3050 @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
3051 @anchor{intro/tutorial04 putting-it-all-together}@anchor{44}
3052 @subsection Putting it all together
3053
3054
3055 The complete example can be seen in the source tree at
3056 @code{gcc/jit/docs/examples/tut04-toyvm/toyvm.c}
3057
3058 along with a Makefile and a couple of sample .toy scripts:
3059
3060 @example
3061 $ ls -al
3062 drwxrwxr-x. 2 david david 4096 Sep 19 17:46 .
3063 drwxrwxr-x. 3 david david 4096 Sep 19 15:26 ..
3064 -rw-rw-r--. 1 david david 615 Sep 19 12:43 factorial.toy
3065 -rw-rw-r--. 1 david david 834 Sep 19 13:08 fibonacci.toy
3066 -rw-rw-r--. 1 david david 238 Sep 19 14:22 Makefile
3067 -rw-rw-r--. 1 david david 16457 Sep 19 17:07 toyvm.c
3068
3069 $ make toyvm
3070 g++ -Wall -g -o toyvm toyvm.c -lgccjit
3071
3072 $ ./toyvm factorial.toy 10
3073 interpreter result: 3628800
3074 compiler result: 3628800
3075
3076 $ ./toyvm fibonacci.toy 10
3077 interpreter result: 55
3078 compiler result: 55
3079 @end example
3080
3081 @node Behind the curtain How does our code get optimized?,,Putting it all together,Tutorial part 4 Adding JIT-compilation to a toy interpreter
3082 @anchor{intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{45}
3083 @subsection Behind the curtain: How does our code get optimized?
3084
3085
3086 Our example is done, but you may be wondering about exactly how the
3087 compiler turned what we gave it into the machine code seen above.
3088
3089 We can examine what the compiler is doing in detail by setting:
3090
3091 @example
3092 gcc_jit_context_set_bool_option (state.ctxt,
3093 GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING,
3094 1);
3095 gcc_jit_context_set_bool_option (state.ctxt,
3096 GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES,
3097 1);
3098 @end example
3099
3100 This will dump detailed information about the compiler’s state to a
3101 directory under @code{/tmp}, and keep it from being cleaned up.
3102
3103 The precise names and their formats of these files is subject to change.
3104 Higher optimization levels lead to more files.
3105 Here’s what I saw (edited for brevity; there were almost 200 files):
3106
3107 @example
3108 intermediate files written to /tmp/libgccjit-KPQbGw
3109 $ ls /tmp/libgccjit-KPQbGw/
3110 fake.c.000i.cgraph
3111 fake.c.000i.type-inheritance
3112 fake.c.004t.gimple
3113 fake.c.007t.omplower
3114 fake.c.008t.lower
3115 fake.c.011t.eh
3116 fake.c.012t.cfg
3117 fake.c.014i.visibility
3118 fake.c.015i.early_local_cleanups
3119 fake.c.016t.ssa
3120 # etc
3121 @end example
3122
3123 The gimple code is converted into Static Single Assignment form,
3124 with annotations for use when generating the debuginfo:
3125
3126 @example
3127 $ less /tmp/libgccjit-KPQbGw/fake.c.016t.ssa
3128 @end example
3129
3130 @example
3131 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3132
3133 factorial (signed int arg)
3134 @{
3135 signed int stack[8];
3136 signed int stack_depth;
3137 signed int x;
3138 signed int y;
3139 <unnamed type> _20;
3140 signed int _21;
3141 signed int _38;
3142 signed int _44;
3143 signed int _51;
3144 signed int _56;
3145
3146 initial:
3147 stack_depth_3 = 0;
3148 # DEBUG stack_depth => stack_depth_3
3149 stack[stack_depth_3] = arg_5(D);
3150 stack_depth_7 = stack_depth_3 + 1;
3151 # DEBUG stack_depth => stack_depth_7
3152 # DEBUG instr0 => NULL
3153 # DEBUG /* DUP */ => NULL
3154 stack_depth_8 = stack_depth_7 + -1;
3155 # DEBUG stack_depth => stack_depth_8
3156 x_9 = stack[stack_depth_8];
3157 # DEBUG x => x_9
3158 stack[stack_depth_8] = x_9;
3159 stack_depth_11 = stack_depth_8 + 1;
3160 # DEBUG stack_depth => stack_depth_11
3161 stack[stack_depth_11] = x_9;
3162 stack_depth_13 = stack_depth_11 + 1;
3163 # DEBUG stack_depth => stack_depth_13
3164 # DEBUG instr1 => NULL
3165 # DEBUG /* PUSH_CONST */ => NULL
3166 stack[stack_depth_13] = 2;
3167
3168 /* etc; edited for brevity */
3169 @end example
3170
3171 We can perhaps better see the code by turning off
3172 @ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to suppress all those @code{DEBUG}
3173 statements, giving:
3174
3175 @example
3176 $ less /tmp/libgccjit-1Hywc0/fake.c.016t.ssa
3177 @end example
3178
3179 @example
3180 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3181
3182 factorial (signed int arg)
3183 @{
3184 signed int stack[8];
3185 signed int stack_depth;
3186 signed int x;
3187 signed int y;
3188 <unnamed type> _20;
3189 signed int _21;
3190 signed int _38;
3191 signed int _44;
3192 signed int _51;
3193 signed int _56;
3194
3195 initial:
3196 stack_depth_3 = 0;
3197 stack[stack_depth_3] = arg_5(D);
3198 stack_depth_7 = stack_depth_3 + 1;
3199 stack_depth_8 = stack_depth_7 + -1;
3200 x_9 = stack[stack_depth_8];
3201 stack[stack_depth_8] = x_9;
3202 stack_depth_11 = stack_depth_8 + 1;
3203 stack[stack_depth_11] = x_9;
3204 stack_depth_13 = stack_depth_11 + 1;
3205 stack[stack_depth_13] = 2;
3206 stack_depth_15 = stack_depth_13 + 1;
3207 stack_depth_16 = stack_depth_15 + -1;
3208 y_17 = stack[stack_depth_16];
3209 stack_depth_18 = stack_depth_16 + -1;
3210 x_19 = stack[stack_depth_18];
3211 _20 = x_19 < y_17;
3212 _21 = (signed int) _20;
3213 stack[stack_depth_18] = _21;
3214 stack_depth_23 = stack_depth_18 + 1;
3215 stack_depth_24 = stack_depth_23 + -1;
3216 x_25 = stack[stack_depth_24];
3217 if (x_25 != 0)
3218 goto <bb 4> (instr9);
3219 else
3220 goto <bb 3> (instr4);
3221
3222 instr4:
3223 /* DUP */:
3224 stack_depth_26 = stack_depth_24 + -1;
3225 x_27 = stack[stack_depth_26];
3226 stack[stack_depth_26] = x_27;
3227 stack_depth_29 = stack_depth_26 + 1;
3228 stack[stack_depth_29] = x_27;
3229 stack_depth_31 = stack_depth_29 + 1;
3230 stack[stack_depth_31] = 1;
3231 stack_depth_33 = stack_depth_31 + 1;
3232 stack_depth_34 = stack_depth_33 + -1;
3233 y_35 = stack[stack_depth_34];
3234 stack_depth_36 = stack_depth_34 + -1;
3235 x_37 = stack[stack_depth_36];
3236 _38 = x_37 - y_35;
3237 stack[stack_depth_36] = _38;
3238 stack_depth_40 = stack_depth_36 + 1;
3239 stack_depth_41 = stack_depth_40 + -1;
3240 x_42 = stack[stack_depth_41];
3241 _44 = factorial (x_42);
3242 stack[stack_depth_41] = _44;
3243 stack_depth_46 = stack_depth_41 + 1;
3244 stack_depth_47 = stack_depth_46 + -1;
3245 y_48 = stack[stack_depth_47];
3246 stack_depth_49 = stack_depth_47 + -1;
3247 x_50 = stack[stack_depth_49];
3248 _51 = x_50 * y_48;
3249 stack[stack_depth_49] = _51;
3250 stack_depth_53 = stack_depth_49 + 1;
3251
3252 # stack_depth_1 = PHI <stack_depth_24(2), stack_depth_53(3)>
3253 instr9:
3254 /* RETURN */:
3255 stack_depth_54 = stack_depth_1 + -1;
3256 x_55 = stack[stack_depth_54];
3257 _56 = x_55;
3258 stack =@{v@} @{CLOBBER@};
3259 return _56;
3260
3261 @}
3262 @end example
3263
3264 Note in the above how all the @ref{28,,gcc_jit_block} instances we
3265 created have been consolidated into just 3 blocks in GCC’s internal
3266 representation: @code{initial}, @code{instr4} and @code{instr9}.
3267
3268 @menu
3269 * Optimizing away stack manipulation::
3270 * Elimination of tail recursion::
3271
3272 @end menu
3273
3274 @node Optimizing away stack manipulation,Elimination of tail recursion,,Behind the curtain How does our code get optimized?
3275 @anchor{intro/tutorial04 optimizing-away-stack-manipulation}@anchor{46}
3276 @subsubsection Optimizing away stack manipulation
3277
3278
3279 Recall our simple implementation of stack operations. Let’s examine
3280 how the stack operations are optimized away.
3281
3282 After a pass of constant-propagation, the depth of the stack at each
3283 opcode can be determined at compile-time:
3284
3285 @example
3286 $ less /tmp/libgccjit-1Hywc0/fake.c.021t.ccp1
3287 @end example
3288
3289 @example
3290 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3291
3292 factorial (signed int arg)
3293 @{
3294 signed int stack[8];
3295 signed int stack_depth;
3296 signed int x;
3297 signed int y;
3298 <unnamed type> _20;
3299 signed int _21;
3300 signed int _38;
3301 signed int _44;
3302 signed int _51;
3303
3304 initial:
3305 stack[0] = arg_5(D);
3306 x_9 = stack[0];
3307 stack[0] = x_9;
3308 stack[1] = x_9;
3309 stack[2] = 2;
3310 y_17 = stack[2];
3311 x_19 = stack[1];
3312 _20 = x_19 < y_17;
3313 _21 = (signed int) _20;
3314 stack[1] = _21;
3315 x_25 = stack[1];
3316 if (x_25 != 0)
3317 goto <bb 4> (instr9);
3318 else
3319 goto <bb 3> (instr4);
3320
3321 instr4:
3322 /* DUP */:
3323 x_27 = stack[0];
3324 stack[0] = x_27;
3325 stack[1] = x_27;
3326 stack[2] = 1;
3327 y_35 = stack[2];
3328 x_37 = stack[1];
3329 _38 = x_37 - y_35;
3330 stack[1] = _38;
3331 x_42 = stack[1];
3332 _44 = factorial (x_42);
3333 stack[1] = _44;
3334 y_48 = stack[1];
3335 x_50 = stack[0];
3336 _51 = x_50 * y_48;
3337 stack[0] = _51;
3338
3339 instr9:
3340 /* RETURN */:
3341 x_55 = stack[0];
3342 x_56 = x_55;
3343 stack =@{v@} @{CLOBBER@};
3344 return x_56;
3345
3346 @}
3347 @end example
3348
3349 Note how, in the above, all those @code{stack_depth} values are now just
3350 constants: we’re accessing specific stack locations at each opcode.
3351
3352 The “esra” pass (“Early Scalar Replacement of Aggregates”) breaks
3353 out our “stack” array into individual elements:
3354
3355 @example
3356 $ less /tmp/libgccjit-1Hywc0/fake.c.024t.esra
3357 @end example
3358
3359 @example
3360 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3361
3362 Created a replacement for stack offset: 0, size: 32: stack$0
3363 Created a replacement for stack offset: 32, size: 32: stack$1
3364 Created a replacement for stack offset: 64, size: 32: stack$2
3365
3366 Symbols to be put in SSA form
3367 @{ D.89 D.90 D.91 @}
3368 Incremental SSA update started at block: 0
3369 Number of blocks in CFG: 5
3370 Number of blocks to update: 4 ( 80%)
3371
3372
3373 factorial (signed int arg)
3374 @{
3375 signed int stack$2;
3376 signed int stack$1;
3377 signed int stack$0;
3378 signed int stack[8];
3379 signed int stack_depth;
3380 signed int x;
3381 signed int y;
3382 <unnamed type> _20;
3383 signed int _21;
3384 signed int _38;
3385 signed int _44;
3386 signed int _51;
3387
3388 initial:
3389 stack$0_45 = arg_5(D);
3390 x_9 = stack$0_45;
3391 stack$0_39 = x_9;
3392 stack$1_32 = x_9;
3393 stack$2_30 = 2;
3394 y_17 = stack$2_30;
3395 x_19 = stack$1_32;
3396 _20 = x_19 < y_17;
3397 _21 = (signed int) _20;
3398 stack$1_28 = _21;
3399 x_25 = stack$1_28;
3400 if (x_25 != 0)
3401 goto <bb 4> (instr9);
3402 else
3403 goto <bb 3> (instr4);
3404
3405 instr4:
3406 /* DUP */:
3407 x_27 = stack$0_39;
3408 stack$0_22 = x_27;
3409 stack$1_14 = x_27;
3410 stack$2_12 = 1;
3411 y_35 = stack$2_12;
3412 x_37 = stack$1_14;
3413 _38 = x_37 - y_35;
3414 stack$1_10 = _38;
3415 x_42 = stack$1_10;
3416 _44 = factorial (x_42);
3417 stack$1_6 = _44;
3418 y_48 = stack$1_6;
3419 x_50 = stack$0_22;
3420 _51 = x_50 * y_48;
3421 stack$0_1 = _51;
3422
3423 # stack$0_52 = PHI <stack$0_39(2), stack$0_1(3)>
3424 instr9:
3425 /* RETURN */:
3426 x_55 = stack$0_52;
3427 x_56 = x_55;
3428 stack =@{v@} @{CLOBBER@};
3429 return x_56;
3430
3431 @}
3432 @end example
3433
3434 Hence at this point, all those pushes and pops of the stack are now
3435 simply assignments to specific temporary variables.
3436
3437 After some copy propagation, the stack manipulation has been completely
3438 optimized away:
3439
3440 @example
3441 $ less /tmp/libgccjit-1Hywc0/fake.c.026t.copyprop1
3442 @end example
3443
3444 @example
3445 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3446
3447 factorial (signed int arg)
3448 @{
3449 signed int stack$2;
3450 signed int stack$1;
3451 signed int stack$0;
3452 signed int stack[8];
3453 signed int stack_depth;
3454 signed int x;
3455 signed int y;
3456 <unnamed type> _20;
3457 signed int _21;
3458 signed int _38;
3459 signed int _44;
3460 signed int _51;
3461
3462 initial:
3463 stack$0_39 = arg_5(D);
3464 _20 = arg_5(D) <= 1;
3465 _21 = (signed int) _20;
3466 if (_21 != 0)
3467 goto <bb 4> (instr9);
3468 else
3469 goto <bb 3> (instr4);
3470
3471 instr4:
3472 /* DUP */:
3473 _38 = arg_5(D) + -1;
3474 _44 = factorial (_38);
3475 _51 = arg_5(D) * _44;
3476 stack$0_1 = _51;
3477
3478 # stack$0_52 = PHI <arg_5(D)(2), _51(3)>
3479 instr9:
3480 /* RETURN */:
3481 stack =@{v@} @{CLOBBER@};
3482 return stack$0_52;
3483
3484 @}
3485 @end example
3486
3487 Later on, another pass finally eliminated @code{stack_depth} local and the
3488 unused parts of the @cite{stack`} array altogether:
3489
3490 @example
3491 $ less /tmp/libgccjit-1Hywc0/fake.c.036t.release_ssa
3492 @end example
3493
3494 @example
3495 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3496
3497 Released 44 names, 314.29%, removed 44 holes
3498 factorial (signed int arg)
3499 @{
3500 signed int stack$0;
3501 signed int mult_acc_1;
3502 <unnamed type> _5;
3503 signed int _6;
3504 signed int _7;
3505 signed int mul_tmp_10;
3506 signed int mult_acc_11;
3507 signed int mult_acc_13;
3508
3509 # arg_9 = PHI <arg_8(D)(0)>
3510 # mult_acc_13 = PHI <1(0)>
3511 initial:
3512
3513 <bb 5>:
3514 # arg_4 = PHI <arg_9(2), _7(3)>
3515 # mult_acc_1 = PHI <mult_acc_13(2), mult_acc_11(3)>
3516 _5 = arg_4 <= 1;
3517 _6 = (signed int) _5;
3518 if (_6 != 0)
3519 goto <bb 4> (instr9);
3520 else
3521 goto <bb 3> (instr4);
3522
3523 instr4:
3524 /* DUP */:
3525 _7 = arg_4 + -1;
3526 mult_acc_11 = mult_acc_1 * arg_4;
3527 goto <bb 5>;
3528
3529 # stack$0_12 = PHI <arg_4(5)>
3530 instr9:
3531 /* RETURN */:
3532 mul_tmp_10 = mult_acc_1 * stack$0_12;
3533 return mul_tmp_10;
3534
3535 @}
3536 @end example
3537
3538 @node Elimination of tail recursion,,Optimizing away stack manipulation,Behind the curtain How does our code get optimized?
3539 @anchor{intro/tutorial04 elimination-of-tail-recursion}@anchor{47}
3540 @subsubsection Elimination of tail recursion
3541
3542
3543 Another significant optimization is the detection that the call to
3544 @code{factorial} is tail recursion, which can be eliminated in favor of
3545 an iteration:
3546
3547 @example
3548 $ less /tmp/libgccjit-1Hywc0/fake.c.030t.tailr1
3549 @end example
3550
3551 @example
3552 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
3553
3554
3555 Symbols to be put in SSA form
3556 @{ D.88 @}
3557 Incremental SSA update started at block: 0
3558 Number of blocks in CFG: 5
3559 Number of blocks to update: 4 ( 80%)
3560
3561
3562 factorial (signed int arg)
3563 @{
3564 signed int stack$2;
3565 signed int stack$1;
3566 signed int stack$0;
3567 signed int stack[8];
3568 signed int stack_depth;
3569 signed int x;
3570 signed int y;
3571 signed int mult_acc_1;
3572 <unnamed type> _20;
3573 signed int _21;
3574 signed int _38;
3575 signed int mul_tmp_44;
3576 signed int mult_acc_51;
3577
3578 # arg_5 = PHI <arg_39(D)(0), _38(3)>
3579 # mult_acc_1 = PHI <1(0), mult_acc_51(3)>
3580 initial:
3581 _20 = arg_5 <= 1;
3582 _21 = (signed int) _20;
3583 if (_21 != 0)
3584 goto <bb 4> (instr9);
3585 else
3586 goto <bb 3> (instr4);
3587
3588 instr4:
3589 /* DUP */:
3590 _38 = arg_5 + -1;
3591 mult_acc_51 = mult_acc_1 * arg_5;
3592 goto <bb 2> (initial);
3593
3594 # stack$0_52 = PHI <arg_5(2)>
3595 instr9:
3596 /* RETURN */:
3597 stack =@{v@} @{CLOBBER@};
3598 mul_tmp_44 = mult_acc_1 * stack$0_52;
3599 return mul_tmp_44;
3600
3601 @}
3602 @end example
3603
3604 @c Copyright (C) 2015-2022 Free Software Foundation, Inc.
3605 @c Originally contributed by David Malcolm <[email protected]>
3606 @c
3607 @c This is free software: you can redistribute it and/or modify it
3608 @c under the terms of the GNU General Public License as published by
3609 @c the Free Software Foundation, either version 3 of the License, or
3610 @c (at your option) any later version.
3611 @c
3612 @c This program is distributed in the hope that it will be useful, but
3613 @c WITHOUT ANY WARRANTY; without even the implied warranty of
3614 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
3615 @c General Public License for more details.
3616 @c
3617 @c You should have received a copy of the GNU General Public License
3618 @c along with this program. If not, see
3619 @c <https://www.gnu.org/licenses/>.
3620
3621 @node Tutorial part 5 Implementing an Ahead-of-Time compiler,,Tutorial part 4 Adding JIT-compilation to a toy interpreter,Tutorial
3622 @anchor{intro/tutorial05 doc}@anchor{48}@anchor{intro/tutorial05 tutorial-part-5-implementing-an-ahead-of-time-compiler}@anchor{49}
3623 @section Tutorial part 5: Implementing an Ahead-of-Time compiler
3624
3625
3626 If you have a pre-existing language frontend that’s compatible with
3627 libgccjit’s license, it’s possible to hook it up to libgccjit as a
3628 backend. In the previous example we showed
3629 how to do that for in-memory JIT-compilation, but libgccjit can also
3630 compile code directly to a file, allowing you to implement a more
3631 traditional ahead-of-time compiler (“JIT” is something of a misnomer
3632 for this use-case).
3633
3634 The essential difference is to compile the context using
3635 @ref{4a,,gcc_jit_context_compile_to_file()} rather than
3636 @ref{15,,gcc_jit_context_compile()}.
3637
3638 @menu
3639 * The “brainf” language::
3640 * Converting a brainf script to libgccjit IR::
3641 * Compiling a context to a file::
3642 * Other forms of ahead-of-time-compilation::
3643
3644 @end menu
3645
3646 @node The “brainf” language,Converting a brainf script to libgccjit IR,,Tutorial part 5 Implementing an Ahead-of-Time compiler
3647 @anchor{intro/tutorial05 the-brainf-language}@anchor{4b}
3648 @subsection The “brainf” language
3649
3650
3651 In this example we use libgccjit to construct an ahead-of-time compiler
3652 for an esoteric programming language that we shall refer to as “brainf”.
3653
3654 brainf scripts operate on an array of bytes, with a notional data pointer
3655 within the array.
3656
3657 brainf is hard for humans to read, but it’s trivial to write a parser for
3658 it, as there is no lexing; just a stream of bytes. The operations are:
3659
3660
3661 @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
3662 @headitem
3663
3664 Character
3665
3666 @tab
3667
3668 Meaning
3669
3670 @item
3671
3672 @code{>}
3673
3674 @tab
3675
3676 @code{idx += 1}
3677
3678 @item
3679
3680 @code{<}
3681
3682 @tab
3683
3684 @code{idx -= 1}
3685
3686 @item
3687
3688 @code{+}
3689
3690 @tab
3691
3692 @code{data[idx] += 1}
3693
3694 @item
3695
3696 @code{-}
3697
3698 @tab
3699
3700 @code{data[idx] -= 1}
3701
3702 @item
3703
3704 @code{.}
3705
3706 @tab
3707
3708 @code{output (data[idx])}
3709
3710 @item
3711
3712 @code{,}
3713
3714 @tab
3715
3716 @code{data[idx] = input ()}
3717
3718 @item
3719
3720 @code{[}
3721
3722 @tab
3723
3724 loop until @code{data[idx] == 0}
3725
3726 @item
3727
3728 @code{]}
3729
3730 @tab
3731
3732 end of loop
3733
3734 @item
3735
3736 Anything else
3737
3738 @tab
3739
3740 ignored
3741
3742 @end multitable
3743
3744
3745 Unlike the previous example, we’ll implement an ahead-of-time compiler,
3746 which reads @code{.bf} scripts and outputs executables (though it would
3747 be trivial to have it run them JIT-compiled in-process).
3748
3749 Here’s what a simple @code{.bf} script looks like:
3750
3751 @quotation
3752
3753 @example
3754 [
3755 Emit the uppercase alphabet
3756 ]
3757
3758 cell 0 = 26
3759 ++++++++++++++++++++++++++
3760
3761 cell 1 = 65
3762 >+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++<
3763
3764 while cell#0 != 0
3765 [
3766 >
3767 . emit cell#1
3768 + increment cell@@1
3769 <- decrement cell@@0
3770 ]
3771 @end example
3772 @end quotation
3773
3774 @cartouche
3775 @quotation Note
3776 This example makes use of whitespace and comments for legibility, but
3777 could have been written as:
3778
3779 @example
3780 ++++++++++++++++++++++++++
3781 >+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++<
3782 [>.+<-]
3783 @end example
3784
3785 It’s not a particularly useful language, except for providing
3786 compiler-writers with a test case that’s easy to parse. The point
3787 is that you can use @ref{4a,,gcc_jit_context_compile_to_file()}
3788 to use libgccjit as a backend for a pre-existing language frontend
3789 (provided that the pre-existing frontend is compatible with libgccjit’s
3790 license).
3791 @end quotation
3792 @end cartouche
3793
3794 @node Converting a brainf script to libgccjit IR,Compiling a context to a file,The “brainf” language,Tutorial part 5 Implementing an Ahead-of-Time compiler
3795 @anchor{intro/tutorial05 converting-a-brainf-script-to-libgccjit-ir}@anchor{4c}
3796 @subsection Converting a brainf script to libgccjit IR
3797
3798
3799 As before we write simple code to populate a @ref{8,,gcc_jit_context *}.
3800
3801 @quotation
3802
3803 @example
3804
3805 typedef struct bf_compiler
3806 @{
3807 const char *filename;
3808 int line;
3809 int column;
3810
3811 gcc_jit_context *ctxt;
3812
3813 gcc_jit_type *void_type;
3814 gcc_jit_type *int_type;
3815 gcc_jit_type *byte_type;
3816 gcc_jit_type *array_type;
3817
3818 gcc_jit_function *func_getchar;
3819 gcc_jit_function *func_putchar;
3820
3821 gcc_jit_function *func;
3822 gcc_jit_block *curblock;
3823
3824 gcc_jit_rvalue *int_zero;
3825 gcc_jit_rvalue *int_one;
3826 gcc_jit_rvalue *byte_zero;
3827 gcc_jit_rvalue *byte_one;
3828 gcc_jit_lvalue *data_cells;
3829 gcc_jit_lvalue *idx;
3830
3831 int num_open_parens;
3832 gcc_jit_block *paren_test[MAX_OPEN_PARENS];
3833 gcc_jit_block *paren_body[MAX_OPEN_PARENS];
3834 gcc_jit_block *paren_after[MAX_OPEN_PARENS];
3835
3836 @} bf_compiler;
3837
3838 /* Bail out, with a message on stderr. */
3839
3840 static void
3841 fatal_error (bf_compiler *bfc, const char *msg)
3842 @{
3843 fprintf (stderr,
3844 "%s:%i:%i: %s",
3845 bfc->filename, bfc->line, bfc->column, msg);
3846 abort ();
3847 @}
3848
3849 /* Get "data_cells[idx]" as an lvalue. */
3850
3851 static gcc_jit_lvalue *
3852 bf_get_current_data (bf_compiler *bfc, gcc_jit_location *loc)
3853 @{
3854 return gcc_jit_context_new_array_access (
3855 bfc->ctxt,
3856 loc,
3857 gcc_jit_lvalue_as_rvalue (bfc->data_cells),
3858 gcc_jit_lvalue_as_rvalue (bfc->idx));
3859 @}
3860
3861 /* Get "data_cells[idx] == 0" as a boolean rvalue. */
3862
3863 static gcc_jit_rvalue *
3864 bf_current_data_is_zero (bf_compiler *bfc, gcc_jit_location *loc)
3865 @{
3866 return gcc_jit_context_new_comparison (
3867 bfc->ctxt,
3868 loc,
3869 GCC_JIT_COMPARISON_EQ,
3870 gcc_jit_lvalue_as_rvalue (bf_get_current_data (bfc, loc)),
3871 bfc->byte_zero);
3872 @}
3873
3874 /* Compile one bf character. */
3875
3876 static void
3877 bf_compile_char (bf_compiler *bfc,
3878 unsigned char ch)
3879 @{
3880 gcc_jit_location *loc =
3881 gcc_jit_context_new_location (bfc->ctxt,
3882 bfc->filename,
3883 bfc->line,
3884 bfc->column);
3885
3886 /* Turn this on to trace execution, by injecting putchar ()
3887 of each source char. */
3888 if (0)
3889 @{
3890 gcc_jit_rvalue *arg =
3891 gcc_jit_context_new_rvalue_from_int (
3892 bfc->ctxt,
3893 bfc->int_type,
3894 ch);
3895 gcc_jit_rvalue *call =
3896 gcc_jit_context_new_call (bfc->ctxt,
3897 loc,
3898 bfc->func_putchar,
3899 1, &arg);
3900 gcc_jit_block_add_eval (bfc->curblock,
3901 loc,
3902 call);
3903 @}
3904
3905 switch (ch)
3906 @{
3907 case '>':
3908 gcc_jit_block_add_comment (bfc->curblock,
3909 loc,
3910 "'>': idx += 1;");
3911 gcc_jit_block_add_assignment_op (bfc->curblock,
3912 loc,
3913 bfc->idx,
3914 GCC_JIT_BINARY_OP_PLUS,
3915 bfc->int_one);
3916 break;
3917
3918 case '<':
3919 gcc_jit_block_add_comment (bfc->curblock,
3920 loc,
3921 "'<': idx -= 1;");
3922 gcc_jit_block_add_assignment_op (bfc->curblock,
3923 loc,
3924 bfc->idx,
3925 GCC_JIT_BINARY_OP_MINUS,
3926 bfc->int_one);
3927 break;
3928
3929 case '+':
3930 gcc_jit_block_add_comment (bfc->curblock,
3931 loc,
3932 "'+': data[idx] += 1;");
3933 gcc_jit_block_add_assignment_op (bfc->curblock,
3934 loc,
3935 bf_get_current_data (bfc, loc),
3936 GCC_JIT_BINARY_OP_PLUS,
3937 bfc->byte_one);
3938 break;
3939
3940 case '-':
3941 gcc_jit_block_add_comment (bfc->curblock,
3942 loc,
3943 "'-': data[idx] -= 1;");
3944 gcc_jit_block_add_assignment_op (bfc->curblock,
3945 loc,
3946 bf_get_current_data (bfc, loc),
3947 GCC_JIT_BINARY_OP_MINUS,
3948 bfc->byte_one);
3949 break;
3950
3951 case '.':
3952 @{
3953 gcc_jit_rvalue *arg =
3954 gcc_jit_context_new_cast (
3955 bfc->ctxt,
3956 loc,
3957 gcc_jit_lvalue_as_rvalue (bf_get_current_data (bfc, loc)),
3958 bfc->int_type);
3959 gcc_jit_rvalue *call =
3960 gcc_jit_context_new_call (bfc->ctxt,
3961 loc,
3962 bfc->func_putchar,
3963 1, &arg);
3964 gcc_jit_block_add_comment (bfc->curblock,
3965 loc,
3966 "'.': putchar ((int)data[idx]);");
3967 gcc_jit_block_add_eval (bfc->curblock,
3968 loc,
3969 call);
3970 @}
3971 break;
3972
3973 case ',':
3974 @{
3975 gcc_jit_rvalue *call =
3976 gcc_jit_context_new_call (bfc->ctxt,
3977 loc,
3978 bfc->func_getchar,
3979 0, NULL);
3980 gcc_jit_block_add_comment (
3981 bfc->curblock,
3982 loc,
3983 "',': data[idx] = (unsigned char)getchar ();");
3984 gcc_jit_block_add_assignment (bfc->curblock,
3985 loc,
3986 bf_get_current_data (bfc, loc),
3987 gcc_jit_context_new_cast (
3988 bfc->ctxt,
3989 loc,
3990 call,
3991 bfc->byte_type));
3992 @}
3993 break;
3994
3995 case '[':
3996 @{
3997 gcc_jit_block *loop_test =
3998 gcc_jit_function_new_block (bfc->func, NULL);
3999 gcc_jit_block *on_zero =
4000 gcc_jit_function_new_block (bfc->func, NULL);
4001 gcc_jit_block *on_non_zero =
4002 gcc_jit_function_new_block (bfc->func, NULL);
4003
4004 if (bfc->num_open_parens == MAX_OPEN_PARENS)
4005 fatal_error (bfc, "too many open parens");
4006
4007 gcc_jit_block_end_with_jump (
4008 bfc->curblock,
4009 loc,
4010 loop_test);
4011
4012 gcc_jit_block_add_comment (
4013 loop_test,
4014 loc,
4015 "'['");
4016 gcc_jit_block_end_with_conditional (
4017 loop_test,
4018 loc,
4019 bf_current_data_is_zero (bfc, loc),
4020 on_zero,
4021 on_non_zero);
4022 bfc->paren_test[bfc->num_open_parens] = loop_test;
4023 bfc->paren_body[bfc->num_open_parens] = on_non_zero;
4024 bfc->paren_after[bfc->num_open_parens] = on_zero;
4025 bfc->num_open_parens += 1;
4026 bfc->curblock = on_non_zero;
4027 @}
4028 break;
4029
4030 case ']':
4031 @{
4032 gcc_jit_block_add_comment (
4033 bfc->curblock,
4034 loc,
4035 "']'");
4036
4037 if (bfc->num_open_parens == 0)
4038 fatal_error (bfc, "mismatching parens");
4039 bfc->num_open_parens -= 1;
4040 gcc_jit_block_end_with_jump (
4041 bfc->curblock,
4042 loc,
4043 bfc->paren_test[bfc->num_open_parens]);
4044 bfc->curblock = bfc->paren_after[bfc->num_open_parens];
4045 @}
4046 break;
4047
4048 case '\n':
4049 bfc->line +=1;
4050 bfc->column = 0;
4051 break;
4052 @}
4053
4054 if (ch != '\n')
4055 bfc->column += 1;
4056 @}
4057
4058 /* Compile the given .bf file into a gcc_jit_context, containing a
4059 single "main" function suitable for compiling into an executable. */
4060
4061 gcc_jit_context *
4062 bf_compile (const char *filename)
4063 @{
4064 bf_compiler bfc;
4065 FILE *f_in;
4066 int ch;
4067
4068 memset (&bfc, 0, sizeof (bfc));
4069
4070 bfc.filename = filename;
4071 f_in = fopen (filename, "r");
4072 if (!f_in)
4073 fatal_error (&bfc, "unable to open file");
4074 bfc.line = 1;
4075
4076 bfc.ctxt = gcc_jit_context_acquire ();
4077
4078 gcc_jit_context_set_int_option (
4079 bfc.ctxt,
4080 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL,
4081 3);
4082 gcc_jit_context_set_bool_option (
4083 bfc.ctxt,
4084 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE,
4085 0);
4086 gcc_jit_context_set_bool_option (
4087 bfc.ctxt,
4088 GCC_JIT_BOOL_OPTION_DEBUGINFO,
4089 1);
4090 gcc_jit_context_set_bool_option (
4091 bfc.ctxt,
4092 GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING,
4093 0);
4094 gcc_jit_context_set_bool_option (
4095 bfc.ctxt,
4096 GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES,
4097 0);
4098
4099 bfc.void_type =
4100 gcc_jit_context_get_type (bfc.ctxt, GCC_JIT_TYPE_VOID);
4101 bfc.int_type =
4102 gcc_jit_context_get_type (bfc.ctxt, GCC_JIT_TYPE_INT);
4103 bfc.byte_type =
4104 gcc_jit_context_get_type (bfc.ctxt, GCC_JIT_TYPE_UNSIGNED_CHAR);
4105 bfc.array_type =
4106 gcc_jit_context_new_array_type (bfc.ctxt,
4107 NULL,
4108 bfc.byte_type,
4109 30000);
4110
4111 bfc.func_getchar =
4112 gcc_jit_context_new_function (bfc.ctxt, NULL,
4113 GCC_JIT_FUNCTION_IMPORTED,
4114 bfc.int_type,
4115 "getchar",
4116 0, NULL,
4117 0);
4118
4119 gcc_jit_param *param_c =
4120 gcc_jit_context_new_param (bfc.ctxt, NULL, bfc.int_type, "c");
4121 bfc.func_putchar =
4122 gcc_jit_context_new_function (bfc.ctxt, NULL,
4123 GCC_JIT_FUNCTION_IMPORTED,
4124 bfc.void_type,
4125 "putchar",
4126 1, &param_c,
4127 0);
4128
4129 bfc.func = make_main (bfc.ctxt);
4130 bfc.curblock =
4131 gcc_jit_function_new_block (bfc.func, "initial");
4132 bfc.int_zero = gcc_jit_context_zero (bfc.ctxt, bfc.int_type);
4133 bfc.int_one = gcc_jit_context_one (bfc.ctxt, bfc.int_type);
4134 bfc.byte_zero = gcc_jit_context_zero (bfc.ctxt, bfc.byte_type);
4135 bfc.byte_one = gcc_jit_context_one (bfc.ctxt, bfc.byte_type);
4136
4137 bfc.data_cells =
4138 gcc_jit_context_new_global (bfc.ctxt, NULL,
4139 GCC_JIT_GLOBAL_INTERNAL,
4140 bfc.array_type,
4141 "data_cells");
4142 bfc.idx =
4143 gcc_jit_function_new_local (bfc.func, NULL,
4144 bfc.int_type,
4145 "idx");
4146
4147 gcc_jit_block_add_comment (bfc.curblock,
4148 NULL,
4149 "idx = 0;");
4150 gcc_jit_block_add_assignment (bfc.curblock,
4151 NULL,
4152 bfc.idx,
4153 bfc.int_zero);
4154
4155 bfc.num_open_parens = 0;
4156
4157 while ( EOF != (ch = fgetc (f_in)))
4158 bf_compile_char (&bfc, (unsigned char)ch);
4159
4160 gcc_jit_block_end_with_return (bfc.curblock, NULL, bfc.int_zero);
4161
4162 fclose (f_in);
4163
4164 return bfc.ctxt;
4165 @}
4166
4167 @end example
4168 @end quotation
4169
4170 @node Compiling a context to a file,Other forms of ahead-of-time-compilation,Converting a brainf script to libgccjit IR,Tutorial part 5 Implementing an Ahead-of-Time compiler
4171 @anchor{intro/tutorial05 compiling-a-context-to-a-file}@anchor{4d}
4172 @subsection Compiling a context to a file
4173
4174
4175 Unlike the previous tutorial, this time we’ll compile the context
4176 directly to an executable, using @ref{4a,,gcc_jit_context_compile_to_file()}:
4177
4178 @example
4179 gcc_jit_context_compile_to_file (ctxt,
4180 GCC_JIT_OUTPUT_KIND_EXECUTABLE,
4181 output_file);
4182 @end example
4183
4184 Here’s the top-level of the compiler, which is what actually calls into
4185 @ref{4a,,gcc_jit_context_compile_to_file()}:
4186
4187 @quotation
4188
4189 @example
4190
4191 int
4192 main (int argc, char **argv)
4193 @{
4194 const char *input_file;
4195 const char *output_file;
4196 gcc_jit_context *ctxt;
4197 const char *err;
4198
4199 if (argc != 3)
4200 @{
4201 fprintf (stderr, "%s: INPUT_FILE OUTPUT_FILE\n", argv[0]);
4202 return 1;
4203 @}
4204
4205 input_file = argv[1];
4206 output_file = argv[2];
4207 ctxt = bf_compile (input_file);
4208
4209 gcc_jit_context_compile_to_file (ctxt,
4210 GCC_JIT_OUTPUT_KIND_EXECUTABLE,
4211 output_file);
4212
4213 err = gcc_jit_context_get_first_error (ctxt);
4214
4215 if (err)
4216 @{
4217 gcc_jit_context_release (ctxt);
4218 return 1;
4219 @}
4220
4221 gcc_jit_context_release (ctxt);
4222 return 0;
4223 @}
4224
4225 @end example
4226 @end quotation
4227
4228 Note how once the context is populated you could trivially instead compile
4229 it to memory using @ref{15,,gcc_jit_context_compile()} and run it in-process
4230 as in the previous tutorial.
4231
4232 To create an executable, we need to export a @code{main} function. Here’s
4233 how to create one from the JIT API:
4234
4235 @quotation
4236
4237 @example
4238
4239 /* Make "main" function:
4240 int
4241 main (int argc, char **argv)
4242 @{
4243 ...
4244 @}
4245 */
4246 static gcc_jit_function *
4247 make_main (gcc_jit_context *ctxt)
4248 @{
4249 gcc_jit_type *int_type =
4250 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
4251 gcc_jit_param *param_argc =
4252 gcc_jit_context_new_param (ctxt, NULL, int_type, "argc");
4253 gcc_jit_type *char_ptr_ptr_type =
4254 gcc_jit_type_get_pointer (
4255 gcc_jit_type_get_pointer (
4256 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_CHAR)));
4257 gcc_jit_param *param_argv =
4258 gcc_jit_context_new_param (ctxt, NULL, char_ptr_ptr_type, "argv");
4259 gcc_jit_param *params[2] = @{param_argc, param_argv@};
4260 gcc_jit_function *func_main =
4261 gcc_jit_context_new_function (ctxt, NULL,
4262 GCC_JIT_FUNCTION_EXPORTED,
4263 int_type,
4264 "main",
4265 2, params,
4266 0);
4267 return func_main;
4268 @}
4269
4270 @end example
4271 @end quotation
4272
4273 @cartouche
4274 @quotation Note
4275 The above implementation ignores @code{argc} and @code{argv}, but you could
4276 make use of them by exposing @code{param_argc} and @code{param_argv} to the
4277 caller.
4278 @end quotation
4279 @end cartouche
4280
4281 Upon compiling this C code, we obtain a bf-to-machine-code compiler;
4282 let’s call it @code{bfc}:
4283
4284 @example
4285 $ gcc \
4286 tut05-bf.c \
4287 -o bfc \
4288 -lgccjit
4289 @end example
4290
4291 We can now use @code{bfc} to compile .bf files into machine code executables:
4292
4293 @example
4294 $ ./bfc \
4295 emit-alphabet.bf \
4296 a.out
4297 @end example
4298
4299 which we can run directly:
4300
4301 @example
4302 $ ./a.out
4303 ABCDEFGHIJKLMNOPQRSTUVWXYZ
4304 @end example
4305
4306 Success!
4307
4308 We can also inspect the generated executable using standard tools:
4309
4310 @example
4311 $ objdump -d a.out |less
4312 @end example
4313
4314 which shows that libgccjit has managed to optimize the function
4315 somewhat (for example, the runs of 26 and 65 increment operations
4316 have become integer constants 0x1a and 0x41):
4317
4318 @example
4319 0000000000400620 <main>:
4320 400620: 80 3d 39 0a 20 00 00 cmpb $0x0,0x200a39(%rip) # 601060 <data
4321 400627: 74 07 je 400630 <main
4322 400629: eb fe jmp 400629 <main+0x9>
4323 40062b: 0f 1f 44 00 00 nopl 0x0(%rax,%rax,1)
4324 400630: 48 83 ec 08 sub $0x8,%rsp
4325 400634: 0f b6 05 26 0a 20 00 movzbl 0x200a26(%rip),%eax # 601061 <data_cells+0x1>
4326 40063b: c6 05 1e 0a 20 00 1a movb $0x1a,0x200a1e(%rip) # 601060 <data_cells>
4327 400642: 8d 78 41 lea 0x41(%rax),%edi
4328 400645: 40 88 3d 15 0a 20 00 mov %dil,0x200a15(%rip) # 601061 <data_cells+0x1>
4329 40064c: 0f 1f 40 00 nopl 0x0(%rax)
4330 400650: 40 0f b6 ff movzbl %dil,%edi
4331 400654: e8 87 fe ff ff callq 4004e0 <putchar@@plt>
4332 400659: 0f b6 05 01 0a 20 00 movzbl 0x200a01(%rip),%eax # 601061 <data_cells+0x1>
4333 400660: 80 2d f9 09 20 00 01 subb $0x1,0x2009f9(%rip) # 601060 <data_cells>
4334 400667: 8d 78 01 lea 0x1(%rax),%edi
4335 40066a: 40 88 3d f0 09 20 00 mov %dil,0x2009f0(%rip) # 601061 <data_cells+0x1>
4336 400671: 75 dd jne 400650 <main+0x30>
4337 400673: 31 c0 xor %eax,%eax
4338 400675: 48 83 c4 08 add $0x8,%rsp
4339 400679: c3 retq
4340 40067a: 66 0f 1f 44 00 00 nopw 0x0(%rax,%rax,1)
4341 @end example
4342
4343 We also set up debugging information (via
4344 @ref{41,,gcc_jit_context_new_location()} and
4345 @ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO}), so it’s possible to use @code{gdb}
4346 to singlestep through the generated binary and inspect the internal
4347 state @code{idx} and @code{data_cells}:
4348
4349 @example
4350 (gdb) break main
4351 Breakpoint 1 at 0x400790
4352 (gdb) run
4353 Starting program: a.out
4354
4355 Breakpoint 1, 0x0000000000400790 in main (argc=1, argv=0x7fffffffe448)
4356 (gdb) stepi
4357 0x0000000000400797 in main (argc=1, argv=0x7fffffffe448)
4358 (gdb) stepi
4359 0x00000000004007a0 in main (argc=1, argv=0x7fffffffe448)
4360 (gdb) stepi
4361 9 >+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++<
4362 (gdb) list
4363 4
4364 5 cell 0 = 26
4365 6 ++++++++++++++++++++++++++
4366 7
4367 8 cell 1 = 65
4368 9 >+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++<
4369 10
4370 11 while cell#0 != 0
4371 12 [
4372 13 >
4373 (gdb) n
4374 6 ++++++++++++++++++++++++++
4375 (gdb) n
4376 9 >+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++<
4377 (gdb) p idx
4378 $1 = 1
4379 (gdb) p data_cells
4380 $2 = "\032", '\000' <repeats 29998 times>
4381 (gdb) p data_cells[0]
4382 $3 = 26 '\032'
4383 (gdb) p data_cells[1]
4384 $4 = 0 '\000'
4385 (gdb) list
4386 4
4387 5 cell 0 = 26
4388 6 ++++++++++++++++++++++++++
4389 7
4390 8 cell 1 = 65
4391 9 >+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++<
4392 10
4393 11 while cell#0 != 0
4394 12 [
4395 13 >
4396 @end example
4397
4398 @node Other forms of ahead-of-time-compilation,,Compiling a context to a file,Tutorial part 5 Implementing an Ahead-of-Time compiler
4399 @anchor{intro/tutorial05 other-forms-of-ahead-of-time-compilation}@anchor{4e}
4400 @subsection Other forms of ahead-of-time-compilation
4401
4402
4403 The above demonstrates compiling a @ref{8,,gcc_jit_context *} directly
4404 to an executable. It’s also possible to compile it to an object file,
4405 and to a dynamic library. See the documentation of
4406 @ref{4a,,gcc_jit_context_compile_to_file()} for more information.
4407
4408 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
4409 @c Originally contributed by David Malcolm <[email protected]>
4410 @c
4411 @c This is free software: you can redistribute it and/or modify it
4412 @c under the terms of the GNU General Public License as published by
4413 @c the Free Software Foundation, either version 3 of the License, or
4414 @c (at your option) any later version.
4415 @c
4416 @c This program is distributed in the hope that it will be useful, but
4417 @c WITHOUT ANY WARRANTY; without even the implied warranty of
4418 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4419 @c General Public License for more details.
4420 @c
4421 @c You should have received a copy of the GNU General Public License
4422 @c along with this program. If not, see
4423 @c <https://www.gnu.org/licenses/>.
4424
4425 @node Topic Reference,C++ bindings for libgccjit,Tutorial,Top
4426 @anchor{topics/index doc}@anchor{4f}@anchor{topics/index topic-reference}@anchor{50}
4427 @chapter Topic Reference
4428
4429
4430 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
4431 @c Originally contributed by David Malcolm <[email protected]>
4432 @c
4433 @c This is free software: you can redistribute it and/or modify it
4434 @c under the terms of the GNU General Public License as published by
4435 @c the Free Software Foundation, either version 3 of the License, or
4436 @c (at your option) any later version.
4437 @c
4438 @c This program is distributed in the hope that it will be useful, but
4439 @c WITHOUT ANY WARRANTY; without even the implied warranty of
4440 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4441 @c General Public License for more details.
4442 @c
4443 @c You should have received a copy of the GNU General Public License
4444 @c along with this program. If not, see
4445 @c <https://www.gnu.org/licenses/>.
4446
4447 @menu
4448 * Compilation contexts::
4449 * Objects::
4450 * Types::
4451 * Expressions::
4452 * Creating and using functions::
4453 * Function pointers: Function pointers<2>.
4454 * Source Locations::
4455 * Compiling a context::
4456 * ABI and API compatibility::
4457 * Performance::
4458 * Using Assembly Language with libgccjit::
4459
4460 @end menu
4461
4462 @node Compilation contexts,Objects,,Topic Reference
4463 @anchor{topics/contexts doc}@anchor{51}@anchor{topics/contexts compilation-contexts}@anchor{52}
4464 @section Compilation contexts
4465
4466
4467 @geindex gcc_jit_context (C type)
4468 @anchor{topics/contexts c gcc_jit_context}@anchor{8}
4469 @deffn {C Type} gcc_jit_context
4470 @end deffn
4471
4472 The top-level of the API is the @ref{8,,gcc_jit_context} type.
4473
4474 A @ref{8,,gcc_jit_context} instance encapsulates the state of a
4475 compilation.
4476
4477 You can set up options on it, and add types, functions and code.
4478 Invoking @ref{15,,gcc_jit_context_compile()} on it gives you a
4479 @ref{16,,gcc_jit_result}.
4480
4481 @menu
4482 * Lifetime-management::
4483 * Thread-safety::
4484 * Error-handling: Error-handling<2>.
4485 * Debugging::
4486 * Options: Options<2>.
4487
4488 @end menu
4489
4490 @node Lifetime-management,Thread-safety,,Compilation contexts
4491 @anchor{topics/contexts lifetime-management}@anchor{53}
4492 @subsection Lifetime-management
4493
4494
4495 Contexts are the unit of lifetime-management within the API: objects
4496 have their lifetime bounded by the context they are created within, and
4497 cleanup of such objects is done for you when the context is released.
4498
4499 @geindex gcc_jit_context_acquire (C function)
4500 @anchor{topics/contexts c gcc_jit_context_acquire}@anchor{9}
4501 @deffn {C Function} gcc_jit_context *gcc_jit_context_acquire (void)
4502
4503 This function acquires a new @ref{8,,gcc_jit_context *} instance,
4504 which is independent of any others that may be present within this
4505 process.
4506 @end deffn
4507
4508 @geindex gcc_jit_context_release (C function)
4509 @anchor{topics/contexts c gcc_jit_context_release}@anchor{c}
4510 @deffn {C Function} void gcc_jit_context_release (gcc_jit_context@w{ }*ctxt)
4511
4512 This function releases all resources associated with the given context.
4513 Both the context itself and all of its @ref{e,,gcc_jit_object *}
4514 instances are cleaned up. It should be called exactly once on a given
4515 context.
4516
4517 It is invalid to use the context or any of its “contextual” objects
4518 after calling this.
4519
4520 @example
4521 gcc_jit_context_release (ctxt);
4522 @end example
4523 @end deffn
4524
4525 @geindex gcc_jit_context_new_child_context (C function)
4526 @anchor{topics/contexts c gcc_jit_context_new_child_context}@anchor{54}
4527 @deffn {C Function} gcc_jit_context * gcc_jit_context_new_child_context (gcc_jit_context@w{ }*parent_ctxt)
4528
4529 Given an existing JIT context, create a child context.
4530
4531 The child inherits a copy of all option-settings from the parent.
4532
4533 The child can reference objects created within the parent, but not
4534 vice-versa.
4535
4536 The lifetime of the child context must be bounded by that of the
4537 parent: you should release a child context before releasing the parent
4538 context.
4539
4540 If you use a function from a parent context within a child context,
4541 you have to compile the parent context before you can compile the
4542 child context, and the gcc_jit_result of the parent context must
4543 outlive the gcc_jit_result of the child context.
4544
4545 This allows caching of shared initializations. For example, you could
4546 create types and declarations of global functions in a parent context
4547 once within a process, and then create child contexts whenever a
4548 function or loop becomes hot. Each such child context can be used for
4549 JIT-compiling just one function or loop, but can reference types
4550 and helper functions created within the parent context.
4551
4552 Contexts can be arbitrarily nested, provided the above rules are
4553 followed, but it’s probably not worth going above 2 or 3 levels, and
4554 there will likely be a performance hit for such nesting.
4555 @end deffn
4556
4557 @node Thread-safety,Error-handling<2>,Lifetime-management,Compilation contexts
4558 @anchor{topics/contexts thread-safety}@anchor{55}
4559 @subsection Thread-safety
4560
4561
4562 Instances of @ref{8,,gcc_jit_context *} created via
4563 @ref{9,,gcc_jit_context_acquire()} are independent from each other:
4564 only one thread may use a given context at once, but multiple threads
4565 could each have their own contexts without needing locks.
4566
4567 Contexts created via @ref{54,,gcc_jit_context_new_child_context()} are
4568 related to their parent context. They can be partitioned by their
4569 ultimate ancestor into independent “family trees”. Only one thread
4570 within a process may use a given “family tree” of such contexts at once,
4571 and if you’re using multiple threads you should provide your own locking
4572 around entire such context partitions.
4573
4574 @node Error-handling<2>,Debugging,Thread-safety,Compilation contexts
4575 @anchor{topics/contexts error-handling}@anchor{19}@anchor{topics/contexts id1}@anchor{56}
4576 @subsection Error-handling
4577
4578
4579 Various kinds of errors are possible when using the API, such as
4580 mismatched types in an assignment. You can only compile and get code from
4581 a context if no errors occur.
4582
4583 Errors are printed on stderr and can be queried using
4584 @ref{57,,gcc_jit_context_get_first_error()}.
4585
4586 They typically contain the name of the API entrypoint where the error
4587 occurred, and pertinent information on the problem:
4588
4589 @example
4590 ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *)
4591 @end example
4592
4593 In general, if an error occurs when using an API entrypoint, the
4594 entrypoint returns NULL. You don’t have to check everywhere for NULL
4595 results, since the API handles a NULL being passed in for any
4596 argument by issuing another error. This typically leads to a cascade of
4597 followup error messages, but is safe (albeit verbose). The first error
4598 message is usually the one to pay attention to, since it is likely to
4599 be responsible for all of the rest:
4600
4601 @geindex gcc_jit_context_get_first_error (C function)
4602 @anchor{topics/contexts c gcc_jit_context_get_first_error}@anchor{57}
4603 @deffn {C Function} const char * gcc_jit_context_get_first_error (gcc_jit_context@w{ }*ctxt)
4604
4605 Returns the first error message that occurred on the context.
4606
4607 The returned string is valid for the rest of the lifetime of the
4608 context.
4609
4610 If no errors occurred, this will be NULL.
4611 @end deffn
4612
4613 If you are wrapping the C API for a higher-level language that supports
4614 exception-handling, you may instead be interested in the last error that
4615 occurred on the context, so that you can embed this in an exception:
4616
4617 @geindex gcc_jit_context_get_last_error (C function)
4618 @anchor{topics/contexts c gcc_jit_context_get_last_error}@anchor{58}
4619 @deffn {C Function} const char * gcc_jit_context_get_last_error (gcc_jit_context@w{ }*ctxt)
4620
4621 Returns the last error message that occurred on the context.
4622
4623 If no errors occurred, this will be NULL.
4624
4625 If non-NULL, the returned string is only guaranteed to be valid until
4626 the next call to libgccjit relating to this context.
4627 @end deffn
4628
4629 @node Debugging,Options<2>,Error-handling<2>,Compilation contexts
4630 @anchor{topics/contexts debugging}@anchor{59}
4631 @subsection Debugging
4632
4633
4634 @geindex gcc_jit_context_dump_to_file (C function)
4635 @anchor{topics/contexts c gcc_jit_context_dump_to_file}@anchor{5a}
4636 @deffn {C Function} void gcc_jit_context_dump_to_file (gcc_jit_context@w{ }*ctxt, const char@w{ }*path, int@w{ }update_locations)
4637
4638 To help with debugging: dump a C-like representation to the given path,
4639 describing what’s been set up on the context.
4640
4641 If “update_locations” is true, then also set up @ref{3b,,gcc_jit_location}
4642 information throughout the context, pointing at the dump file as if it
4643 were a source file. This may be of use in conjunction with
4644 @ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to allow stepping through the
4645 code in a debugger.
4646 @end deffn
4647
4648 @geindex gcc_jit_context_set_logfile (C function)
4649 @anchor{topics/contexts c gcc_jit_context_set_logfile}@anchor{5b}
4650 @deffn {C Function} void gcc_jit_context_set_logfile (gcc_jit_context@w{ }*ctxt, FILE@w{ }*logfile, int@w{ }flags, int@w{ }verbosity)
4651
4652 To help with debugging; enable ongoing logging of the context’s
4653 activity to the given file.
4654
4655 For example, the following will enable logging to stderr.
4656
4657 @example
4658 gcc_jit_context_set_logfile (ctxt, stderr, 0, 0);
4659 @end example
4660
4661 Examples of information logged include:
4662
4663
4664 @itemize *
4665
4666 @item
4667 API calls
4668
4669 @item
4670 the various steps involved within compilation
4671
4672 @item
4673 activity on any @ref{16,,gcc_jit_result} instances created by
4674 the context
4675
4676 @item
4677 activity within any child contexts
4678 @end itemize
4679
4680 An example of a log can be seen @ref{5c,,here},
4681 though the precise format and kinds of information logged is subject
4682 to change.
4683
4684 The caller remains responsible for closing @cite{logfile}, and it must not
4685 be closed until all users are released. In particular, note that
4686 child contexts and @ref{16,,gcc_jit_result} instances created by
4687 the context will use the logfile.
4688
4689 There may a performance cost for logging.
4690
4691 You can turn off logging on @cite{ctxt} by passing @cite{NULL} for @cite{logfile}.
4692 Doing so only affects the context; it does not affect child contexts
4693 or @ref{16,,gcc_jit_result} instances already created by
4694 the context.
4695
4696 The parameters “flags” and “verbosity” are reserved for future
4697 expansion, and must be zero for now.
4698 @end deffn
4699
4700 To contrast the above: @ref{5a,,gcc_jit_context_dump_to_file()} dumps the
4701 current state of a context to the given path, whereas
4702 @ref{5b,,gcc_jit_context_set_logfile()} enables on-going logging of
4703 future activies on a context to the given @cite{FILE *}.
4704
4705 @geindex gcc_jit_context_dump_reproducer_to_file (C function)
4706 @anchor{topics/contexts c gcc_jit_context_dump_reproducer_to_file}@anchor{5d}
4707 @deffn {C Function} void gcc_jit_context_dump_reproducer_to_file (gcc_jit_context@w{ }*ctxt, const char@w{ }*path)
4708
4709 Write C source code into @cite{path} that can be compiled into a
4710 self-contained executable (i.e. with libgccjit as the only dependency).
4711 The generated code will attempt to replay the API calls that have been
4712 made into the given context.
4713
4714 This may be useful when debugging the library or client code, for
4715 reducing a complicated recipe for reproducing a bug into a simpler
4716 form. For example, consider client code that parses some source file
4717 into some internal representation, and then walks this IR, calling into
4718 libgccjit. If this encounters a bug, a call to
4719 @cite{gcc_jit_context_dump_reproducer_to_file} will write out C code for
4720 a much simpler executable that performs the equivalent calls into
4721 libgccjit, without needing the client code and its data.
4722
4723 Typically you need to supply @code{-Wno-unused-variable} when
4724 compiling the generated file (since the result of each API call is
4725 assigned to a unique variable within the generated C source, and not
4726 all are necessarily then used).
4727 @end deffn
4728
4729 @geindex gcc_jit_context_enable_dump (C function)
4730 @anchor{topics/contexts c gcc_jit_context_enable_dump}@anchor{5e}
4731 @deffn {C Function} void gcc_jit_context_enable_dump (gcc_jit_context@w{ }*ctxt, const char@w{ }*dumpname, char@w{ }**out_ptr)
4732
4733 Enable the dumping of a specific set of internal state from the
4734 compilation, capturing the result in-memory as a buffer.
4735
4736 Parameter “dumpname” corresponds to the equivalent gcc command-line
4737 option, without the “-fdump-” prefix.
4738 For example, to get the equivalent of @code{-fdump-tree-vrp1},
4739 supply @code{"tree-vrp1"}:
4740
4741 @example
4742 static char *dump_vrp1;
4743
4744 void
4745 create_code (gcc_jit_context *ctxt)
4746 @{
4747 gcc_jit_context_enable_dump (ctxt, "tree-vrp1", &dump_vrp1);
4748 /* (other API calls omitted for brevity) */
4749 @}
4750 @end example
4751
4752 The context directly stores the dumpname as a @code{(const char *)}, so
4753 the passed string must outlive the context.
4754
4755 @ref{15,,gcc_jit_context_compile()} will capture the dump as a
4756 dynamically-allocated buffer, writing it to @code{*out_ptr}.
4757
4758 The caller becomes responsible for calling:
4759
4760 @example
4761 free (*out_ptr)
4762 @end example
4763
4764 each time that @ref{15,,gcc_jit_context_compile()} is called.
4765 @code{*out_ptr} will be written to, either with the address of a buffer,
4766 or with @code{NULL} if an error occurred.
4767
4768 @cartouche
4769 @quotation Warning
4770 This API entrypoint is likely to be less stable than the others.
4771 In particular, both the precise dumpnames, and the format and content
4772 of the dumps are subject to change.
4773
4774 It exists primarily for writing the library’s own test suite.
4775 @end quotation
4776 @end cartouche
4777 @end deffn
4778
4779 @node Options<2>,,Debugging,Compilation contexts
4780 @anchor{topics/contexts options}@anchor{5f}
4781 @subsection Options
4782
4783
4784 Options present in the initial release of libgccjit were handled using
4785 enums, whereas those added subsequently have their own per-option API
4786 entrypoints.
4787
4788 Adding entrypoints for each new option means that client code that use
4789 the new options can be identified directly from binary metadata, which
4790 would not be possible if we instead extended the various
4791 @code{enum gcc_jit_*_option}.
4792
4793 @menu
4794 * String Options::
4795 * Boolean options::
4796 * Integer options::
4797 * Additional command-line options::
4798
4799 @end menu
4800
4801 @node String Options,Boolean options,,Options<2>
4802 @anchor{topics/contexts string-options}@anchor{60}
4803 @subsubsection String Options
4804
4805
4806 @geindex gcc_jit_context_set_str_option (C function)
4807 @anchor{topics/contexts c gcc_jit_context_set_str_option}@anchor{61}
4808 @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)
4809
4810 Set a string option of the context.
4811
4812 @geindex gcc_jit_str_option (C type)
4813 @anchor{topics/contexts c gcc_jit_str_option}@anchor{62}
4814 @deffn {C Type} enum gcc_jit_str_option
4815 @end deffn
4816
4817 The parameter @code{value} can be NULL. If non-NULL, the call takes a
4818 copy of the underlying string, so it is valid to pass in a pointer to
4819 an on-stack buffer.
4820
4821 There is just one string option specified this way:
4822
4823 @geindex GCC_JIT_STR_OPTION_PROGNAME (C macro)
4824 @anchor{topics/contexts c GCC_JIT_STR_OPTION_PROGNAME}@anchor{63}
4825 @deffn {C Macro} GCC_JIT_STR_OPTION_PROGNAME
4826
4827 The name of the program, for use as a prefix when printing error
4828 messages to stderr. If @cite{NULL}, or default, “libgccjit.so” is used.
4829 @end deffn
4830 @end deffn
4831
4832 @node Boolean options,Integer options,String Options,Options<2>
4833 @anchor{topics/contexts boolean-options}@anchor{64}
4834 @subsubsection Boolean options
4835
4836
4837 @geindex gcc_jit_context_set_bool_option (C function)
4838 @anchor{topics/contexts c gcc_jit_context_set_bool_option}@anchor{1b}
4839 @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)
4840
4841 Set a boolean option of the context.
4842 Zero is “false” (the default), non-zero is “true”.
4843
4844 @geindex gcc_jit_bool_option (C type)
4845 @anchor{topics/contexts c gcc_jit_bool_option}@anchor{65}
4846 @deffn {C Type} enum gcc_jit_bool_option
4847 @end deffn
4848
4849 @geindex GCC_JIT_BOOL_OPTION_DEBUGINFO (C macro)
4850 @anchor{topics/contexts c GCC_JIT_BOOL_OPTION_DEBUGINFO}@anchor{42}
4851 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DEBUGINFO
4852
4853 If true, @ref{15,,gcc_jit_context_compile()} will attempt to do the right
4854 thing so that if you attach a debugger to the process, it will
4855 be able to inspect variables and step through your code.
4856
4857 Note that you can’t step through code unless you set up source
4858 location information for the code (by creating and passing in
4859 @ref{3b,,gcc_jit_location} instances).
4860 @end deffn
4861
4862 @geindex GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE (C macro)
4863 @anchor{topics/contexts c GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}@anchor{66}
4864 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE
4865
4866 If true, @ref{15,,gcc_jit_context_compile()} will dump its initial
4867 “tree” representation of your code to stderr (before any
4868 optimizations).
4869
4870 Here’s some sample output (from the @cite{square} example):
4871
4872 @example
4873 <statement_list 0x7f4875a62cc0
4874 type <void_type 0x7f4875a64bd0 VOID
4875 align 8 symtab 0 alias set -1 canonical type 0x7f4875a64bd0
4876 pointer_to_this <pointer_type 0x7f4875a64c78>>
4877 side-effects head 0x7f4875a761e0 tail 0x7f4875a761f8 stmts 0x7f4875a62d20 0x7f4875a62d00
4878
4879 stmt <label_expr 0x7f4875a62d20 type <void_type 0x7f4875a64bd0>
4880 side-effects
4881 arg 0 <label_decl 0x7f4875a79080 entry type <void_type 0x7f4875a64bd0>
4882 VOID file (null) line 0 col 0
4883 align 1 context <function_decl 0x7f4875a77500 square>>>
4884 stmt <return_expr 0x7f4875a62d00
4885 type <integer_type 0x7f4875a645e8 public SI
4886 size <integer_cst 0x7f4875a623a0 constant 32>
4887 unit size <integer_cst 0x7f4875a623c0 constant 4>
4888 align 32 symtab 0 alias set -1 canonical type 0x7f4875a645e8 precision 32 min <integer_cst 0x7f4875a62340 -2147483648> max <integer_cst 0x7f4875a62360 2147483647>
4889 pointer_to_this <pointer_type 0x7f4875a6b348>>
4890 side-effects
4891 arg 0 <modify_expr 0x7f4875a72a78 type <integer_type 0x7f4875a645e8>
4892 side-effects arg 0 <result_decl 0x7f4875a7a000 D.54>
4893 arg 1 <mult_expr 0x7f4875a72a50 type <integer_type 0x7f4875a645e8>
4894 arg 0 <parm_decl 0x7f4875a79000 i> arg 1 <parm_decl 0x7f4875a79000 i>>>>>
4895 @end example
4896 @end deffn
4897
4898 @geindex GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE (C macro)
4899 @anchor{topics/contexts c GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE}@anchor{1c}
4900 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE
4901
4902 If true, @ref{15,,gcc_jit_context_compile()} will dump the “gimple”
4903 representation of your code to stderr, before any optimizations
4904 are performed. The dump resembles C code:
4905
4906 @example
4907 square (signed int i)
4908 @{
4909 signed int D.56;
4910
4911 entry:
4912 D.56 = i * i;
4913 return D.56;
4914 @}
4915 @end example
4916 @end deffn
4917
4918 @geindex GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE (C macro)
4919 @anchor{topics/contexts c GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE}@anchor{1d}
4920 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE
4921
4922 If true, @ref{15,,gcc_jit_context_compile()} will dump the final
4923 generated code to stderr, in the form of assembly language:
4924
4925 @example
4926 .file "fake.c"
4927 .text
4928 .globl square
4929 .type square, @@function
4930 square:
4931 .LFB0:
4932 .cfi_startproc
4933 pushq %rbp
4934 .cfi_def_cfa_offset 16
4935 .cfi_offset 6, -16
4936 movq %rsp, %rbp
4937 .cfi_def_cfa_register 6
4938 movl %edi, -4(%rbp)
4939 .L2:
4940 movl -4(%rbp), %eax
4941 imull -4(%rbp), %eax
4942 popq %rbp
4943 .cfi_def_cfa 7, 8
4944 ret
4945 .cfi_endproc
4946 .LFE0:
4947 .size square, .-square
4948 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.1-%@{gcc_release@})"
4949 .section .note.GNU-stack,"",@@progbits
4950 @end example
4951 @end deffn
4952
4953 @geindex GCC_JIT_BOOL_OPTION_DUMP_SUMMARY (C macro)
4954 @anchor{topics/contexts c GCC_JIT_BOOL_OPTION_DUMP_SUMMARY}@anchor{67}
4955 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_SUMMARY
4956
4957 If true, @ref{15,,gcc_jit_context_compile()} will print information to stderr
4958 on the actions it is performing.
4959 @end deffn
4960
4961 @geindex GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING (C macro)
4962 @anchor{topics/contexts c GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING}@anchor{68}
4963 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING
4964
4965 If true, @ref{15,,gcc_jit_context_compile()} will dump copious
4966 amount of information on what it’s doing to various
4967 files within a temporary directory. Use
4968 @ref{69,,GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES} (see below) to
4969 see the results. The files are intended to be human-readable,
4970 but the exact files and their formats are subject to change.
4971 @end deffn
4972
4973 @geindex GCC_JIT_BOOL_OPTION_SELFCHECK_GC (C macro)
4974 @anchor{topics/contexts c GCC_JIT_BOOL_OPTION_SELFCHECK_GC}@anchor{6a}
4975 @deffn {C Macro} GCC_JIT_BOOL_OPTION_SELFCHECK_GC
4976
4977 If true, libgccjit will aggressively run its garbage collector, to
4978 shake out bugs (greatly slowing down the compile). This is likely
4979 to only be of interest to developers @emph{of} the library. It is
4980 used when running the selftest suite.
4981 @end deffn
4982
4983 @geindex GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES (C macro)
4984 @anchor{topics/contexts c GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES}@anchor{69}
4985 @deffn {C Macro} GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES
4986
4987 If true, the @ref{8,,gcc_jit_context} will not clean up intermediate files
4988 written to the filesystem, and will display their location on stderr.
4989 @end deffn
4990 @end deffn
4991
4992 @geindex gcc_jit_context_set_bool_allow_unreachable_blocks (C function)
4993 @anchor{topics/contexts c gcc_jit_context_set_bool_allow_unreachable_blocks}@anchor{6b}
4994 @deffn {C Function} void gcc_jit_context_set_bool_allow_unreachable_blocks (gcc_jit_context@w{ }*ctxt, int@w{ }bool_value)
4995
4996 By default, libgccjit will issue an error about unreachable blocks
4997 within a function.
4998
4999 This entrypoint can be used to disable that error.
5000
5001 This entrypoint was added in @ref{6c,,LIBGCCJIT_ABI_2}; you can test for
5002 its presence using
5003
5004 @example
5005 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks
5006 @end example
5007 @end deffn
5008
5009 @geindex gcc_jit_context_set_bool_use_external_driver (C function)
5010 @anchor{topics/contexts c gcc_jit_context_set_bool_use_external_driver}@anchor{6d}
5011 @deffn {C Function} void gcc_jit_context_set_bool_use_external_driver (gcc_jit_context@w{ }*ctxt, int@w{ }bool_value)
5012
5013 libgccjit internally generates assembler, and uses “driver” code
5014 for converting it to other formats (e.g. shared libraries).
5015
5016 By default, libgccjit will use an embedded copy of the driver
5017 code.
5018
5019 This option can be used to instead invoke an external driver executable
5020 as a subprocess.
5021
5022 This entrypoint was added in @ref{6e,,LIBGCCJIT_ABI_5}; you can test for
5023 its presence using
5024
5025 @example
5026 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver
5027 @end example
5028 @end deffn
5029
5030 @geindex gcc_jit_context_set_bool_print_errors_to_stderr (C function)
5031 @anchor{topics/contexts c gcc_jit_context_set_bool_print_errors_to_stderr}@anchor{6f}
5032 @deffn {C Function} void gcc_jit_context_set_bool_print_errors_to_stderr (gcc_jit_context@w{ }*ctxt, int@w{ }enabled)
5033
5034 By default, libgccjit will print errors to stderr.
5035
5036 This entrypoint can be used to disable the printing.
5037
5038 This entrypoint was added in @ref{70,,LIBGCCJIT_ABI_23}; you can test for
5039 its presence using
5040
5041 @example
5042 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_print_errors_to_stderr
5043 @end example
5044 @end deffn
5045
5046 @node Integer options,Additional command-line options,Boolean options,Options<2>
5047 @anchor{topics/contexts integer-options}@anchor{71}
5048 @subsubsection Integer options
5049
5050
5051 @geindex gcc_jit_context_set_int_option (C function)
5052 @anchor{topics/contexts c gcc_jit_context_set_int_option}@anchor{1e}
5053 @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)
5054
5055 Set an integer option of the context.
5056
5057 @geindex gcc_jit_int_option (C type)
5058 @anchor{topics/contexts c gcc_jit_int_option}@anchor{72}
5059 @deffn {C Type} enum gcc_jit_int_option
5060 @end deffn
5061
5062 There is just one integer option specified this way:
5063
5064 @geindex GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL (C macro)
5065 @anchor{topics/contexts c GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}@anchor{1f}
5066 @deffn {C Macro} GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL
5067
5068 How much to optimize the code.
5069
5070 Valid values are 0-3, corresponding to GCC’s command-line options
5071 -O0 through -O3.
5072
5073 The default value is 0 (unoptimized).
5074 @end deffn
5075 @end deffn
5076
5077 @node Additional command-line options,,Integer options,Options<2>
5078 @anchor{topics/contexts additional-command-line-options}@anchor{73}
5079 @subsubsection Additional command-line options
5080
5081
5082 @geindex gcc_jit_context_add_command_line_option (C function)
5083 @anchor{topics/contexts c gcc_jit_context_add_command_line_option}@anchor{74}
5084 @deffn {C Function} void gcc_jit_context_add_command_line_option (gcc_jit_context@w{ }*ctxt, const char@w{ }*optname)
5085
5086 Add an arbitrary gcc command-line option to the context, for use
5087 by @ref{15,,gcc_jit_context_compile()} and
5088 @ref{4a,,gcc_jit_context_compile_to_file()}.
5089
5090 The parameter @code{optname} must be non-NULL. The underlying buffer is
5091 copied, so that it does not need to outlive the call.
5092
5093 Extra options added by @cite{gcc_jit_context_add_command_line_option} are
5094 applied @emph{after} the regular options above, potentially overriding them.
5095 Options from parent contexts are inherited by child contexts; options
5096 from the parent are applied @emph{before} those from the child.
5097
5098 For example:
5099
5100 @example
5101 gcc_jit_context_add_command_line_option (ctxt, "-ffast-math");
5102 gcc_jit_context_add_command_line_option (ctxt, "-fverbose-asm");
5103 @end example
5104
5105 Note that only some options are likely to be meaningful; there is no
5106 “frontend” within libgccjit, so typically only those affecting
5107 optimization and code-generation are likely to be useful.
5108
5109 This entrypoint was added in @ref{75,,LIBGCCJIT_ABI_1}; you can test for
5110 its presence using
5111
5112 @example
5113 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option
5114 @end example
5115 @end deffn
5116
5117 @geindex gcc_jit_context_add_driver_option (C function)
5118 @anchor{topics/contexts c gcc_jit_context_add_driver_option}@anchor{76}
5119 @deffn {C Function} void gcc_jit_context_add_driver_option (gcc_jit_context@w{ }*ctxt, const char@w{ }*optname)
5120
5121 Add an arbitrary gcc driver option to the context, for use by
5122 @ref{15,,gcc_jit_context_compile()} and
5123 @ref{4a,,gcc_jit_context_compile_to_file()}.
5124
5125 The parameter @code{optname} must be non-NULL. The underlying buffer is
5126 copied, so that it does not need to outlive the call.
5127
5128 Extra options added by @cite{gcc_jit_context_add_driver_option} are
5129 applied @emph{after} all other options potentially overriding them.
5130 Options from parent contexts are inherited by child contexts; options
5131 from the parent are applied @emph{before} those from the child.
5132
5133 For example:
5134
5135 @example
5136 gcc_jit_context_add_driver_option (ctxt, "-lm");
5137 gcc_jit_context_add_driver_option (ctxt, "-fuse-linker-plugin");
5138
5139 gcc_jit_context_add_driver_option (ctxt, "obj.o");
5140
5141 gcc_jit_context_add_driver_option (ctxt, "-L.");
5142 gcc_jit_context_add_driver_option (ctxt, "-lwhatever");
5143 @end example
5144
5145 Note that only some options are likely to be meaningful; there is no
5146 “frontend” within libgccjit, so typically only those affecting
5147 assembler and linker are likely to be useful.
5148
5149 This entrypoint was added in @ref{77,,LIBGCCJIT_ABI_11}; you can test for
5150 its presence using
5151
5152 @example
5153 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_driver_option
5154 @end example
5155 @end deffn
5156
5157 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
5158 @c Originally contributed by David Malcolm <[email protected]>
5159 @c
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.
5164 @c
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.
5169 @c
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 <https://www.gnu.org/licenses/>.
5173
5174 @node Objects,Types,Compilation contexts,Topic Reference
5175 @anchor{topics/objects doc}@anchor{78}@anchor{topics/objects objects}@anchor{79}
5176 @section Objects
5177
5178
5179 @geindex gcc_jit_object (C type)
5180 @anchor{topics/objects c gcc_jit_object}@anchor{e}
5181 @deffn {C Type} gcc_jit_object
5182 @end deffn
5183
5184 Almost every entity in the API (with the exception of
5185 @ref{8,,gcc_jit_context *} and @ref{16,,gcc_jit_result *}) is a
5186 “contextual” object, a @ref{e,,gcc_jit_object *}
5187
5188 A JIT object:
5189
5190 @quotation
5191
5192
5193 @itemize *
5194
5195 @item
5196 is associated with a @ref{8,,gcc_jit_context *}.
5197
5198 @item
5199 is automatically cleaned up for you when its context is released so
5200 you don’t need to manually track and cleanup all objects, just the
5201 contexts.
5202 @end itemize
5203 @end quotation
5204
5205 Although the API is C-based, there is a form of class hierarchy, which
5206 looks like this:
5207
5208 @example
5209 +- gcc_jit_object
5210 +- gcc_jit_location
5211 +- gcc_jit_type
5212 +- gcc_jit_struct
5213 +- gcc_jit_field
5214 +- gcc_jit_function
5215 +- gcc_jit_block
5216 +- gcc_jit_rvalue
5217 +- gcc_jit_lvalue
5218 +- gcc_jit_param
5219 +- gcc_jit_case
5220 +- gcc_jit_extended_asm
5221 @end example
5222
5223 There are casting methods for upcasting from subclasses to parent classes.
5224 For example, @ref{d,,gcc_jit_type_as_object()}:
5225
5226 @example
5227 gcc_jit_object *obj = gcc_jit_type_as_object (int_type);
5228 @end example
5229
5230 The object “base class” has the following operations:
5231
5232 @geindex gcc_jit_object_get_context (C function)
5233 @anchor{topics/objects c gcc_jit_object_get_context}@anchor{7a}
5234 @deffn {C Function} gcc_jit_context *gcc_jit_object_get_context (gcc_jit_object@w{ }*obj)
5235
5236 Which context is “obj” within?
5237 @end deffn
5238
5239 @geindex gcc_jit_object_get_debug_string (C function)
5240 @anchor{topics/objects c gcc_jit_object_get_debug_string}@anchor{f}
5241 @deffn {C Function} const char *gcc_jit_object_get_debug_string (gcc_jit_object@w{ }*obj)
5242
5243 Generate a human-readable description for the given object.
5244
5245 For example,
5246
5247 @example
5248 printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj));
5249 @end example
5250
5251 might give this text on stdout:
5252
5253 @example
5254 obj: 4.0 * (float)i
5255 @end example
5256
5257 @cartouche
5258 @quotation Note
5259 If you call this on an object, the @cite{const char *} buffer is allocated
5260 and generated on the first call for that object, and the buffer will
5261 have the same lifetime as the object i.e. it will exist until the
5262 object’s context is released.
5263 @end quotation
5264 @end cartouche
5265 @end deffn
5266
5267 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
5268 @c Originally contributed by David Malcolm <[email protected]>
5269 @c
5270 @c This is free software: you can redistribute it and/or modify it
5271 @c under the terms of the GNU General Public License as published by
5272 @c the Free Software Foundation, either version 3 of the License, or
5273 @c (at your option) any later version.
5274 @c
5275 @c This program is distributed in the hope that it will be useful, but
5276 @c WITHOUT ANY WARRANTY; without even the implied warranty of
5277 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5278 @c General Public License for more details.
5279 @c
5280 @c You should have received a copy of the GNU General Public License
5281 @c along with this program. If not, see
5282 @c <https://www.gnu.org/licenses/>.
5283
5284 @node Types,Expressions,Objects,Topic Reference
5285 @anchor{topics/types doc}@anchor{7b}@anchor{topics/types types}@anchor{7c}
5286 @section Types
5287
5288
5289 @geindex gcc_jit_type (C type)
5290 @anchor{topics/types c gcc_jit_type}@anchor{a}
5291 @deffn {C Type} gcc_jit_type
5292
5293 gcc_jit_type represents a type within the library.
5294 @end deffn
5295
5296 @geindex gcc_jit_type_as_object (C function)
5297 @anchor{topics/types c gcc_jit_type_as_object}@anchor{d}
5298 @deffn {C Function} gcc_jit_object *gcc_jit_type_as_object (gcc_jit_type@w{ }*type)
5299
5300 Upcast a type to an object.
5301 @end deffn
5302
5303 Types can be created in several ways:
5304
5305
5306 @itemize *
5307
5308 @item
5309 fundamental types can be accessed using
5310 @ref{b,,gcc_jit_context_get_type()}:
5311
5312 @example
5313 gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
5314 @end example
5315
5316 See @ref{b,,gcc_jit_context_get_type()} for the available types.
5317
5318 @item
5319 derived types can be accessed by using functions such as
5320 @ref{7d,,gcc_jit_type_get_pointer()} and @ref{7e,,gcc_jit_type_get_const()}:
5321
5322 @example
5323 gcc_jit_type *const_int_star = gcc_jit_type_get_pointer (gcc_jit_type_get_const (int_type));
5324 gcc_jit_type *int_const_star = gcc_jit_type_get_const (gcc_jit_type_get_pointer (int_type));
5325 @end example
5326
5327 @item
5328 by creating structures (see below).
5329 @end itemize
5330
5331 @menu
5332 * Standard types::
5333 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile.
5334 * Vector types::
5335 * Structures and unions::
5336 * Function pointer types::
5337 * Reflection API::
5338
5339 @end menu
5340
5341 @node Standard types,Pointers const and volatile,,Types
5342 @anchor{topics/types standard-types}@anchor{7f}
5343 @subsection Standard types
5344
5345
5346 @geindex gcc_jit_context_get_type (C function)
5347 @anchor{topics/types c gcc_jit_context_get_type}@anchor{b}
5348 @deffn {C Function} gcc_jit_type *gcc_jit_context_get_type (gcc_jit_context@w{ }*ctxt, enum gcc_jit_types@w{ }type_)
5349
5350 Access a specific type. The available types are:
5351
5352
5353 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
5354 @headitem
5355
5356 @cite{enum gcc_jit_types} value
5357
5358 @tab
5359
5360 Meaning
5361
5362 @item
5363
5364 @code{GCC_JIT_TYPE_VOID}
5365
5366 @tab
5367
5368 C’s @code{void} type.
5369
5370 @item
5371
5372 @code{GCC_JIT_TYPE_VOID_PTR}
5373
5374 @tab
5375
5376 C’s @code{void *}.
5377
5378 @item
5379
5380 @code{GCC_JIT_TYPE_BOOL}
5381
5382 @tab
5383
5384 C++’s @code{bool} type; also C99’s
5385 @code{_Bool} type, aka @code{bool} if
5386 using stdbool.h.
5387
5388 @item
5389
5390 @code{GCC_JIT_TYPE_CHAR}
5391
5392 @tab
5393
5394 C’s @code{char} (of some signedness)
5395
5396 @item
5397
5398 @code{GCC_JIT_TYPE_SIGNED_CHAR}
5399
5400 @tab
5401
5402 C’s @code{signed char}
5403
5404 @item
5405
5406 @code{GCC_JIT_TYPE_UNSIGNED_CHAR}
5407
5408 @tab
5409
5410 C’s @code{unsigned char}
5411
5412 @item
5413
5414 @code{GCC_JIT_TYPE_SHORT}
5415
5416 @tab
5417
5418 C’s @code{short} (signed)
5419
5420 @item
5421
5422 @code{GCC_JIT_TYPE_UNSIGNED_SHORT}
5423
5424 @tab
5425
5426 C’s @code{unsigned short}
5427
5428 @item
5429
5430 @code{GCC_JIT_TYPE_INT}
5431
5432 @tab
5433
5434 C’s @code{int} (signed)
5435
5436 @item
5437
5438 @code{GCC_JIT_TYPE_UNSIGNED_INT}
5439
5440 @tab
5441
5442 C’s @code{unsigned int}
5443
5444 @item
5445
5446 @code{GCC_JIT_TYPE_LONG}
5447
5448 @tab
5449
5450 C’s @code{long} (signed)
5451
5452 @item
5453
5454 @code{GCC_JIT_TYPE_UNSIGNED_LONG}
5455
5456 @tab
5457
5458 C’s @code{unsigned long}
5459
5460 @item
5461
5462 @code{GCC_JIT_TYPE_LONG_LONG}
5463
5464 @tab
5465
5466 C99’s @code{long long} (signed)
5467
5468 @item
5469
5470 @code{GCC_JIT_TYPE_UNSIGNED_LONG_LONG}
5471
5472 @tab
5473
5474 C99’s @code{unsigned long long}
5475
5476 @item
5477
5478 @code{GCC_JIT_TYPE_UINT8_T}
5479
5480 @tab
5481
5482 C99’s @code{uint8_t}
5483
5484 @item
5485
5486 @code{GCC_JIT_TYPE_UINT16_T}
5487
5488 @tab
5489
5490 C99’s @code{uint16_t}
5491
5492 @item
5493
5494 @code{GCC_JIT_TYPE_UINT32_T}
5495
5496 @tab
5497
5498 C99’s @code{uint32_t}
5499
5500 @item
5501
5502 @code{GCC_JIT_TYPE_UINT64_T}
5503
5504 @tab
5505
5506 C99’s @code{uint64_t}
5507
5508 @item
5509
5510 @code{GCC_JIT_TYPE_UINT128_T}
5511
5512 @tab
5513
5514 C99’s @code{__uint128_t}
5515
5516 @item
5517
5518 @code{GCC_JIT_TYPE_INT8_T}
5519
5520 @tab
5521
5522 C99’s @code{int8_t}
5523
5524 @item
5525
5526 @code{GCC_JIT_TYPE_INT16_T}
5527
5528 @tab
5529
5530 C99’s @code{int16_t}
5531
5532 @item
5533
5534 @code{GCC_JIT_TYPE_INT32_T}
5535
5536 @tab
5537
5538 C99’s @code{int32_t}
5539
5540 @item
5541
5542 @code{GCC_JIT_TYPE_INT64_T}
5543
5544 @tab
5545
5546 C99’s @code{int64_t}
5547
5548 @item
5549
5550 @code{GCC_JIT_TYPE_INT128_T}
5551
5552 @tab
5553
5554 C99’s @code{__int128_t}
5555
5556 @item
5557
5558 @code{GCC_JIT_TYPE_FLOAT}
5559
5560 @tab
5561
5562 @item
5563
5564 @code{GCC_JIT_TYPE_DOUBLE}
5565
5566 @tab
5567
5568 @item
5569
5570 @code{GCC_JIT_TYPE_LONG_DOUBLE}
5571
5572 @tab
5573
5574 @item
5575
5576 @code{GCC_JIT_TYPE_CONST_CHAR_PTR}
5577
5578 @tab
5579
5580 C type: @code{(const char *)}
5581
5582 @item
5583
5584 @code{GCC_JIT_TYPE_SIZE_T}
5585
5586 @tab
5587
5588 C’s @code{size_t} type
5589
5590 @item
5591
5592 @code{GCC_JIT_TYPE_FILE_PTR}
5593
5594 @tab
5595
5596 C type: @code{(FILE *)}
5597
5598 @item
5599
5600 @code{GCC_JIT_TYPE_COMPLEX_FLOAT}
5601
5602 @tab
5603
5604 C99’s @code{_Complex float}
5605
5606 @item
5607
5608 @code{GCC_JIT_TYPE_COMPLEX_DOUBLE}
5609
5610 @tab
5611
5612 C99’s @code{_Complex double}
5613
5614 @item
5615
5616 @code{GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE}
5617
5618 @tab
5619
5620 C99’s @code{_Complex long double}
5621
5622 @end multitable
5623
5624 @end deffn
5625
5626 @geindex gcc_jit_context_get_int_type (C function)
5627 @anchor{topics/types c gcc_jit_context_get_int_type}@anchor{80}
5628 @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)
5629
5630 Access the integer type of the given size.
5631 @end deffn
5632
5633 @node Pointers const and volatile,Vector types,Standard types,Types
5634 @anchor{topics/types pointers-const-and-volatile}@anchor{81}
5635 @subsection Pointers, @cite{const}, and @cite{volatile}
5636
5637
5638 @geindex gcc_jit_type_get_pointer (C function)
5639 @anchor{topics/types c gcc_jit_type_get_pointer}@anchor{7d}
5640 @deffn {C Function} gcc_jit_type *gcc_jit_type_get_pointer (gcc_jit_type@w{ }*type)
5641
5642 Given type “T”, get type “T*”.
5643 @end deffn
5644
5645 @geindex gcc_jit_type_get_const (C function)
5646 @anchor{topics/types c gcc_jit_type_get_const}@anchor{7e}
5647 @deffn {C Function} gcc_jit_type *gcc_jit_type_get_const (gcc_jit_type@w{ }*type)
5648
5649 Given type “T”, get type “const T”.
5650 @end deffn
5651
5652 @geindex gcc_jit_type_get_volatile (C function)
5653 @anchor{topics/types c gcc_jit_type_get_volatile}@anchor{82}
5654 @deffn {C Function} gcc_jit_type *gcc_jit_type_get_volatile (gcc_jit_type@w{ }*type)
5655
5656 Given type “T”, get type “volatile T”.
5657 @end deffn
5658
5659 @geindex gcc_jit_context_new_array_type (C function)
5660 @anchor{topics/types c gcc_jit_context_new_array_type}@anchor{83}
5661 @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)
5662
5663 Given non-@cite{void} type “T”, get type “T[N]” (for a constant N).
5664 @end deffn
5665
5666 @geindex gcc_jit_type_get_aligned (C function)
5667 @anchor{topics/types c gcc_jit_type_get_aligned}@anchor{84}
5668 @deffn {C Function} gcc_jit_type * gcc_jit_type_get_aligned (gcc_jit_type@w{ }*type, size_t@w{ }alignment_in_bytes)
5669
5670 Given non-@cite{void} type “T”, get type:
5671
5672 @example
5673 T __attribute__ ((aligned (ALIGNMENT_IN_BYTES)))
5674 @end example
5675
5676 The alignment must be a power of two.
5677
5678 This entrypoint was added in @ref{85,,LIBGCCJIT_ABI_7}; you can test for
5679 its presence using
5680
5681 @example
5682 #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_aligned
5683 @end example
5684 @end deffn
5685
5686 @node Vector types,Structures and unions,Pointers const and volatile,Types
5687 @anchor{topics/types vector-types}@anchor{86}
5688 @subsection Vector types
5689
5690
5691 @geindex gcc_jit_type_get_vector (C function)
5692 @anchor{topics/types c gcc_jit_type_get_vector}@anchor{87}
5693 @deffn {C Function} gcc_jit_type * gcc_jit_type_get_vector (gcc_jit_type@w{ }*type, size_t@w{ }num_units)
5694
5695 Given type “T”, get type:
5696
5697 @example
5698 T __attribute__ ((vector_size (sizeof(T) * num_units))
5699 @end example
5700
5701 T must be integral or floating point; num_units must be a power of two.
5702
5703 This can be used to construct a vector type in which operations
5704 are applied element-wise. The compiler will automatically
5705 use SIMD instructions where possible. See:
5706 @indicateurl{https://gcc.gnu.org/onlinedocs/gcc/Vector-Extensions.html}
5707
5708 For example, assuming 4-byte @code{ints}, then:
5709
5710 @example
5711 typedef int v4si __attribute__ ((vector_size (16)));
5712 @end example
5713
5714 can be obtained using:
5715
5716 @example
5717 gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt,
5718 GCC_JIT_TYPE_INT);
5719 gcc_jit_type *v4si_type = gcc_jit_type_get_vector (int_type, 4);
5720 @end example
5721
5722 This API entrypoint was added in @ref{88,,LIBGCCJIT_ABI_8}; you can test
5723 for its presence using
5724
5725 @example
5726 #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_vector
5727 @end example
5728
5729 Vector rvalues can be generated using
5730 @ref{89,,gcc_jit_context_new_rvalue_from_vector()}.
5731 @end deffn
5732
5733 @node Structures and unions,Function pointer types,Vector types,Types
5734 @anchor{topics/types structures-and-unions}@anchor{8a}
5735 @subsection Structures and unions
5736
5737
5738 @geindex gcc_jit_struct (C type)
5739 @anchor{topics/types c gcc_jit_struct}@anchor{8b}
5740 @deffn {C Type} gcc_jit_struct
5741 @end deffn
5742
5743 A compound type analagous to a C @cite{struct}.
5744
5745 @geindex gcc_jit_field (C type)
5746 @anchor{topics/types c gcc_jit_field}@anchor{8c}
5747 @deffn {C Type} gcc_jit_field
5748 @end deffn
5749
5750 A field within a @ref{8b,,gcc_jit_struct}.
5751
5752 You can model C @cite{struct} types by creating @ref{8b,,gcc_jit_struct} and
5753 @ref{8c,,gcc_jit_field} instances, in either order:
5754
5755
5756 @itemize *
5757
5758 @item
5759 by creating the fields, then the structure. For example, to model:
5760
5761 @example
5762 struct coord @{double x; double y; @};
5763 @end example
5764
5765 you could call:
5766
5767 @example
5768 gcc_jit_field *field_x =
5769 gcc_jit_context_new_field (ctxt, NULL, double_type, "x");
5770 gcc_jit_field *field_y =
5771 gcc_jit_context_new_field (ctxt, NULL, double_type, "y");
5772 gcc_jit_field *fields[2] = @{field_x, field_y@};
5773 gcc_jit_struct *coord =
5774 gcc_jit_context_new_struct_type (ctxt, NULL, "coord", 2, fields);
5775 @end example
5776
5777 @item
5778 by creating the structure, then populating it with fields, typically
5779 to allow modelling self-referential structs such as:
5780
5781 @example
5782 struct node @{ int m_hash; struct node *m_next; @};
5783 @end example
5784
5785 like this:
5786
5787 @example
5788 gcc_jit_type *node =
5789 gcc_jit_context_new_opaque_struct (ctxt, NULL, "node");
5790 gcc_jit_type *node_ptr =
5791 gcc_jit_type_get_pointer (node);
5792 gcc_jit_field *field_hash =
5793 gcc_jit_context_new_field (ctxt, NULL, int_type, "m_hash");
5794 gcc_jit_field *field_next =
5795 gcc_jit_context_new_field (ctxt, NULL, node_ptr, "m_next");
5796 gcc_jit_field *fields[2] = @{field_hash, field_next@};
5797 gcc_jit_struct_set_fields (node, NULL, 2, fields);
5798 @end example
5799 @end itemize
5800
5801 @geindex gcc_jit_context_new_field (C function)
5802 @anchor{topics/types c gcc_jit_context_new_field}@anchor{8d}
5803 @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)
5804
5805 Construct a new field, with the given type and name.
5806
5807 The parameter @code{type} must be non-@cite{void}.
5808
5809 The parameter @code{name} must be non-NULL. The call takes a copy of the
5810 underlying string, so it is valid to pass in a pointer to an on-stack
5811 buffer.
5812 @end deffn
5813
5814 @geindex gcc_jit_context_new_bitfield (C function)
5815 @anchor{topics/types c gcc_jit_context_new_bitfield}@anchor{8e}
5816 @deffn {C Function} gcc_jit_field * gcc_jit_context_new_bitfield (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, int@w{ }width, const char@w{ }*name)
5817
5818 Construct a new bit field, with the given type width and name.
5819
5820 The parameter @code{name} must be non-NULL. The call takes a copy of the
5821 underlying string, so it is valid to pass in a pointer to an on-stack
5822 buffer.
5823
5824 The parameter @code{type} must be an integer type.
5825
5826 The parameter @code{width} must be a positive integer that does not exceed the
5827 size of @code{type}.
5828
5829 This API entrypoint was added in @ref{8f,,LIBGCCJIT_ABI_12}; you can test
5830 for its presence using
5831
5832 @example
5833 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitfield
5834 @end example
5835 @end deffn
5836
5837 @geindex gcc_jit_field_as_object (C function)
5838 @anchor{topics/types c gcc_jit_field_as_object}@anchor{90}
5839 @deffn {C Function} gcc_jit_object * gcc_jit_field_as_object (gcc_jit_field@w{ }*field)
5840
5841 Upcast from field to object.
5842 @end deffn
5843
5844 @geindex gcc_jit_context_new_struct_type (C function)
5845 @anchor{topics/types c gcc_jit_context_new_struct_type}@anchor{91}
5846 @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)
5847
5848 @quotation
5849
5850 Construct a new struct type, with the given name and fields.
5851
5852 The parameter @code{name} must be non-NULL. The call takes a copy of
5853 the underlying string, so it is valid to pass in a pointer to an
5854 on-stack buffer.
5855 @end quotation
5856 @end deffn
5857
5858 @geindex gcc_jit_context_new_opaque_struct (C function)
5859 @anchor{topics/types c gcc_jit_context_new_opaque_struct}@anchor{92}
5860 @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)
5861
5862 Construct a new struct type, with the given name, but without
5863 specifying the fields. The fields can be omitted (in which case the
5864 size of the struct is not known), or later specified using
5865 @ref{93,,gcc_jit_struct_set_fields()}.
5866
5867 The parameter @code{name} must be non-NULL. The call takes a copy of
5868 the underlying string, so it is valid to pass in a pointer to an
5869 on-stack buffer.
5870 @end deffn
5871
5872 @geindex gcc_jit_struct_as_type (C function)
5873 @anchor{topics/types c gcc_jit_struct_as_type}@anchor{94}
5874 @deffn {C Function} gcc_jit_type * gcc_jit_struct_as_type (gcc_jit_struct@w{ }*struct_type)
5875
5876 Upcast from struct to type.
5877 @end deffn
5878
5879 @geindex gcc_jit_struct_set_fields (C function)
5880 @anchor{topics/types c gcc_jit_struct_set_fields}@anchor{93}
5881 @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)
5882
5883 Populate the fields of a formerly-opaque struct type.
5884
5885 This can only be called once on a given struct type.
5886 @end deffn
5887
5888 @geindex gcc_jit_context_new_union_type (C function)
5889 @anchor{topics/types c gcc_jit_context_new_union_type}@anchor{95}
5890 @deffn {C Function} gcc_jit_type * gcc_jit_context_new_union_type (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, const char@w{ }*name, int@w{ }num_fields, gcc_jit_field@w{ }**fields)
5891
5892 Construct a new union type, with the given name and fields.
5893
5894 The parameter @code{name} must be non-NULL. It is copied, so the input
5895 buffer does not need to outlive the call.
5896
5897 Example of use:
5898
5899 @example
5900
5901 union int_or_float
5902 @{
5903 int as_int;
5904 float as_float;
5905 @};
5906
5907 void
5908 create_code (gcc_jit_context *ctxt, void *user_data)
5909 @{
5910 /* Let's try to inject the equivalent of:
5911 float
5912 test_union (int i)
5913 @{
5914 union int_or_float u;
5915 u.as_int = i;
5916 return u.as_float;
5917 @}
5918 */
5919 gcc_jit_type *int_type =
5920 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
5921 gcc_jit_type *float_type =
5922 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_FLOAT);
5923 gcc_jit_field *as_int =
5924 gcc_jit_context_new_field (ctxt,
5925 NULL,
5926 int_type,
5927 "as_int");
5928 gcc_jit_field *as_float =
5929 gcc_jit_context_new_field (ctxt,
5930 NULL,
5931 float_type,
5932 "as_float");
5933 gcc_jit_field *fields[] = @{as_int, as_float@};
5934 gcc_jit_type *union_type =
5935 gcc_jit_context_new_union_type (ctxt, NULL,
5936 "int_or_float", 2, fields);
5937
5938 /* Build the test function. */
5939 gcc_jit_param *param_i =
5940 gcc_jit_context_new_param (ctxt, NULL, int_type, "i");
5941 gcc_jit_function *test_fn =
5942 gcc_jit_context_new_function (ctxt, NULL,
5943 GCC_JIT_FUNCTION_EXPORTED,
5944 float_type,
5945 "test_union",
5946 1, &param_i,
5947 0);
5948
5949 gcc_jit_lvalue *u =
5950 gcc_jit_function_new_local (test_fn, NULL,
5951 union_type, "u");
5952
5953 gcc_jit_block *block = gcc_jit_function_new_block (test_fn, NULL);
5954
5955 /* u.as_int = i; */
5956 gcc_jit_block_add_assignment (
5957 block,
5958 NULL,
5959 /* "u.as_int = ..." */
5960 gcc_jit_lvalue_access_field (u,
5961 NULL,
5962 as_int),
5963 gcc_jit_param_as_rvalue (param_i));
5964
5965 /* return u.as_float; */
5966 gcc_jit_block_end_with_return (
5967 block, NULL,
5968 gcc_jit_rvalue_access_field (gcc_jit_lvalue_as_rvalue (u),
5969 NULL,
5970 as_float));
5971 @}
5972
5973 @end example
5974 @end deffn
5975
5976 @node Function pointer types,Reflection API,Structures and unions,Types
5977 @anchor{topics/types function-pointer-types}@anchor{96}
5978 @subsection Function pointer types
5979
5980
5981 Function pointer types can be created using
5982 @ref{97,,gcc_jit_context_new_function_ptr_type()}.
5983
5984 @node Reflection API,,Function pointer types,Types
5985 @anchor{topics/types reflection-api}@anchor{98}
5986 @subsection Reflection API
5987
5988
5989 @geindex gcc_jit_type_dyncast_array (C function)
5990 @anchor{topics/types c gcc_jit_type_dyncast_array}@anchor{99}
5991 @deffn {C Function} gcc_jit_type * gcc_jit_type_dyncast_array (gcc_jit_type@w{ }*type)
5992
5993 Get the element type of an array type or NULL if it’s not an array.
5994 @end deffn
5995
5996 @geindex gcc_jit_type_is_bool (C function)
5997 @anchor{topics/types c gcc_jit_type_is_bool}@anchor{9a}
5998 @deffn {C Function} int gcc_jit_type_is_bool (gcc_jit_type@w{ }*type)
5999
6000 Return non-zero if the type is a bool.
6001 @end deffn
6002
6003 @geindex gcc_jit_type_dyncast_function_ptr_type (C function)
6004 @anchor{topics/types c gcc_jit_type_dyncast_function_ptr_type}@anchor{9b}
6005 @deffn {C Function} gcc_jit_function_type * gcc_jit_type_dyncast_function_ptr_type (gcc_jit_type@w{ }*type)
6006
6007 Return the function type if it is one or NULL.
6008 @end deffn
6009
6010 @geindex gcc_jit_function_type_get_return_type (C function)
6011 @anchor{topics/types c gcc_jit_function_type_get_return_type}@anchor{9c}
6012 @deffn {C Function} gcc_jit_type * gcc_jit_function_type_get_return_type (gcc_jit_function_type@w{ }*function_type)
6013
6014 Given a function type, return its return type.
6015 @end deffn
6016
6017 @geindex gcc_jit_function_type_get_param_count (C function)
6018 @anchor{topics/types c gcc_jit_function_type_get_param_count}@anchor{9d}
6019 @deffn {C Function} size_t gcc_jit_function_type_get_param_count (gcc_jit_function_type@w{ }*function_type)
6020
6021 Given a function type, return its number of parameters.
6022 @end deffn
6023
6024 @geindex gcc_jit_function_type_get_param_type (C function)
6025 @anchor{topics/types c gcc_jit_function_type_get_param_type}@anchor{9e}
6026 @deffn {C Function} gcc_jit_type * gcc_jit_function_type_get_param_type (gcc_jit_function_type@w{ }*function_type, size_t@w{ }index)
6027
6028 Given a function type, return the type of the specified parameter.
6029 @end deffn
6030
6031 @geindex gcc_jit_type_is_integral (C function)
6032 @anchor{topics/types c gcc_jit_type_is_integral}@anchor{9f}
6033 @deffn {C Function} int gcc_jit_type_is_integral (gcc_jit_type@w{ }*type)
6034
6035 Return non-zero if the type is an integral.
6036 @end deffn
6037
6038 @geindex gcc_jit_type_is_pointer (C function)
6039 @anchor{topics/types c gcc_jit_type_is_pointer}@anchor{a0}
6040 @deffn {C Function} gcc_jit_type * gcc_jit_type_is_pointer (gcc_jit_type@w{ }*type)
6041
6042 Return the type pointed by the pointer type or NULL if it’s not a pointer.
6043 @end deffn
6044
6045 @geindex gcc_jit_type_dyncast_vector (C function)
6046 @anchor{topics/types c gcc_jit_type_dyncast_vector}@anchor{a1}
6047 @deffn {C Function} gcc_jit_vector_type * gcc_jit_type_dyncast_vector (gcc_jit_type@w{ }*type)
6048
6049 Given a type, return a dynamic cast to a vector type or NULL.
6050 @end deffn
6051
6052 @geindex gcc_jit_type_is_struct (C function)
6053 @anchor{topics/types c gcc_jit_type_is_struct}@anchor{a2}
6054 @deffn {C Function} gcc_jit_struct * gcc_jit_type_is_struct (gcc_jit_type@w{ }*type)
6055
6056 Given a type, return a dynamic cast to a struct type or NULL.
6057 @end deffn
6058
6059 @geindex gcc_jit_vector_type_get_num_units (C function)
6060 @anchor{topics/types c gcc_jit_vector_type_get_num_units}@anchor{a3}
6061 @deffn {C Function} size_t gcc_jit_vector_type_get_num_units (gcc_jit_vector_type@w{ }*vector_type)
6062
6063 Given a vector type, return the number of units it contains.
6064 @end deffn
6065
6066 @geindex gcc_jit_vector_type_get_element_type (C function)
6067 @anchor{topics/types c gcc_jit_vector_type_get_element_type}@anchor{a4}
6068 @deffn {C Function} gcc_jit_type * gcc_jit_vector_type_get_element_type (gcc_jit_vector_type *@w{ }vector_type)
6069
6070 Given a vector type, return the type of its elements.
6071 @end deffn
6072
6073 @geindex gcc_jit_type_unqualified (C function)
6074 @anchor{topics/types c gcc_jit_type_unqualified}@anchor{a5}
6075 @deffn {C Function} gcc_jit_type * gcc_jit_type_unqualified (gcc_jit_type@w{ }*type)
6076
6077 Given a type, return the unqualified type, removing “const”, “volatile” and
6078 alignment qualifiers.
6079 @end deffn
6080
6081 @geindex gcc_jit_struct_get_field (C function)
6082 @anchor{topics/types c gcc_jit_struct_get_field}@anchor{a6}
6083 @deffn {C Function} gcc_jit_field * gcc_jit_struct_get_field (gcc_jit_struct@w{ }*struct_type, size_t@w{ }index)
6084
6085 Get a struct field by index.
6086 @end deffn
6087
6088 @geindex gcc_jit_struct_get_field_count (C function)
6089 @anchor{topics/types c gcc_jit_struct_get_field_count}@anchor{a7}
6090 @deffn {C Function} size_t gcc_jit_struct_get_field_count (gcc_jit_struct@w{ }*struct_type)
6091
6092 @quotation
6093
6094 Get the number of fields in the struct.
6095 @end quotation
6096
6097 The API entrypoints related to the reflection API:
6098
6099 @quotation
6100
6101
6102 @itemize *
6103
6104 @item
6105 @ref{9c,,gcc_jit_function_type_get_return_type()}
6106
6107 @item
6108 @ref{9d,,gcc_jit_function_type_get_param_count()}
6109
6110 @item
6111 @ref{9e,,gcc_jit_function_type_get_param_type()}
6112
6113 @item
6114 @ref{a5,,gcc_jit_type_unqualified()}
6115
6116 @item
6117 @ref{99,,gcc_jit_type_dyncast_array()}
6118
6119 @item
6120 @ref{9a,,gcc_jit_type_is_bool()}
6121
6122 @item
6123 @ref{9b,,gcc_jit_type_dyncast_function_ptr_type()}
6124
6125 @item
6126 @ref{9f,,gcc_jit_type_is_integral()}
6127
6128 @item
6129 @ref{a0,,gcc_jit_type_is_pointer()}
6130
6131 @item
6132 @ref{a1,,gcc_jit_type_dyncast_vector()}
6133
6134 @item
6135 @ref{a4,,gcc_jit_vector_type_get_element_type()}
6136
6137 @item
6138 @ref{a3,,gcc_jit_vector_type_get_num_units()}
6139
6140 @item
6141 @ref{a6,,gcc_jit_struct_get_field()}
6142
6143 @item
6144 @ref{a2,,gcc_jit_type_is_struct()}
6145
6146 @item
6147 @ref{a7,,gcc_jit_struct_get_field_count()}
6148 @end itemize
6149 @end quotation
6150
6151 were added in @ref{a8,,LIBGCCJIT_ABI_16}; you can test for their presence
6152 using
6153
6154 @example
6155 #ifdef LIBGCCJIT_HAVE_REFLECTION
6156 @end example
6157
6158 @geindex gcc_jit_case (C type)
6159 @anchor{topics/types c gcc_jit_case}@anchor{a9}
6160 @deffn {C Type} gcc_jit_case
6161 @end deffn
6162 @end deffn
6163
6164 @geindex gcc_jit_compatible_types (C function)
6165 @anchor{topics/types c gcc_jit_compatible_types}@anchor{aa}
6166 @deffn {C Function} int gcc_jit_compatible_types (gcc_jit_type@w{ }*ltype, gcc_jit_type@w{ }*rtype)
6167
6168 @quotation
6169
6170 Return non-zero if the two types are compatible. For instance,
6171 if @code{GCC_JIT_TYPE_UINT64_T} and @code{GCC_JIT_TYPE_UNSIGNED_LONG}
6172 are the same size on the target, this will return non-zero.
6173 The parameters @code{ltype} and @code{rtype} must be non-NULL.
6174 Return 0 on errors.
6175 @end quotation
6176
6177 This entrypoint was added in @ref{ab,,LIBGCCJIT_ABI_20}; you can test for
6178 its presence using
6179
6180 @example
6181 #ifdef LIBGCCJIT_HAVE_SIZED_INTEGERS
6182 @end example
6183 @end deffn
6184
6185 @geindex gcc_jit_type_get_size (C function)
6186 @anchor{topics/types c gcc_jit_type_get_size}@anchor{ac}
6187 @deffn {C Function} ssize_t gcc_jit_type_get_size (gcc_jit_type@w{ }*type)
6188
6189 @quotation
6190
6191 Return the size of a type, in bytes. It only works on integer types for now.
6192 The parameter @code{type} must be non-NULL.
6193 Return -1 on errors.
6194 @end quotation
6195
6196 This entrypoint was added in @ref{ab,,LIBGCCJIT_ABI_20}; you can test for
6197 its presence using
6198
6199 @example
6200 #ifdef LIBGCCJIT_HAVE_SIZED_INTEGERS
6201 @end example
6202 @end deffn
6203
6204 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
6205 @c Originally contributed by David Malcolm <[email protected]>
6206 @c
6207 @c This is free software: you can redistribute it and/or modify it
6208 @c under the terms of the GNU General Public License as published by
6209 @c the Free Software Foundation, either version 3 of the License, or
6210 @c (at your option) any later version.
6211 @c
6212 @c This program is distributed in the hope that it will be useful, but
6213 @c WITHOUT ANY WARRANTY; without even the implied warranty of
6214 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6215 @c General Public License for more details.
6216 @c
6217 @c You should have received a copy of the GNU General Public License
6218 @c along with this program. If not, see
6219 @c <https://www.gnu.org/licenses/>.
6220
6221 @node Expressions,Creating and using functions,Types,Topic Reference
6222 @anchor{topics/expressions doc}@anchor{ad}@anchor{topics/expressions expressions}@anchor{ae}
6223 @section Expressions
6224
6225
6226 @menu
6227 * Rvalues::
6228 * Lvalues::
6229 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions.
6230
6231 @end menu
6232
6233 @node Rvalues,Lvalues,,Expressions
6234 @anchor{topics/expressions rvalues}@anchor{af}
6235 @subsection Rvalues
6236
6237
6238 @geindex gcc_jit_rvalue (C type)
6239 @anchor{topics/expressions c gcc_jit_rvalue}@anchor{13}
6240 @deffn {C Type} gcc_jit_rvalue
6241 @end deffn
6242
6243 A @ref{13,,gcc_jit_rvalue} is an expression that can be computed.
6244
6245 It can be simple, e.g.:
6246
6247 @quotation
6248
6249
6250 @itemize *
6251
6252 @item
6253 an integer value e.g. @cite{0} or @cite{42}
6254
6255 @item
6256 a string literal e.g. @cite{“Hello world”}
6257
6258 @item
6259 a variable e.g. @cite{i}. These are also lvalues (see below).
6260 @end itemize
6261 @end quotation
6262
6263 or compound e.g.:
6264
6265 @quotation
6266
6267
6268 @itemize *
6269
6270 @item
6271 a unary expression e.g. @cite{!cond}
6272
6273 @item
6274 a binary expression e.g. @cite{(a + b)}
6275
6276 @item
6277 a function call e.g. @cite{get_distance (&player_ship@comma{} &target)}
6278
6279 @item
6280 etc.
6281 @end itemize
6282 @end quotation
6283
6284 Every rvalue has an associated type, and the API will check to ensure
6285 that types match up correctly (otherwise the context will emit an error).
6286
6287 @geindex gcc_jit_rvalue_get_type (C function)
6288 @anchor{topics/expressions c gcc_jit_rvalue_get_type}@anchor{b0}
6289 @deffn {C Function} gcc_jit_type *gcc_jit_rvalue_get_type (gcc_jit_rvalue@w{ }*rvalue)
6290
6291 Get the type of this rvalue.
6292 @end deffn
6293
6294 @geindex gcc_jit_rvalue_as_object (C function)
6295 @anchor{topics/expressions c gcc_jit_rvalue_as_object}@anchor{14}
6296 @deffn {C Function} gcc_jit_object *gcc_jit_rvalue_as_object (gcc_jit_rvalue@w{ }*rvalue)
6297
6298 Upcast the given rvalue to be an object.
6299 @end deffn
6300
6301 @menu
6302 * Simple expressions::
6303 * Constructor expressions::
6304 * Vector expressions::
6305 * Unary Operations::
6306 * Binary Operations::
6307 * Comparisons::
6308 * Function calls::
6309 * Function pointers::
6310 * Type-coercion::
6311
6312 @end menu
6313
6314 @node Simple expressions,Constructor expressions,,Rvalues
6315 @anchor{topics/expressions simple-expressions}@anchor{b1}
6316 @subsubsection Simple expressions
6317
6318
6319 @geindex gcc_jit_context_new_rvalue_from_int (C function)
6320 @anchor{topics/expressions c gcc_jit_context_new_rvalue_from_int}@anchor{30}
6321 @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)
6322
6323 Given a numeric type (integer or floating point), build an rvalue for
6324 the given constant @code{int} value.
6325 @end deffn
6326
6327 @geindex gcc_jit_context_new_rvalue_from_long (C function)
6328 @anchor{topics/expressions c gcc_jit_context_new_rvalue_from_long}@anchor{b2}
6329 @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)
6330
6331 Given a numeric type (integer or floating point), build an rvalue for
6332 the given constant @code{long} value.
6333 @end deffn
6334
6335 @geindex gcc_jit_context_zero (C function)
6336 @anchor{topics/expressions c gcc_jit_context_zero}@anchor{2b}
6337 @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type)
6338
6339 Given a numeric type (integer or floating point), get the rvalue for
6340 zero. Essentially this is just a shortcut for:
6341
6342 @example
6343 gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 0)
6344 @end example
6345 @end deffn
6346
6347 @geindex gcc_jit_context_one (C function)
6348 @anchor{topics/expressions c gcc_jit_context_one}@anchor{2f}
6349 @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_one (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type)
6350
6351 Given a numeric type (integer or floating point), get the rvalue for
6352 one. Essentially this is just a shortcut for:
6353
6354 @example
6355 gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 1)
6356 @end example
6357 @end deffn
6358
6359 @geindex gcc_jit_context_new_rvalue_from_double (C function)
6360 @anchor{topics/expressions c gcc_jit_context_new_rvalue_from_double}@anchor{31}
6361 @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)
6362
6363 Given a numeric type (integer or floating point), build an rvalue for
6364 the given constant @code{double} value.
6365 @end deffn
6366
6367 @geindex gcc_jit_context_new_rvalue_from_ptr (C function)
6368 @anchor{topics/expressions c gcc_jit_context_new_rvalue_from_ptr}@anchor{b3}
6369 @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)
6370
6371 Given a pointer type, build an rvalue for the given address.
6372 @end deffn
6373
6374 @geindex gcc_jit_context_null (C function)
6375 @anchor{topics/expressions c gcc_jit_context_null}@anchor{b4}
6376 @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_null (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*pointer_type)
6377
6378 Given a pointer type, build an rvalue for @code{NULL}. Essentially this
6379 is just a shortcut for:
6380
6381 @example
6382 gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL)
6383 @end example
6384 @end deffn
6385
6386 @geindex gcc_jit_context_new_string_literal (C function)
6387 @anchor{topics/expressions c gcc_jit_context_new_string_literal}@anchor{b5}
6388 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_string_literal (gcc_jit_context@w{ }*ctxt, const char@w{ }*value)
6389
6390 Generate an rvalue for the given NIL-terminated string, of type
6391 @code{GCC_JIT_TYPE_CONST_CHAR_PTR}.
6392
6393 The parameter @code{value} must be non-NULL. The call takes a copy of the
6394 underlying string, so it is valid to pass in a pointer to an on-stack
6395 buffer.
6396 @end deffn
6397
6398 @node Constructor expressions,Vector expressions,Simple expressions,Rvalues
6399 @anchor{topics/expressions constructor-expressions}@anchor{b6}
6400 @subsubsection Constructor expressions
6401
6402
6403 @quotation
6404
6405 The following functions make constructors for array, struct and union
6406 types.
6407
6408 The constructor rvalue can be used for assignment to locals.
6409 It can be used to initialize global variables with
6410 @ref{b7,,gcc_jit_global_set_initializer_rvalue()}. It can also be used as a
6411 temporary value for function calls and return values, but its address
6412 can’t be taken.
6413
6414 Note that arrays in libgccjit do not collapse to pointers like in
6415 C. I.e. if an array constructor is used as e.g. a return value, the whole
6416 array would be returned by value - array constructors can be assigned to
6417 array variables.
6418
6419 The constructor can contain nested constructors.
6420
6421 Note that a string literal rvalue can’t be used to construct a char array;
6422 the latter needs one rvalue for each char.
6423
6424 These entrypoints were added in @ref{b8,,LIBGCCJIT_ABI_19}; you can test for
6425 their presence using:
6426
6427 @example
6428 #ifdef LIBGCCJIT_HAVE_CTORS
6429 @end example
6430 @end quotation
6431
6432 @geindex gcc_jit_context_new_array_constructor (C function)
6433 @anchor{topics/expressions c gcc_jit_context_new_array_constructor}@anchor{b9}
6434 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_array_constructor (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, size_t@w{ }num_values, gcc_jit_rvalue@w{ }**values)
6435
6436 Create a constructor for an array as an rvalue.
6437
6438 Returns NULL on error. @code{values} are copied and
6439 do not have to outlive the context.
6440
6441 @code{type} specifies what the constructor will build and has to be
6442 an array.
6443
6444 @code{num_values} specifies the number of elements in @code{values} and
6445 it can’t have more elements than the array type.
6446
6447 Each value in @code{values} sets the corresponding value in the array.
6448 If the array type itself has more elements than @code{values}, the
6449 left-over elements will be zeroed.
6450
6451 Each value in @code{values} need to be the same unqualified type as the
6452 array type’s element type.
6453
6454 If @code{num_values} is 0, the @code{values} parameter will be
6455 ignored and zero initialization will be used.
6456
6457 This entrypoint was added in @ref{b8,,LIBGCCJIT_ABI_19}; you can test for its
6458 presence using:
6459
6460 @example
6461 #ifdef LIBGCCJIT_HAVE_CTORS
6462 @end example
6463 @end deffn
6464
6465 @geindex gcc_jit_context_new_struct_constructor (C function)
6466 @anchor{topics/expressions c gcc_jit_context_new_struct_constructor}@anchor{ba}
6467 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_struct_constructor (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, size_t@w{ }num_values, gcc_jit_field@w{ }**fields, gcc_jit_rvalue@w{ }**values)
6468
6469 Create a constructor for a struct as an rvalue.
6470
6471 Returns NULL on error. The two parameter arrays are copied and
6472 do not have to outlive the context.
6473
6474 @code{type} specifies what the constructor will build and has to be
6475 a struct.
6476
6477 @code{num_values} specifies the number of elements in @code{values}.
6478
6479 @code{fields} need to have the same length as @code{values}, or be NULL.
6480
6481 If @code{fields} is null, the values are applied in definition order.
6482
6483 Otherwise, each field in @code{fields} specifies which field in the struct to
6484 set to the corresponding value in @code{values}. @code{fields} and @code{values}
6485 are paired by index.
6486
6487 The fields in @code{fields} have to be in definition order, but there
6488 can be gaps. Any field in the struct that is not specified in
6489 @code{fields} will be zeroed.
6490
6491 The fields in @code{fields} need to be the same objects that were used
6492 to create the struct.
6493
6494 Each value has to have have the same unqualified type as the field
6495 it is applied to.
6496
6497 A NULL value element in @code{values} is a shorthand for zero initialization
6498 of the corresponding field.
6499
6500 If @code{num_values} is 0, the array parameters will be
6501 ignored and zero initialization will be used.
6502
6503 This entrypoint was added in @ref{b8,,LIBGCCJIT_ABI_19}; you can test for its
6504 presence using:
6505
6506 @example
6507 #ifdef LIBGCCJIT_HAVE_CTORS
6508 @end example
6509 @end deffn
6510
6511 @geindex gcc_jit_context_new_union_constructor (C function)
6512 @anchor{topics/expressions c gcc_jit_context_new_union_constructor}@anchor{bb}
6513 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_union_constructor (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, gcc_jit_field@w{ }*field, gcc_jit_rvalue@w{ }*value)
6514
6515 Create a constructor for a union as an rvalue.
6516
6517 Returns NULL on error.
6518
6519 @code{type} specifies what the constructor will build and has to be
6520 an union.
6521
6522 @code{field} specifies which field to set. If it is NULL, the first
6523 field in the union will be set.`@w{`}field`@w{`} need to be the same object
6524 that were used to create the union.
6525
6526 @code{value} specifies what value to set the corresponding field to.
6527 If @code{value} is NULL, zero initialization will be used.
6528
6529 Each value has to have have the same unqualified type as the field
6530 it is applied to.
6531
6532 This entrypoint was added in @ref{b8,,LIBGCCJIT_ABI_19}; you can test for its
6533 presence using:
6534
6535 @example
6536 #ifdef LIBGCCJIT_HAVE_CTORS
6537 @end example
6538 @end deffn
6539
6540 @node Vector expressions,Unary Operations,Constructor expressions,Rvalues
6541 @anchor{topics/expressions vector-expressions}@anchor{bc}
6542 @subsubsection Vector expressions
6543
6544
6545 @geindex gcc_jit_context_new_rvalue_from_vector (C function)
6546 @anchor{topics/expressions c gcc_jit_context_new_rvalue_from_vector}@anchor{89}
6547 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_rvalue_from_vector (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*vec_type, size_t@w{ }num_elements, gcc_jit_rvalue@w{ }**elements)
6548
6549 Build a vector rvalue from an array of elements.
6550
6551 “vec_type” should be a vector type, created using
6552 @ref{87,,gcc_jit_type_get_vector()}.
6553
6554 “num_elements” should match that of the vector type.
6555
6556 This entrypoint was added in @ref{bd,,LIBGCCJIT_ABI_10}; you can test for
6557 its presence using
6558
6559 @example
6560 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector
6561 @end example
6562 @end deffn
6563
6564 @node Unary Operations,Binary Operations,Vector expressions,Rvalues
6565 @anchor{topics/expressions unary-operations}@anchor{be}
6566 @subsubsection Unary Operations
6567
6568
6569 @geindex gcc_jit_context_new_unary_op (C function)
6570 @anchor{topics/expressions c gcc_jit_context_new_unary_op}@anchor{bf}
6571 @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)
6572
6573 Build a unary operation out of an input rvalue.
6574
6575 The parameter @code{result_type} must be a numeric type.
6576 @end deffn
6577
6578 @geindex gcc_jit_unary_op (C type)
6579 @anchor{topics/expressions c gcc_jit_unary_op}@anchor{c0}
6580 @deffn {C Type} enum gcc_jit_unary_op
6581 @end deffn
6582
6583 The available unary operations are:
6584
6585
6586 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx}
6587 @headitem
6588
6589 Unary Operation
6590
6591 @tab
6592
6593 C equivalent
6594
6595 @item
6596
6597 @ref{c1,,GCC_JIT_UNARY_OP_MINUS}
6598
6599 @tab
6600
6601 @cite{-(EXPR)}
6602
6603 @item
6604
6605 @ref{c2,,GCC_JIT_UNARY_OP_BITWISE_NEGATE}
6606
6607 @tab
6608
6609 @cite{~(EXPR)}
6610
6611 @item
6612
6613 @ref{c3,,GCC_JIT_UNARY_OP_LOGICAL_NEGATE}
6614
6615 @tab
6616
6617 @cite{!(EXPR)}
6618
6619 @item
6620
6621 @ref{c4,,GCC_JIT_UNARY_OP_ABS}
6622
6623 @tab
6624
6625 @cite{abs (EXPR)}
6626
6627 @end multitable
6628
6629
6630 @geindex GCC_JIT_UNARY_OP_MINUS (C macro)
6631 @anchor{topics/expressions c GCC_JIT_UNARY_OP_MINUS}@anchor{c1}
6632 @deffn {C Macro} GCC_JIT_UNARY_OP_MINUS
6633
6634 Negate an arithmetic value; analogous to:
6635
6636 @example
6637 -(EXPR)
6638 @end example
6639
6640 in C.
6641 @end deffn
6642
6643 @geindex GCC_JIT_UNARY_OP_BITWISE_NEGATE (C macro)
6644 @anchor{topics/expressions c GCC_JIT_UNARY_OP_BITWISE_NEGATE}@anchor{c2}
6645 @deffn {C Macro} GCC_JIT_UNARY_OP_BITWISE_NEGATE
6646
6647 Bitwise negation of an integer value (one’s complement); analogous
6648 to:
6649
6650 @example
6651 ~(EXPR)
6652 @end example
6653
6654 in C.
6655 @end deffn
6656
6657 @geindex GCC_JIT_UNARY_OP_LOGICAL_NEGATE (C macro)
6658 @anchor{topics/expressions c GCC_JIT_UNARY_OP_LOGICAL_NEGATE}@anchor{c3}
6659 @deffn {C Macro} GCC_JIT_UNARY_OP_LOGICAL_NEGATE
6660
6661 Logical negation of an arithmetic or pointer value; analogous to:
6662
6663 @example
6664 !(EXPR)
6665 @end example
6666
6667 in C.
6668 @end deffn
6669
6670 @geindex GCC_JIT_UNARY_OP_ABS (C macro)
6671 @anchor{topics/expressions c GCC_JIT_UNARY_OP_ABS}@anchor{c4}
6672 @deffn {C Macro} GCC_JIT_UNARY_OP_ABS
6673
6674 Absolute value of an arithmetic expression; analogous to:
6675
6676 @example
6677 abs (EXPR)
6678 @end example
6679
6680 in C.
6681 @end deffn
6682
6683 @node Binary Operations,Comparisons,Unary Operations,Rvalues
6684 @anchor{topics/expressions binary-operations}@anchor{c5}
6685 @subsubsection Binary Operations
6686
6687
6688 @geindex gcc_jit_context_new_binary_op (C function)
6689 @anchor{topics/expressions c gcc_jit_context_new_binary_op}@anchor{12}
6690 @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)
6691
6692 Build a binary operation out of two constituent rvalues.
6693
6694 The parameter @code{result_type} must be a numeric type.
6695 @end deffn
6696
6697 @geindex gcc_jit_binary_op (C type)
6698 @anchor{topics/expressions c gcc_jit_binary_op}@anchor{c6}
6699 @deffn {C Type} enum gcc_jit_binary_op
6700 @end deffn
6701
6702 The available binary operations are:
6703
6704
6705 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx}
6706 @headitem
6707
6708 Binary Operation
6709
6710 @tab
6711
6712 C equivalent
6713
6714 @item
6715
6716 @ref{c7,,GCC_JIT_BINARY_OP_PLUS}
6717
6718 @tab
6719
6720 @cite{x + y}
6721
6722 @item
6723
6724 @ref{c8,,GCC_JIT_BINARY_OP_MINUS}
6725
6726 @tab
6727
6728 @cite{x - y}
6729
6730 @item
6731
6732 @ref{c9,,GCC_JIT_BINARY_OP_MULT}
6733
6734 @tab
6735
6736 @cite{x * y}
6737
6738 @item
6739
6740 @ref{ca,,GCC_JIT_BINARY_OP_DIVIDE}
6741
6742 @tab
6743
6744 @cite{x / y}
6745
6746 @item
6747
6748 @ref{cb,,GCC_JIT_BINARY_OP_MODULO}
6749
6750 @tab
6751
6752 @cite{x % y}
6753
6754 @item
6755
6756 @ref{cc,,GCC_JIT_BINARY_OP_BITWISE_AND}
6757
6758 @tab
6759
6760 @cite{x & y}
6761
6762 @item
6763
6764 @ref{cd,,GCC_JIT_BINARY_OP_BITWISE_XOR}
6765
6766 @tab
6767
6768 @cite{x ^ y}
6769
6770 @item
6771
6772 @ref{ce,,GCC_JIT_BINARY_OP_BITWISE_OR}
6773
6774 @tab
6775
6776 @cite{x | y}
6777
6778 @item
6779
6780 @ref{cf,,GCC_JIT_BINARY_OP_LOGICAL_AND}
6781
6782 @tab
6783
6784 @cite{x && y}
6785
6786 @item
6787
6788 @ref{d0,,GCC_JIT_BINARY_OP_LOGICAL_OR}
6789
6790 @tab
6791
6792 @cite{x || y}
6793
6794 @item
6795
6796 @ref{d1,,GCC_JIT_BINARY_OP_LSHIFT}
6797
6798 @tab
6799
6800 @cite{x << y}
6801
6802 @item
6803
6804 @ref{d2,,GCC_JIT_BINARY_OP_RSHIFT}
6805
6806 @tab
6807
6808 @cite{x >> y}
6809
6810 @end multitable
6811
6812
6813 @geindex GCC_JIT_BINARY_OP_PLUS (C macro)
6814 @anchor{topics/expressions c GCC_JIT_BINARY_OP_PLUS}@anchor{c7}
6815 @deffn {C Macro} GCC_JIT_BINARY_OP_PLUS
6816
6817 Addition of arithmetic values; analogous to:
6818
6819 @example
6820 (EXPR_A) + (EXPR_B)
6821 @end example
6822
6823 in C.
6824
6825 For pointer addition, use @ref{d3,,gcc_jit_context_new_array_access()}.
6826 @end deffn
6827
6828 @geindex GCC_JIT_BINARY_OP_MINUS (C macro)
6829 @anchor{topics/expressions c GCC_JIT_BINARY_OP_MINUS}@anchor{c8}
6830 @deffn {C Macro} GCC_JIT_BINARY_OP_MINUS
6831
6832 Subtraction of arithmetic values; analogous to:
6833
6834 @example
6835 (EXPR_A) - (EXPR_B)
6836 @end example
6837
6838 in C.
6839 @end deffn
6840
6841 @geindex GCC_JIT_BINARY_OP_MULT (C macro)
6842 @anchor{topics/expressions c GCC_JIT_BINARY_OP_MULT}@anchor{c9}
6843 @deffn {C Macro} GCC_JIT_BINARY_OP_MULT
6844
6845 Multiplication of a pair of arithmetic values; analogous to:
6846
6847 @example
6848 (EXPR_A) * (EXPR_B)
6849 @end example
6850
6851 in C.
6852 @end deffn
6853
6854 @geindex GCC_JIT_BINARY_OP_DIVIDE (C macro)
6855 @anchor{topics/expressions c GCC_JIT_BINARY_OP_DIVIDE}@anchor{ca}
6856 @deffn {C Macro} GCC_JIT_BINARY_OP_DIVIDE
6857
6858 Quotient of division of arithmetic values; analogous to:
6859
6860 @example
6861 (EXPR_A) / (EXPR_B)
6862 @end example
6863
6864 in C.
6865
6866 The result type affects the kind of division: if the result type is
6867 integer-based, then the result is truncated towards zero, whereas
6868 a floating-point result type indicates floating-point division.
6869 @end deffn
6870
6871 @geindex GCC_JIT_BINARY_OP_MODULO (C macro)
6872 @anchor{topics/expressions c GCC_JIT_BINARY_OP_MODULO}@anchor{cb}
6873 @deffn {C Macro} GCC_JIT_BINARY_OP_MODULO
6874
6875 Remainder of division of arithmetic values; analogous to:
6876
6877 @example
6878 (EXPR_A) % (EXPR_B)
6879 @end example
6880
6881 in C.
6882 @end deffn
6883
6884 @geindex GCC_JIT_BINARY_OP_BITWISE_AND (C macro)
6885 @anchor{topics/expressions c GCC_JIT_BINARY_OP_BITWISE_AND}@anchor{cc}
6886 @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_AND
6887
6888 Bitwise AND; analogous to:
6889
6890 @example
6891 (EXPR_A) & (EXPR_B)
6892 @end example
6893
6894 in C.
6895 @end deffn
6896
6897 @geindex GCC_JIT_BINARY_OP_BITWISE_XOR (C macro)
6898 @anchor{topics/expressions c GCC_JIT_BINARY_OP_BITWISE_XOR}@anchor{cd}
6899 @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_XOR
6900
6901 Bitwise exclusive OR; analogous to:
6902
6903 @example
6904 (EXPR_A) ^ (EXPR_B)
6905 @end example
6906
6907 in C.
6908 @end deffn
6909
6910 @geindex GCC_JIT_BINARY_OP_BITWISE_OR (C macro)
6911 @anchor{topics/expressions c GCC_JIT_BINARY_OP_BITWISE_OR}@anchor{ce}
6912 @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_OR
6913
6914 Bitwise inclusive OR; analogous to:
6915
6916 @example
6917 (EXPR_A) | (EXPR_B)
6918 @end example
6919
6920 in C.
6921 @end deffn
6922
6923 @geindex GCC_JIT_BINARY_OP_LOGICAL_AND (C macro)
6924 @anchor{topics/expressions c GCC_JIT_BINARY_OP_LOGICAL_AND}@anchor{cf}
6925 @deffn {C Macro} GCC_JIT_BINARY_OP_LOGICAL_AND
6926
6927 Logical AND; analogous to:
6928
6929 @example
6930 (EXPR_A) && (EXPR_B)
6931 @end example
6932
6933 in C.
6934 @end deffn
6935
6936 @geindex GCC_JIT_BINARY_OP_LOGICAL_OR (C macro)
6937 @anchor{topics/expressions c GCC_JIT_BINARY_OP_LOGICAL_OR}@anchor{d0}
6938 @deffn {C Macro} GCC_JIT_BINARY_OP_LOGICAL_OR
6939
6940 Logical OR; analogous to:
6941
6942 @example
6943 (EXPR_A) || (EXPR_B)
6944 @end example
6945
6946 in C.
6947 @end deffn
6948
6949 @geindex GCC_JIT_BINARY_OP_LSHIFT (C macro)
6950 @anchor{topics/expressions c GCC_JIT_BINARY_OP_LSHIFT}@anchor{d1}
6951 @deffn {C Macro} GCC_JIT_BINARY_OP_LSHIFT
6952
6953 Left shift; analogous to:
6954
6955 @example
6956 (EXPR_A) << (EXPR_B)
6957 @end example
6958
6959 in C.
6960 @end deffn
6961
6962 @geindex GCC_JIT_BINARY_OP_RSHIFT (C macro)
6963 @anchor{topics/expressions c GCC_JIT_BINARY_OP_RSHIFT}@anchor{d2}
6964 @deffn {C Macro} GCC_JIT_BINARY_OP_RSHIFT
6965
6966 Right shift; analogous to:
6967
6968 @example
6969 (EXPR_A) >> (EXPR_B)
6970 @end example
6971
6972 in C.
6973 @end deffn
6974
6975 @node Comparisons,Function calls,Binary Operations,Rvalues
6976 @anchor{topics/expressions comparisons}@anchor{d4}
6977 @subsubsection Comparisons
6978
6979
6980 @geindex gcc_jit_context_new_comparison (C function)
6981 @anchor{topics/expressions c gcc_jit_context_new_comparison}@anchor{2c}
6982 @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)
6983
6984 Build a boolean rvalue out of the comparison of two other rvalues.
6985 @end deffn
6986
6987 @geindex gcc_jit_comparison (C type)
6988 @anchor{topics/expressions c gcc_jit_comparison}@anchor{d5}
6989 @deffn {C Type} enum gcc_jit_comparison
6990 @end deffn
6991
6992
6993 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx}
6994 @headitem
6995
6996 Comparison
6997
6998 @tab
6999
7000 C equivalent
7001
7002 @item
7003
7004 @code{GCC_JIT_COMPARISON_EQ}
7005
7006 @tab
7007
7008 @cite{x == y}
7009
7010 @item
7011
7012 @code{GCC_JIT_COMPARISON_NE}
7013
7014 @tab
7015
7016 @cite{x != y}
7017
7018 @item
7019
7020 @code{GCC_JIT_COMPARISON_LT}
7021
7022 @tab
7023
7024 @cite{x < y}
7025
7026 @item
7027
7028 @code{GCC_JIT_COMPARISON_LE}
7029
7030 @tab
7031
7032 @cite{x <= y}
7033
7034 @item
7035
7036 @code{GCC_JIT_COMPARISON_GT}
7037
7038 @tab
7039
7040 @cite{x > y}
7041
7042 @item
7043
7044 @code{GCC_JIT_COMPARISON_GE}
7045
7046 @tab
7047
7048 @cite{x >= y}
7049
7050 @end multitable
7051
7052
7053 @node Function calls,Function pointers,Comparisons,Rvalues
7054 @anchor{topics/expressions function-calls}@anchor{d6}
7055 @subsubsection Function calls
7056
7057
7058 @geindex gcc_jit_context_new_call (C function)
7059 @anchor{topics/expressions c gcc_jit_context_new_call}@anchor{d7}
7060 @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)
7061
7062 Given a function and the given table of argument rvalues, construct a
7063 call to the function, with the result as an rvalue.
7064
7065 @cartouche
7066 @quotation Note
7067 @ref{d7,,gcc_jit_context_new_call()} merely builds a
7068 @ref{13,,gcc_jit_rvalue} i.e. an expression that can be evaluated,
7069 perhaps as part of a more complicated expression.
7070 The call @emph{won’t} happen unless you add a statement to a function
7071 that evaluates the expression.
7072
7073 For example, if you want to call a function and discard the result
7074 (or to call a function with @code{void} return type), use
7075 @ref{d8,,gcc_jit_block_add_eval()}:
7076
7077 @example
7078 /* Add "(void)printf (arg0, arg1);". */
7079 gcc_jit_block_add_eval (
7080 block, NULL,
7081 gcc_jit_context_new_call (
7082 ctxt,
7083 NULL,
7084 printf_func,
7085 2, args));
7086 @end example
7087 @end quotation
7088 @end cartouche
7089 @end deffn
7090
7091 @geindex gcc_jit_context_new_call_through_ptr (C function)
7092 @anchor{topics/expressions c gcc_jit_context_new_call_through_ptr}@anchor{d9}
7093 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_call_through_ptr (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*fn_ptr, int@w{ }numargs, gcc_jit_rvalue@w{ }**args)
7094
7095 Given an rvalue of function pointer type (e.g. from
7096 @ref{97,,gcc_jit_context_new_function_ptr_type()}), and the given table of
7097 argument rvalues, construct a call to the function pointer, with the
7098 result as an rvalue.
7099
7100 @cartouche
7101 @quotation Note
7102 The same caveat as for @ref{d7,,gcc_jit_context_new_call()} applies.
7103 @end quotation
7104 @end cartouche
7105 @end deffn
7106
7107 @geindex gcc_jit_rvalue_set_bool_require_tail_call (C function)
7108 @anchor{topics/expressions c gcc_jit_rvalue_set_bool_require_tail_call}@anchor{da}
7109 @deffn {C Function} void gcc_jit_rvalue_set_bool_require_tail_call (gcc_jit_rvalue@w{ }*call, int@w{ }require_tail_call)
7110
7111 Given an @ref{13,,gcc_jit_rvalue} for a call created through
7112 @ref{d7,,gcc_jit_context_new_call()} or
7113 @ref{d9,,gcc_jit_context_new_call_through_ptr()}, mark/clear the
7114 call as needing tail-call optimization. The optimizer will
7115 attempt to optimize the call into a jump instruction; if it is
7116 unable to do do, an error will be emitted.
7117
7118 This may be useful when implementing functions that use the
7119 continuation-passing style (e.g. for functional programming
7120 languages), in which every function “returns” by calling a
7121 “continuation” function pointer. This call must be
7122 guaranteed to be implemented as a jump, otherwise the program
7123 could consume an arbitrary amount of stack space as it executed.
7124
7125 This entrypoint was added in @ref{db,,LIBGCCJIT_ABI_6}; you can test for
7126 its presence using
7127
7128 @example
7129 #ifdef LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call
7130 @end example
7131 @end deffn
7132
7133 @node Function pointers,Type-coercion,Function calls,Rvalues
7134 @anchor{topics/expressions function-pointers}@anchor{dc}
7135 @subsubsection Function pointers
7136
7137
7138 Function pointers can be obtained:
7139
7140 @quotation
7141
7142
7143 @itemize *
7144
7145 @item
7146 from a @ref{29,,gcc_jit_function} using
7147 @ref{dd,,gcc_jit_function_get_address()}, or
7148
7149 @item
7150 from an existing function using
7151 @ref{b3,,gcc_jit_context_new_rvalue_from_ptr()},
7152 using a function pointer type obtained using
7153 @ref{97,,gcc_jit_context_new_function_ptr_type()}.
7154 @end itemize
7155 @end quotation
7156
7157 @node Type-coercion,,Function pointers,Rvalues
7158 @anchor{topics/expressions type-coercion}@anchor{de}
7159 @subsubsection Type-coercion
7160
7161
7162 @geindex gcc_jit_context_new_cast (C function)
7163 @anchor{topics/expressions c gcc_jit_context_new_cast}@anchor{df}
7164 @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)
7165
7166 Given an rvalue of T, construct another rvalue of another type.
7167
7168 Currently only a limited set of conversions are possible:
7169
7170 @quotation
7171
7172
7173 @itemize *
7174
7175 @item
7176 int <-> float
7177
7178 @item
7179 int <-> bool
7180
7181 @item
7182 P* <-> Q*, for pointer types P and Q
7183 @end itemize
7184 @end quotation
7185 @end deffn
7186
7187 @geindex gcc_jit_context_new_bitcast (C function)
7188 @anchor{topics/expressions c gcc_jit_context_new_bitcast}@anchor{e0}
7189 @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_bitcast (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*rvalue, gcc_jit_type@w{ }*type)
7190
7191 Given an rvalue of T, bitcast it to another type, meaning that this will
7192 generate a new rvalue by interpreting the bits of @code{rvalue} to the layout
7193 of @code{type}.
7194
7195 The type of rvalue must be the same size as the size of @code{type}.
7196
7197 This entrypoint was added in @ref{e1,,LIBGCCJIT_ABI_21}; you can test for
7198 its presence using
7199
7200 @example
7201 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitcast
7202 @end example
7203 @end deffn
7204
7205 @node Lvalues,Working with pointers structs and unions,Rvalues,Expressions
7206 @anchor{topics/expressions lvalues}@anchor{e2}
7207 @subsection Lvalues
7208
7209
7210 @geindex gcc_jit_lvalue (C type)
7211 @anchor{topics/expressions c gcc_jit_lvalue}@anchor{24}
7212 @deffn {C Type} gcc_jit_lvalue
7213 @end deffn
7214
7215 An lvalue is something that can of the @emph{left}-hand side of an assignment:
7216 a storage area (such as a variable). It is also usable as an rvalue,
7217 where the rvalue is computed by reading from the storage area.
7218
7219 @geindex gcc_jit_lvalue_as_object (C function)
7220 @anchor{topics/expressions c gcc_jit_lvalue_as_object}@anchor{e3}
7221 @deffn {C Function} gcc_jit_object * gcc_jit_lvalue_as_object (gcc_jit_lvalue@w{ }*lvalue)
7222
7223 Upcast an lvalue to be an object.
7224 @end deffn
7225
7226 @geindex gcc_jit_lvalue_as_rvalue (C function)
7227 @anchor{topics/expressions c gcc_jit_lvalue_as_rvalue}@anchor{e4}
7228 @deffn {C Function} gcc_jit_rvalue * gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue@w{ }*lvalue)
7229
7230 Upcast an lvalue to be an rvalue.
7231 @end deffn
7232
7233 @geindex gcc_jit_lvalue_get_address (C function)
7234 @anchor{topics/expressions c gcc_jit_lvalue_get_address}@anchor{e5}
7235 @deffn {C Function} gcc_jit_rvalue * gcc_jit_lvalue_get_address (gcc_jit_lvalue@w{ }*lvalue, gcc_jit_location@w{ }*loc)
7236
7237 Take the address of an lvalue; analogous to:
7238
7239 @example
7240 &(EXPR)
7241 @end example
7242
7243 in C.
7244 @end deffn
7245
7246 @geindex gcc_jit_lvalue_set_tls_model (C function)
7247 @anchor{topics/expressions c gcc_jit_lvalue_set_tls_model}@anchor{e6}
7248 @deffn {C Function} void gcc_jit_lvalue_set_tls_model (gcc_jit_lvalue@w{ }*lvalue, enum gcc_jit_tls_model@w{ }model)
7249
7250 Make a variable a thread-local variable.
7251
7252 The “model” parameter determines the thread-local storage model of the “lvalue”:
7253
7254 @geindex gcc_jit_tls_model (C type)
7255 @anchor{topics/expressions c gcc_jit_tls_model}@anchor{e7}
7256 @deffn {C Type} enum gcc_jit_tls_model
7257 @end deffn
7258
7259 @geindex GCC_JIT_TLS_MODEL_NONE (C macro)
7260 @anchor{topics/expressions c GCC_JIT_TLS_MODEL_NONE}@anchor{e8}
7261 @deffn {C Macro} GCC_JIT_TLS_MODEL_NONE
7262
7263 Don’t set the TLS model.
7264 @end deffn
7265
7266 @geindex GCC_JIT_TLS_MODEL_GLOBAL_DYNAMIC (C macro)
7267 @anchor{topics/expressions c GCC_JIT_TLS_MODEL_GLOBAL_DYNAMIC}@anchor{e9}
7268 @deffn {C Macro} GCC_JIT_TLS_MODEL_GLOBAL_DYNAMIC
7269 @end deffn
7270
7271 @geindex GCC_JIT_TLS_MODEL_LOCAL_DYNAMIC (C macro)
7272 @anchor{topics/expressions c GCC_JIT_TLS_MODEL_LOCAL_DYNAMIC}@anchor{ea}
7273 @deffn {C Macro} GCC_JIT_TLS_MODEL_LOCAL_DYNAMIC
7274 @end deffn
7275
7276 @geindex GCC_JIT_TLS_MODEL_INITIAL_EXEC (C macro)
7277 @anchor{topics/expressions c GCC_JIT_TLS_MODEL_INITIAL_EXEC}@anchor{eb}
7278 @deffn {C Macro} GCC_JIT_TLS_MODEL_INITIAL_EXEC
7279 @end deffn
7280
7281 @geindex GCC_JIT_TLS_MODEL_LOCAL_EXEC (C macro)
7282 @anchor{topics/expressions c GCC_JIT_TLS_MODEL_LOCAL_EXEC}@anchor{ec}
7283 @deffn {C Macro} GCC_JIT_TLS_MODEL_LOCAL_EXEC
7284 @end deffn
7285
7286 This is analogous to:
7287
7288 @example
7289 _Thread_local int foo __attribute__ ((tls_model("MODEL")));
7290 @end example
7291
7292 in C.
7293
7294 This entrypoint was added in @ref{ed,,LIBGCCJIT_ABI_17}; you can test for
7295 its presence using
7296
7297 @example
7298 #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_tls_model
7299 @end example
7300 @end deffn
7301
7302 @geindex gcc_jit_lvalue_set_link_section (C function)
7303 @anchor{topics/expressions c gcc_jit_lvalue_set_link_section}@anchor{ee}
7304 @deffn {C Function} void gcc_jit_lvalue_set_link_section (gcc_jit_lvalue@w{ }*lvalue, const char@w{ }*section_name)
7305
7306 Set the link section of a variable.
7307 The parameter @code{section_name} must be non-NULL and must contain the
7308 leading dot. Analogous to:
7309
7310 @example
7311 int variable __attribute__((section(".section")));
7312 @end example
7313
7314 in C.
7315
7316 This entrypoint was added in @ref{ef,,LIBGCCJIT_ABI_18}; you can test for
7317 its presence using
7318
7319 @example
7320 #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_link_section
7321 @end example
7322 @end deffn
7323
7324
7325 @deffn {C Function} void gcc_jit_lvalue_set_register_name (gcc_jit_lvalue *lvalue, const char *reg_name);
7326
7327 Set the register name of a variable.
7328 The parameter @code{reg_name} must be non-NULL. Analogous to:
7329
7330 @example
7331 register int variable asm ("r12");
7332 @end example
7333
7334 in C.
7335
7336 This entrypoint was added in @ref{f0,,LIBGCCJIT_ABI_22}; you can test for
7337 its presence using
7338
7339 @example
7340 #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_register_name
7341 @end example
7342 @end deffn
7343
7344 @geindex gcc_jit_lvalue_set_alignment (C function)
7345 @anchor{topics/expressions c gcc_jit_lvalue_set_alignment}@anchor{f1}
7346 @deffn {C Function} void gcc_jit_lvalue_set_alignment (gcc_jit_lvalue@w{ }*lvalue, unsigned@w{ }bytes)
7347
7348 Set the alignment of a variable, in bytes.
7349 Analogous to:
7350
7351 @example
7352 int variable __attribute__((aligned (16)));
7353 @end example
7354
7355 in C.
7356
7357 This entrypoint was added in @ref{f2,,LIBGCCJIT_ABI_24}; you can test for
7358 its presence using
7359
7360 @example
7361 #ifdef LIBGCCJIT_HAVE_ALIGNMENT
7362 @end example
7363 @end deffn
7364
7365 @geindex gcc_jit_lvalue_get_alignment (C function)
7366 @anchor{topics/expressions c gcc_jit_lvalue_get_alignment}@anchor{f3}
7367 @deffn {C Function} unsigned gcc_jit_lvalue_get_alignment (gcc_jit_lvalue@w{ }*lvalue)
7368
7369 Return the alignment of a variable set by @code{gcc_jit_lvalue_set_alignment}.
7370 Return 0 if the alignment was not set. Analogous to:
7371
7372 @example
7373 _Alignof (variable)
7374 @end example
7375
7376 in C.
7377
7378 This entrypoint was added in @ref{f2,,LIBGCCJIT_ABI_24}; you can test for
7379 its presence using
7380
7381 @example
7382 #ifdef LIBGCCJIT_HAVE_ALIGNMENT
7383 @end example
7384 @end deffn
7385
7386 @menu
7387 * Global variables::
7388
7389 @end menu
7390
7391 @node Global variables,,,Lvalues
7392 @anchor{topics/expressions global-variables}@anchor{f4}
7393 @subsubsection Global variables
7394
7395
7396 @geindex gcc_jit_context_new_global (C function)
7397 @anchor{topics/expressions c gcc_jit_context_new_global}@anchor{f5}
7398 @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)
7399
7400 Add a new global variable of the given type and name to the context.
7401
7402 The parameter @code{type} must be non-@cite{void}.
7403
7404 The parameter @code{name} must be non-NULL. The call takes a copy of the
7405 underlying string, so it is valid to pass in a pointer to an on-stack
7406 buffer.
7407
7408 The “kind” parameter determines the visibility of the “global” outside
7409 of the @ref{16,,gcc_jit_result}:
7410
7411 @geindex gcc_jit_global_kind (C type)
7412 @anchor{topics/expressions c gcc_jit_global_kind}@anchor{f6}
7413 @deffn {C Type} enum gcc_jit_global_kind
7414 @end deffn
7415
7416 @geindex GCC_JIT_GLOBAL_EXPORTED (C macro)
7417 @anchor{topics/expressions c GCC_JIT_GLOBAL_EXPORTED}@anchor{f7}
7418 @deffn {C Macro} GCC_JIT_GLOBAL_EXPORTED
7419
7420 Global is defined by the client code and is visible
7421 by name outside of this JIT context via
7422 @ref{f8,,gcc_jit_result_get_global()} (and this value is required for
7423 the global to be accessible via that entrypoint).
7424 @end deffn
7425
7426 @geindex GCC_JIT_GLOBAL_INTERNAL (C macro)
7427 @anchor{topics/expressions c GCC_JIT_GLOBAL_INTERNAL}@anchor{f9}
7428 @deffn {C Macro} GCC_JIT_GLOBAL_INTERNAL
7429
7430 Global is defined by the client code, but is invisible
7431 outside of it. Analogous to a “static” global within a .c file.
7432 Specifically, the variable will only be visible within this
7433 context and within child contexts.
7434 @end deffn
7435
7436 @geindex GCC_JIT_GLOBAL_IMPORTED (C macro)
7437 @anchor{topics/expressions c GCC_JIT_GLOBAL_IMPORTED}@anchor{fa}
7438 @deffn {C Macro} GCC_JIT_GLOBAL_IMPORTED
7439
7440 Global is not defined by the client code; we’re merely
7441 referring to it. Analogous to using an “extern” global from a
7442 header file.
7443 @end deffn
7444 @end deffn
7445
7446 @geindex gcc_jit_global_set_initializer (C function)
7447 @anchor{topics/expressions c gcc_jit_global_set_initializer}@anchor{fb}
7448 @deffn {C Function} gcc_jit_lvalue * gcc_jit_global_set_initializer (gcc_jit_lvalue@w{ }*global, const void@w{ }*blob, size_t@w{ }num_bytes)
7449
7450 Set an initializer for @code{global} using the memory content pointed
7451 by @code{blob} for @code{num_bytes}. @code{global} must be an array of an
7452 integral type. Return the global itself.
7453
7454 The parameter @code{blob} must be non-NULL. The call copies the memory
7455 pointed by @code{blob} for @code{num_bytes} bytes, so it is valid to pass
7456 in a pointer to an on-stack buffer. The content will be stored in
7457 the compilation unit and used as initialization value of the array.
7458
7459 This entrypoint was added in @ref{fc,,LIBGCCJIT_ABI_14}; you can test for
7460 its presence using
7461
7462 @example
7463 #ifdef LIBGCCJIT_HAVE_gcc_jit_global_set_initializer
7464 @end example
7465 @end deffn
7466
7467 @geindex gcc_jit_global_set_initializer_rvalue (C function)
7468 @anchor{topics/expressions c gcc_jit_global_set_initializer_rvalue}@anchor{b7}
7469 @deffn {C Function} gcc_jit_lvalue * gcc_jit_global_set_initializer_rvalue (gcc_jit_lvalue@w{ }*global, gcc_jit_rvalue@w{ }*init_value)
7470
7471 Set the initial value of a global with an rvalue.
7472
7473 The rvalue needs to be a constant expression, e.g. no function calls.
7474
7475 The global can’t have the @code{kind} @ref{fa,,GCC_JIT_GLOBAL_IMPORTED}.
7476
7477 As a non-comprehensive example it is OK to do the equivalent of:
7478
7479 @example
7480 int foo = 3 * 2; /* rvalue from gcc_jit_context_new_binary_op. */
7481 int arr[] = @{1,2,3,4@}; /* rvalue from gcc_jit_context_new_constructor. */
7482 int *bar = &arr[2] + 1; /* rvalue from nested "get address" of "array access". */
7483 const int baz = 3; /* rvalue from gcc_jit_context_rvalue_from_int. */
7484 int boz = baz; /* rvalue from gcc_jit_lvalue_as_rvalue. */
7485 @end example
7486
7487 Use together with @ref{ba,,gcc_jit_context_new_struct_constructor()},
7488 @ref{bb,,gcc_jit_context_new_union_constructor()}, @ref{b9,,gcc_jit_context_new_array_constructor()}
7489 to initialize structs, unions and arrays.
7490
7491 On success, returns the @code{global} parameter unchanged. Otherwise, @code{NULL}.
7492
7493 This entrypoint was added in @ref{b8,,LIBGCCJIT_ABI_19}; you can test for its
7494 presence using:
7495
7496 @example
7497 #ifdef LIBGCCJIT_HAVE_CTORS
7498 @end example
7499 @end deffn
7500
7501 @node Working with pointers structs and unions,,Lvalues,Expressions
7502 @anchor{topics/expressions working-with-pointers-structs-and-unions}@anchor{fd}
7503 @subsection Working with pointers, structs and unions
7504
7505
7506 @geindex gcc_jit_rvalue_dereference (C function)
7507 @anchor{topics/expressions c gcc_jit_rvalue_dereference}@anchor{fe}
7508 @deffn {C Function} gcc_jit_lvalue * gcc_jit_rvalue_dereference (gcc_jit_rvalue@w{ }*rvalue, gcc_jit_location@w{ }*loc)
7509
7510 Given an rvalue of pointer type @code{T *}, dereferencing the pointer,
7511 getting an lvalue of type @code{T}. Analogous to:
7512
7513 @example
7514 *(EXPR)
7515 @end example
7516
7517 in C.
7518 @end deffn
7519
7520 Field access is provided separately for both lvalues and rvalues.
7521
7522 @geindex gcc_jit_lvalue_access_field (C function)
7523 @anchor{topics/expressions c gcc_jit_lvalue_access_field}@anchor{ff}
7524 @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)
7525
7526 Given an lvalue of struct or union type, access the given field,
7527 getting an lvalue of the field’s type. Analogous to:
7528
7529 @example
7530 (EXPR).field = ...;
7531 @end example
7532
7533 in C.
7534 @end deffn
7535
7536 @geindex gcc_jit_rvalue_access_field (C function)
7537 @anchor{topics/expressions c gcc_jit_rvalue_access_field}@anchor{100}
7538 @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)
7539
7540 Given an rvalue of struct or union type, access the given field
7541 as an rvalue. Analogous to:
7542
7543 @example
7544 (EXPR).field
7545 @end example
7546
7547 in C.
7548 @end deffn
7549
7550 @geindex gcc_jit_rvalue_dereference_field (C function)
7551 @anchor{topics/expressions c gcc_jit_rvalue_dereference_field}@anchor{101}
7552 @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)
7553
7554 Given an rvalue of pointer type @code{T *} where T is of struct or union
7555 type, access the given field as an lvalue. Analogous to:
7556
7557 @example
7558 (EXPR)->field
7559 @end example
7560
7561 in C, itself equivalent to @code{(*EXPR).FIELD}.
7562 @end deffn
7563
7564 @geindex gcc_jit_context_new_array_access (C function)
7565 @anchor{topics/expressions c gcc_jit_context_new_array_access}@anchor{d3}
7566 @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)
7567
7568 Given an rvalue of pointer type @code{T *}, get at the element @cite{T} at
7569 the given index, using standard C array indexing rules i.e. each
7570 increment of @code{index} corresponds to @code{sizeof(T)} bytes.
7571 Analogous to:
7572
7573 @example
7574 PTR[INDEX]
7575 @end example
7576
7577 in C (or, indeed, to @code{PTR + INDEX}).
7578 @end deffn
7579
7580 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
7581 @c Originally contributed by David Malcolm <[email protected]>
7582 @c
7583 @c This is free software: you can redistribute it and/or modify it
7584 @c under the terms of the GNU General Public License as published by
7585 @c the Free Software Foundation, either version 3 of the License, or
7586 @c (at your option) any later version.
7587 @c
7588 @c This program is distributed in the hope that it will be useful, but
7589 @c WITHOUT ANY WARRANTY; without even the implied warranty of
7590 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
7591 @c General Public License for more details.
7592 @c
7593 @c You should have received a copy of the GNU General Public License
7594 @c along with this program. If not, see
7595 @c <https://www.gnu.org/licenses/>.
7596
7597 @node Creating and using functions,Function pointers<2>,Expressions,Topic Reference
7598 @anchor{topics/functions doc}@anchor{102}@anchor{topics/functions creating-and-using-functions}@anchor{103}
7599 @section Creating and using functions
7600
7601
7602 @menu
7603 * Params::
7604 * Functions::
7605 * Blocks::
7606 * Statements::
7607
7608 @end menu
7609
7610 @node Params,Functions,,Creating and using functions
7611 @anchor{topics/functions params}@anchor{104}
7612 @subsection Params
7613
7614
7615 @geindex gcc_jit_param (C type)
7616 @anchor{topics/functions c gcc_jit_param}@anchor{25}
7617 @deffn {C Type} gcc_jit_param
7618
7619 A @cite{gcc_jit_param} represents a parameter to a function.
7620 @end deffn
7621
7622 @geindex gcc_jit_context_new_param (C function)
7623 @anchor{topics/functions c gcc_jit_context_new_param}@anchor{10}
7624 @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)
7625
7626 In preparation for creating a function, create a new parameter of the
7627 given type and name.
7628
7629 The parameter @code{type} must be non-@cite{void}.
7630
7631 The parameter @code{name} must be non-NULL. The call takes a copy of the
7632 underlying string, so it is valid to pass in a pointer to an on-stack
7633 buffer.
7634 @end deffn
7635
7636 Parameters are lvalues, and thus are also rvalues (and objects), so the
7637 following upcasts are available:
7638
7639 @geindex gcc_jit_param_as_lvalue (C function)
7640 @anchor{topics/functions c gcc_jit_param_as_lvalue}@anchor{105}
7641 @deffn {C Function} gcc_jit_lvalue * gcc_jit_param_as_lvalue (gcc_jit_param@w{ }*param)
7642
7643 Upcasting from param to lvalue.
7644 @end deffn
7645
7646 @geindex gcc_jit_param_as_rvalue (C function)
7647 @anchor{topics/functions c gcc_jit_param_as_rvalue}@anchor{106}
7648 @deffn {C Function} gcc_jit_rvalue * gcc_jit_param_as_rvalue (gcc_jit_param@w{ }*param)
7649
7650 Upcasting from param to rvalue.
7651 @end deffn
7652
7653 @geindex gcc_jit_param_as_object (C function)
7654 @anchor{topics/functions c gcc_jit_param_as_object}@anchor{107}
7655 @deffn {C Function} gcc_jit_object * gcc_jit_param_as_object (gcc_jit_param@w{ }*param)
7656
7657 Upcasting from param to object.
7658 @end deffn
7659
7660 @node Functions,Blocks,Params,Creating and using functions
7661 @anchor{topics/functions functions}@anchor{108}
7662 @subsection Functions
7663
7664
7665 @geindex gcc_jit_function (C type)
7666 @anchor{topics/functions c gcc_jit_function}@anchor{29}
7667 @deffn {C Type} gcc_jit_function
7668
7669 A @cite{gcc_jit_function} represents a function - either one that we’re
7670 creating ourselves, or one that we’re referencing.
7671 @end deffn
7672
7673 @geindex gcc_jit_context_new_function (C function)
7674 @anchor{topics/functions c gcc_jit_context_new_function}@anchor{11}
7675 @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)
7676
7677 Create a gcc_jit_function with the given name and parameters.
7678
7679 @geindex gcc_jit_function_kind (C type)
7680 @anchor{topics/functions c gcc_jit_function_kind}@anchor{109}
7681 @deffn {C Type} enum gcc_jit_function_kind
7682 @end deffn
7683
7684 This enum controls the kind of function created, and has the following
7685 values:
7686
7687 @quotation
7688
7689 @geindex GCC_JIT_FUNCTION_EXPORTED (C macro)
7690 @anchor{topics/functions c GCC_JIT_FUNCTION_EXPORTED}@anchor{10a}
7691 @deffn {C Macro} GCC_JIT_FUNCTION_EXPORTED
7692
7693 Function is defined by the client code and visible
7694 by name outside of the JIT.
7695
7696 This value is required if you want to extract machine code
7697 for this function from a @ref{16,,gcc_jit_result} via
7698 @ref{17,,gcc_jit_result_get_code()}.
7699 @end deffn
7700
7701 @geindex GCC_JIT_FUNCTION_INTERNAL (C macro)
7702 @anchor{topics/functions c GCC_JIT_FUNCTION_INTERNAL}@anchor{10b}
7703 @deffn {C Macro} GCC_JIT_FUNCTION_INTERNAL
7704
7705 Function is defined by the client code, but is invisible
7706 outside of the JIT. Analogous to a “static” function.
7707 @end deffn
7708
7709 @geindex GCC_JIT_FUNCTION_IMPORTED (C macro)
7710 @anchor{topics/functions c GCC_JIT_FUNCTION_IMPORTED}@anchor{10c}
7711 @deffn {C Macro} GCC_JIT_FUNCTION_IMPORTED
7712
7713 Function is not defined by the client code; we’re merely
7714 referring to it. Analogous to using an “extern” function from a
7715 header file.
7716 @end deffn
7717
7718 @geindex GCC_JIT_FUNCTION_ALWAYS_INLINE (C macro)
7719 @anchor{topics/functions c GCC_JIT_FUNCTION_ALWAYS_INLINE}@anchor{10d}
7720 @deffn {C Macro} GCC_JIT_FUNCTION_ALWAYS_INLINE
7721
7722 Function is only ever inlined into other functions, and is
7723 invisible outside of the JIT.
7724
7725 Analogous to prefixing with @code{inline} and adding
7726 @code{__attribute__((always_inline))}
7727
7728 Inlining will only occur when the optimization level is
7729 above 0; when optimization is off, this is essentially the
7730 same as GCC_JIT_FUNCTION_INTERNAL.
7731 @end deffn
7732 @end quotation
7733
7734 The parameter @code{name} must be non-NULL. The call takes a copy of the
7735 underlying string, so it is valid to pass in a pointer to an on-stack
7736 buffer.
7737 @end deffn
7738
7739 @geindex gcc_jit_context_get_builtin_function (C function)
7740 @anchor{topics/functions c gcc_jit_context_get_builtin_function}@anchor{10e}
7741 @deffn {C Function} gcc_jit_function * gcc_jit_context_get_builtin_function (gcc_jit_context@w{ }*ctxt, const char@w{ }*name)
7742
7743 Get the @ref{29,,gcc_jit_function} for the built-in function with the
7744 given name. For example:
7745
7746 @example
7747 gcc_jit_function *fn
7748 = gcc_jit_context_get_builtin_function (ctxt, "__builtin_memcpy");
7749 @end example
7750
7751 @cartouche
7752 @quotation Note
7753 Due to technical limitations with how libgccjit interacts with
7754 the insides of GCC, not all built-in functions are supported. More
7755 precisely, not all types are supported for parameters of built-in
7756 functions from libgccjit. Attempts to get a built-in function that
7757 uses such a parameter will lead to an error being emitted within
7758 the context.
7759 @end quotation
7760 @end cartouche
7761 @end deffn
7762
7763 @geindex gcc_jit_function_as_object (C function)
7764 @anchor{topics/functions c gcc_jit_function_as_object}@anchor{10f}
7765 @deffn {C Function} gcc_jit_object * gcc_jit_function_as_object (gcc_jit_function@w{ }*func)
7766
7767 Upcasting from function to object.
7768 @end deffn
7769
7770 @geindex gcc_jit_function_get_param (C function)
7771 @anchor{topics/functions c gcc_jit_function_get_param}@anchor{110}
7772 @deffn {C Function} gcc_jit_param * gcc_jit_function_get_param (gcc_jit_function@w{ }*func, int@w{ }index)
7773
7774 Get the param of the given index (0-based).
7775 @end deffn
7776
7777 @geindex gcc_jit_function_dump_to_dot (C function)
7778 @anchor{topics/functions c gcc_jit_function_dump_to_dot}@anchor{33}
7779 @deffn {C Function} void gcc_jit_function_dump_to_dot (gcc_jit_function@w{ }*func, const char@w{ }*path)
7780
7781 Emit the function in graphviz format to the given path.
7782 @end deffn
7783
7784 @geindex gcc_jit_function_new_local (C function)
7785 @anchor{topics/functions c gcc_jit_function_new_local}@anchor{26}
7786 @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)
7787
7788 Create a new local variable within the function, of the given type and
7789 name.
7790
7791 The parameter @code{type} must be non-@cite{void}.
7792
7793 The parameter @code{name} must be non-NULL. The call takes a copy of the
7794 underlying string, so it is valid to pass in a pointer to an on-stack
7795 buffer.
7796 @end deffn
7797
7798 @geindex gcc_jit_function_get_param_count (C function)
7799 @anchor{topics/functions c gcc_jit_function_get_param_count}@anchor{111}
7800 @deffn {C Function} size_t gcc_jit_function_get_param_count (gcc_jit_function@w{ }*func)
7801
7802 Get the number of parameters of the function.
7803 @end deffn
7804
7805 @geindex gcc_jit_function_get_return_type (C function)
7806 @anchor{topics/functions c gcc_jit_function_get_return_type}@anchor{112}
7807 @deffn {C Function} gcc_jit_type * gcc_jit_function_get_return_type (gcc_jit_function@w{ }*func)
7808
7809 Get the return type of the function.
7810
7811 The API entrypoints relating to getting info about parameters and return
7812 types:
7813
7814 @quotation
7815
7816
7817 @itemize *
7818
7819 @item
7820 @ref{112,,gcc_jit_function_get_return_type()}
7821
7822 @item
7823 @ref{111,,gcc_jit_function_get_param_count()}
7824 @end itemize
7825 @end quotation
7826
7827 were added in @ref{a8,,LIBGCCJIT_ABI_16}; you can test for their presence
7828 using
7829
7830 @example
7831 #ifdef LIBGCCJIT_HAVE_REFLECTION
7832 @end example
7833
7834 @geindex gcc_jit_case (C type)
7835 @anchor{topics/functions c gcc_jit_case}@anchor{113}
7836 @deffn {C Type} gcc_jit_case
7837 @end deffn
7838 @end deffn
7839
7840 @node Blocks,Statements,Functions,Creating and using functions
7841 @anchor{topics/functions blocks}@anchor{114}
7842 @subsection Blocks
7843
7844
7845 @geindex gcc_jit_block (C type)
7846 @anchor{topics/functions c gcc_jit_block}@anchor{28}
7847 @deffn {C Type} gcc_jit_block
7848
7849 A @cite{gcc_jit_block} represents a basic block within a function i.e. a
7850 sequence of statements with a single entry point and a single exit
7851 point.
7852
7853 The first basic block that you create within a function will
7854 be the entrypoint.
7855
7856 Each basic block that you create within a function must be
7857 terminated, either with a conditional, a jump, a return, or a
7858 switch.
7859
7860 It’s legal to have multiple basic blocks that return within
7861 one function.
7862 @end deffn
7863
7864 @geindex gcc_jit_function_new_block (C function)
7865 @anchor{topics/functions c gcc_jit_function_new_block}@anchor{115}
7866 @deffn {C Function} gcc_jit_block * gcc_jit_function_new_block (gcc_jit_function@w{ }*func, const char@w{ }*name)
7867
7868 Create a basic block of the given name. The name may be NULL, but
7869 providing meaningful names is often helpful when debugging: it may
7870 show up in dumps of the internal representation, and in error
7871 messages. It is copied, so the input buffer does not need to outlive
7872 the call; you can pass in a pointer to an on-stack buffer, e.g.:
7873
7874 @example
7875 for (pc = 0; pc < fn->fn_num_ops; pc++)
7876 @{
7877 char buf[16];
7878 sprintf (buf, "instr%i", pc);
7879 state.op_blocks[pc] = gcc_jit_function_new_block (state.fn, buf);
7880 @}
7881 @end example
7882 @end deffn
7883
7884 @geindex gcc_jit_block_as_object (C function)
7885 @anchor{topics/functions c gcc_jit_block_as_object}@anchor{116}
7886 @deffn {C Function} gcc_jit_object * gcc_jit_block_as_object (gcc_jit_block@w{ }*block)
7887
7888 Upcast from block to object.
7889 @end deffn
7890
7891 @geindex gcc_jit_block_get_function (C function)
7892 @anchor{topics/functions c gcc_jit_block_get_function}@anchor{117}
7893 @deffn {C Function} gcc_jit_function * gcc_jit_block_get_function (gcc_jit_block@w{ }*block)
7894
7895 Which function is this block within?
7896 @end deffn
7897
7898 @node Statements,,Blocks,Creating and using functions
7899 @anchor{topics/functions statements}@anchor{118}
7900 @subsection Statements
7901
7902
7903 @geindex gcc_jit_block_add_eval (C function)
7904 @anchor{topics/functions c gcc_jit_block_add_eval}@anchor{d8}
7905 @deffn {C Function} void gcc_jit_block_add_eval (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*rvalue)
7906
7907 Add evaluation of an rvalue, discarding the result
7908 (e.g. a function call that “returns” void).
7909
7910 This is equivalent to this C code:
7911
7912 @example
7913 (void)expression;
7914 @end example
7915 @end deffn
7916
7917 @geindex gcc_jit_block_add_assignment (C function)
7918 @anchor{topics/functions c gcc_jit_block_add_assignment}@anchor{2a}
7919 @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)
7920
7921 Add evaluation of an rvalue, assigning the result to the given
7922 lvalue.
7923
7924 This is roughly equivalent to this C code:
7925
7926 @example
7927 lvalue = rvalue;
7928 @end example
7929 @end deffn
7930
7931 @geindex gcc_jit_block_add_assignment_op (C function)
7932 @anchor{topics/functions c gcc_jit_block_add_assignment_op}@anchor{2e}
7933 @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)
7934
7935 Add evaluation of an rvalue, using the result to modify an
7936 lvalue.
7937
7938 This is analogous to “+=” and friends:
7939
7940 @example
7941 lvalue += rvalue;
7942 lvalue *= rvalue;
7943 lvalue /= rvalue;
7944 @end example
7945
7946 etc. For example:
7947
7948 @example
7949 /* "i++" */
7950 gcc_jit_block_add_assignment_op (
7951 loop_body, NULL,
7952 i,
7953 GCC_JIT_BINARY_OP_PLUS,
7954 gcc_jit_context_one (ctxt, int_type));
7955 @end example
7956 @end deffn
7957
7958 @geindex gcc_jit_block_add_comment (C function)
7959 @anchor{topics/functions c gcc_jit_block_add_comment}@anchor{3d}
7960 @deffn {C Function} void gcc_jit_block_add_comment (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, const char@w{ }*text)
7961
7962 Add a no-op textual comment to the internal representation of the
7963 code. It will be optimized away, but will be visible in the dumps
7964 seen via @ref{66,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}
7965 and @ref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE},
7966 and thus may be of use when debugging how your project’s internal
7967 representation gets converted to the libgccjit IR.
7968
7969 The parameter @code{text} must be non-NULL. It is copied, so the input
7970 buffer does not need to outlive the call. For example:
7971
7972 @example
7973 char buf[100];
7974 snprintf (buf, sizeof (buf),
7975 "op%i: %s",
7976 pc, opcode_names[op->op_opcode]);
7977 gcc_jit_block_add_comment (block, loc, buf);
7978 @end example
7979 @end deffn
7980
7981 @geindex gcc_jit_block_end_with_conditional (C function)
7982 @anchor{topics/functions c gcc_jit_block_end_with_conditional}@anchor{2d}
7983 @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)
7984
7985 Terminate a block by adding evaluation of an rvalue, branching on the
7986 result to the appropriate successor block.
7987
7988 This is roughly equivalent to this C code:
7989
7990 @example
7991 if (boolval)
7992 goto on_true;
7993 else
7994 goto on_false;
7995 @end example
7996
7997 block, boolval, on_true, and on_false must be non-NULL.
7998 @end deffn
7999
8000 @geindex gcc_jit_block_end_with_jump (C function)
8001 @anchor{topics/functions c gcc_jit_block_end_with_jump}@anchor{119}
8002 @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)
8003
8004 Terminate a block by adding a jump to the given target block.
8005
8006 This is roughly equivalent to this C code:
8007
8008 @example
8009 goto target;
8010 @end example
8011 @end deffn
8012
8013 @geindex gcc_jit_block_end_with_return (C function)
8014 @anchor{topics/functions c gcc_jit_block_end_with_return}@anchor{11a}
8015 @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)
8016
8017 Terminate a block by adding evaluation of an rvalue, returning the value.
8018
8019 This is roughly equivalent to this C code:
8020
8021 @example
8022 return expression;
8023 @end example
8024 @end deffn
8025
8026 @geindex gcc_jit_block_end_with_void_return (C function)
8027 @anchor{topics/functions c gcc_jit_block_end_with_void_return}@anchor{11b}
8028 @deffn {C Function} void gcc_jit_block_end_with_void_return (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc)
8029
8030 Terminate a block by adding a valueless return, for use within a function
8031 with “void” return type.
8032
8033 This is equivalent to this C code:
8034
8035 @example
8036 return;
8037 @end example
8038 @end deffn
8039
8040 @geindex gcc_jit_block_end_with_switch (C function)
8041 @anchor{topics/functions c gcc_jit_block_end_with_switch}@anchor{11c}
8042 @deffn {C Function} void gcc_jit_block_end_with_switch (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*expr, gcc_jit_block@w{ }*default_block, int@w{ }num_cases, gcc_jit_case@w{ }**cases)
8043
8044 Terminate a block by adding evalation of an rvalue, then performing
8045 a multiway branch.
8046
8047 This is roughly equivalent to this C code:
8048
8049 @example
8050 switch (expr)
8051 @{
8052 default:
8053 goto default_block;
8054
8055 case C0.min_value ... C0.max_value:
8056 goto C0.dest_block;
8057
8058 case C1.min_value ... C1.max_value:
8059 goto C1.dest_block;
8060
8061 ...etc...
8062
8063 case C[N - 1].min_value ... C[N - 1].max_value:
8064 goto C[N - 1].dest_block;
8065 @}
8066 @end example
8067
8068 @code{block}, @code{expr}, @code{default_block} and @code{cases} must all be
8069 non-NULL.
8070
8071 @code{expr} must be of the same integer type as all of the @code{min_value}
8072 and @code{max_value} within the cases.
8073
8074 @code{num_cases} must be >= 0.
8075
8076 The ranges of the cases must not overlap (or have duplicate
8077 values).
8078
8079 The API entrypoints relating to switch statements and cases:
8080
8081 @quotation
8082
8083
8084 @itemize *
8085
8086 @item
8087 @ref{11c,,gcc_jit_block_end_with_switch()}
8088
8089 @item
8090 @ref{11d,,gcc_jit_case_as_object()}
8091
8092 @item
8093 @ref{11e,,gcc_jit_context_new_case()}
8094 @end itemize
8095 @end quotation
8096
8097 were added in @ref{11f,,LIBGCCJIT_ABI_3}; you can test for their presence
8098 using
8099
8100 @example
8101 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS
8102 @end example
8103
8104 @geindex gcc_jit_case (C type)
8105
8106 @deffn {C Type} gcc_jit_case
8107 @end deffn
8108
8109 A @cite{gcc_jit_case} represents a case within a switch statement, and
8110 is created within a particular @ref{8,,gcc_jit_context} using
8111 @ref{11e,,gcc_jit_context_new_case()}.
8112
8113 Each case expresses a multivalued range of integer values. You
8114 can express single-valued cases by passing in the same value for
8115 both @cite{min_value} and @cite{max_value}.
8116
8117 @geindex gcc_jit_context_new_case (C function)
8118 @anchor{topics/functions c gcc_jit_context_new_case}@anchor{11e}
8119 @deffn {C Function} gcc_jit_case * gcc_jit_context_new_case (gcc_jit_context@w{ }*ctxt, gcc_jit_rvalue@w{ }*min_value, gcc_jit_rvalue@w{ }*max_value, gcc_jit_block@w{ }*dest_block)
8120
8121 Create a new gcc_jit_case instance for use in a switch statement.
8122 @cite{min_value} and @cite{max_value} must be constants of an integer type,
8123 which must match that of the expression of the switch statement.
8124
8125 @cite{dest_block} must be within the same function as the switch
8126 statement.
8127 @end deffn
8128
8129 @geindex gcc_jit_case_as_object (C function)
8130 @anchor{topics/functions c gcc_jit_case_as_object}@anchor{11d}
8131 @deffn {C Function} gcc_jit_object * gcc_jit_case_as_object (gcc_jit_case@w{ }*case_)
8132
8133 Upcast from a case to an object.
8134 @end deffn
8135
8136 Here’s an example of creating a switch statement:
8137
8138 @quotation
8139
8140 @example
8141
8142 void
8143 create_code (gcc_jit_context *ctxt, void *user_data)
8144 @{
8145 /* Let's try to inject the equivalent of:
8146 int
8147 test_switch (int x)
8148 @{
8149 switch (x)
8150 @{
8151 case 0 ... 5:
8152 return 3;
8153
8154 case 25 ... 27:
8155 return 4;
8156
8157 case -42 ... -17:
8158 return 83;
8159
8160 case 40:
8161 return 8;
8162
8163 default:
8164 return 10;
8165 @}
8166 @}
8167 */
8168 gcc_jit_type *t_int =
8169 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
8170 gcc_jit_type *return_type = t_int;
8171 gcc_jit_param *x =
8172 gcc_jit_context_new_param (ctxt, NULL, t_int, "x");
8173 gcc_jit_param *params[1] = @{x@};
8174 gcc_jit_function *func =
8175 gcc_jit_context_new_function (ctxt, NULL,
8176 GCC_JIT_FUNCTION_EXPORTED,
8177 return_type,
8178 "test_switch",
8179 1, params, 0);
8180
8181 gcc_jit_block *b_initial =
8182 gcc_jit_function_new_block (func, "initial");
8183
8184 gcc_jit_block *b_default =
8185 gcc_jit_function_new_block (func, "default");
8186 gcc_jit_block *b_case_0_5 =
8187 gcc_jit_function_new_block (func, "case_0_5");
8188 gcc_jit_block *b_case_25_27 =
8189 gcc_jit_function_new_block (func, "case_25_27");
8190 gcc_jit_block *b_case_m42_m17 =
8191 gcc_jit_function_new_block (func, "case_m42_m17");
8192 gcc_jit_block *b_case_40 =
8193 gcc_jit_function_new_block (func, "case_40");
8194
8195 gcc_jit_case *cases[4] = @{
8196 gcc_jit_context_new_case (
8197 ctxt,
8198 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, 0),
8199 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, 5),
8200 b_case_0_5),
8201 gcc_jit_context_new_case (
8202 ctxt,
8203 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, 25),
8204 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, 27),
8205 b_case_25_27),
8206 gcc_jit_context_new_case (
8207 ctxt,
8208 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, -42),
8209 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, -17),
8210 b_case_m42_m17),
8211 gcc_jit_context_new_case (
8212 ctxt,
8213 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, 40),
8214 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, 40),
8215 b_case_40)
8216 @};
8217 gcc_jit_block_end_with_switch (
8218 b_initial, NULL,
8219 gcc_jit_param_as_rvalue (x),
8220 b_default,
8221 4, cases);
8222
8223 gcc_jit_block_end_with_return (
8224 b_case_0_5, NULL,
8225 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, 3));
8226 gcc_jit_block_end_with_return (
8227 b_case_25_27, NULL,
8228 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, 4));
8229 gcc_jit_block_end_with_return (
8230 b_case_m42_m17, NULL,
8231 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, 83));
8232 gcc_jit_block_end_with_return (
8233 b_case_40, NULL,
8234 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, 8));
8235 gcc_jit_block_end_with_return (
8236 b_default, NULL,
8237 gcc_jit_context_new_rvalue_from_int (ctxt, t_int, 10));
8238 @}
8239
8240 @end example
8241 @end quotation
8242 @end deffn
8243
8244 See also @ref{120,,gcc_jit_extended_asm} for entrypoints for adding inline
8245 assembler statements to a function.
8246
8247 @c Copyright (C) 2017-2022 Free Software Foundation, Inc.
8248 @c Originally contributed by David Malcolm <[email protected]>
8249 @c
8250 @c This is free software: you can redistribute it and/or modify it
8251 @c under the terms of the GNU General Public License as published by
8252 @c the Free Software Foundation, either version 3 of the License, or
8253 @c (at your option) any later version.
8254 @c
8255 @c This program is distributed in the hope that it will be useful, but
8256 @c WITHOUT ANY WARRANTY; without even the implied warranty of
8257 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
8258 @c General Public License for more details.
8259 @c
8260 @c You should have received a copy of the GNU General Public License
8261 @c along with this program. If not, see
8262 @c <https://www.gnu.org/licenses/>.
8263
8264 @node Function pointers<2>,Source Locations,Creating and using functions,Topic Reference
8265 @anchor{topics/function-pointers doc}@anchor{121}@anchor{topics/function-pointers function-pointers}@anchor{122}
8266 @section Function pointers
8267
8268
8269 You can generate calls that use a function pointer via
8270 @ref{d9,,gcc_jit_context_new_call_through_ptr()}.
8271
8272 To do requires a @ref{13,,gcc_jit_rvalue} of the correct function pointer type.
8273
8274 Function pointers for a @ref{29,,gcc_jit_function} can be obtained
8275 via @ref{dd,,gcc_jit_function_get_address()}.
8276
8277 @geindex gcc_jit_function_get_address (C function)
8278 @anchor{topics/function-pointers c gcc_jit_function_get_address}@anchor{dd}
8279 @deffn {C Function} gcc_jit_rvalue * gcc_jit_function_get_address (gcc_jit_function@w{ }*fn, gcc_jit_location@w{ }*loc)
8280
8281 Get the address of a function as an rvalue, of function pointer
8282 type.
8283
8284 This entrypoint was added in @ref{123,,LIBGCCJIT_ABI_9}; you can test
8285 for its presence using
8286
8287 @example
8288 #ifdef LIBGCCJIT_HAVE_gcc_jit_function_get_address
8289 @end example
8290 @end deffn
8291
8292 Alternatively, given an existing function, you can obtain a pointer
8293 to it in @ref{13,,gcc_jit_rvalue} form using
8294 @ref{b3,,gcc_jit_context_new_rvalue_from_ptr()}, using a function pointer
8295 type obtained using @ref{97,,gcc_jit_context_new_function_ptr_type()}.
8296
8297 Here’s an example of creating a function pointer type corresponding to C’s
8298 @code{void (*) (int, int, int)}:
8299
8300 @example
8301 gcc_jit_type *void_type =
8302 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_VOID);
8303 gcc_jit_type *int_type =
8304 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
8305
8306 /* Build the function ptr type. */
8307 gcc_jit_type *param_types[3];
8308 param_types[0] = int_type;
8309 param_types[1] = int_type;
8310 param_types[2] = int_type;
8311
8312 gcc_jit_type *fn_ptr_type =
8313 gcc_jit_context_new_function_ptr_type (ctxt, NULL,
8314 void_type,
8315 3, param_types, 0);
8316 @end example
8317
8318 @geindex gcc_jit_context_new_function_ptr_type (C function)
8319 @anchor{topics/function-pointers c gcc_jit_context_new_function_ptr_type}@anchor{97}
8320 @deffn {C Function} gcc_jit_type * gcc_jit_context_new_function_ptr_type (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*return_type, int@w{ }num_params, gcc_jit_type@w{ }**param_types, int@w{ }is_variadic)
8321
8322 Generate a @ref{a,,gcc_jit_type} for a function pointer with the
8323 given return type and parameters.
8324
8325 Each of @cite{param_types} must be non-@cite{void}; @cite{return_type} may be @cite{void}.
8326 @end deffn
8327
8328 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
8329 @c Originally contributed by David Malcolm <[email protected]>
8330 @c
8331 @c This is free software: you can redistribute it and/or modify it
8332 @c under the terms of the GNU General Public License as published by
8333 @c the Free Software Foundation, either version 3 of the License, or
8334 @c (at your option) any later version.
8335 @c
8336 @c This program is distributed in the hope that it will be useful, but
8337 @c WITHOUT ANY WARRANTY; without even the implied warranty of
8338 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
8339 @c General Public License for more details.
8340 @c
8341 @c You should have received a copy of the GNU General Public License
8342 @c along with this program. If not, see
8343 @c <https://www.gnu.org/licenses/>.
8344
8345 @node Source Locations,Compiling a context,Function pointers<2>,Topic Reference
8346 @anchor{topics/locations doc}@anchor{124}@anchor{topics/locations source-locations}@anchor{125}
8347 @section Source Locations
8348
8349
8350 @geindex gcc_jit_location (C type)
8351 @anchor{topics/locations c gcc_jit_location}@anchor{3b}
8352 @deffn {C Type} gcc_jit_location
8353
8354 A @cite{gcc_jit_location} encapsulates a source code location, so that
8355 you can (optionally) associate locations in your language with
8356 statements in the JIT-compiled code, allowing the debugger to
8357 single-step through your language.
8358
8359 @cite{gcc_jit_location} instances are optional: you can always pass NULL to
8360 any API entrypoint accepting one.
8361
8362 You can construct them using @ref{41,,gcc_jit_context_new_location()}.
8363
8364 You need to enable @ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
8365 @ref{8,,gcc_jit_context} for these locations to actually be usable by
8366 the debugger:
8367
8368 @example
8369 gcc_jit_context_set_bool_option (
8370 ctxt,
8371 GCC_JIT_BOOL_OPTION_DEBUGINFO,
8372 1);
8373 @end example
8374 @end deffn
8375
8376 @geindex gcc_jit_context_new_location (C function)
8377 @anchor{topics/locations c gcc_jit_context_new_location}@anchor{41}
8378 @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)
8379
8380 Create a @cite{gcc_jit_location} instance representing the given source
8381 location.
8382
8383 The parameter @code{filename} must be non-NULL. The call takes a copy of
8384 the underlying string, so it is valid to pass in a pointer to an
8385 on-stack buffer.
8386 @end deffn
8387
8388 @menu
8389 * Faking it::
8390
8391 @end menu
8392
8393 @node Faking it,,,Source Locations
8394 @anchor{topics/locations faking-it}@anchor{126}
8395 @subsection Faking it
8396
8397
8398 If you don’t have source code for your internal representation, but need
8399 to debug, you can generate a C-like representation of the functions in
8400 your context using @ref{5a,,gcc_jit_context_dump_to_file()}:
8401
8402 @example
8403 gcc_jit_context_dump_to_file (ctxt, "/tmp/something.c",
8404 1 /* update_locations */);
8405 @end example
8406
8407 This will dump C-like code to the given path. If the @cite{update_locations}
8408 argument is true, this will also set up @cite{gcc_jit_location} information
8409 throughout the context, pointing at the dump file as if it were a source
8410 file, giving you @emph{something} you can step through in the debugger.
8411
8412 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
8413 @c Originally contributed by David Malcolm <[email protected]>
8414 @c
8415 @c This is free software: you can redistribute it and/or modify it
8416 @c under the terms of the GNU General Public License as published by
8417 @c the Free Software Foundation, either version 3 of the License, or
8418 @c (at your option) any later version.
8419 @c
8420 @c This program is distributed in the hope that it will be useful, but
8421 @c WITHOUT ANY WARRANTY; without even the implied warranty of
8422 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
8423 @c General Public License for more details.
8424 @c
8425 @c You should have received a copy of the GNU General Public License
8426 @c along with this program. If not, see
8427 @c <https://www.gnu.org/licenses/>.
8428
8429 @node Compiling a context,ABI and API compatibility,Source Locations,Topic Reference
8430 @anchor{topics/compilation doc}@anchor{127}@anchor{topics/compilation compiling-a-context}@anchor{128}
8431 @section Compiling a context
8432
8433
8434 Once populated, a @ref{8,,gcc_jit_context *} can be compiled to
8435 machine code, either in-memory via @ref{15,,gcc_jit_context_compile()} or
8436 to disk via @ref{4a,,gcc_jit_context_compile_to_file()}.
8437
8438 You can compile a context multiple times (using either form of
8439 compilation), although any errors that occur on the context will
8440 prevent any future compilation of that context.
8441
8442 @menu
8443 * In-memory compilation::
8444 * Ahead-of-time compilation::
8445
8446 @end menu
8447
8448 @node In-memory compilation,Ahead-of-time compilation,,Compiling a context
8449 @anchor{topics/compilation in-memory-compilation}@anchor{129}
8450 @subsection In-memory compilation
8451
8452
8453 @geindex gcc_jit_context_compile (C function)
8454 @anchor{topics/compilation c gcc_jit_context_compile}@anchor{15}
8455 @deffn {C Function} gcc_jit_result * gcc_jit_context_compile (gcc_jit_context@w{ }*ctxt)
8456
8457 This calls into GCC and builds the code, returning a
8458 @cite{gcc_jit_result *}.
8459
8460 If the result is non-NULL, the caller becomes responsible for
8461 calling @ref{39,,gcc_jit_result_release()} on it once they’re done
8462 with it.
8463 @end deffn
8464
8465 @geindex gcc_jit_result (C type)
8466 @anchor{topics/compilation c gcc_jit_result}@anchor{16}
8467 @deffn {C Type} gcc_jit_result
8468
8469 A @cite{gcc_jit_result} encapsulates the result of compiling a context
8470 in-memory, and the lifetimes of any machine code functions or globals
8471 that are within the result.
8472 @end deffn
8473
8474 @geindex gcc_jit_result_get_code (C function)
8475 @anchor{topics/compilation c gcc_jit_result_get_code}@anchor{17}
8476 @deffn {C Function} void * gcc_jit_result_get_code (gcc_jit_result@w{ }*result, const char@w{ }*funcname)
8477
8478 Locate a given function within the built machine code.
8479
8480 Functions are looked up by name. For this to succeed, a function
8481 with a name matching @cite{funcname} must have been created on
8482 @cite{result}’s context (or a parent context) via a call to
8483 @ref{11,,gcc_jit_context_new_function()} with @cite{kind}
8484 @ref{10a,,GCC_JIT_FUNCTION_EXPORTED}:
8485
8486 @example
8487 gcc_jit_context_new_function (ctxt,
8488 any_location, /* or NULL */
8489 /* Required for func to be visible to
8490 gcc_jit_result_get_code: */
8491 GCC_JIT_FUNCTION_EXPORTED,
8492 any_return_type,
8493 /* Must string-compare equal: */
8494 funcname,
8495 /* etc */);
8496 @end example
8497
8498 If such a function is not found (or @cite{result} or @cite{funcname} are
8499 @code{NULL}), an error message will be emitted on stderr and
8500 @code{NULL} will be returned.
8501
8502 If the function is found, the result will need to be cast to a
8503 function pointer of the correct type before it can be called.
8504
8505 Note that the resulting machine code becomes invalid after
8506 @ref{39,,gcc_jit_result_release()} is called on the
8507 @ref{16,,gcc_jit_result *}; attempting to call it after that may lead
8508 to a segmentation fault.
8509 @end deffn
8510
8511 @geindex gcc_jit_result_get_global (C function)
8512 @anchor{topics/compilation c gcc_jit_result_get_global}@anchor{f8}
8513 @deffn {C Function} void * gcc_jit_result_get_global (gcc_jit_result@w{ }*result, const char@w{ }*name)
8514
8515 Locate a given global within the built machine code.
8516
8517 Globals are looked up by name. For this to succeed, a global
8518 with a name matching @cite{name} must have been created on
8519 @cite{result}’s context (or a parent context) via a call to
8520 @ref{f5,,gcc_jit_context_new_global()} with @cite{kind}
8521 @ref{f7,,GCC_JIT_GLOBAL_EXPORTED}.
8522
8523 If the global is found, the result will need to be cast to a
8524 pointer of the correct type before it can be called.
8525
8526 This is a @emph{pointer} to the global, so e.g. for an @code{int} this is
8527 an @code{int *}.
8528
8529 For example, given an @code{int foo;} created this way:
8530
8531 @example
8532 gcc_jit_lvalue *exported_global =
8533 gcc_jit_context_new_global (ctxt,
8534 any_location, /* or NULL */
8535 GCC_JIT_GLOBAL_EXPORTED,
8536 int_type,
8537 "foo");
8538 @end example
8539
8540 we can access it like this:
8541
8542 @example
8543 int *ptr_to_foo =
8544 (int *)gcc_jit_result_get_global (result, "foo");
8545 @end example
8546
8547 If such a global is not found (or @cite{result} or @cite{name} are
8548 @code{NULL}), an error message will be emitted on stderr and
8549 @code{NULL} will be returned.
8550
8551 Note that the resulting address becomes invalid after
8552 @ref{39,,gcc_jit_result_release()} is called on the
8553 @ref{16,,gcc_jit_result *}; attempting to use it after that may lead
8554 to a segmentation fault.
8555 @end deffn
8556
8557 @geindex gcc_jit_result_release (C function)
8558 @anchor{topics/compilation c gcc_jit_result_release}@anchor{39}
8559 @deffn {C Function} void gcc_jit_result_release (gcc_jit_result@w{ }*result)
8560
8561 Once we’re done with the code, this unloads the built .so file.
8562 This cleans up the result; after calling this, it’s no longer
8563 valid to use the result, or any code or globals that were obtained
8564 by calling @ref{17,,gcc_jit_result_get_code()} or
8565 @ref{f8,,gcc_jit_result_get_global()} on it.
8566 @end deffn
8567
8568 @node Ahead-of-time compilation,,In-memory compilation,Compiling a context
8569 @anchor{topics/compilation ahead-of-time-compilation}@anchor{12a}
8570 @subsection Ahead-of-time compilation
8571
8572
8573 Although libgccjit is primarily aimed at just-in-time compilation, it
8574 can also be used for implementing more traditional ahead-of-time
8575 compilers, via the @ref{4a,,gcc_jit_context_compile_to_file()}
8576 API entrypoint.
8577
8578 For linking in object files, use @ref{76,,gcc_jit_context_add_driver_option()}.
8579
8580 @geindex gcc_jit_context_compile_to_file (C function)
8581 @anchor{topics/compilation c gcc_jit_context_compile_to_file}@anchor{4a}
8582 @deffn {C Function} void gcc_jit_context_compile_to_file (gcc_jit_context@w{ }*ctxt, enum gcc_jit_output_kind@w{ }output_kind, const char@w{ }*output_path)
8583
8584 Compile the @ref{8,,gcc_jit_context *} to a file of the given
8585 kind.
8586 @end deffn
8587
8588 @ref{4a,,gcc_jit_context_compile_to_file()} ignores the suffix of
8589 @code{output_path}, and insteads uses the given
8590 @code{enum gcc_jit_output_kind} to decide what to do.
8591
8592 @cartouche
8593 @quotation Note
8594 This is different from the @code{gcc} program, which does make use of the
8595 suffix of the output file when determining what to do.
8596 @end quotation
8597 @end cartouche
8598
8599 @geindex gcc_jit_output_kind (C type)
8600 @anchor{topics/compilation c gcc_jit_output_kind}@anchor{12b}
8601 @deffn {C Type} enum gcc_jit_output_kind
8602 @end deffn
8603
8604 The available kinds of output are:
8605
8606
8607 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx}
8608 @headitem
8609
8610 Output kind
8611
8612 @tab
8613
8614 Typical suffix
8615
8616 @item
8617
8618 @ref{12c,,GCC_JIT_OUTPUT_KIND_ASSEMBLER}
8619
8620 @tab
8621
8622 .s
8623
8624 @item
8625
8626 @ref{12d,,GCC_JIT_OUTPUT_KIND_OBJECT_FILE}
8627
8628 @tab
8629
8630 .o
8631
8632 @item
8633
8634 @ref{12e,,GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY}
8635
8636 @tab
8637
8638 .so or .dll
8639
8640 @item
8641
8642 @ref{12f,,GCC_JIT_OUTPUT_KIND_EXECUTABLE}
8643
8644 @tab
8645
8646 None, or .exe
8647
8648 @end multitable
8649
8650
8651 @geindex GCC_JIT_OUTPUT_KIND_ASSEMBLER (C macro)
8652 @anchor{topics/compilation c GCC_JIT_OUTPUT_KIND_ASSEMBLER}@anchor{12c}
8653 @deffn {C Macro} GCC_JIT_OUTPUT_KIND_ASSEMBLER
8654
8655 Compile the context to an assembler file.
8656 @end deffn
8657
8658 @geindex GCC_JIT_OUTPUT_KIND_OBJECT_FILE (C macro)
8659 @anchor{topics/compilation c GCC_JIT_OUTPUT_KIND_OBJECT_FILE}@anchor{12d}
8660 @deffn {C Macro} GCC_JIT_OUTPUT_KIND_OBJECT_FILE
8661
8662 Compile the context to an object file.
8663 @end deffn
8664
8665 @geindex GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY (C macro)
8666 @anchor{topics/compilation c GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY}@anchor{12e}
8667 @deffn {C Macro} GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY
8668
8669 Compile the context to a dynamic library.
8670 @end deffn
8671
8672 @geindex GCC_JIT_OUTPUT_KIND_EXECUTABLE (C macro)
8673 @anchor{topics/compilation c GCC_JIT_OUTPUT_KIND_EXECUTABLE}@anchor{12f}
8674 @deffn {C Macro} GCC_JIT_OUTPUT_KIND_EXECUTABLE
8675
8676 Compile the context to an executable.
8677 @end deffn
8678
8679 @c Copyright (C) 2015-2022 Free Software Foundation, Inc.
8680 @c Originally contributed by David Malcolm <[email protected]>
8681 @c
8682 @c This is free software: you can redistribute it and/or modify it
8683 @c under the terms of the GNU General Public License as published by
8684 @c the Free Software Foundation, either version 3 of the License, or
8685 @c (at your option) any later version.
8686 @c
8687 @c This program is distributed in the hope that it will be useful, but
8688 @c WITHOUT ANY WARRANTY; without even the implied warranty of
8689 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
8690 @c General Public License for more details.
8691 @c
8692 @c You should have received a copy of the GNU General Public License
8693 @c along with this program. If not, see
8694 @c <https://www.gnu.org/licenses/>.
8695
8696 @node ABI and API compatibility,Performance,Compiling a context,Topic Reference
8697 @anchor{topics/compatibility doc}@anchor{130}@anchor{topics/compatibility abi-and-api-compatibility}@anchor{131}
8698 @section ABI and API compatibility
8699
8700
8701 The libgccjit developers strive for ABI and API backward-compatibility:
8702 programs built against libgccjit.so stand a good chance of running
8703 without recompilation against newer versions of libgccjit.so, and
8704 ought to recompile without modification against newer versions of
8705 libgccjit.h.
8706
8707 @cartouche
8708 @quotation Note
8709 The libgccjit++.h C++ API is more experimental, and less
8710 locked-down at this time.
8711 @end quotation
8712 @end cartouche
8713
8714 API compatibility is achieved by extending the API rather than changing
8715 it. For ABI compatiblity, we avoid bumping the SONAME, and instead use
8716 symbol versioning to tag each symbol, so that a binary linked against
8717 libgccjit.so is tagged according to the symbols that it uses.
8718
8719 For example, @ref{74,,gcc_jit_context_add_command_line_option()} was added in
8720 @code{LIBGCCJIT_ABI_1}. If a client program uses it, this can be detected
8721 from metadata by using @code{objdump}:
8722
8723 @example
8724 $ objdump -p testsuite/jit/test-extra-options.c.exe | tail -n 8
8725
8726 Version References:
8727 required from libgccjit.so.0:
8728 0x00824161 0x00 04 LIBGCCJIT_ABI_1
8729 0x00824160 0x00 03 LIBGCCJIT_ABI_0
8730 required from libc.so.6:
8731 @end example
8732
8733 You can see the symbol tags provided by libgccjit.so using @code{objdump}:
8734
8735 @example
8736 $ objdump -p libgccjit.so | less
8737 [...snip...]
8738 Version definitions:
8739 1 0x01 0x0ff81f20 libgccjit.so.0
8740 2 0x00 0x00824160 LIBGCCJIT_ABI_0
8741 3 0x00 0x00824161 LIBGCCJIT_ABI_1
8742 LIBGCCJIT_ABI_0
8743 [...snip...]
8744 @end example
8745
8746 @menu
8747 * Programmatically checking version::
8748 * ABI symbol tags::
8749
8750 @end menu
8751
8752 @node Programmatically checking version,ABI symbol tags,,ABI and API compatibility
8753 @anchor{topics/compatibility programmatically-checking-version}@anchor{132}
8754 @subsection Programmatically checking version
8755
8756
8757 Client code can programmatically check libgccjit version using:
8758
8759 @geindex gcc_jit_version_major (C function)
8760 @anchor{topics/compatibility c gcc_jit_version_major}@anchor{133}
8761 @deffn {C Function} int gcc_jit_version_major (void)
8762
8763 Return libgccjit major version. This is analogous to __GNUC__ in C code.
8764 @end deffn
8765
8766 @geindex gcc_jit_version_minor (C function)
8767 @anchor{topics/compatibility c gcc_jit_version_minor}@anchor{134}
8768 @deffn {C Function} int gcc_jit_version_minor (void)
8769
8770 Return libgccjit minor version. This is analogous to
8771 __GNUC_MINOR__ in C code.
8772 @end deffn
8773
8774 @geindex gcc_jit_version_patchlevel (C function)
8775 @anchor{topics/compatibility c gcc_jit_version_patchlevel}@anchor{135}
8776 @deffn {C Function} int gcc_jit_version_patchlevel (void)
8777
8778 Return libgccjit patchlevel version. This is analogous to
8779 __GNUC_PATCHLEVEL__ in C code.
8780 @end deffn
8781
8782 @cartouche
8783 @quotation Note
8784 These entry points has been added with @code{LIBGCCJIT_ABI_13}
8785 (see below).
8786 @end quotation
8787 @end cartouche
8788
8789 @node ABI symbol tags,,Programmatically checking version,ABI and API compatibility
8790 @anchor{topics/compatibility abi-symbol-tags}@anchor{136}
8791 @subsection ABI symbol tags
8792
8793
8794 The initial release of libgccjit (in gcc 5.1) did not use symbol versioning.
8795
8796 Newer releases use the following tags.
8797
8798 @menu
8799 * LIBGCCJIT_ABI_0::
8800 * LIBGCCJIT_ABI_1::
8801 * LIBGCCJIT_ABI_2::
8802 * LIBGCCJIT_ABI_3::
8803 * LIBGCCJIT_ABI_4::
8804 * LIBGCCJIT_ABI_5::
8805 * LIBGCCJIT_ABI_6::
8806 * LIBGCCJIT_ABI_7::
8807 * LIBGCCJIT_ABI_8::
8808 * LIBGCCJIT_ABI_9::
8809 * LIBGCCJIT_ABI_10::
8810 * LIBGCCJIT_ABI_11::
8811 * LIBGCCJIT_ABI_12::
8812 * LIBGCCJIT_ABI_13::
8813 * LIBGCCJIT_ABI_14::
8814 * LIBGCCJIT_ABI_15::
8815 * LIBGCCJIT_ABI_16::
8816 * LIBGCCJIT_ABI_17::
8817 * LIBGCCJIT_ABI_18::
8818 * LIBGCCJIT_ABI_19::
8819 * LIBGCCJIT_ABI_20::
8820 * LIBGCCJIT_ABI_21::
8821 * LIBGCCJIT_ABI_22::
8822 * LIBGCCJIT_ABI_23::
8823 * LIBGCCJIT_ABI_24::
8824
8825 @end menu
8826
8827 @node LIBGCCJIT_ABI_0,LIBGCCJIT_ABI_1,,ABI symbol tags
8828 @anchor{topics/compatibility id1}@anchor{137}@anchor{topics/compatibility libgccjit-abi-0}@anchor{138}
8829 @subsubsection @code{LIBGCCJIT_ABI_0}
8830
8831
8832 All entrypoints in the initial release of libgccjit are tagged with
8833 @code{LIBGCCJIT_ABI_0}, to signify the transition to symbol versioning.
8834
8835 Binaries built against older copies of @code{libgccjit.so} should
8836 continue to work, with this being handled transparently by the linker
8837 (see this post@footnote{https://gcc.gnu.org/ml/gcc-patches/2015-06/msg02126.html})
8838
8839 @node LIBGCCJIT_ABI_1,LIBGCCJIT_ABI_2,LIBGCCJIT_ABI_0,ABI symbol tags
8840 @anchor{topics/compatibility id2}@anchor{139}@anchor{topics/compatibility libgccjit-abi-1}@anchor{75}
8841 @subsubsection @code{LIBGCCJIT_ABI_1}
8842
8843
8844 @code{LIBGCCJIT_ABI_1} covers the addition of
8845 @ref{74,,gcc_jit_context_add_command_line_option()}
8846
8847 @node LIBGCCJIT_ABI_2,LIBGCCJIT_ABI_3,LIBGCCJIT_ABI_1,ABI symbol tags
8848 @anchor{topics/compatibility id3}@anchor{13a}@anchor{topics/compatibility libgccjit-abi-2}@anchor{6c}
8849 @subsubsection @code{LIBGCCJIT_ABI_2}
8850
8851
8852 @code{LIBGCCJIT_ABI_2} covers the addition of
8853 @ref{6b,,gcc_jit_context_set_bool_allow_unreachable_blocks()}
8854
8855 @node LIBGCCJIT_ABI_3,LIBGCCJIT_ABI_4,LIBGCCJIT_ABI_2,ABI symbol tags
8856 @anchor{topics/compatibility id4}@anchor{13b}@anchor{topics/compatibility libgccjit-abi-3}@anchor{11f}
8857 @subsubsection @code{LIBGCCJIT_ABI_3}
8858
8859
8860 @code{LIBGCCJIT_ABI_3} covers the addition of switch statements via API
8861 entrypoints:
8862
8863 @quotation
8864
8865
8866 @itemize *
8867
8868 @item
8869 @ref{11c,,gcc_jit_block_end_with_switch()}
8870
8871 @item
8872 @ref{11d,,gcc_jit_case_as_object()}
8873
8874 @item
8875 @ref{11e,,gcc_jit_context_new_case()}
8876 @end itemize
8877 @end quotation
8878
8879 @node LIBGCCJIT_ABI_4,LIBGCCJIT_ABI_5,LIBGCCJIT_ABI_3,ABI symbol tags
8880 @anchor{topics/compatibility id5}@anchor{13c}@anchor{topics/compatibility libgccjit-abi-4}@anchor{13d}
8881 @subsubsection @code{LIBGCCJIT_ABI_4}
8882
8883
8884 @code{LIBGCCJIT_ABI_4} covers the addition of timers via API
8885 entrypoints:
8886
8887 @quotation
8888
8889
8890 @itemize *
8891
8892 @item
8893 @ref{13e,,gcc_jit_context_get_timer()}
8894
8895 @item
8896 @ref{13f,,gcc_jit_context_set_timer()}
8897
8898 @item
8899 @ref{140,,gcc_jit_timer_new()}
8900
8901 @item
8902 @ref{141,,gcc_jit_timer_release()}
8903
8904 @item
8905 @ref{142,,gcc_jit_timer_push()}
8906
8907 @item
8908 @ref{143,,gcc_jit_timer_pop()}
8909
8910 @item
8911 @ref{144,,gcc_jit_timer_print()}
8912 @end itemize
8913 @end quotation
8914
8915 @node LIBGCCJIT_ABI_5,LIBGCCJIT_ABI_6,LIBGCCJIT_ABI_4,ABI symbol tags
8916 @anchor{topics/compatibility id6}@anchor{145}@anchor{topics/compatibility libgccjit-abi-5}@anchor{6e}
8917 @subsubsection @code{LIBGCCJIT_ABI_5}
8918
8919
8920 @code{LIBGCCJIT_ABI_5} covers the addition of
8921 @ref{6d,,gcc_jit_context_set_bool_use_external_driver()}
8922
8923 @node LIBGCCJIT_ABI_6,LIBGCCJIT_ABI_7,LIBGCCJIT_ABI_5,ABI symbol tags
8924 @anchor{topics/compatibility id7}@anchor{146}@anchor{topics/compatibility libgccjit-abi-6}@anchor{db}
8925 @subsubsection @code{LIBGCCJIT_ABI_6}
8926
8927
8928 @code{LIBGCCJIT_ABI_6} covers the addition of
8929 @ref{da,,gcc_jit_rvalue_set_bool_require_tail_call()}
8930
8931 @node LIBGCCJIT_ABI_7,LIBGCCJIT_ABI_8,LIBGCCJIT_ABI_6,ABI symbol tags
8932 @anchor{topics/compatibility id8}@anchor{147}@anchor{topics/compatibility libgccjit-abi-7}@anchor{85}
8933 @subsubsection @code{LIBGCCJIT_ABI_7}
8934
8935
8936 @code{LIBGCCJIT_ABI_7} covers the addition of
8937 @ref{84,,gcc_jit_type_get_aligned()}
8938
8939 @node LIBGCCJIT_ABI_8,LIBGCCJIT_ABI_9,LIBGCCJIT_ABI_7,ABI symbol tags
8940 @anchor{topics/compatibility id9}@anchor{148}@anchor{topics/compatibility libgccjit-abi-8}@anchor{88}
8941 @subsubsection @code{LIBGCCJIT_ABI_8}
8942
8943
8944 @code{LIBGCCJIT_ABI_8} covers the addition of
8945 @ref{87,,gcc_jit_type_get_vector()}
8946
8947 @node LIBGCCJIT_ABI_9,LIBGCCJIT_ABI_10,LIBGCCJIT_ABI_8,ABI symbol tags
8948 @anchor{topics/compatibility id10}@anchor{149}@anchor{topics/compatibility libgccjit-abi-9}@anchor{123}
8949 @subsubsection @code{LIBGCCJIT_ABI_9}
8950
8951
8952 @code{LIBGCCJIT_ABI_9} covers the addition of
8953 @ref{dd,,gcc_jit_function_get_address()}
8954
8955 @node LIBGCCJIT_ABI_10,LIBGCCJIT_ABI_11,LIBGCCJIT_ABI_9,ABI symbol tags
8956 @anchor{topics/compatibility id11}@anchor{14a}@anchor{topics/compatibility libgccjit-abi-10}@anchor{bd}
8957 @subsubsection @code{LIBGCCJIT_ABI_10}
8958
8959
8960 @code{LIBGCCJIT_ABI_10} covers the addition of
8961 @ref{89,,gcc_jit_context_new_rvalue_from_vector()}
8962
8963 @node LIBGCCJIT_ABI_11,LIBGCCJIT_ABI_12,LIBGCCJIT_ABI_10,ABI symbol tags
8964 @anchor{topics/compatibility id12}@anchor{14b}@anchor{topics/compatibility libgccjit-abi-11}@anchor{77}
8965 @subsubsection @code{LIBGCCJIT_ABI_11}
8966
8967
8968 @code{LIBGCCJIT_ABI_11} covers the addition of
8969 @ref{76,,gcc_jit_context_add_driver_option()}
8970
8971 @node LIBGCCJIT_ABI_12,LIBGCCJIT_ABI_13,LIBGCCJIT_ABI_11,ABI symbol tags
8972 @anchor{topics/compatibility id13}@anchor{14c}@anchor{topics/compatibility libgccjit-abi-12}@anchor{8f}
8973 @subsubsection @code{LIBGCCJIT_ABI_12}
8974
8975
8976 @code{LIBGCCJIT_ABI_12} covers the addition of
8977 @ref{8e,,gcc_jit_context_new_bitfield()}
8978
8979 @node LIBGCCJIT_ABI_13,LIBGCCJIT_ABI_14,LIBGCCJIT_ABI_12,ABI symbol tags
8980 @anchor{topics/compatibility id14}@anchor{14d}@anchor{topics/compatibility libgccjit-abi-13}@anchor{14e}
8981 @subsubsection @code{LIBGCCJIT_ABI_13}
8982
8983
8984 @code{LIBGCCJIT_ABI_13} covers the addition of version functions via API
8985 entrypoints:
8986
8987 @quotation
8988
8989
8990 @itemize *
8991
8992 @item
8993 @ref{133,,gcc_jit_version_major()}
8994
8995 @item
8996 @ref{134,,gcc_jit_version_minor()}
8997
8998 @item
8999 @ref{135,,gcc_jit_version_patchlevel()}
9000 @end itemize
9001 @end quotation
9002
9003 @node LIBGCCJIT_ABI_14,LIBGCCJIT_ABI_15,LIBGCCJIT_ABI_13,ABI symbol tags
9004 @anchor{topics/compatibility id15}@anchor{14f}@anchor{topics/compatibility libgccjit-abi-14}@anchor{fc}
9005 @subsubsection @code{LIBGCCJIT_ABI_14}
9006
9007
9008 @code{LIBGCCJIT_ABI_14} covers the addition of
9009 @ref{fb,,gcc_jit_global_set_initializer()}
9010
9011 @node LIBGCCJIT_ABI_15,LIBGCCJIT_ABI_16,LIBGCCJIT_ABI_14,ABI symbol tags
9012 @anchor{topics/compatibility id16}@anchor{150}@anchor{topics/compatibility libgccjit-abi-15}@anchor{151}
9013 @subsubsection @code{LIBGCCJIT_ABI_15}
9014
9015
9016 @code{LIBGCCJIT_ABI_15} covers the addition of API entrypoints for directly
9017 embedding assembler instructions:
9018
9019 @quotation
9020
9021
9022 @itemize *
9023
9024 @item
9025 @ref{152,,gcc_jit_block_add_extended_asm()}
9026
9027 @item
9028 @ref{153,,gcc_jit_block_end_with_extended_asm_goto()}
9029
9030 @item
9031 @ref{154,,gcc_jit_extended_asm_as_object()}
9032
9033 @item
9034 @ref{155,,gcc_jit_extended_asm_set_volatile_flag()}
9035
9036 @item
9037 @ref{156,,gcc_jit_extended_asm_set_inline_flag()}
9038
9039 @item
9040 @ref{157,,gcc_jit_extended_asm_add_output_operand()}
9041
9042 @item
9043 @ref{158,,gcc_jit_extended_asm_add_input_operand()}
9044
9045 @item
9046 @ref{159,,gcc_jit_extended_asm_add_clobber()}
9047
9048 @item
9049 @ref{15a,,gcc_jit_context_add_top_level_asm()}
9050 @end itemize
9051 @end quotation
9052
9053 @node LIBGCCJIT_ABI_16,LIBGCCJIT_ABI_17,LIBGCCJIT_ABI_15,ABI symbol tags
9054 @anchor{topics/compatibility id17}@anchor{15b}@anchor{topics/compatibility libgccjit-abi-16}@anchor{a8}
9055 @subsubsection @code{LIBGCCJIT_ABI_16}
9056
9057
9058 @code{LIBGCCJIT_ABI_16} covers the addition of reflection functions via API
9059 entrypoints:
9060
9061 @quotation
9062
9063
9064 @itemize *
9065
9066 @item
9067 @ref{112,,gcc_jit_function_get_return_type()}
9068
9069 @item
9070 @ref{111,,gcc_jit_function_get_param_count()}
9071
9072 @item
9073 @ref{99,,gcc_jit_type_dyncast_array()}
9074
9075 @item
9076 @ref{9a,,gcc_jit_type_is_bool()}
9077
9078 @item
9079 @ref{9f,,gcc_jit_type_is_integral()}
9080
9081 @item
9082 @ref{a0,,gcc_jit_type_is_pointer()}
9083
9084 @item
9085 @ref{a2,,gcc_jit_type_is_struct()}
9086
9087 @item
9088 @ref{a1,,gcc_jit_type_dyncast_vector()}
9089
9090 @item
9091 @ref{a5,,gcc_jit_type_unqualified()}
9092
9093 @item
9094 @ref{9b,,gcc_jit_type_dyncast_function_ptr_type()}
9095
9096 @item
9097 @ref{9c,,gcc_jit_function_type_get_return_type()}
9098
9099 @item
9100 @ref{9d,,gcc_jit_function_type_get_param_count()}
9101
9102 @item
9103 @ref{9e,,gcc_jit_function_type_get_param_type()}
9104
9105 @item
9106 @ref{a3,,gcc_jit_vector_type_get_num_units()}
9107
9108 @item
9109 @ref{a4,,gcc_jit_vector_type_get_element_type()}
9110
9111 @item
9112 @ref{a6,,gcc_jit_struct_get_field()}
9113
9114 @item
9115 @ref{a7,,gcc_jit_struct_get_field_count()}
9116 @end itemize
9117 @end quotation
9118
9119 @node LIBGCCJIT_ABI_17,LIBGCCJIT_ABI_18,LIBGCCJIT_ABI_16,ABI symbol tags
9120 @anchor{topics/compatibility id18}@anchor{15c}@anchor{topics/compatibility libgccjit-abi-17}@anchor{ed}
9121 @subsubsection @code{LIBGCCJIT_ABI_17}
9122
9123
9124 @code{LIBGCCJIT_ABI_17} covers the addition of an API entrypoint to set the
9125 thread-local storage model of a variable:
9126
9127 @quotation
9128
9129
9130 @itemize *
9131
9132 @item
9133 @ref{e6,,gcc_jit_lvalue_set_tls_model()}
9134 @end itemize
9135 @end quotation
9136
9137 @node LIBGCCJIT_ABI_18,LIBGCCJIT_ABI_19,LIBGCCJIT_ABI_17,ABI symbol tags
9138 @anchor{topics/compatibility id19}@anchor{15d}@anchor{topics/compatibility libgccjit-abi-18}@anchor{ef}
9139 @subsubsection @code{LIBGCCJIT_ABI_18}
9140
9141
9142 @code{LIBGCCJIT_ABI_18} covers the addition of an API entrypoint to set the link
9143 section of a variable:
9144
9145 @quotation
9146
9147
9148 @itemize *
9149
9150 @item
9151 @ref{ee,,gcc_jit_lvalue_set_link_section()}
9152 @end itemize
9153 @end quotation
9154
9155 @node LIBGCCJIT_ABI_19,LIBGCCJIT_ABI_20,LIBGCCJIT_ABI_18,ABI symbol tags
9156 @anchor{topics/compatibility id20}@anchor{15e}@anchor{topics/compatibility libgccjit-abi-19}@anchor{b8}
9157 @subsubsection @code{LIBGCCJIT_ABI_19}
9158
9159
9160 @code{LIBGCCJIT_ABI_19} covers the addition of API entrypoints to set the initial value
9161 of a global with an rvalue and to use constructors:
9162
9163 @quotation
9164
9165
9166 @itemize *
9167
9168 @item
9169 @ref{b9,,gcc_jit_context_new_array_constructor()}
9170
9171 @item
9172 @ref{ba,,gcc_jit_context_new_struct_constructor()}
9173
9174 @item
9175 @ref{bb,,gcc_jit_context_new_union_constructor()}
9176
9177 @item
9178 @ref{b7,,gcc_jit_global_set_initializer_rvalue()}
9179 @end itemize
9180 @end quotation
9181
9182 @node LIBGCCJIT_ABI_20,LIBGCCJIT_ABI_21,LIBGCCJIT_ABI_19,ABI symbol tags
9183 @anchor{topics/compatibility id21}@anchor{15f}@anchor{topics/compatibility libgccjit-abi-20}@anchor{ab}
9184 @subsubsection @code{LIBGCCJIT_ABI_20}
9185
9186
9187 @code{LIBGCCJIT_ABI_20} covers the addition of sized integer types, including
9188 128-bit integers and helper functions for types:
9189
9190 @quotation
9191
9192
9193 @itemize *
9194
9195 @item
9196 @ref{aa,,gcc_jit_compatible_types()}
9197
9198 @item
9199 @ref{ac,,gcc_jit_type_get_size()}
9200
9201 @item
9202 @code{GCC_JIT_TYPE_UINT8_T}
9203
9204 @item
9205 @code{GCC_JIT_TYPE_UINT16_T}
9206
9207 @item
9208 @code{GCC_JIT_TYPE_UINT32_T}
9209
9210 @item
9211 @code{GCC_JIT_TYPE_UINT64_T}
9212
9213 @item
9214 @code{GCC_JIT_TYPE_UINT128_T}
9215
9216 @item
9217 @code{GCC_JIT_TYPE_INT8_T}
9218
9219 @item
9220 @code{GCC_JIT_TYPE_INT16_T}
9221
9222 @item
9223 @code{GCC_JIT_TYPE_INT32_T}
9224
9225 @item
9226 @code{GCC_JIT_TYPE_INT64_T}
9227
9228 @item
9229 @code{GCC_JIT_TYPE_INT128_T}
9230 @end itemize
9231 @end quotation
9232
9233 @node LIBGCCJIT_ABI_21,LIBGCCJIT_ABI_22,LIBGCCJIT_ABI_20,ABI symbol tags
9234 @anchor{topics/compatibility id22}@anchor{160}@anchor{topics/compatibility libgccjit-abi-21}@anchor{e1}
9235 @subsubsection @code{LIBGCCJIT_ABI_21}
9236
9237
9238 @code{LIBGCCJIT_ABI_21} covers the addition of an API entrypoint to bitcast a
9239 value from one type to another:
9240
9241 @quotation
9242
9243
9244 @itemize *
9245
9246 @item
9247 @ref{e0,,gcc_jit_context_new_bitcast()}
9248 @end itemize
9249 @end quotation
9250
9251 @node LIBGCCJIT_ABI_22,LIBGCCJIT_ABI_23,LIBGCCJIT_ABI_21,ABI symbol tags
9252 @anchor{topics/compatibility id23}@anchor{161}@anchor{topics/compatibility libgccjit-abi-22}@anchor{f0}
9253 @subsubsection @code{LIBGCCJIT_ABI_22}
9254
9255
9256 @code{LIBGCCJIT_ABI_22} covers the addition of an API entrypoint to set the
9257 register name of a variable:
9258
9259 @quotation
9260
9261
9262 @itemize *
9263
9264 @item
9265 @code{gcc_jit_lvalue_set_register_name()}
9266 @end itemize
9267 @end quotation
9268
9269 @node LIBGCCJIT_ABI_23,LIBGCCJIT_ABI_24,LIBGCCJIT_ABI_22,ABI symbol tags
9270 @anchor{topics/compatibility id24}@anchor{162}@anchor{topics/compatibility libgccjit-abi-23}@anchor{70}
9271 @subsubsection @code{LIBGCCJIT_ABI_23}
9272
9273
9274 @code{LIBGCCJIT_ABI_23} covers the addition of an API entrypoint to hide stderr
9275 logs:
9276
9277 @quotation
9278
9279
9280 @itemize *
9281
9282 @item
9283 @ref{6f,,gcc_jit_context_set_bool_print_errors_to_stderr()}
9284 @end itemize
9285 @end quotation
9286
9287 @node LIBGCCJIT_ABI_24,,LIBGCCJIT_ABI_23,ABI symbol tags
9288 @anchor{topics/compatibility id25}@anchor{163}@anchor{topics/compatibility libgccjit-abi-24}@anchor{f2}
9289 @subsubsection @code{LIBGCCJIT_ABI_24}
9290
9291
9292 @code{LIBGCCJIT_ABI_24} covers the addition of functions to get and set the
9293 alignment of a variable:
9294
9295 @quotation
9296
9297
9298 @itemize *
9299
9300 @item
9301 @ref{f1,,gcc_jit_lvalue_set_alignment()}
9302
9303 @item
9304 @ref{f3,,gcc_jit_lvalue_get_alignment()}
9305 @end itemize
9306 @end quotation
9307
9308 @c Copyright (C) 2015-2022 Free Software Foundation, Inc.
9309 @c Originally contributed by David Malcolm <[email protected]>
9310 @c
9311 @c This is free software: you can redistribute it and/or modify it
9312 @c under the terms of the GNU General Public License as published by
9313 @c the Free Software Foundation, either version 3 of the License, or
9314 @c (at your option) any later version.
9315 @c
9316 @c This program is distributed in the hope that it will be useful, but
9317 @c WITHOUT ANY WARRANTY; without even the implied warranty of
9318 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
9319 @c General Public License for more details.
9320 @c
9321 @c You should have received a copy of the GNU General Public License
9322 @c along with this program. If not, see
9323 @c <https://www.gnu.org/licenses/>.
9324
9325 @node Performance,Using Assembly Language with libgccjit,ABI and API compatibility,Topic Reference
9326 @anchor{topics/performance doc}@anchor{164}@anchor{topics/performance performance}@anchor{165}
9327 @section Performance
9328
9329
9330 @menu
9331 * The timing API::
9332
9333 @end menu
9334
9335 @node The timing API,,,Performance
9336 @anchor{topics/performance the-timing-api}@anchor{166}
9337 @subsection The timing API
9338
9339
9340 As of GCC 6, libgccjit exposes a timing API, for printing reports on
9341 how long was spent in different parts of code.
9342
9343 You can create a @ref{167,,gcc_jit_timer} instance, which will
9344 measure time spent since its creation. The timer maintains a stack
9345 of “timer items”: as control flow moves through your code, you can push
9346 and pop named items relating to your code onto the stack, and the timer
9347 will account the time spent accordingly.
9348
9349 You can also asssociate a timer with a @ref{8,,gcc_jit_context}, in
9350 which case the time spent inside compilation will be subdivided.
9351
9352 For example, the following code uses a timer, recording client items
9353 “create_code”, “compile”, and “running code”:
9354
9355 @example
9356 /* Create a timer. */
9357 gcc_jit_timer *timer = gcc_jit_timer_new ();
9358 if (!timer)
9359 @{
9360 error ("gcc_jit_timer_new failed");
9361 return -1;
9362 @}
9363
9364 /* Let's repeatedly compile and run some code, accumulating it
9365 all into the timer. */
9366 for (int i = 0; i < num_iterations; i++)
9367 @{
9368 /* Create a context and associate it with the timer. */
9369 gcc_jit_context *ctxt = gcc_jit_context_acquire ();
9370 if (!ctxt)
9371 @{
9372 error ("gcc_jit_context_acquire failed");
9373 return -1;
9374 @}
9375 gcc_jit_context_set_timer (ctxt, timer);
9376
9377 /* Populate the context, timing it as client item "create_code". */
9378 gcc_jit_timer_push (timer, "create_code");
9379 create_code (ctxt);
9380 gcc_jit_timer_pop (timer, "create_code");
9381
9382 /* Compile the context, timing it as client item "compile". */
9383 gcc_jit_timer_push (timer, "compile");
9384 result = gcc_jit_context_compile (ctxt);
9385 gcc_jit_timer_pop (timer, "compile");
9386
9387 /* Run the generated code, timing it as client item "running code". */
9388 gcc_jit_timer_push (timer, "running code");
9389 run_the_code (ctxt, result);
9390 gcc_jit_timer_pop (timer, "running code");
9391
9392 /* Clean up. */
9393 gcc_jit_context_release (ctxt);
9394 gcc_jit_result_release (result);
9395 @}
9396
9397 /* Print the accumulated timings. */
9398 gcc_jit_timer_print (timer, stderr);
9399 gcc_jit_timer_release (timer);
9400 @end example
9401
9402 giving output like this, showing the internal GCC items at the top, then
9403 client items, then the total:
9404
9405 @example
9406 Execution times (seconds)
9407 GCC items:
9408 phase setup : 0.29 (14%) usr 0.00 ( 0%) sys 0.32 ( 5%) wall 10661 kB (50%) ggc
9409 phase parsing : 0.02 ( 1%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 653 kB ( 3%) ggc
9410 phase finalize : 0.01 ( 1%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 0 kB ( 0%) ggc
9411 dump files : 0.02 ( 1%) usr 0.00 ( 0%) sys 0.01 ( 0%) wall 0 kB ( 0%) ggc
9412 callgraph construction : 0.02 ( 1%) usr 0.01 ( 6%) sys 0.01 ( 0%) wall 242 kB ( 1%) ggc
9413 callgraph optimization : 0.03 ( 2%) usr 0.00 ( 0%) sys 0.02 ( 0%) wall 142 kB ( 1%) ggc
9414 trivially dead code : 0.01 ( 1%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 0 kB ( 0%) ggc
9415 df scan insns : 0.01 ( 1%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 9 kB ( 0%) ggc
9416 df live regs : 0.01 ( 1%) usr 0.00 ( 0%) sys 0.01 ( 0%) wall 0 kB ( 0%) ggc
9417 inline parameters : 0.02 ( 1%) usr 0.00 ( 0%) sys 0.01 ( 0%) wall 82 kB ( 0%) ggc
9418 tree CFG cleanup : 0.01 ( 1%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 0 kB ( 0%) ggc
9419 tree PHI insertion : 0.01 ( 1%) usr 0.00 ( 0%) sys 0.02 ( 0%) wall 64 kB ( 0%) ggc
9420 tree SSA other : 0.01 ( 1%) usr 0.00 ( 0%) sys 0.01 ( 0%) wall 18 kB ( 0%) ggc
9421 expand : 0.01 ( 1%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 398 kB ( 2%) ggc
9422 jump : 0.01 ( 1%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 0 kB ( 0%) ggc
9423 loop init : 0.01 ( 0%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 67 kB ( 0%) ggc
9424 integrated RA : 0.02 ( 1%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 2468 kB (12%) ggc
9425 thread pro- & epilogue : 0.01 ( 1%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 162 kB ( 1%) ggc
9426 final : 0.01 ( 1%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 216 kB ( 1%) ggc
9427 rest of compilation : 1.37 (69%) usr 0.00 ( 0%) sys 1.13 (18%) wall 1391 kB ( 6%) ggc
9428 assemble JIT code : 0.01 ( 1%) usr 0.00 ( 0%) sys 4.04 (66%) wall 0 kB ( 0%) ggc
9429 load JIT result : 0.02 ( 1%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 0 kB ( 0%) ggc
9430 JIT client code : 0.00 ( 0%) usr 0.01 ( 6%) sys 0.00 ( 0%) wall 0 kB ( 0%) ggc
9431 Client items:
9432 create_code : 0.00 ( 0%) usr 0.01 ( 6%) sys 0.00 ( 0%) wall 0 kB ( 0%) ggc
9433 compile : 0.36 (18%) usr 0.15 (83%) sys 0.86 (14%) wall 14939 kB (70%) ggc
9434 running code : 0.00 ( 0%) usr 0.00 ( 0%) sys 0.00 ( 0%) wall 0 kB ( 0%) ggc
9435 TOTAL : 2.00 0.18 6.12 21444 kB
9436 @end example
9437
9438 The exact format is intended to be human-readable, and is subject to change.
9439
9440 @geindex LIBGCCJIT_HAVE_TIMING_API (C macro)
9441 @anchor{topics/performance c LIBGCCJIT_HAVE_TIMING_API}@anchor{168}
9442 @deffn {C Macro} LIBGCCJIT_HAVE_TIMING_API
9443
9444 The timer API was added to libgccjit in GCC 6.
9445 This macro is only defined in versions of libgccjit.h which have the
9446 timer API, and so can be used to guard code that may need to compile
9447 against earlier releases:
9448
9449 @example
9450 #ifdef LIBGCCJIT_HAVE_TIMING_API
9451 gcc_jit_timer *t = gcc_jit_timer_new ();
9452 gcc_jit_context_set_timer (ctxt, t);
9453 #endif
9454 @end example
9455 @end deffn
9456
9457 @geindex gcc_jit_timer (C type)
9458 @anchor{topics/performance c gcc_jit_timer}@anchor{167}
9459 @deffn {C Type} gcc_jit_timer
9460 @end deffn
9461
9462 @geindex gcc_jit_timer_new (C function)
9463 @anchor{topics/performance c gcc_jit_timer_new}@anchor{140}
9464 @deffn {C Function} gcc_jit_timer * gcc_jit_timer_new (void)
9465
9466 Create a @ref{167,,gcc_jit_timer} instance, and start timing:
9467
9468 @example
9469 gcc_jit_timer *t = gcc_jit_timer_new ();
9470 @end example
9471
9472 This API entrypoint was added in @ref{13d,,LIBGCCJIT_ABI_4}; you can test
9473 for its presence using
9474
9475 @example
9476 #ifdef LIBGCCJIT_HAVE_TIMING_API
9477 @end example
9478 @end deffn
9479
9480 @geindex gcc_jit_timer_release (C function)
9481 @anchor{topics/performance c gcc_jit_timer_release}@anchor{141}
9482 @deffn {C Function} void gcc_jit_timer_release (gcc_jit_timer@w{ }*timer)
9483
9484 Release a @ref{167,,gcc_jit_timer} instance:
9485
9486 @example
9487 gcc_jit_timer_release (t);
9488 @end example
9489
9490 This should be called exactly once on a timer.
9491
9492 This API entrypoint was added in @ref{13d,,LIBGCCJIT_ABI_4}; you can test
9493 for its presence using
9494
9495 @example
9496 #ifdef LIBGCCJIT_HAVE_TIMING_API
9497 @end example
9498 @end deffn
9499
9500 @geindex gcc_jit_context_set_timer (C function)
9501 @anchor{topics/performance c gcc_jit_context_set_timer}@anchor{13f}
9502 @deffn {C Function} void gcc_jit_context_set_timer (gcc_jit_context@w{ }*ctxt, gcc_jit_timer@w{ }*timer)
9503
9504 Associate a @ref{167,,gcc_jit_timer} instance with a context:
9505
9506 @example
9507 gcc_jit_context_set_timer (ctxt, t);
9508 @end example
9509
9510 A timer instance can be shared between multiple
9511 @ref{8,,gcc_jit_context} instances.
9512
9513 Timers have no locking, so if you have a multithreaded program, you
9514 must provide your own locks if more than one thread could be working
9515 with the same timer via timer-associated contexts.
9516
9517 This API entrypoint was added in @ref{13d,,LIBGCCJIT_ABI_4}; you can test
9518 for its presence using
9519
9520 @example
9521 #ifdef LIBGCCJIT_HAVE_TIMING_API
9522 @end example
9523 @end deffn
9524
9525 @geindex gcc_jit_context_get_timer (C function)
9526 @anchor{topics/performance c gcc_jit_context_get_timer}@anchor{13e}
9527 @deffn {C Function} gcc_jit_timer *gcc_jit_context_get_timer (gcc_jit_context@w{ }*ctxt)
9528
9529 Get the timer associated with a context (if any).
9530
9531 This API entrypoint was added in @ref{13d,,LIBGCCJIT_ABI_4}; you can test
9532 for its presence using
9533
9534 @example
9535 #ifdef LIBGCCJIT_HAVE_TIMING_API
9536 @end example
9537 @end deffn
9538
9539 @geindex gcc_jit_timer_push (C function)
9540 @anchor{topics/performance c gcc_jit_timer_push}@anchor{142}
9541 @deffn {C Function} void gcc_jit_timer_push (gcc_jit_timer@w{ }*timer, const char@w{ }*item_name)
9542
9543 Push the given item onto the timer’s stack:
9544
9545 @example
9546 gcc_jit_timer_push (t, "running code");
9547 run_the_code (ctxt, result);
9548 gcc_jit_timer_pop (t, "running code");
9549 @end example
9550
9551 This API entrypoint was added in @ref{13d,,LIBGCCJIT_ABI_4}; you can test
9552 for its presence using
9553
9554 @example
9555 #ifdef LIBGCCJIT_HAVE_TIMING_API
9556 @end example
9557 @end deffn
9558
9559 @geindex gcc_jit_timer_pop (C function)
9560 @anchor{topics/performance c gcc_jit_timer_pop}@anchor{143}
9561 @deffn {C Function} void gcc_jit_timer_pop (gcc_jit_timer@w{ }*timer, const char@w{ }*item_name)
9562
9563 Pop the top item from the timer’s stack.
9564
9565 If “item_name” is provided, it must match that of the top item.
9566 Alternatively, @code{NULL} can be passed in, to suppress checking.
9567
9568 This API entrypoint was added in @ref{13d,,LIBGCCJIT_ABI_4}; you can test
9569 for its presence using
9570
9571 @example
9572 #ifdef LIBGCCJIT_HAVE_TIMING_API
9573 @end example
9574 @end deffn
9575
9576 @geindex gcc_jit_timer_print (C function)
9577 @anchor{topics/performance c gcc_jit_timer_print}@anchor{144}
9578 @deffn {C Function} void gcc_jit_timer_print (gcc_jit_timer@w{ }*timer, FILE@w{ }*f_out)
9579
9580 Print timing information to the given stream about activity since
9581 the timer was started.
9582
9583 This API entrypoint was added in @ref{13d,,LIBGCCJIT_ABI_4}; you can test
9584 for its presence using
9585
9586 @example
9587 #ifdef LIBGCCJIT_HAVE_TIMING_API
9588 @end example
9589 @end deffn
9590
9591 @c Copyright (C) 2020-2022 Free Software Foundation, Inc.
9592 @c Originally contributed by David Malcolm <[email protected]>
9593 @c
9594 @c This is free software: you can redistribute it and/or modify it
9595 @c under the terms of the GNU General Public License as published by
9596 @c the Free Software Foundation, either version 3 of the License, or
9597 @c (at your option) any later version.
9598 @c
9599 @c This program is distributed in the hope that it will be useful, but
9600 @c WITHOUT ANY WARRANTY; without even the implied warranty of
9601 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
9602 @c General Public License for more details.
9603 @c
9604 @c You should have received a copy of the GNU General Public License
9605 @c along with this program. If not, see
9606 @c <https://www.gnu.org/licenses/>.
9607
9608 @node Using Assembly Language with libgccjit,,Performance,Topic Reference
9609 @anchor{topics/asm doc}@anchor{169}@anchor{topics/asm using-assembly-language-with-libgccjit}@anchor{16a}
9610 @section Using Assembly Language with libgccjit
9611
9612
9613 libgccjit has some support for directly embedding assembler instructions.
9614 This is based on GCC’s support for inline @code{asm} in C code, and the
9615 following assumes a familiarity with that functionality. See
9616 How to Use Inline Assembly Language in C Code@footnote{https://gcc.gnu.org/onlinedocs/gcc/Using-Assembly-Language-with-C.html}
9617 in GCC’s documentation, the “Extended Asm” section in particular.
9618
9619 These entrypoints were added in @ref{151,,LIBGCCJIT_ABI_15}; you can test
9620 for their presence using
9621
9622 @quotation
9623
9624 @example
9625 #ifdef LIBGCCJIT_HAVE_ASM_STATEMENTS
9626 @end example
9627 @end quotation
9628
9629 @menu
9630 * Adding assembler instructions within a function::
9631 * Adding top-level assembler statements::
9632
9633 @end menu
9634
9635 @node Adding assembler instructions within a function,Adding top-level assembler statements,,Using Assembly Language with libgccjit
9636 @anchor{topics/asm adding-assembler-instructions-within-a-function}@anchor{16b}
9637 @subsection Adding assembler instructions within a function
9638
9639
9640 @geindex gcc_jit_extended_asm (C type)
9641 @anchor{topics/asm c gcc_jit_extended_asm}@anchor{120}
9642 @deffn {C Type} gcc_jit_extended_asm
9643
9644 A @cite{gcc_jit_extended_asm} represents an extended @code{asm} statement: a
9645 series of low-level instructions inside a function that convert inputs
9646 to outputs.
9647
9648 To avoid having an API entrypoint with a very large number of
9649 parameters, an extended @code{asm} statement is made in stages:
9650 an initial call to create the @ref{120,,gcc_jit_extended_asm},
9651 followed by calls to add operands and set other properties of the
9652 statement.
9653
9654 There are two API entrypoints for creating a @ref{120,,gcc_jit_extended_asm}:
9655
9656
9657 @itemize *
9658
9659 @item
9660 @ref{152,,gcc_jit_block_add_extended_asm()} for an @code{asm} statement with
9661 no control flow, and
9662
9663 @item
9664 @ref{153,,gcc_jit_block_end_with_extended_asm_goto()} for an @code{asm goto}.
9665 @end itemize
9666
9667 For example, to create the equivalent of:
9668
9669 @example
9670 asm ("mov %1, %0\n\t"
9671 "add $1, %0"
9672 : "=r" (dst)
9673 : "r" (src));
9674 @end example
9675
9676 the following API calls could be used:
9677
9678 @example
9679 gcc_jit_extended_asm *ext_asm
9680 = gcc_jit_block_add_extended_asm (block, NULL,
9681 "mov %1, %0\n\t"
9682 "add $1, %0");
9683 gcc_jit_extended_asm_add_output_operand (ext_asm, NULL, "=r", dst);
9684 gcc_jit_extended_asm_add_input_operand (ext_asm, NULL, "r",
9685 gcc_jit_lvalue_as_rvalue (src));
9686 @end example
9687
9688 @cartouche
9689 @quotation Warning
9690 When considering the numbering of operands within an
9691 extended @code{asm} statement (e.g. the @code{%0} and @code{%1}
9692 above), the equivalent to the C syntax is followed i.e. all
9693 output operands, then all input operands, regardless of
9694 what order the calls to
9695 @ref{157,,gcc_jit_extended_asm_add_output_operand()} and
9696 @ref{158,,gcc_jit_extended_asm_add_input_operand()} were made in.
9697 @end quotation
9698 @end cartouche
9699
9700 As in the C syntax, operands can be given symbolic names to avoid having
9701 to number them. For example, to create the equivalent of:
9702
9703 @example
9704 asm ("bsfl %[aMask], %[aIndex]"
9705 : [aIndex] "=r" (Index)
9706 : [aMask] "r" (Mask)
9707 : "cc");
9708 @end example
9709
9710 the following API calls could be used:
9711
9712 @example
9713 gcc_jit_extended_asm *ext_asm
9714 = gcc_jit_block_add_extended_asm (block, NULL,
9715 "bsfl %[aMask], %[aIndex]");
9716 gcc_jit_extended_asm_add_output_operand (ext_asm, "aIndex", "=r", index);
9717 gcc_jit_extended_asm_add_input_operand (ext_asm, "aMask", "r",
9718 gcc_jit_param_as_rvalue (mask));
9719 gcc_jit_extended_asm_add_clobber (ext_asm, "cc");
9720 @end example
9721 @end deffn
9722
9723 @geindex gcc_jit_block_add_extended_asm (C function)
9724 @anchor{topics/asm c gcc_jit_block_add_extended_asm}@anchor{152}
9725 @deffn {C Function} gcc_jit_extended_asm * gcc_jit_block_add_extended_asm (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, const char@w{ }*asm_template)
9726
9727 Create a @ref{120,,gcc_jit_extended_asm} for an extended @code{asm} statement
9728 with no control flow (i.e. without the @code{goto} qualifier).
9729
9730 The parameter @code{asm_template} corresponds to the @cite{AssemblerTemplate}
9731 within C’s extended @code{asm} syntax. It must be non-NULL. The call takes
9732 a copy of the underlying string, so it is valid to pass in a pointer to
9733 an on-stack buffer.
9734 @end deffn
9735
9736 @geindex gcc_jit_block_end_with_extended_asm_goto (C function)
9737 @anchor{topics/asm c gcc_jit_block_end_with_extended_asm_goto}@anchor{153}
9738 @deffn {C Function} gcc_jit_extended_asm * gcc_jit_block_end_with_extended_asm_goto (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, const char@w{ }*asm_template, int@w{ }num_goto_blocks, gcc_jit_block@w{ }**goto_blocks, gcc_jit_block@w{ }*fallthrough_block)
9739
9740 Create a @ref{120,,gcc_jit_extended_asm} for an extended @code{asm} statement
9741 that may perform jumps, and use it to terminate the given block.
9742 This is equivalent to the @code{goto} qualifier in C’s extended @code{asm}
9743 syntax.
9744
9745 For example, to create the equivalent of:
9746
9747 @example
9748 asm goto ("btl %1, %0\n\t"
9749 "jc %l[carry]"
9750 : // No outputs
9751 : "r" (p1), "r" (p2)
9752 : "cc"
9753 : carry);
9754 @end example
9755
9756 the following API calls could be used:
9757
9758 @example
9759 const char *asm_template =
9760 (use_name
9761 ? /* Label referred to by name: "%l[carry]". */
9762 ("btl %1, %0\n\t"
9763 "jc %l[carry]")
9764 : /* Label referred to numerically: "%l2". */
9765 ("btl %1, %0\n\t"
9766 "jc %l2"));
9767
9768 gcc_jit_extended_asm *ext_asm
9769 = gcc_jit_block_end_with_extended_asm_goto (b_start, NULL,
9770 asm_template,
9771 1, &b_carry,
9772 b_fallthru);
9773 gcc_jit_extended_asm_add_input_operand (ext_asm, NULL, "r",
9774 gcc_jit_param_as_rvalue (p1));
9775 gcc_jit_extended_asm_add_input_operand (ext_asm, NULL, "r",
9776 gcc_jit_param_as_rvalue (p2));
9777 gcc_jit_extended_asm_add_clobber (ext_asm, "cc");
9778 @end example
9779
9780 here referencing a @ref{28,,gcc_jit_block} named “carry”.
9781
9782 @code{num_goto_blocks} must be >= 0.
9783
9784 @code{goto_blocks} must be non-NULL. This corresponds to the @code{GotoLabels}
9785 parameter within C’s extended @code{asm} syntax. The block names can be
9786 referenced within the assembler template.
9787
9788 @code{fallthrough_block} can be NULL. If non-NULL, it specifies the block
9789 to fall through to after the statement.
9790
9791 @cartouche
9792 @quotation Note
9793 This is needed since each @ref{28,,gcc_jit_block} must have a
9794 single exit point, as a basic block: you can’t jump from the
9795 middle of a block. A “goto” is implicitly added after the
9796 asm to handle the fallthrough case, which is equivalent to what
9797 would have happened in the C case.
9798 @end quotation
9799 @end cartouche
9800 @end deffn
9801
9802 @geindex gcc_jit_extended_asm_set_volatile_flag (C function)
9803 @anchor{topics/asm c gcc_jit_extended_asm_set_volatile_flag}@anchor{155}
9804 @deffn {C Function} void gcc_jit_extended_asm_set_volatile_flag (gcc_jit_extended_asm@w{ }*ext_asm, int@w{ }flag)
9805
9806 Set whether the @ref{120,,gcc_jit_extended_asm} has side-effects, equivalent to the
9807 volatile@footnote{https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#Volatile}
9808 qualifier in C’s extended asm syntax.
9809
9810 For example, to create the equivalent of:
9811
9812 @example
9813 asm volatile ("rdtsc\n\t" // Returns the time in EDX:EAX.
9814 "shl $32, %%rdx\n\t" // Shift the upper bits left.
9815 "or %%rdx, %0" // 'Or' in the lower bits.
9816 : "=a" (msr)
9817 :
9818 : "rdx");
9819 @end example
9820
9821 the following API calls could be used:
9822
9823 @example
9824 gcc_jit_extended_asm *ext_asm
9825 = gcc_jit_block_add_extended_asm
9826 (block, NULL,
9827 "rdtsc\n\t" /* Returns the time in EDX:EAX. */
9828 "shl $32, %%rdx\n\t" /* Shift the upper bits left. */
9829 "or %%rdx, %0"); /* 'Or' in the lower bits. */
9830 gcc_jit_extended_asm_set_volatile_flag (ext_asm, 1);
9831 gcc_jit_extended_asm_add_output_operand (ext_asm, NULL, "=a", msr);
9832 gcc_jit_extended_asm_add_clobber (ext_asm, "rdx");
9833 @end example
9834
9835 where the @ref{120,,gcc_jit_extended_asm} is flagged as volatile.
9836 @end deffn
9837
9838 @geindex gcc_jit_extended_asm_set_inline_flag (C function)
9839 @anchor{topics/asm c gcc_jit_extended_asm_set_inline_flag}@anchor{156}
9840 @deffn {C Function} void gcc_jit_extended_asm_set_inline_flag (gcc_jit_extended_asm@w{ }*ext_asm, int@w{ }flag)
9841
9842 Set the equivalent of the
9843 inline@footnote{https://gcc.gnu.org/onlinedocs/gcc/Size-of-an-asm.html#Size-of-an-asm}
9844 qualifier in C’s extended @code{asm} syntax.
9845 @end deffn
9846
9847 @geindex gcc_jit_extended_asm_add_output_operand (C function)
9848 @anchor{topics/asm c gcc_jit_extended_asm_add_output_operand}@anchor{157}
9849 @deffn {C Function} void gcc_jit_extended_asm_add_output_operand (gcc_jit_extended_asm@w{ }*ext_asm, const char@w{ }*asm_symbolic_name, const char@w{ }*constraint, gcc_jit_lvalue@w{ }*dest)
9850
9851 Add an output operand to the extended @code{asm} statement. See the
9852 Output Operands@footnote{https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#OutputOperands}
9853 section of the documentation of the C syntax.
9854
9855 @code{asm_symbolic_name} corresponds to the @code{asmSymbolicName} component of C’s
9856 extended @code{asm} syntax. It can be NULL. If non-NULL it specifies the
9857 symbolic name for the operand.
9858
9859 @code{constraint} corresponds to the @code{constraint} component of C’s extended
9860 @code{asm} syntax. It must be non-NULL.
9861
9862 @code{dest} corresponds to the @code{cvariablename} component of C’s extended
9863 @code{asm} syntax. It must be non-NULL.
9864
9865 @example
9866 // Example with a NULL symbolic name, the equivalent of:
9867 // : "=r" (dst)
9868 gcc_jit_extended_asm_add_output_operand (ext_asm, NULL, "=r", dst);
9869
9870 // Example with a symbolic name ("aIndex"), the equivalent of:
9871 // : [aIndex] "=r" (index)
9872 gcc_jit_extended_asm_add_output_operand (ext_asm, "aIndex", "=r", index);
9873 @end example
9874
9875 This function can’t be called on an @code{asm goto} as such instructions can’t
9876 have outputs; see the
9877 Goto Labels@footnote{https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#GotoLabels}
9878 section of GCC’s “Extended Asm” documentation.
9879 @end deffn
9880
9881 @geindex gcc_jit_extended_asm_add_input_operand (C function)
9882 @anchor{topics/asm c gcc_jit_extended_asm_add_input_operand}@anchor{158}
9883 @deffn {C Function} void gcc_jit_extended_asm_add_input_operand (gcc_jit_extended_asm@w{ }*ext_asm, const char@w{ }*asm_symbolic_name, const char@w{ }*constraint, gcc_jit_rvalue@w{ }*src)
9884
9885 Add an input operand to the extended @code{asm} statement. See the
9886 Input Operands@footnote{https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#InputOperands}
9887 section of the documentation of the C syntax.
9888
9889 @code{asm_symbolic_name} corresponds to the @code{asmSymbolicName} component of C’s
9890 extended @code{asm} syntax. It can be NULL. If non-NULL it specifies the
9891 symbolic name for the operand.
9892
9893 @code{constraint} corresponds to the @code{constraint} component of C’s extended
9894 @code{asm} syntax. It must be non-NULL.
9895
9896 @code{src} corresponds to the @code{cexpression} component of C’s extended
9897 @code{asm} syntax. It must be non-NULL.
9898
9899 @example
9900 // Example with a NULL symbolic name, the equivalent of:
9901 // : "r" (src)
9902 gcc_jit_extended_asm_add_input_operand (ext_asm, NULL, "r",
9903 gcc_jit_lvalue_as_rvalue (src));
9904
9905 // Example with a symbolic name ("aMask"), the equivalent of:
9906 // : [aMask] "r" (Mask)
9907 gcc_jit_extended_asm_add_input_operand (ext_asm, "aMask", "r",
9908 gcc_jit_lvalue_as_rvalue (mask));
9909 @end example
9910 @end deffn
9911
9912 @geindex gcc_jit_extended_asm_add_clobber (C function)
9913 @anchor{topics/asm c gcc_jit_extended_asm_add_clobber}@anchor{159}
9914 @deffn {C Function} void gcc_jit_extended_asm_add_clobber (gcc_jit_extended_asm@w{ }*ext_asm, const char@w{ }*victim)
9915
9916 Add @cite{victim} to the list of registers clobbered by the extended @code{asm}
9917 statement. It must be non-NULL. See the
9918 Clobbers and Scratch Registers@footnote{https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#Clobbers-and-Scratch-Registers#}
9919 section of the documentation of the C syntax.
9920
9921 Statements with multiple clobbers will require multiple calls, one per
9922 clobber.
9923
9924 For example:
9925
9926 @example
9927 gcc_jit_extended_asm_add_clobber (ext_asm, "r0");
9928 gcc_jit_extended_asm_add_clobber (ext_asm, "cc");
9929 gcc_jit_extended_asm_add_clobber (ext_asm, "memory");
9930 @end example
9931 @end deffn
9932
9933 A @ref{120,,gcc_jit_extended_asm} is a @ref{e,,gcc_jit_object} “owned” by
9934 the block’s context. The following upcast is available:
9935
9936 @geindex gcc_jit_extended_asm_as_object (C function)
9937 @anchor{topics/asm c gcc_jit_extended_asm_as_object}@anchor{154}
9938 @deffn {C Function} gcc_jit_object * gcc_jit_extended_asm_as_object (gcc_jit_extended_asm@w{ }*ext_asm)
9939
9940 Upcast from extended @code{asm} to object.
9941 @end deffn
9942
9943 @node Adding top-level assembler statements,,Adding assembler instructions within a function,Using Assembly Language with libgccjit
9944 @anchor{topics/asm adding-top-level-assembler-statements}@anchor{16c}
9945 @subsection Adding top-level assembler statements
9946
9947
9948 In addition to creating extended @code{asm} instructions within a function,
9949 there is support for creating “top-level” assembler statements, outside
9950 of any function.
9951
9952 @geindex gcc_jit_context_add_top_level_asm (C function)
9953 @anchor{topics/asm c gcc_jit_context_add_top_level_asm}@anchor{15a}
9954 @deffn {C Function} void gcc_jit_context_add_top_level_asm (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, const char@w{ }*asm_stmts)
9955
9956 Create a set of top-level asm statements, analogous to those created
9957 by GCC’s “basic” @code{asm} syntax in C at file scope.
9958
9959 For example, to create the equivalent of:
9960
9961 @example
9962 asm ("\t.pushsection .text\n"
9963 "\t.globl add_asm\n"
9964 "\t.type add_asm, @@function\n"
9965 "add_asm:\n"
9966 "\tmovq %rdi, %rax\n"
9967 "\tadd %rsi, %rax\n"
9968 "\tret\n"
9969 "\t.popsection\n");
9970 @end example
9971
9972 the following API calls could be used:
9973
9974 @example
9975 gcc_jit_context_add_top_level_asm (ctxt, NULL,
9976 "\t.pushsection .text\n"
9977 "\t.globl add_asm\n"
9978 "\t.type add_asm, @@function\n"
9979 "add_asm:\n"
9980 "\tmovq %rdi, %rax\n"
9981 "\tadd %rsi, %rax\n"
9982 "\tret\n"
9983 "\t# some asm here\n"
9984 "\t.popsection\n");
9985 @end example
9986 @end deffn
9987
9988 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
9989 @c Originally contributed by David Malcolm <[email protected]>
9990 @c
9991 @c This is free software: you can redistribute it and/or modify it
9992 @c under the terms of the GNU General Public License as published by
9993 @c the Free Software Foundation, either version 3 of the License, or
9994 @c (at your option) any later version.
9995 @c
9996 @c This program is distributed in the hope that it will be useful, but
9997 @c WITHOUT ANY WARRANTY; without even the implied warranty of
9998 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
9999 @c General Public License for more details.
10000 @c
10001 @c You should have received a copy of the GNU General Public License
10002 @c along with this program. If not, see
10003 @c <https://www.gnu.org/licenses/>.
10004
10005 @node C++ bindings for libgccjit,Internals,Topic Reference,Top
10006 @anchor{cp/index doc}@anchor{16d}@anchor{cp/index c-bindings-for-libgccjit}@anchor{16e}
10007 @chapter C++ bindings for libgccjit
10008
10009
10010 This document describes the C++ bindings to
10011 libgccjit@footnote{https://gcc.gnu.org/wiki/JIT}, an API for embedding GCC
10012 inside programs and libraries.
10013
10014 The C++ bindings consist of a single header file @code{libgccjit++.h}.
10015
10016 This is a collection of “thin” wrapper classes around the C API.
10017 Everything is an inline function, implemented in terms of the C API,
10018 so there is nothing extra to link against.
10019
10020 Contents:
10021
10022 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
10023 @c Originally contributed by David Malcolm <[email protected]>
10024 @c
10025 @c This is free software: you can redistribute it and/or modify it
10026 @c under the terms of the GNU General Public License as published by
10027 @c the Free Software Foundation, either version 3 of the License, or
10028 @c (at your option) any later version.
10029 @c
10030 @c This program is distributed in the hope that it will be useful, but
10031 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10032 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10033 @c General Public License for more details.
10034 @c
10035 @c You should have received a copy of the GNU General Public License
10036 @c along with this program. If not, see
10037 @c <https://www.gnu.org/licenses/>.
10038
10039 @menu
10040 * Tutorial: Tutorial<2>.
10041 * Topic Reference: Topic Reference<2>.
10042
10043 @end menu
10044
10045 @node Tutorial<2>,Topic Reference<2>,,C++ bindings for libgccjit
10046 @anchor{cp/intro/index doc}@anchor{16f}@anchor{cp/intro/index tutorial}@anchor{170}
10047 @section Tutorial
10048
10049
10050 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
10051 @c Originally contributed by David Malcolm <[email protected]>
10052 @c
10053 @c This is free software: you can redistribute it and/or modify it
10054 @c under the terms of the GNU General Public License as published by
10055 @c the Free Software Foundation, either version 3 of the License, or
10056 @c (at your option) any later version.
10057 @c
10058 @c This program is distributed in the hope that it will be useful, but
10059 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10060 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10061 @c General Public License for more details.
10062 @c
10063 @c You should have received a copy of the GNU General Public License
10064 @c along with this program. If not, see
10065 @c <https://www.gnu.org/licenses/>.
10066
10067 @menu
10068 * Tutorial part 1; “Hello world”: Tutorial part 1 “Hello world”<2>.
10069 * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>.
10070 * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>.
10071 * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>.
10072
10073 @end menu
10074
10075 @node Tutorial part 1 “Hello world”<2>,Tutorial part 2 Creating a trivial machine code function<2>,,Tutorial<2>
10076 @anchor{cp/intro/tutorial01 doc}@anchor{171}@anchor{cp/intro/tutorial01 tutorial-part-1-hello-world}@anchor{172}
10077 @subsection Tutorial part 1: “Hello world”
10078
10079
10080 Before we look at the details of the API, let’s look at building and
10081 running programs that use the library.
10082
10083 Here’s a toy “hello world” program that uses the library’s C++ API to
10084 synthesize a call to @cite{printf} and uses it to write a message to stdout.
10085
10086 Don’t worry about the content of the program for now; we’ll cover
10087 the details in later parts of this tutorial.
10088
10089 @quotation
10090
10091 @example
10092 /* Smoketest example for libgccjit.so C++ API
10093 Copyright (C) 2014-2022 Free Software Foundation, Inc.
10094
10095 This file is part of GCC.
10096
10097 GCC is free software; you can redistribute it and/or modify it
10098 under the terms of the GNU General Public License as published by
10099 the Free Software Foundation; either version 3, or (at your option)
10100 any later version.
10101
10102 GCC is distributed in the hope that it will be useful, but
10103 WITHOUT ANY WARRANTY; without even the implied warranty of
10104 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10105 General Public License for more details.
10106
10107 You should have received a copy of the GNU General Public License
10108 along with GCC; see the file COPYING3. If not see
10109 <http://www.gnu.org/licenses/>. */
10110
10111 #include <libgccjit++.h>
10112
10113 #include <stdlib.h>
10114 #include <stdio.h>
10115
10116 static void
10117 create_code (gccjit::context ctxt)
10118 @{
10119 /* Let's try to inject the equivalent of this C code:
10120 void
10121 greet (const char *name)
10122 @{
10123 printf ("hello %s\n", name);
10124 @}
10125 */
10126 gccjit::type void_type = ctxt.get_type (GCC_JIT_TYPE_VOID);
10127 gccjit::type const_char_ptr_type =
10128 ctxt.get_type (GCC_JIT_TYPE_CONST_CHAR_PTR);
10129 gccjit::param param_name =
10130 ctxt.new_param (const_char_ptr_type, "name");
10131 std::vector<gccjit::param> func_params;
10132 func_params.push_back (param_name);
10133 gccjit::function func =
10134 ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
10135 void_type,
10136 "greet",
10137 func_params, 0);
10138
10139 gccjit::param param_format =
10140 ctxt.new_param (const_char_ptr_type, "format");
10141 std::vector<gccjit::param> printf_params;
10142 printf_params.push_back (param_format);
10143 gccjit::function printf_func =
10144 ctxt.new_function (GCC_JIT_FUNCTION_IMPORTED,
10145 ctxt.get_type (GCC_JIT_TYPE_INT),
10146 "printf",
10147 printf_params, 1);
10148
10149 gccjit::block block = func.new_block ();
10150 block.add_eval (ctxt.new_call (printf_func,
10151 ctxt.new_rvalue ("hello %s\n"),
10152 param_name));
10153 block.end_with_return ();
10154 @}
10155
10156 int
10157 main (int argc, char **argv)
10158 @{
10159 gccjit::context ctxt;
10160 gcc_jit_result *result;
10161
10162 /* Get a "context" object for working with the library. */
10163 ctxt = gccjit::context::acquire ();
10164
10165 /* Set some options on the context.
10166 Turn this on to see the code being generated, in assembler form. */
10167 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 0);
10168
10169 /* Populate the context. */
10170 create_code (ctxt);
10171
10172 /* Compile the code. */
10173 result = ctxt.compile ();
10174 if (!result)
10175 @{
10176 fprintf (stderr, "NULL result");
10177 exit (1);
10178 @}
10179
10180 ctxt.release ();
10181
10182 /* Extract the generated code from "result". */
10183 typedef void (*fn_type) (const char *);
10184 fn_type greet =
10185 (fn_type)gcc_jit_result_get_code (result, "greet");
10186 if (!greet)
10187 @{
10188 fprintf (stderr, "NULL greet");
10189 exit (1);
10190 @}
10191
10192 /* Now call the generated function: */
10193 greet ("world");
10194 fflush (stdout);
10195
10196 gcc_jit_result_release (result);
10197 return 0;
10198 @}
10199 @end example
10200 @end quotation
10201
10202 Copy the above to @cite{tut01-hello-world.cc}.
10203
10204 Assuming you have the jit library installed, build the test program
10205 using:
10206
10207 @example
10208 $ gcc \
10209 tut01-hello-world.cc \
10210 -o tut01-hello-world \
10211 -lgccjit
10212 @end example
10213
10214 You should then be able to run the built program:
10215
10216 @example
10217 $ ./tut01-hello-world
10218 hello world
10219 @end example
10220
10221 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
10222 @c Originally contributed by David Malcolm <[email protected]>
10223 @c
10224 @c This is free software: you can redistribute it and/or modify it
10225 @c under the terms of the GNU General Public License as published by
10226 @c the Free Software Foundation, either version 3 of the License, or
10227 @c (at your option) any later version.
10228 @c
10229 @c This program is distributed in the hope that it will be useful, but
10230 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10231 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10232 @c General Public License for more details.
10233 @c
10234 @c You should have received a copy of the GNU General Public License
10235 @c along with this program. If not, see
10236 @c <https://www.gnu.org/licenses/>.
10237
10238 @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>
10239 @anchor{cp/intro/tutorial02 doc}@anchor{173}@anchor{cp/intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{174}
10240 @subsection Tutorial part 2: Creating a trivial machine code function
10241
10242
10243 Consider this C function:
10244
10245 @example
10246 int square (int i)
10247 @{
10248 return i * i;
10249 @}
10250 @end example
10251
10252 How can we construct this at run-time using libgccjit’s C++ API?
10253
10254 First we need to include the relevant header:
10255
10256 @example
10257 #include <libgccjit++.h>
10258 @end example
10259
10260 All state associated with compilation is associated with a
10261 @ref{175,,gccjit;;context}, which is a thin C++ wrapper around the C API’s
10262 @ref{8,,gcc_jit_context *}.
10263
10264 Create one using @ref{176,,gccjit;;context;;acquire()}:
10265
10266 @example
10267 gccjit::context ctxt;
10268 ctxt = gccjit::context::acquire ();
10269 @end example
10270
10271 The JIT library has a system of types. It is statically-typed: every
10272 expression is of a specific type, fixed at compile-time. In our example,
10273 all of the expressions are of the C @cite{int} type, so let’s obtain this from
10274 the context, as a @ref{177,,gccjit;;type}, using
10275 @ref{178,,gccjit;;context;;get_type()}:
10276
10277 @example
10278 gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
10279 @end example
10280
10281 @ref{177,,gccjit;;type} is an example of a “contextual” object: every
10282 entity in the API is associated with a @ref{175,,gccjit;;context}.
10283
10284 Memory management is easy: all such “contextual” objects are automatically
10285 cleaned up for you when the context is released, using
10286 @ref{179,,gccjit;;context;;release()}:
10287
10288 @example
10289 ctxt.release ();
10290 @end example
10291
10292 so you don’t need to manually track and cleanup all objects, just the
10293 contexts.
10294
10295 All of the C++ classes in the API are thin wrappers around pointers to
10296 types in the C API.
10297
10298 The C++ class hierarchy within the @code{gccjit} namespace looks like this:
10299
10300 @example
10301 +- object
10302 +- location
10303 +- type
10304 +- struct
10305 +- field
10306 +- function
10307 +- block
10308 +- rvalue
10309 +- lvalue
10310 +- param
10311 @end example
10312
10313 One thing you can do with a @ref{17a,,gccjit;;object} is
10314 to ask it for a human-readable description as a @code{std::string}, using
10315 @ref{17b,,gccjit;;object;;get_debug_string()}:
10316
10317 @example
10318 printf ("obj: %s\n", obj.get_debug_string ().c_str ());
10319 @end example
10320
10321 giving this text on stdout:
10322
10323 @example
10324 obj: int
10325 @end example
10326
10327 This is invaluable when debugging.
10328
10329 Let’s create the function. To do so, we first need to construct
10330 its single parameter, specifying its type and giving it a name,
10331 using @ref{17c,,gccjit;;context;;new_param()}:
10332
10333 @example
10334 gccjit::param param_i = ctxt.new_param (int_type, "i");
10335 @end example
10336
10337 and we can then make a vector of all of the params of the function,
10338 in this case just one:
10339
10340 @example
10341 std::vector<gccjit::param> params;
10342 params.push_back (param_i);
10343 @end example
10344
10345 Now we can create the function, using
10346 @code{gccjit::context::new_function()}:
10347
10348 @example
10349 gccjit::function func =
10350 ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
10351 int_type,
10352 "square",
10353 params,
10354 0);
10355 @end example
10356
10357 To define the code within the function, we must create basic blocks
10358 containing statements.
10359
10360 Every basic block contains a list of statements, eventually terminated
10361 by a statement that either returns, or jumps to another basic block.
10362
10363 Our function has no control-flow, so we just need one basic block:
10364
10365 @example
10366 gccjit::block block = func.new_block ();
10367 @end example
10368
10369 Our basic block is relatively simple: it immediately terminates by
10370 returning the value of an expression.
10371
10372 We can build the expression using @ref{17d,,gccjit;;context;;new_binary_op()}:
10373
10374 @example
10375 gccjit::rvalue expr =
10376 ctxt.new_binary_op (
10377 GCC_JIT_BINARY_OP_MULT, int_type,
10378 param_i, param_i);
10379 @end example
10380
10381 A @ref{17e,,gccjit;;rvalue} is another example of a
10382 @ref{17a,,gccjit;;object} subclass. As before, we can print it with
10383 @ref{17b,,gccjit;;object;;get_debug_string()}.
10384
10385 @example
10386 printf ("expr: %s\n", expr.get_debug_string ().c_str ());
10387 @end example
10388
10389 giving this output:
10390
10391 @example
10392 expr: i * i
10393 @end example
10394
10395 Note that @ref{17e,,gccjit;;rvalue} provides numerous overloaded operators
10396 which can be used to dramatically reduce the amount of typing needed.
10397 We can build the above binary operation more directly with this one-liner:
10398
10399 @example
10400 gccjit::rvalue expr = param_i * param_i;
10401 @end example
10402
10403 Creating the expression in itself doesn’t do anything; we have to add
10404 this expression to a statement within the block. In this case, we use it
10405 to build a return statement, which terminates the basic block:
10406
10407 @example
10408 block.end_with_return (expr);
10409 @end example
10410
10411 OK, we’ve populated the context. We can now compile it using
10412 @ref{17f,,gccjit;;context;;compile()}:
10413
10414 @example
10415 gcc_jit_result *result;
10416 result = ctxt.compile ();
10417 @end example
10418
10419 and get a @ref{16,,gcc_jit_result *}.
10420
10421 We can now use @ref{17,,gcc_jit_result_get_code()} to look up a specific
10422 machine code routine within the result, in this case, the function we
10423 created above.
10424
10425 @example
10426 void *fn_ptr = gcc_jit_result_get_code (result, "square");
10427 if (!fn_ptr)
10428 @{
10429 fprintf (stderr, "NULL fn_ptr");
10430 goto error;
10431 @}
10432 @end example
10433
10434 We can now cast the pointer to an appropriate function pointer type, and
10435 then call it:
10436
10437 @example
10438 typedef int (*fn_type) (int);
10439 fn_type square = (fn_type)fn_ptr;
10440 printf ("result: %d", square (5));
10441 @end example
10442
10443 @example
10444 result: 25
10445 @end example
10446
10447 @menu
10448 * Options: Options<3>.
10449 * Full example: Full example<3>.
10450
10451 @end menu
10452
10453 @node Options<3>,Full example<3>,,Tutorial part 2 Creating a trivial machine code function<2>
10454 @anchor{cp/intro/tutorial02 options}@anchor{180}
10455 @subsubsection Options
10456
10457
10458 To get more information on what’s going on, you can set debugging flags
10459 on the context using @ref{181,,gccjit;;context;;set_bool_option()}.
10460
10461 @c (I'm deliberately not mentioning
10462 @c :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE` here since I think
10463 @c it's probably more of use to implementors than to users)
10464
10465 Setting @ref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE} will dump a
10466 C-like representation to stderr when you compile (GCC’s “GIMPLE”
10467 representation):
10468
10469 @example
10470 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1);
10471 result = ctxt.compile ();
10472 @end example
10473
10474 @example
10475 square (signed int i)
10476 @{
10477 signed int D.260;
10478
10479 entry:
10480 D.260 = i * i;
10481 return D.260;
10482 @}
10483 @end example
10484
10485 We can see the generated machine code in assembler form (on stderr) by
10486 setting @ref{1d,,GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE} on the context
10487 before compiling:
10488
10489 @example
10490 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 1);
10491 result = ctxt.compile ();
10492 @end example
10493
10494 @example
10495 .file "fake.c"
10496 .text
10497 .globl square
10498 .type square, @@function
10499 square:
10500 .LFB6:
10501 .cfi_startproc
10502 pushq %rbp
10503 .cfi_def_cfa_offset 16
10504 .cfi_offset 6, -16
10505 movq %rsp, %rbp
10506 .cfi_def_cfa_register 6
10507 movl %edi, -4(%rbp)
10508 .L14:
10509 movl -4(%rbp), %eax
10510 imull -4(%rbp), %eax
10511 popq %rbp
10512 .cfi_def_cfa 7, 8
10513 ret
10514 .cfi_endproc
10515 .LFE6:
10516 .size square, .-square
10517 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
10518 .section .note.GNU-stack,"",@@progbits
10519 @end example
10520
10521 By default, no optimizations are performed, the equivalent of GCC’s
10522 @cite{-O0} option. We can turn things up to e.g. @cite{-O3} by calling
10523 @ref{182,,gccjit;;context;;set_int_option()} with
10524 @ref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
10525
10526 @example
10527 ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3);
10528 @end example
10529
10530 @example
10531 .file "fake.c"
10532 .text
10533 .p2align 4,,15
10534 .globl square
10535 .type square, @@function
10536 square:
10537 .LFB7:
10538 .cfi_startproc
10539 .L16:
10540 movl %edi, %eax
10541 imull %edi, %eax
10542 ret
10543 .cfi_endproc
10544 .LFE7:
10545 .size square, .-square
10546 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
10547 .section .note.GNU-stack,"",@@progbits
10548 @end example
10549
10550 Naturally this has only a small effect on such a trivial function.
10551
10552 @node Full example<3>,,Options<3>,Tutorial part 2 Creating a trivial machine code function<2>
10553 @anchor{cp/intro/tutorial02 full-example}@anchor{183}
10554 @subsubsection Full example
10555
10556
10557 Here’s what the above looks like as a complete program:
10558
10559 @quotation
10560
10561 @example
10562 /* Usage example for libgccjit.so's C++ API
10563 Copyright (C) 2014-2022 Free Software Foundation, Inc.
10564
10565 This file is part of GCC.
10566
10567 GCC is free software; you can redistribute it and/or modify it
10568 under the terms of the GNU General Public License as published by
10569 the Free Software Foundation; either version 3, or (at your option)
10570 any later version.
10571
10572 GCC is distributed in the hope that it will be useful, but
10573 WITHOUT ANY WARRANTY; without even the implied warranty of
10574 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10575 General Public License for more details.
10576
10577 You should have received a copy of the GNU General Public License
10578 along with GCC; see the file COPYING3. If not see
10579 <http://www.gnu.org/licenses/>. */
10580
10581 #include <libgccjit++.h>
10582
10583 #include <stdlib.h>
10584 #include <stdio.h>
10585
10586 void
10587 create_code (gccjit::context ctxt)
10588 @{
10589 /* Let's try to inject the equivalent of this C code:
10590
10591 int square (int i)
10592 @{
10593 return i * i;
10594 @}
10595 */
10596 gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
10597 gccjit::param param_i = ctxt.new_param (int_type, "i");
10598 std::vector<gccjit::param> params;
10599 params.push_back (param_i);
10600 gccjit::function func = ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
10601 int_type,
10602 "square",
10603 params, 0);
10604
10605 gccjit::block block = func.new_block ();
10606
10607 gccjit::rvalue expr =
10608 ctxt.new_binary_op (GCC_JIT_BINARY_OP_MULT, int_type,
10609 param_i, param_i);
10610
10611 block.end_with_return (expr);
10612 @}
10613
10614 int
10615 main (int argc, char **argv)
10616 @{
10617 /* Get a "context" object for working with the library. */
10618 gccjit::context ctxt = gccjit::context::acquire ();
10619
10620 /* Set some options on the context.
10621 Turn this on to see the code being generated, in assembler form. */
10622 ctxt.set_bool_option (
10623 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
10624 0);
10625
10626 /* Populate the context. */
10627 create_code (ctxt);
10628
10629 /* Compile the code. */
10630 gcc_jit_result *result = ctxt.compile ();
10631
10632 /* We're done with the context; we can release it: */
10633 ctxt.release ();
10634
10635 if (!result)
10636 @{
10637 fprintf (stderr, "NULL result");
10638 return 1;
10639 @}
10640
10641 /* Extract the generated code from "result". */
10642 void *fn_ptr = gcc_jit_result_get_code (result, "square");
10643 if (!fn_ptr)
10644 @{
10645 fprintf (stderr, "NULL fn_ptr");
10646 gcc_jit_result_release (result);
10647 return 1;
10648 @}
10649
10650 typedef int (*fn_type) (int);
10651 fn_type square = (fn_type)fn_ptr;
10652 printf ("result: %d\n", square (5));
10653
10654 gcc_jit_result_release (result);
10655 return 0;
10656 @}
10657 @end example
10658 @end quotation
10659
10660 Building and running it:
10661
10662 @example
10663 $ gcc \
10664 tut02-square.cc \
10665 -o tut02-square \
10666 -lgccjit
10667
10668 # Run the built program:
10669 $ ./tut02-square
10670 result: 25
10671 @end example
10672
10673 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
10674 @c Originally contributed by David Malcolm <[email protected]>
10675 @c
10676 @c This is free software: you can redistribute it and/or modify it
10677 @c under the terms of the GNU General Public License as published by
10678 @c the Free Software Foundation, either version 3 of the License, or
10679 @c (at your option) any later version.
10680 @c
10681 @c This program is distributed in the hope that it will be useful, but
10682 @c WITHOUT ANY WARRANTY; without even the implied warranty of
10683 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10684 @c General Public License for more details.
10685 @c
10686 @c You should have received a copy of the GNU General Public License
10687 @c along with this program. If not, see
10688 @c <https://www.gnu.org/licenses/>.
10689
10690 @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>
10691 @anchor{cp/intro/tutorial03 doc}@anchor{184}@anchor{cp/intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{185}
10692 @subsection Tutorial part 3: Loops and variables
10693
10694
10695 Consider this C function:
10696
10697 @quotation
10698
10699 @example
10700 int loop_test (int n)
10701 @{
10702 int sum = 0;
10703 for (int i = 0; i < n; i++)
10704 sum += i * i;
10705 return sum;
10706 @}
10707 @end example
10708 @end quotation
10709
10710 This example demonstrates some more features of libgccjit, with local
10711 variables and a loop.
10712
10713 To break this down into libgccjit terms, it’s usually easier to reword
10714 the @cite{for} loop as a @cite{while} loop, giving:
10715
10716 @quotation
10717
10718 @example
10719 int loop_test (int n)
10720 @{
10721 int sum = 0;
10722 int i = 0;
10723 while (i < n)
10724 @{
10725 sum += i * i;
10726 i++;
10727 @}
10728 return sum;
10729 @}
10730 @end example
10731 @end quotation
10732
10733 Here’s what the final control flow graph will look like:
10734
10735 @quotation
10736
10737
10738 @float Figure
10739
10740 @image{libgccjit-figures/sum-of-squares,,,image of a control flow graph,png}
10741
10742 @end float
10743
10744 @end quotation
10745
10746 As before, we include the libgccjit++ header and make a
10747 @ref{175,,gccjit;;context}.
10748
10749 @example
10750 #include <libgccjit++.h>
10751
10752 void test (void)
10753 @{
10754 gccjit::context ctxt;
10755 ctxt = gccjit::context::acquire ();
10756 @end example
10757
10758 The function works with the C @cite{int} type.
10759
10760 In the previous tutorial we acquired this via
10761
10762 @example
10763 gccjit::type the_type = ctxt.get_type (ctxt, GCC_JIT_TYPE_INT);
10764 @end example
10765
10766 though we could equally well make it work on, say, @cite{double}:
10767
10768 @example
10769 gccjit::type the_type = ctxt.get_type (ctxt, GCC_JIT_TYPE_DOUBLE);
10770 @end example
10771
10772 For integer types we can use @code{gccjit::context::get_int_type}
10773 to directly bind a specific type:
10774
10775 @example
10776 gccjit::type the_type = ctxt.get_int_type <int> ();
10777 @end example
10778
10779 Let’s build the function:
10780
10781 @example
10782 gcc_jit_param n = ctxt.new_param (the_type, "n");
10783 std::vector<gccjit::param> params;
10784 params.push_back (n);
10785 gccjit::function func =
10786 ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
10787 return_type,
10788 "loop_test",
10789 params, 0);
10790 @end example
10791
10792 @menu
10793 * Expressions; lvalues and rvalues: Expressions lvalues and rvalues<2>.
10794 * Control flow: Control flow<2>.
10795 * Visualizing the control flow graph: Visualizing the control flow graph<2>.
10796 * Full example: Full example<4>.
10797
10798 @end menu
10799
10800 @node Expressions lvalues and rvalues<2>,Control flow<2>,,Tutorial part 3 Loops and variables<2>
10801 @anchor{cp/intro/tutorial03 expressions-lvalues-and-rvalues}@anchor{186}
10802 @subsubsection Expressions: lvalues and rvalues
10803
10804
10805 The base class of expression is the @ref{17e,,gccjit;;rvalue},
10806 representing an expression that can be on the @emph{right}-hand side of
10807 an assignment: a value that can be computed somehow, and assigned
10808 @emph{to} a storage area (such as a variable). It has a specific
10809 @ref{177,,gccjit;;type}.
10810
10811 Anothe important class is @ref{187,,gccjit;;lvalue}.
10812 A @ref{187,,gccjit;;lvalue}. is something that can of the @emph{left}-hand
10813 side of an assignment: a storage area (such as a variable).
10814
10815 In other words, every assignment can be thought of as:
10816
10817 @example
10818 LVALUE = RVALUE;
10819 @end example
10820
10821 Note that @ref{187,,gccjit;;lvalue} is a subclass of
10822 @ref{17e,,gccjit;;rvalue}, where in an assignment of the form:
10823
10824 @example
10825 LVALUE_A = LVALUE_B;
10826 @end example
10827
10828 the @cite{LVALUE_B} implies reading the current value of that storage
10829 area, assigning it into the @cite{LVALUE_A}.
10830
10831 So far the only expressions we’ve seen are from the previous tutorial:
10832
10833
10834 @enumerate
10835
10836 @item
10837 the multiplication @cite{i * i}:
10838 @end enumerate
10839
10840 @quotation
10841
10842 @example
10843 gccjit::rvalue expr =
10844 ctxt.new_binary_op (
10845 GCC_JIT_BINARY_OP_MULT, int_type,
10846 param_i, param_i);
10847
10848 /* Alternatively, using operator-overloading: */
10849 gccjit::rvalue expr = param_i * param_i;
10850 @end example
10851
10852 which is a @ref{17e,,gccjit;;rvalue}, and
10853 @end quotation
10854
10855
10856 @enumerate 2
10857
10858 @item
10859 the various function parameters: @cite{param_i} and @cite{param_n}, instances of
10860 @ref{188,,gccjit;;param}, which is a subclass of @ref{187,,gccjit;;lvalue}
10861 (and, in turn, of @ref{17e,,gccjit;;rvalue}):
10862 we can both read from and write to function parameters within the
10863 body of a function.
10864 @end enumerate
10865
10866 Our new example has a new kind of expression: we have two local
10867 variables. We create them by calling
10868 @ref{189,,gccjit;;function;;new_local()}, supplying a type and a name:
10869
10870 @example
10871 /* Build locals: */
10872 gccjit::lvalue i = func.new_local (the_type, "i");
10873 gccjit::lvalue sum = func.new_local (the_type, "sum");
10874 @end example
10875
10876 These are instances of @ref{187,,gccjit;;lvalue} - they can be read from
10877 and written to.
10878
10879 Note that there is no precanned way to create @emph{and} initialize a variable
10880 like in C:
10881
10882 @example
10883 int i = 0;
10884 @end example
10885
10886 Instead, having added the local to the function, we have to separately add
10887 an assignment of @cite{0} to @cite{local_i} at the beginning of the function.
10888
10889 @node Control flow<2>,Visualizing the control flow graph<2>,Expressions lvalues and rvalues<2>,Tutorial part 3 Loops and variables<2>
10890 @anchor{cp/intro/tutorial03 control-flow}@anchor{18a}
10891 @subsubsection Control flow
10892
10893
10894 This function has a loop, so we need to build some basic blocks to
10895 handle the control flow. In this case, we need 4 blocks:
10896
10897
10898 @enumerate
10899
10900 @item
10901 before the loop (initializing the locals)
10902
10903 @item
10904 the conditional at the top of the loop (comparing @cite{i < n})
10905
10906 @item
10907 the body of the loop
10908
10909 @item
10910 after the loop terminates (@cite{return sum})
10911 @end enumerate
10912
10913 so we create these as @ref{18b,,gccjit;;block} instances within the
10914 @ref{18c,,gccjit;;function}:
10915
10916 @example
10917 gccjit::block b_initial = func.new_block ("initial");
10918 gccjit::block b_loop_cond = func.new_block ("loop_cond");
10919 gccjit::block b_loop_body = func.new_block ("loop_body");
10920 gccjit::block b_after_loop = func.new_block ("after_loop");
10921 @end example
10922
10923 We now populate each block with statements.
10924
10925 The entry block @cite{b_initial} consists of initializations followed by a jump
10926 to the conditional. We assign @cite{0} to @cite{i} and to @cite{sum}, using
10927 @ref{18d,,gccjit;;block;;add_assignment()} to add
10928 an assignment statement, and using @ref{18e,,gccjit;;context;;zero()} to get
10929 the constant value @cite{0} for the relevant type for the right-hand side of
10930 the assignment:
10931
10932 @example
10933 /* sum = 0; */
10934 b_initial.add_assignment (sum, ctxt.zero (the_type));
10935
10936 /* i = 0; */
10937 b_initial.add_assignment (i, ctxt.zero (the_type));
10938 @end example
10939
10940 We can then terminate the entry block by jumping to the conditional:
10941
10942 @example
10943 b_initial.end_with_jump (b_loop_cond);
10944 @end example
10945
10946 The conditional block is equivalent to the line @cite{while (i < n)} from our
10947 C example. It contains a single statement: a conditional, which jumps to
10948 one of two destination blocks depending on a boolean
10949 @ref{17e,,gccjit;;rvalue}, in this case the comparison of @cite{i} and @cite{n}.
10950
10951 We could build the comparison using @ref{18f,,gccjit;;context;;new_comparison()}:
10952
10953 @example
10954 gccjit::rvalue guard =
10955 ctxt.new_comparison (GCC_JIT_COMPARISON_GE,
10956 i, n);
10957 @end example
10958
10959 and can then use this to add @cite{b_loop_cond}’s sole statement, via
10960 @ref{190,,gccjit;;block;;end_with_conditional()}:
10961
10962 @example
10963 b_loop_cond.end_with_conditional (guard,
10964 b_after_loop, // on_true
10965 b_loop_body); // on_false
10966 @end example
10967
10968 However @ref{17e,,gccjit;;rvalue} has overloaded operators for this, so we
10969 express the conditional as
10970
10971 @example
10972 gccjit::rvalue guard = (i >= n);
10973 @end example
10974
10975 and hence we can write the block more concisely as:
10976
10977 @example
10978 b_loop_cond.end_with_conditional (
10979 i >= n,
10980 b_after_loop, // on_true
10981 b_loop_body); // on_false
10982 @end example
10983
10984 Next, we populate the body of the loop.
10985
10986 The C statement @cite{sum += i * i;} is an assignment operation, where an
10987 lvalue is modified “in-place”. We use
10988 @ref{191,,gccjit;;block;;add_assignment_op()} to handle these operations:
10989
10990 @example
10991 /* sum += i * i */
10992 b_loop_body.add_assignment_op (sum,
10993 GCC_JIT_BINARY_OP_PLUS,
10994 i * i);
10995 @end example
10996
10997 The @cite{i++} can be thought of as @cite{i += 1}, and can thus be handled in
10998 a similar way. We use @ref{2f,,gcc_jit_context_one()} to get the constant
10999 value @cite{1} (for the relevant type) for the right-hand side
11000 of the assignment.
11001
11002 @example
11003 /* i++ */
11004 b_loop_body.add_assignment_op (i,
11005 GCC_JIT_BINARY_OP_PLUS,
11006 ctxt.one (the_type));
11007 @end example
11008
11009 @cartouche
11010 @quotation Note
11011 For numeric constants other than 0 or 1, we could use
11012 @ref{192,,gccjit;;context;;new_rvalue()}, which has overloads
11013 for both @code{int} and @code{double}.
11014 @end quotation
11015 @end cartouche
11016
11017 The loop body completes by jumping back to the conditional:
11018
11019 @example
11020 b_loop_body.end_with_jump (b_loop_cond);
11021 @end example
11022
11023 Finally, we populate the @cite{b_after_loop} block, reached when the loop
11024 conditional is false. We want to generate the equivalent of:
11025
11026 @example
11027 return sum;
11028 @end example
11029
11030 so the block is just one statement:
11031
11032 @example
11033 /* return sum */
11034 b_after_loop.end_with_return (sum);
11035 @end example
11036
11037 @cartouche
11038 @quotation Note
11039 You can intermingle block creation with statement creation,
11040 but given that the terminator statements generally include references
11041 to other blocks, I find it’s clearer to create all the blocks,
11042 @emph{then} all the statements.
11043 @end quotation
11044 @end cartouche
11045
11046 We’ve finished populating the function. As before, we can now compile it
11047 to machine code:
11048
11049 @example
11050 gcc_jit_result *result;
11051 result = ctxt.compile ();
11052
11053 ctxt.release ();
11054
11055 if (!result)
11056 @{
11057 fprintf (stderr, "NULL result");
11058 return 1;
11059 @}
11060
11061 typedef int (*loop_test_fn_type) (int);
11062 loop_test_fn_type loop_test =
11063 (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
11064 if (!loop_test)
11065 @{
11066 fprintf (stderr, "NULL loop_test");
11067 gcc_jit_result_release (result);
11068 return 1;
11069 @}
11070 printf ("result: %d", loop_test (10));
11071 @end example
11072
11073 @example
11074 result: 285
11075 @end example
11076
11077 @node Visualizing the control flow graph<2>,Full example<4>,Control flow<2>,Tutorial part 3 Loops and variables<2>
11078 @anchor{cp/intro/tutorial03 visualizing-the-control-flow-graph}@anchor{193}
11079 @subsubsection Visualizing the control flow graph
11080
11081
11082 You can see the control flow graph of a function using
11083 @ref{194,,gccjit;;function;;dump_to_dot()}:
11084
11085 @example
11086 func.dump_to_dot ("/tmp/sum-of-squares.dot");
11087 @end example
11088
11089 giving a .dot file in GraphViz format.
11090
11091 You can convert this to an image using @cite{dot}:
11092
11093 @example
11094 $ dot -Tpng /tmp/sum-of-squares.dot -o /tmp/sum-of-squares.png
11095 @end example
11096
11097 or use a viewer (my preferred one is xdot.py; see
11098 @indicateurl{https://github.com/jrfonseca/xdot.py}; on Fedora you can
11099 install it with @cite{yum install python-xdot}):
11100
11101 @quotation
11102
11103
11104 @float Figure
11105
11106 @image{libgccjit-figures/sum-of-squares,,,image of a control flow graph,png}
11107
11108 @end float
11109
11110 @end quotation
11111
11112 @node Full example<4>,,Visualizing the control flow graph<2>,Tutorial part 3 Loops and variables<2>
11113 @anchor{cp/intro/tutorial03 full-example}@anchor{195}
11114 @subsubsection Full example
11115
11116
11117 @quotation
11118
11119 @example
11120 /* Usage example for libgccjit.so's C++ API
11121 Copyright (C) 2014-2022 Free Software Foundation, Inc.
11122
11123 This file is part of GCC.
11124
11125 GCC is free software; you can redistribute it and/or modify it
11126 under the terms of the GNU General Public License as published by
11127 the Free Software Foundation; either version 3, or (at your option)
11128 any later version.
11129
11130 GCC is distributed in the hope that it will be useful, but
11131 WITHOUT ANY WARRANTY; without even the implied warranty of
11132 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11133 General Public License for more details.
11134
11135 You should have received a copy of the GNU General Public License
11136 along with GCC; see the file COPYING3. If not see
11137 <http://www.gnu.org/licenses/>. */
11138
11139 #include <libgccjit++.h>
11140
11141 #include <stdlib.h>
11142 #include <stdio.h>
11143
11144 void
11145 create_code (gccjit::context ctxt)
11146 @{
11147 /*
11148 Simple sum-of-squares, to test conditionals and looping
11149
11150 int loop_test (int n)
11151 @{
11152 int i;
11153 int sum = 0;
11154 for (i = 0; i < n ; i ++)
11155 @{
11156 sum += i * i;
11157 @}
11158 return sum;
11159 */
11160 gccjit::type the_type = ctxt.get_int_type <int> ();
11161 gccjit::type return_type = the_type;
11162
11163 gccjit::param n = ctxt.new_param (the_type, "n");
11164 std::vector<gccjit::param> params;
11165 params.push_back (n);
11166 gccjit::function func =
11167 ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
11168 return_type,
11169 "loop_test",
11170 params, 0);
11171
11172 /* Build locals: */
11173 gccjit::lvalue i = func.new_local (the_type, "i");
11174 gccjit::lvalue sum = func.new_local (the_type, "sum");
11175
11176 gccjit::block b_initial = func.new_block ("initial");
11177 gccjit::block b_loop_cond = func.new_block ("loop_cond");
11178 gccjit::block b_loop_body = func.new_block ("loop_body");
11179 gccjit::block b_after_loop = func.new_block ("after_loop");
11180
11181 /* sum = 0; */
11182 b_initial.add_assignment (sum, ctxt.zero (the_type));
11183
11184 /* i = 0; */
11185 b_initial.add_assignment (i, ctxt.zero (the_type));
11186
11187 b_initial.end_with_jump (b_loop_cond);
11188
11189 /* if (i >= n) */
11190 b_loop_cond.end_with_conditional (
11191 i >= n,
11192 b_after_loop,
11193 b_loop_body);
11194
11195 /* sum += i * i */
11196 b_loop_body.add_assignment_op (sum,
11197 GCC_JIT_BINARY_OP_PLUS,
11198 i * i);
11199
11200 /* i++ */
11201 b_loop_body.add_assignment_op (i,
11202 GCC_JIT_BINARY_OP_PLUS,
11203 ctxt.one (the_type));
11204
11205 b_loop_body.end_with_jump (b_loop_cond);
11206
11207 /* return sum */
11208 b_after_loop.end_with_return (sum);
11209 @}
11210
11211 int
11212 main (int argc, char **argv)
11213 @{
11214 gccjit::context ctxt;
11215 gcc_jit_result *result = NULL;
11216
11217 /* Get a "context" object for working with the library. */
11218 ctxt = gccjit::context::acquire ();
11219
11220 /* Set some options on the context.
11221 Turn this on to see the code being generated, in assembler form. */
11222 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
11223 0);
11224
11225 /* Populate the context. */
11226 create_code (ctxt);
11227
11228 /* Compile the code. */
11229 result = ctxt.compile ();
11230
11231 ctxt.release ();
11232
11233 if (!result)
11234 @{
11235 fprintf (stderr, "NULL result");
11236 return 1;
11237 @}
11238
11239 /* Extract the generated code from "result". */
11240 typedef int (*loop_test_fn_type) (int);
11241 loop_test_fn_type loop_test =
11242 (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
11243 if (!loop_test)
11244 @{
11245 fprintf (stderr, "NULL loop_test");
11246 gcc_jit_result_release (result);
11247 return 1;
11248 @}
11249
11250 /* Run the generated code. */
11251 int val = loop_test (10);
11252 printf("loop_test returned: %d\n", val);
11253
11254 gcc_jit_result_release (result);
11255 return 0;
11256 @}
11257 @end example
11258 @end quotation
11259
11260 Building and running it:
11261
11262 @example
11263 $ gcc \
11264 tut03-sum-of-squares.cc \
11265 -o tut03-sum-of-squares \
11266 -lgccjit
11267
11268 # Run the built program:
11269 $ ./tut03-sum-of-squares
11270 loop_test returned: 285
11271 @end example
11272
11273 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
11274 @c Originally contributed by David Malcolm <[email protected]>
11275 @c
11276 @c This is free software: you can redistribute it and/or modify it
11277 @c under the terms of the GNU General Public License as published by
11278 @c the Free Software Foundation, either version 3 of the License, or
11279 @c (at your option) any later version.
11280 @c
11281 @c This program is distributed in the hope that it will be useful, but
11282 @c WITHOUT ANY WARRANTY; without even the implied warranty of
11283 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11284 @c General Public License for more details.
11285 @c
11286 @c You should have received a copy of the GNU General Public License
11287 @c along with this program. If not, see
11288 @c <https://www.gnu.org/licenses/>.
11289
11290 @node Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>,,Tutorial part 3 Loops and variables<2>,Tutorial<2>
11291 @anchor{cp/intro/tutorial04 doc}@anchor{196}@anchor{cp/intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{197}
11292 @subsection Tutorial part 4: Adding JIT-compilation to a toy interpreter
11293
11294
11295 In this example we construct a “toy” interpreter, and add JIT-compilation
11296 to it.
11297
11298 @menu
11299 * Our toy interpreter: Our toy interpreter<2>.
11300 * Compiling to machine code: Compiling to machine code<2>.
11301 * Setting things up: Setting things up<2>.
11302 * Populating the function: Populating the function<2>.
11303 * Verifying the control flow graph: Verifying the control flow graph<2>.
11304 * Compiling the context: Compiling the context<2>.
11305 * Single-stepping through the generated code: Single-stepping through the generated code<2>.
11306 * Examining the generated code: Examining the generated code<2>.
11307 * Putting it all together: Putting it all together<2>.
11308 * Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?<2>.
11309
11310 @end menu
11311
11312 @node Our toy interpreter<2>,Compiling to machine code<2>,,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
11313 @anchor{cp/intro/tutorial04 our-toy-interpreter}@anchor{198}
11314 @subsubsection Our toy interpreter
11315
11316
11317 It’s a stack-based interpreter, and is intended as a (very simple) example
11318 of the kind of bytecode interpreter seen in dynamic languages such as
11319 Python, Ruby etc.
11320
11321 For the sake of simplicity, our toy virtual machine is very limited:
11322
11323 @quotation
11324
11325
11326 @itemize *
11327
11328 @item
11329 The only data type is @cite{int}
11330
11331 @item
11332 It can only work on one function at a time (so that the only
11333 function call that can be made is to recurse).
11334
11335 @item
11336 Functions can only take one parameter.
11337
11338 @item
11339 Functions have a stack of @cite{int} values.
11340
11341 @item
11342 We’ll implement function call within the interpreter by calling a
11343 function in our implementation, rather than implementing our own
11344 frame stack.
11345
11346 @item
11347 The parser is only good enough to get the examples to work.
11348 @end itemize
11349 @end quotation
11350
11351 Naturally, a real interpreter would be much more complicated that this.
11352
11353 The following operations are supported:
11354
11355
11356 @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx}
11357 @headitem
11358
11359 Operation
11360
11361 @tab
11362
11363 Meaning
11364
11365 @tab
11366
11367 Old Stack
11368
11369 @tab
11370
11371 New Stack
11372
11373 @item
11374
11375 DUP
11376
11377 @tab
11378
11379 Duplicate top of stack.
11380
11381 @tab
11382
11383 @code{[..., x]}
11384
11385 @tab
11386
11387 @code{[..., x, x]}
11388
11389 @item
11390
11391 ROT
11392
11393 @tab
11394
11395 Swap top two elements
11396 of stack.
11397
11398 @tab
11399
11400 @code{[..., x, y]}
11401
11402 @tab
11403
11404 @code{[..., y, x]}
11405
11406 @item
11407
11408 BINARY_ADD
11409
11410 @tab
11411
11412 Add the top two elements
11413 on the stack.
11414
11415 @tab
11416
11417 @code{[..., x, y]}
11418
11419 @tab
11420
11421 @code{[..., (x+y)]}
11422
11423 @item
11424
11425 BINARY_SUBTRACT
11426
11427 @tab
11428
11429 Likewise, but subtract.
11430
11431 @tab
11432
11433 @code{[..., x, y]}
11434
11435 @tab
11436
11437 @code{[..., (x-y)]}
11438
11439 @item
11440
11441 BINARY_MULT
11442
11443 @tab
11444
11445 Likewise, but multiply.
11446
11447 @tab
11448
11449 @code{[..., x, y]}
11450
11451 @tab
11452
11453 @code{[..., (x*y)]}
11454
11455 @item
11456
11457 BINARY_COMPARE_LT
11458
11459 @tab
11460
11461 Compare the top two
11462 elements on the stack
11463 and push a nonzero/zero
11464 if (x<y).
11465
11466 @tab
11467
11468 @code{[..., x, y]}
11469
11470 @tab
11471
11472 @code{[..., (x<y)]}
11473
11474 @item
11475
11476 RECURSE
11477
11478 @tab
11479
11480 Recurse, passing the top
11481 of the stack, and
11482 popping the result.
11483
11484 @tab
11485
11486 @code{[..., x]}
11487
11488 @tab
11489
11490 @code{[..., fn(x)]}
11491
11492 @item
11493
11494 RETURN
11495
11496 @tab
11497
11498 Return the top of the
11499 stack.
11500
11501 @tab
11502
11503 @code{[x]}
11504
11505 @tab
11506
11507 @code{[]}
11508
11509 @item
11510
11511 PUSH_CONST @cite{arg}
11512
11513 @tab
11514
11515 Push an int const.
11516
11517 @tab
11518
11519 @code{[...]}
11520
11521 @tab
11522
11523 @code{[..., arg]}
11524
11525 @item
11526
11527 JUMP_ABS_IF_TRUE @cite{arg}
11528
11529 @tab
11530
11531 Pop; if top of stack was
11532 nonzero, jump to
11533 @code{arg}.
11534
11535 @tab
11536
11537 @code{[..., x]}
11538
11539 @tab
11540
11541 @code{[...]}
11542
11543 @end multitable
11544
11545
11546 Programs can be interpreted, disassembled, and compiled to machine code.
11547
11548 The interpreter reads @code{.toy} scripts. Here’s what a simple recursive
11549 factorial program looks like, the script @code{factorial.toy}.
11550 The parser ignores lines beginning with a @cite{#}.
11551
11552 @quotation
11553
11554 @example
11555 # Simple recursive factorial implementation, roughly equivalent to:
11556 #
11557 # int factorial (int arg)
11558 # @{
11559 # if (arg < 2)
11560 # return arg
11561 # return arg * factorial (arg - 1)
11562 # @}
11563
11564 # Initial state:
11565 # stack: [arg]
11566
11567 # 0:
11568 DUP
11569 # stack: [arg, arg]
11570
11571 # 1:
11572 PUSH_CONST 2
11573 # stack: [arg, arg, 2]
11574
11575 # 2:
11576 BINARY_COMPARE_LT
11577 # stack: [arg, (arg < 2)]
11578
11579 # 3:
11580 JUMP_ABS_IF_TRUE 9
11581 # stack: [arg]
11582
11583 # 4:
11584 DUP
11585 # stack: [arg, arg]
11586
11587 # 5:
11588 PUSH_CONST 1
11589 # stack: [arg, arg, 1]
11590
11591 # 6:
11592 BINARY_SUBTRACT
11593 # stack: [arg, (arg - 1)
11594
11595 # 7:
11596 RECURSE
11597 # stack: [arg, factorial(arg - 1)]
11598
11599 # 8:
11600 BINARY_MULT
11601 # stack: [arg * factorial(arg - 1)]
11602
11603 # 9:
11604 RETURN
11605 @end example
11606 @end quotation
11607
11608 The interpreter is a simple infinite loop with a big @code{switch} statement
11609 based on what the next opcode is:
11610
11611 @quotation
11612
11613 @example
11614
11615 int
11616 toyvm_function::interpret (int arg, FILE *trace)
11617 @{
11618 toyvm_frame frame;
11619 #define PUSH(ARG) (frame.push (ARG))
11620 #define POP(ARG) (frame.pop ())
11621
11622 frame.frm_function = this;
11623 frame.frm_pc = 0;
11624 frame.frm_cur_depth = 0;
11625
11626 PUSH (arg);
11627
11628 while (1)
11629 @{
11630 toyvm_op *op;
11631 int x, y;
11632 assert (frame.frm_pc < fn_num_ops);
11633 op = &fn_ops[frame.frm_pc++];
11634
11635 if (trace)
11636 @{
11637 frame.dump_stack (trace);
11638 disassemble_op (op, frame.frm_pc, trace);
11639 @}
11640
11641 switch (op->op_opcode)
11642 @{
11643 /* Ops taking no operand. */
11644 case DUP:
11645 x = POP ();
11646 PUSH (x);
11647 PUSH (x);
11648 break;
11649
11650 case ROT:
11651 y = POP ();
11652 x = POP ();
11653 PUSH (y);
11654 PUSH (x);
11655 break;
11656
11657 case BINARY_ADD:
11658 y = POP ();
11659 x = POP ();
11660 PUSH (x + y);
11661 break;
11662
11663 case BINARY_SUBTRACT:
11664 y = POP ();
11665 x = POP ();
11666 PUSH (x - y);
11667 break;
11668
11669 case BINARY_MULT:
11670 y = POP ();
11671 x = POP ();
11672 PUSH (x * y);
11673 break;
11674
11675 case BINARY_COMPARE_LT:
11676 y = POP ();
11677 x = POP ();
11678 PUSH (x < y);
11679 break;
11680
11681 case RECURSE:
11682 x = POP ();
11683 x = interpret (x, trace);
11684 PUSH (x);
11685 break;
11686
11687 case RETURN:
11688 return POP ();
11689
11690 /* Ops taking an operand. */
11691 case PUSH_CONST:
11692 PUSH (op->op_operand);
11693 break;
11694
11695 case JUMP_ABS_IF_TRUE:
11696 x = POP ();
11697 if (x)
11698 frame.frm_pc = op->op_operand;
11699 break;
11700
11701 default:
11702 assert (0); /* unknown opcode */
11703
11704 @} /* end of switch on opcode */
11705 @} /* end of while loop */
11706
11707 #undef PUSH
11708 #undef POP
11709 @}
11710
11711 @end example
11712 @end quotation
11713
11714 @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>
11715 @anchor{cp/intro/tutorial04 compiling-to-machine-code}@anchor{199}
11716 @subsubsection Compiling to machine code
11717
11718
11719 We want to generate machine code that can be cast to this type and
11720 then directly executed in-process:
11721
11722 @quotation
11723
11724 @example
11725 typedef int (*toyvm_compiled_func) (int);
11726
11727 @end example
11728 @end quotation
11729
11730 Our compiler isn’t very sophisticated; it takes the implementation of
11731 each opcode above, and maps it directly to the operations supported by
11732 the libgccjit API.
11733
11734 How should we handle the stack? In theory we could calculate what the
11735 stack depth will be at each opcode, and optimize away the stack
11736 manipulation “by hand”. We’ll see below that libgccjit is able to do
11737 this for us, so we’ll implement stack manipulation
11738 in a direct way, by creating a @code{stack} array and @code{stack_depth}
11739 variables, local within the generated function, equivalent to this C code:
11740
11741 @example
11742 int stack_depth;
11743 int stack[MAX_STACK_DEPTH];
11744 @end example
11745
11746 We’ll also have local variables @code{x} and @code{y} for use when implementing
11747 the opcodes, equivalent to this:
11748
11749 @example
11750 int x;
11751 int y;
11752 @end example
11753
11754 This means our compiler has the following state:
11755
11756 @quotation
11757
11758 @example
11759
11760 toyvm_function &toyvmfn;
11761
11762 gccjit::context ctxt;
11763
11764 gccjit::type int_type;
11765 gccjit::type bool_type;
11766 gccjit::type stack_type; /* int[MAX_STACK_DEPTH] */
11767
11768 gccjit::rvalue const_one;
11769
11770 gccjit::function fn;
11771 gccjit::param param_arg;
11772 gccjit::lvalue stack;
11773 gccjit::lvalue stack_depth;
11774 gccjit::lvalue x;
11775 gccjit::lvalue y;
11776
11777 gccjit::location op_locs[MAX_OPS];
11778 gccjit::block initial_block;
11779 gccjit::block op_blocks[MAX_OPS];
11780
11781 @end example
11782 @end quotation
11783
11784 @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>
11785 @anchor{cp/intro/tutorial04 setting-things-up}@anchor{19a}
11786 @subsubsection Setting things up
11787
11788
11789 First we create our types:
11790
11791 @quotation
11792
11793 @example
11794
11795 void
11796 compilation_state::create_types ()
11797 @{
11798 /* Create types. */
11799 int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
11800 bool_type = ctxt.get_type (GCC_JIT_TYPE_BOOL);
11801 stack_type = ctxt.new_array_type (int_type, MAX_STACK_DEPTH);
11802
11803 @end example
11804 @end quotation
11805
11806 along with extracting a useful @cite{int} constant:
11807
11808 @quotation
11809
11810 @example
11811 const_one = ctxt.one (int_type);
11812
11813 @}
11814
11815 @end example
11816 @end quotation
11817
11818 We’ll implement push and pop in terms of the @code{stack} array and
11819 @code{stack_depth}. Here are helper functions for adding statements to
11820 a block, implementing pushing and popping values:
11821
11822 @quotation
11823
11824 @example
11825
11826 void
11827 compilation_state::add_push (gccjit::block block,
11828 gccjit::rvalue rvalue,
11829 gccjit::location loc)
11830 @{
11831 /* stack[stack_depth] = RVALUE */
11832 block.add_assignment (
11833 /* stack[stack_depth] */
11834 ctxt.new_array_access (
11835 stack,
11836 stack_depth,
11837 loc),
11838 rvalue,
11839 loc);
11840
11841 /* "stack_depth++;". */
11842 block.add_assignment_op (
11843 stack_depth,
11844 GCC_JIT_BINARY_OP_PLUS,
11845 const_one,
11846 loc);
11847 @}
11848
11849 void
11850 compilation_state::add_pop (gccjit::block block,
11851 gccjit::lvalue lvalue,
11852 gccjit::location loc)
11853 @{
11854 /* "--stack_depth;". */
11855 block.add_assignment_op (
11856 stack_depth,
11857 GCC_JIT_BINARY_OP_MINUS,
11858 const_one,
11859 loc);
11860
11861 /* "LVALUE = stack[stack_depth];". */
11862 block.add_assignment (
11863 lvalue,
11864 /* stack[stack_depth] */
11865 ctxt.new_array_access (stack,
11866 stack_depth,
11867 loc),
11868 loc);
11869 @}
11870
11871 @end example
11872 @end quotation
11873
11874 We will support single-stepping through the generated code in the
11875 debugger, so we need to create @ref{19b,,gccjit;;location} instances, one
11876 per operation in the source code. These will reference the lines of
11877 e.g. @code{factorial.toy}.
11878
11879 @quotation
11880
11881 @example
11882
11883 void
11884 compilation_state::create_locations ()
11885 @{
11886 for (int pc = 0; pc < toyvmfn.fn_num_ops; pc++)
11887 @{
11888 toyvm_op *op = &toyvmfn.fn_ops[pc];
11889
11890 op_locs[pc] = ctxt.new_location (toyvmfn.fn_filename,
11891 op->op_linenum,
11892 0); /* column */
11893 @}
11894 @}
11895
11896 @end example
11897 @end quotation
11898
11899 Let’s create the function itself. As usual, we create its parameter
11900 first, then use the parameter to create the function:
11901
11902 @quotation
11903
11904 @example
11905
11906 void
11907 compilation_state::create_function (const char *funcname)
11908 @{
11909 std::vector <gccjit::param> params;
11910 param_arg = ctxt.new_param (int_type, "arg", op_locs[0]);
11911 params.push_back (param_arg);
11912 fn = ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
11913 int_type,
11914 funcname,
11915 params, 0,
11916 op_locs[0]);
11917
11918 @end example
11919 @end quotation
11920
11921 We create the locals within the function.
11922
11923 @quotation
11924
11925 @example
11926 stack = fn.new_local (stack_type, "stack");
11927 stack_depth = fn.new_local (int_type, "stack_depth");
11928 x = fn.new_local (int_type, "x");
11929 y = fn.new_local (int_type, "y");
11930
11931 @end example
11932 @end quotation
11933
11934 @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>
11935 @anchor{cp/intro/tutorial04 populating-the-function}@anchor{19c}
11936 @subsubsection Populating the function
11937
11938
11939 There’s some one-time initialization, and the API treats the first block
11940 you create as the entrypoint of the function, so we need to create that
11941 block first:
11942
11943 @quotation
11944
11945 @example
11946 initial_block = fn.new_block ("initial");
11947
11948 @end example
11949 @end quotation
11950
11951 We can now create blocks for each of the operations. Most of these will
11952 be consolidated into larger blocks when the optimizer runs.
11953
11954 @quotation
11955
11956 @example
11957 for (int pc = 0; pc < toyvmfn.fn_num_ops; pc++)
11958 @{
11959 char buf[100];
11960 sprintf (buf, "instr%i", pc);
11961 op_blocks[pc] = fn.new_block (buf);
11962 @}
11963
11964 @end example
11965 @end quotation
11966
11967 Now that we have a block it can jump to when it’s done, we can populate
11968 the initial block:
11969
11970 @quotation
11971
11972 @example
11973
11974 /* "stack_depth = 0;". */
11975 initial_block.add_assignment (stack_depth,
11976 ctxt.zero (int_type),
11977 op_locs[0]);
11978
11979 /* "PUSH (arg);". */
11980 add_push (initial_block,
11981 param_arg,
11982 op_locs[0]);
11983
11984 /* ...and jump to insn 0. */
11985 initial_block.end_with_jump (op_blocks[0],
11986 op_locs[0]);
11987
11988 @end example
11989 @end quotation
11990
11991 We can now populate the blocks for the individual operations. We loop
11992 through them, adding instructions to their blocks:
11993
11994 @quotation
11995
11996 @example
11997 for (int pc = 0; pc < toyvmfn.fn_num_ops; pc++)
11998 @{
11999 gccjit::location loc = op_locs[pc];
12000
12001 gccjit::block block = op_blocks[pc];
12002 gccjit::block next_block = (pc < toyvmfn.fn_num_ops
12003 ? op_blocks[pc + 1]
12004 : NULL);
12005
12006 toyvm_op *op;
12007 op = &toyvmfn.fn_ops[pc];
12008
12009 @end example
12010 @end quotation
12011
12012 We’re going to have another big @code{switch} statement for implementing
12013 the opcodes, this time for compiling them, rather than interpreting
12014 them. It’s helpful to have macros for implementing push and pop, so that
12015 we can make the @code{switch} statement that’s coming up look as much as
12016 possible like the one above within the interpreter:
12017
12018 @example
12019
12020 #define X_EQUALS_POP()\
12021 add_pop (block, x, loc)
12022 #define Y_EQUALS_POP()\
12023 add_pop (block, y, loc)
12024 #define PUSH_RVALUE(RVALUE)\
12025 add_push (block, (RVALUE), loc)
12026 #define PUSH_X()\
12027 PUSH_RVALUE (x)
12028 #define PUSH_Y() \
12029 PUSH_RVALUE (y)
12030
12031 @end example
12032
12033 @cartouche
12034 @quotation Note
12035 A particularly clever implementation would have an @emph{identical}
12036 @code{switch} statement shared by the interpreter and the compiler, with
12037 some preprocessor “magic”. We’re not doing that here, for the sake
12038 of simplicity.
12039 @end quotation
12040 @end cartouche
12041
12042 When I first implemented this compiler, I accidentally missed an edit
12043 when copying and pasting the @code{Y_EQUALS_POP} macro, so that popping the
12044 stack into @code{y} instead erroneously assigned it to @code{x}, leaving @code{y}
12045 uninitialized.
12046
12047 To track this kind of thing down, we can use
12048 @ref{19d,,gccjit;;block;;add_comment()} to add descriptive comments
12049 to the internal representation. This is invaluable when looking through
12050 the generated IR for, say @code{factorial}:
12051
12052 @quotation
12053
12054 @example
12055
12056 block.add_comment (opcode_names[op->op_opcode], loc);
12057
12058 @end example
12059 @end quotation
12060
12061 We can now write the big @code{switch} statement that implements the
12062 individual opcodes, populating the relevant block with statements:
12063
12064 @quotation
12065
12066 @example
12067
12068 switch (op->op_opcode)
12069 @{
12070 case DUP:
12071 X_EQUALS_POP ();
12072 PUSH_X ();
12073 PUSH_X ();
12074 break;
12075
12076 case ROT:
12077 Y_EQUALS_POP ();
12078 X_EQUALS_POP ();
12079 PUSH_Y ();
12080 PUSH_X ();
12081 break;
12082
12083 case BINARY_ADD:
12084 Y_EQUALS_POP ();
12085 X_EQUALS_POP ();
12086 PUSH_RVALUE (
12087 ctxt.new_binary_op (
12088 GCC_JIT_BINARY_OP_PLUS,
12089 int_type,
12090 x, y,
12091 loc));
12092 break;
12093
12094 case BINARY_SUBTRACT:
12095 Y_EQUALS_POP ();
12096 X_EQUALS_POP ();
12097 PUSH_RVALUE (
12098 ctxt.new_binary_op (
12099 GCC_JIT_BINARY_OP_MINUS,
12100 int_type,
12101 x, y,
12102 loc));
12103 break;
12104
12105 case BINARY_MULT:
12106 Y_EQUALS_POP ();
12107 X_EQUALS_POP ();
12108 PUSH_RVALUE (
12109 ctxt.new_binary_op (
12110 GCC_JIT_BINARY_OP_MULT,
12111 int_type,
12112 x, y,
12113 loc));
12114 break;
12115
12116 case BINARY_COMPARE_LT:
12117 Y_EQUALS_POP ();
12118 X_EQUALS_POP ();
12119 PUSH_RVALUE (
12120 /* cast of bool to int */
12121 ctxt.new_cast (
12122 /* (x < y) as a bool */
12123 ctxt.new_comparison (
12124 GCC_JIT_COMPARISON_LT,
12125 x, y,
12126 loc),
12127 int_type,
12128 loc));
12129 break;
12130
12131 case RECURSE:
12132 @{
12133 X_EQUALS_POP ();
12134 PUSH_RVALUE (
12135 ctxt.new_call (
12136 fn,
12137 x,
12138 loc));
12139 break;
12140 @}
12141
12142 case RETURN:
12143 X_EQUALS_POP ();
12144 block.end_with_return (x, loc);
12145 break;
12146
12147 /* Ops taking an operand. */
12148 case PUSH_CONST:
12149 PUSH_RVALUE (
12150 ctxt.new_rvalue (int_type, op->op_operand));
12151 break;
12152
12153 case JUMP_ABS_IF_TRUE:
12154 X_EQUALS_POP ();
12155 block.end_with_conditional (
12156 /* "(bool)x". */
12157 ctxt.new_cast (x, bool_type, loc),
12158 op_blocks[op->op_operand], /* on_true */
12159 next_block, /* on_false */
12160 loc);
12161 break;
12162
12163 default:
12164 assert(0);
12165 @} /* end of switch on opcode */
12166
12167 @end example
12168 @end quotation
12169
12170 Every block must be terminated, via a call to one of the
12171 @code{gccjit::block::end_with_} entrypoints. This has been done for two
12172 of the opcodes, but we need to do it for the other ones, by jumping
12173 to the next block.
12174
12175 @quotation
12176
12177 @example
12178 if (op->op_opcode != JUMP_ABS_IF_TRUE
12179 && op->op_opcode != RETURN)
12180 block.end_with_jump (next_block, loc);
12181
12182 @end example
12183 @end quotation
12184
12185 This is analogous to simply incrementing the program counter.
12186
12187 @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>
12188 @anchor{cp/intro/tutorial04 verifying-the-control-flow-graph}@anchor{19e}
12189 @subsubsection Verifying the control flow graph
12190
12191
12192 Having finished looping over the blocks, the context is complete.
12193
12194 As before, we can verify that the control flow and statements are sane by
12195 using @ref{194,,gccjit;;function;;dump_to_dot()}:
12196
12197 @example
12198 fn.dump_to_dot ("/tmp/factorial.dot");
12199 @end example
12200
12201 and viewing the result. Note how the label names, comments, and
12202 variable names show up in the dump, to make it easier to spot
12203 errors in our compiler.
12204
12205 @quotation
12206
12207
12208 @float Figure
12209
12210 @image{libgccjit-figures/factorial,,,image of a control flow graph,png}
12211
12212 @end float
12213
12214 @end quotation
12215
12216 @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>
12217 @anchor{cp/intro/tutorial04 compiling-the-context}@anchor{19f}
12218 @subsubsection Compiling the context
12219
12220
12221 Having finished looping over the blocks and populating them with
12222 statements, the context is complete.
12223
12224 We can now compile it, extract machine code from the result, and
12225 run it:
12226
12227 @quotation
12228
12229 @example
12230
12231 class compilation_result
12232 @{
12233 public:
12234 compilation_result (gcc_jit_result *result) :
12235 m_result (result)
12236 @{
12237 @}
12238 ~compilation_result ()
12239 @{
12240 gcc_jit_result_release (m_result);
12241 @}
12242
12243 void *get_code (const char *funcname)
12244 @{
12245 return gcc_jit_result_get_code (m_result, funcname);
12246 @}
12247
12248 private:
12249 gcc_jit_result *m_result;
12250 @};
12251
12252 @end example
12253
12254 @example
12255 compilation_result compiler_result = fn->compile ();
12256
12257 const char *funcname = fn->get_function_name ();
12258 toyvm_compiled_func code
12259 = (toyvm_compiled_func)compiler_result.get_code (funcname);
12260
12261 printf ("compiler result: %d\n",
12262 code (atoi (argv[2])));
12263
12264 @end example
12265 @end quotation
12266
12267 @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>
12268 @anchor{cp/intro/tutorial04 single-stepping-through-the-generated-code}@anchor{1a0}
12269 @subsubsection Single-stepping through the generated code
12270
12271
12272 It’s possible to debug the generated code. To do this we need to both:
12273
12274 @quotation
12275
12276
12277 @itemize *
12278
12279 @item
12280 Set up source code locations for our statements, so that we can
12281 meaningfully step through the code. We did this above by
12282 calling @ref{1a1,,gccjit;;context;;new_location()} and using the
12283 results.
12284
12285 @item
12286 Enable the generation of debugging information, by setting
12287 @ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
12288 @ref{175,,gccjit;;context} via
12289 @ref{181,,gccjit;;context;;set_bool_option()}:
12290
12291 @example
12292 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1);
12293 @end example
12294 @end itemize
12295 @end quotation
12296
12297 Having done this, we can put a breakpoint on the generated function:
12298
12299 @example
12300 $ gdb --args ./toyvm factorial.toy 10
12301 (gdb) break factorial
12302 Function "factorial" not defined.
12303 Make breakpoint pending on future shared library load? (y or [n]) y
12304 Breakpoint 1 (factorial) pending.
12305 (gdb) run
12306 Breakpoint 1, factorial (arg=10) at factorial.toy:14
12307 14 DUP
12308 @end example
12309
12310 We’ve set up location information, which references @code{factorial.toy}.
12311 This allows us to use e.g. @code{list} to see where we are in the script:
12312
12313 @example
12314 (gdb) list
12315 9
12316 10 # Initial state:
12317 11 # stack: [arg]
12318 12
12319 13 # 0:
12320 14 DUP
12321 15 # stack: [arg, arg]
12322 16
12323 17 # 1:
12324 18 PUSH_CONST 2
12325 @end example
12326
12327 and to step through the function, examining the data:
12328
12329 @example
12330 (gdb) n
12331 18 PUSH_CONST 2
12332 (gdb) n
12333 22 BINARY_COMPARE_LT
12334 (gdb) print stack
12335 $5 = @{10, 10, 2, 0, -7152, 32767, 0, 0@}
12336 (gdb) print stack_depth
12337 $6 = 3
12338 @end example
12339
12340 You’ll see that the parts of the @code{stack} array that haven’t been
12341 touched yet are uninitialized.
12342
12343 @cartouche
12344 @quotation Note
12345 Turning on optimizations may lead to unpredictable results when
12346 stepping through the generated code: the execution may appear to
12347 “jump around” the source code. This is analogous to turning up the
12348 optimization level in a regular compiler.
12349 @end quotation
12350 @end cartouche
12351
12352 @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>
12353 @anchor{cp/intro/tutorial04 examining-the-generated-code}@anchor{1a2}
12354 @subsubsection Examining the generated code
12355
12356
12357 How good is the optimized code?
12358
12359 We can turn up optimizations, by calling
12360 @ref{182,,gccjit;;context;;set_int_option()} with
12361 @ref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
12362
12363 @example
12364 ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3);
12365 @end example
12366
12367 One of GCC’s internal representations is called “gimple”. A dump of the
12368 initial gimple representation of the code can be seen by setting:
12369
12370 @example
12371 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1);
12372 @end example
12373
12374 With optimization on and source locations displayed, this gives:
12375
12376 @c We'll use "c" for gimple dumps
12377
12378 @example
12379 factorial (signed int arg)
12380 @{
12381 <unnamed type> D.80;
12382 signed int D.81;
12383 signed int D.82;
12384 signed int D.83;
12385 signed int D.84;
12386 signed int D.85;
12387 signed int y;
12388 signed int x;
12389 signed int stack_depth;
12390 signed int stack[8];
12391
12392 try
12393 @{
12394 initial:
12395 stack_depth = 0;
12396 stack[stack_depth] = arg;
12397 stack_depth = stack_depth + 1;
12398 goto instr0;
12399 instr0:
12400 /* DUP */:
12401 stack_depth = stack_depth + -1;
12402 x = stack[stack_depth];
12403 stack[stack_depth] = x;
12404 stack_depth = stack_depth + 1;
12405 stack[stack_depth] = x;
12406 stack_depth = stack_depth + 1;
12407 goto instr1;
12408 instr1:
12409 /* PUSH_CONST */:
12410 stack[stack_depth] = 2;
12411 stack_depth = stack_depth + 1;
12412 goto instr2;
12413
12414 /* etc */
12415 @end example
12416
12417 You can see the generated machine code in assembly form via:
12418
12419 @example
12420 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 1);
12421 result = ctxt.compile ();
12422 @end example
12423
12424 which shows that (on this x86_64 box) the compiler has unrolled the loop
12425 and is using MMX instructions to perform several multiplications
12426 simultaneously:
12427
12428 @example
12429 .file "fake.c"
12430 .text
12431 .Ltext0:
12432 .p2align 4,,15
12433 .globl factorial
12434 .type factorial, @@function
12435 factorial:
12436 .LFB0:
12437 .file 1 "factorial.toy"
12438 .loc 1 14 0
12439 .cfi_startproc
12440 .LVL0:
12441 .L2:
12442 .loc 1 26 0
12443 cmpl $1, %edi
12444 jle .L13
12445 leal -1(%rdi), %edx
12446 movl %edx, %ecx
12447 shrl $2, %ecx
12448 leal 0(,%rcx,4), %esi
12449 testl %esi, %esi
12450 je .L14
12451 cmpl $9, %edx
12452 jbe .L14
12453 leal -2(%rdi), %eax
12454 movl %eax, -16(%rsp)
12455 leal -3(%rdi), %eax
12456 movd -16(%rsp), %xmm0
12457 movl %edi, -16(%rsp)
12458 movl %eax, -12(%rsp)
12459 movd -16(%rsp), %xmm1
12460 xorl %eax, %eax
12461 movl %edx, -16(%rsp)
12462 movd -12(%rsp), %xmm4
12463 movd -16(%rsp), %xmm6
12464 punpckldq %xmm4, %xmm0
12465 movdqa .LC1(%rip), %xmm4
12466 punpckldq %xmm6, %xmm1
12467 punpcklqdq %xmm0, %xmm1
12468 movdqa .LC0(%rip), %xmm0
12469 jmp .L5
12470 # etc - edited for brevity
12471 @end example
12472
12473 This is clearly overkill for a function that will likely overflow the
12474 @code{int} type before the vectorization is worthwhile - but then again, this
12475 is a toy example.
12476
12477 Turning down the optimization level to 2:
12478
12479 @example
12480 ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 2);
12481 @end example
12482
12483 yields this code, which is simple enough to quote in its entirety:
12484
12485 @example
12486 .file "fake.c"
12487 .text
12488 .p2align 4,,15
12489 .globl factorial
12490 .type factorial, @@function
12491 factorial:
12492 .LFB0:
12493 .cfi_startproc
12494 .L2:
12495 cmpl $1, %edi
12496 jle .L8
12497 movl $1, %edx
12498 jmp .L4
12499 .p2align 4,,10
12500 .p2align 3
12501 .L6:
12502 movl %eax, %edi
12503 .L4:
12504 .L5:
12505 leal -1(%rdi), %eax
12506 imull %edi, %edx
12507 cmpl $1, %eax
12508 jne .L6
12509 .L3:
12510 .L7:
12511 imull %edx, %eax
12512 ret
12513 .L8:
12514 movl %edi, %eax
12515 movl $1, %edx
12516 jmp .L7
12517 .cfi_endproc
12518 .LFE0:
12519 .size factorial, .-factorial
12520 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-%@{gcc_release@})"
12521 .section .note.GNU-stack,"",@@progbits
12522 @end example
12523
12524 Note that the stack pushing and popping have been eliminated, as has the
12525 recursive call (in favor of an iteration).
12526
12527 @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>
12528 @anchor{cp/intro/tutorial04 putting-it-all-together}@anchor{1a3}
12529 @subsubsection Putting it all together
12530
12531
12532 The complete example can be seen in the source tree at
12533 @code{gcc/jit/docs/examples/tut04-toyvm/toyvm.cc}
12534
12535 along with a Makefile and a couple of sample .toy scripts:
12536
12537 @example
12538 $ ls -al
12539 drwxrwxr-x. 2 david david 4096 Sep 19 17:46 .
12540 drwxrwxr-x. 3 david david 4096 Sep 19 15:26 ..
12541 -rw-rw-r--. 1 david david 615 Sep 19 12:43 factorial.toy
12542 -rw-rw-r--. 1 david david 834 Sep 19 13:08 fibonacci.toy
12543 -rw-rw-r--. 1 david david 238 Sep 19 14:22 Makefile
12544 -rw-rw-r--. 1 david david 16457 Sep 19 17:07 toyvm.cc
12545
12546 $ make toyvm
12547 g++ -Wall -g -o toyvm toyvm.cc -lgccjit
12548
12549 $ ./toyvm factorial.toy 10
12550 interpreter result: 3628800
12551 compiler result: 3628800
12552
12553 $ ./toyvm fibonacci.toy 10
12554 interpreter result: 55
12555 compiler result: 55
12556 @end example
12557
12558 @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>
12559 @anchor{cp/intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{1a4}
12560 @subsubsection Behind the curtain: How does our code get optimized?
12561
12562
12563 Our example is done, but you may be wondering about exactly how the
12564 compiler turned what we gave it into the machine code seen above.
12565
12566 We can examine what the compiler is doing in detail by setting:
12567
12568 @example
12569 state.ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING, 1);
12570 state.ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES, 1);
12571 @end example
12572
12573 This will dump detailed information about the compiler’s state to a
12574 directory under @code{/tmp}, and keep it from being cleaned up.
12575
12576 The precise names and their formats of these files is subject to change.
12577 Higher optimization levels lead to more files.
12578 Here’s what I saw (edited for brevity; there were almost 200 files):
12579
12580 @example
12581 intermediate files written to /tmp/libgccjit-KPQbGw
12582 $ ls /tmp/libgccjit-KPQbGw/
12583 fake.c.000i.cgraph
12584 fake.c.000i.type-inheritance
12585 fake.c.004t.gimple
12586 fake.c.007t.omplower
12587 fake.c.008t.lower
12588 fake.c.011t.eh
12589 fake.c.012t.cfg
12590 fake.c.014i.visibility
12591 fake.c.015i.early_local_cleanups
12592 fake.c.016t.ssa
12593 # etc
12594 @end example
12595
12596 The gimple code is converted into Static Single Assignment form,
12597 with annotations for use when generating the debuginfo:
12598
12599 @example
12600 $ less /tmp/libgccjit-KPQbGw/fake.c.016t.ssa
12601 @end example
12602
12603 @example
12604 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
12605
12606 factorial (signed int arg)
12607 @{
12608 signed int stack[8];
12609 signed int stack_depth;
12610 signed int x;
12611 signed int y;
12612 <unnamed type> _20;
12613 signed int _21;
12614 signed int _38;
12615 signed int _44;
12616 signed int _51;
12617 signed int _56;
12618
12619 initial:
12620 stack_depth_3 = 0;
12621 # DEBUG stack_depth => stack_depth_3
12622 stack[stack_depth_3] = arg_5(D);
12623 stack_depth_7 = stack_depth_3 + 1;
12624 # DEBUG stack_depth => stack_depth_7
12625 # DEBUG instr0 => NULL
12626 # DEBUG /* DUP */ => NULL
12627 stack_depth_8 = stack_depth_7 + -1;
12628 # DEBUG stack_depth => stack_depth_8
12629 x_9 = stack[stack_depth_8];
12630 # DEBUG x => x_9
12631 stack[stack_depth_8] = x_9;
12632 stack_depth_11 = stack_depth_8 + 1;
12633 # DEBUG stack_depth => stack_depth_11
12634 stack[stack_depth_11] = x_9;
12635 stack_depth_13 = stack_depth_11 + 1;
12636 # DEBUG stack_depth => stack_depth_13
12637 # DEBUG instr1 => NULL
12638 # DEBUG /* PUSH_CONST */ => NULL
12639 stack[stack_depth_13] = 2;
12640
12641 /* etc; edited for brevity */
12642 @end example
12643
12644 We can perhaps better see the code by turning off
12645 @ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to suppress all those @code{DEBUG}
12646 statements, giving:
12647
12648 @example
12649 $ less /tmp/libgccjit-1Hywc0/fake.c.016t.ssa
12650 @end example
12651
12652 @example
12653 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
12654
12655 factorial (signed int arg)
12656 @{
12657 signed int stack[8];
12658 signed int stack_depth;
12659 signed int x;
12660 signed int y;
12661 <unnamed type> _20;
12662 signed int _21;
12663 signed int _38;
12664 signed int _44;
12665 signed int _51;
12666 signed int _56;
12667
12668 initial:
12669 stack_depth_3 = 0;
12670 stack[stack_depth_3] = arg_5(D);
12671 stack_depth_7 = stack_depth_3 + 1;
12672 stack_depth_8 = stack_depth_7 + -1;
12673 x_9 = stack[stack_depth_8];
12674 stack[stack_depth_8] = x_9;
12675 stack_depth_11 = stack_depth_8 + 1;
12676 stack[stack_depth_11] = x_9;
12677 stack_depth_13 = stack_depth_11 + 1;
12678 stack[stack_depth_13] = 2;
12679 stack_depth_15 = stack_depth_13 + 1;
12680 stack_depth_16 = stack_depth_15 + -1;
12681 y_17 = stack[stack_depth_16];
12682 stack_depth_18 = stack_depth_16 + -1;
12683 x_19 = stack[stack_depth_18];
12684 _20 = x_19 < y_17;
12685 _21 = (signed int) _20;
12686 stack[stack_depth_18] = _21;
12687 stack_depth_23 = stack_depth_18 + 1;
12688 stack_depth_24 = stack_depth_23 + -1;
12689 x_25 = stack[stack_depth_24];
12690 if (x_25 != 0)
12691 goto <bb 4> (instr9);
12692 else
12693 goto <bb 3> (instr4);
12694
12695 instr4:
12696 /* DUP */:
12697 stack_depth_26 = stack_depth_24 + -1;
12698 x_27 = stack[stack_depth_26];
12699 stack[stack_depth_26] = x_27;
12700 stack_depth_29 = stack_depth_26 + 1;
12701 stack[stack_depth_29] = x_27;
12702 stack_depth_31 = stack_depth_29 + 1;
12703 stack[stack_depth_31] = 1;
12704 stack_depth_33 = stack_depth_31 + 1;
12705 stack_depth_34 = stack_depth_33 + -1;
12706 y_35 = stack[stack_depth_34];
12707 stack_depth_36 = stack_depth_34 + -1;
12708 x_37 = stack[stack_depth_36];
12709 _38 = x_37 - y_35;
12710 stack[stack_depth_36] = _38;
12711 stack_depth_40 = stack_depth_36 + 1;
12712 stack_depth_41 = stack_depth_40 + -1;
12713 x_42 = stack[stack_depth_41];
12714 _44 = factorial (x_42);
12715 stack[stack_depth_41] = _44;
12716 stack_depth_46 = stack_depth_41 + 1;
12717 stack_depth_47 = stack_depth_46 + -1;
12718 y_48 = stack[stack_depth_47];
12719 stack_depth_49 = stack_depth_47 + -1;
12720 x_50 = stack[stack_depth_49];
12721 _51 = x_50 * y_48;
12722 stack[stack_depth_49] = _51;
12723 stack_depth_53 = stack_depth_49 + 1;
12724
12725 # stack_depth_1 = PHI <stack_depth_24(2), stack_depth_53(3)>
12726 instr9:
12727 /* RETURN */:
12728 stack_depth_54 = stack_depth_1 + -1;
12729 x_55 = stack[stack_depth_54];
12730 _56 = x_55;
12731 stack =@{v@} @{CLOBBER@};
12732 return _56;
12733
12734 @}
12735 @end example
12736
12737 Note in the above how all the @ref{18b,,gccjit;;block} instances we
12738 created have been consolidated into just 3 blocks in GCC’s internal
12739 representation: @code{initial}, @code{instr4} and @code{instr9}.
12740
12741 @menu
12742 * Optimizing away stack manipulation: Optimizing away stack manipulation<2>.
12743 * Elimination of tail recursion: Elimination of tail recursion<2>.
12744
12745 @end menu
12746
12747 @node Optimizing away stack manipulation<2>,Elimination of tail recursion<2>,,Behind the curtain How does our code get optimized?<2>
12748 @anchor{cp/intro/tutorial04 optimizing-away-stack-manipulation}@anchor{1a5}
12749 @subsubsection Optimizing away stack manipulation
12750
12751
12752 Recall our simple implementation of stack operations. Let’s examine
12753 how the stack operations are optimized away.
12754
12755 After a pass of constant-propagation, the depth of the stack at each
12756 opcode can be determined at compile-time:
12757
12758 @example
12759 $ less /tmp/libgccjit-1Hywc0/fake.c.021t.ccp1
12760 @end example
12761
12762 @example
12763 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
12764
12765 factorial (signed int arg)
12766 @{
12767 signed int stack[8];
12768 signed int stack_depth;
12769 signed int x;
12770 signed int y;
12771 <unnamed type> _20;
12772 signed int _21;
12773 signed int _38;
12774 signed int _44;
12775 signed int _51;
12776
12777 initial:
12778 stack[0] = arg_5(D);
12779 x_9 = stack[0];
12780 stack[0] = x_9;
12781 stack[1] = x_9;
12782 stack[2] = 2;
12783 y_17 = stack[2];
12784 x_19 = stack[1];
12785 _20 = x_19 < y_17;
12786 _21 = (signed int) _20;
12787 stack[1] = _21;
12788 x_25 = stack[1];
12789 if (x_25 != 0)
12790 goto <bb 4> (instr9);
12791 else
12792 goto <bb 3> (instr4);
12793
12794 instr4:
12795 /* DUP */:
12796 x_27 = stack[0];
12797 stack[0] = x_27;
12798 stack[1] = x_27;
12799 stack[2] = 1;
12800 y_35 = stack[2];
12801 x_37 = stack[1];
12802 _38 = x_37 - y_35;
12803 stack[1] = _38;
12804 x_42 = stack[1];
12805 _44 = factorial (x_42);
12806 stack[1] = _44;
12807 y_48 = stack[1];
12808 x_50 = stack[0];
12809 _51 = x_50 * y_48;
12810 stack[0] = _51;
12811
12812 instr9:
12813 /* RETURN */:
12814 x_55 = stack[0];
12815 x_56 = x_55;
12816 stack =@{v@} @{CLOBBER@};
12817 return x_56;
12818
12819 @}
12820 @end example
12821
12822 Note how, in the above, all those @code{stack_depth} values are now just
12823 constants: we’re accessing specific stack locations at each opcode.
12824
12825 The “esra” pass (“Early Scalar Replacement of Aggregates”) breaks
12826 out our “stack” array into individual elements:
12827
12828 @example
12829 $ less /tmp/libgccjit-1Hywc0/fake.c.024t.esra
12830 @end example
12831
12832 @example
12833 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
12834
12835 Created a replacement for stack offset: 0, size: 32: stack$0
12836 Created a replacement for stack offset: 32, size: 32: stack$1
12837 Created a replacement for stack offset: 64, size: 32: stack$2
12838
12839 Symbols to be put in SSA form
12840 @{ D.89 D.90 D.91 @}
12841 Incremental SSA update started at block: 0
12842 Number of blocks in CFG: 5
12843 Number of blocks to update: 4 ( 80%)
12844
12845
12846 factorial (signed int arg)
12847 @{
12848 signed int stack$2;
12849 signed int stack$1;
12850 signed int stack$0;
12851 signed int stack[8];
12852 signed int stack_depth;
12853 signed int x;
12854 signed int y;
12855 <unnamed type> _20;
12856 signed int _21;
12857 signed int _38;
12858 signed int _44;
12859 signed int _51;
12860
12861 initial:
12862 stack$0_45 = arg_5(D);
12863 x_9 = stack$0_45;
12864 stack$0_39 = x_9;
12865 stack$1_32 = x_9;
12866 stack$2_30 = 2;
12867 y_17 = stack$2_30;
12868 x_19 = stack$1_32;
12869 _20 = x_19 < y_17;
12870 _21 = (signed int) _20;
12871 stack$1_28 = _21;
12872 x_25 = stack$1_28;
12873 if (x_25 != 0)
12874 goto <bb 4> (instr9);
12875 else
12876 goto <bb 3> (instr4);
12877
12878 instr4:
12879 /* DUP */:
12880 x_27 = stack$0_39;
12881 stack$0_22 = x_27;
12882 stack$1_14 = x_27;
12883 stack$2_12 = 1;
12884 y_35 = stack$2_12;
12885 x_37 = stack$1_14;
12886 _38 = x_37 - y_35;
12887 stack$1_10 = _38;
12888 x_42 = stack$1_10;
12889 _44 = factorial (x_42);
12890 stack$1_6 = _44;
12891 y_48 = stack$1_6;
12892 x_50 = stack$0_22;
12893 _51 = x_50 * y_48;
12894 stack$0_1 = _51;
12895
12896 # stack$0_52 = PHI <stack$0_39(2), stack$0_1(3)>
12897 instr9:
12898 /* RETURN */:
12899 x_55 = stack$0_52;
12900 x_56 = x_55;
12901 stack =@{v@} @{CLOBBER@};
12902 return x_56;
12903
12904 @}
12905 @end example
12906
12907 Hence at this point, all those pushes and pops of the stack are now
12908 simply assignments to specific temporary variables.
12909
12910 After some copy propagation, the stack manipulation has been completely
12911 optimized away:
12912
12913 @example
12914 $ less /tmp/libgccjit-1Hywc0/fake.c.026t.copyprop1
12915 @end example
12916
12917 @example
12918 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
12919
12920 factorial (signed int arg)
12921 @{
12922 signed int stack$2;
12923 signed int stack$1;
12924 signed int stack$0;
12925 signed int stack[8];
12926 signed int stack_depth;
12927 signed int x;
12928 signed int y;
12929 <unnamed type> _20;
12930 signed int _21;
12931 signed int _38;
12932 signed int _44;
12933 signed int _51;
12934
12935 initial:
12936 stack$0_39 = arg_5(D);
12937 _20 = arg_5(D) <= 1;
12938 _21 = (signed int) _20;
12939 if (_21 != 0)
12940 goto <bb 4> (instr9);
12941 else
12942 goto <bb 3> (instr4);
12943
12944 instr4:
12945 /* DUP */:
12946 _38 = arg_5(D) + -1;
12947 _44 = factorial (_38);
12948 _51 = arg_5(D) * _44;
12949 stack$0_1 = _51;
12950
12951 # stack$0_52 = PHI <arg_5(D)(2), _51(3)>
12952 instr9:
12953 /* RETURN */:
12954 stack =@{v@} @{CLOBBER@};
12955 return stack$0_52;
12956
12957 @}
12958 @end example
12959
12960 Later on, another pass finally eliminated @code{stack_depth} local and the
12961 unused parts of the @cite{stack`} array altogether:
12962
12963 @example
12964 $ less /tmp/libgccjit-1Hywc0/fake.c.036t.release_ssa
12965 @end example
12966
12967 @example
12968 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
12969
12970 Released 44 names, 314.29%, removed 44 holes
12971 factorial (signed int arg)
12972 @{
12973 signed int stack$0;
12974 signed int mult_acc_1;
12975 <unnamed type> _5;
12976 signed int _6;
12977 signed int _7;
12978 signed int mul_tmp_10;
12979 signed int mult_acc_11;
12980 signed int mult_acc_13;
12981
12982 # arg_9 = PHI <arg_8(D)(0)>
12983 # mult_acc_13 = PHI <1(0)>
12984 initial:
12985
12986 <bb 5>:
12987 # arg_4 = PHI <arg_9(2), _7(3)>
12988 # mult_acc_1 = PHI <mult_acc_13(2), mult_acc_11(3)>
12989 _5 = arg_4 <= 1;
12990 _6 = (signed int) _5;
12991 if (_6 != 0)
12992 goto <bb 4> (instr9);
12993 else
12994 goto <bb 3> (instr4);
12995
12996 instr4:
12997 /* DUP */:
12998 _7 = arg_4 + -1;
12999 mult_acc_11 = mult_acc_1 * arg_4;
13000 goto <bb 5>;
13001
13002 # stack$0_12 = PHI <arg_4(5)>
13003 instr9:
13004 /* RETURN */:
13005 mul_tmp_10 = mult_acc_1 * stack$0_12;
13006 return mul_tmp_10;
13007
13008 @}
13009 @end example
13010
13011 @node Elimination of tail recursion<2>,,Optimizing away stack manipulation<2>,Behind the curtain How does our code get optimized?<2>
13012 @anchor{cp/intro/tutorial04 elimination-of-tail-recursion}@anchor{1a6}
13013 @subsubsection Elimination of tail recursion
13014
13015
13016 Another significant optimization is the detection that the call to
13017 @code{factorial} is tail recursion, which can be eliminated in favor of
13018 an iteration:
13019
13020 @example
13021 $ less /tmp/libgccjit-1Hywc0/fake.c.030t.tailr1
13022 @end example
13023
13024 @example
13025 ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
13026
13027
13028 Symbols to be put in SSA form
13029 @{ D.88 @}
13030 Incremental SSA update started at block: 0
13031 Number of blocks in CFG: 5
13032 Number of blocks to update: 4 ( 80%)
13033
13034
13035 factorial (signed int arg)
13036 @{
13037 signed int stack$2;
13038 signed int stack$1;
13039 signed int stack$0;
13040 signed int stack[8];
13041 signed int stack_depth;
13042 signed int x;
13043 signed int y;
13044 signed int mult_acc_1;
13045 <unnamed type> _20;
13046 signed int _21;
13047 signed int _38;
13048 signed int mul_tmp_44;
13049 signed int mult_acc_51;
13050
13051 # arg_5 = PHI <arg_39(D)(0), _38(3)>
13052 # mult_acc_1 = PHI <1(0), mult_acc_51(3)>
13053 initial:
13054 _20 = arg_5 <= 1;
13055 _21 = (signed int) _20;
13056 if (_21 != 0)
13057 goto <bb 4> (instr9);
13058 else
13059 goto <bb 3> (instr4);
13060
13061 instr4:
13062 /* DUP */:
13063 _38 = arg_5 + -1;
13064 mult_acc_51 = mult_acc_1 * arg_5;
13065 goto <bb 2> (initial);
13066
13067 # stack$0_52 = PHI <arg_5(2)>
13068 instr9:
13069 /* RETURN */:
13070 stack =@{v@} @{CLOBBER@};
13071 mul_tmp_44 = mult_acc_1 * stack$0_52;
13072 return mul_tmp_44;
13073
13074 @}
13075 @end example
13076
13077 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
13078 @c Originally contributed by David Malcolm <[email protected]>
13079 @c
13080 @c This is free software: you can redistribute it and/or modify it
13081 @c under the terms of the GNU General Public License as published by
13082 @c the Free Software Foundation, either version 3 of the License, or
13083 @c (at your option) any later version.
13084 @c
13085 @c This program is distributed in the hope that it will be useful, but
13086 @c WITHOUT ANY WARRANTY; without even the implied warranty of
13087 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13088 @c General Public License for more details.
13089 @c
13090 @c You should have received a copy of the GNU General Public License
13091 @c along with this program. If not, see
13092 @c <https://www.gnu.org/licenses/>.
13093
13094 @node Topic Reference<2>,,Tutorial<2>,C++ bindings for libgccjit
13095 @anchor{cp/topics/index doc}@anchor{1a7}@anchor{cp/topics/index topic-reference}@anchor{1a8}
13096 @section Topic Reference
13097
13098
13099 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
13100 @c Originally contributed by David Malcolm <[email protected]>
13101 @c
13102 @c This is free software: you can redistribute it and/or modify it
13103 @c under the terms of the GNU General Public License as published by
13104 @c the Free Software Foundation, either version 3 of the License, or
13105 @c (at your option) any later version.
13106 @c
13107 @c This program is distributed in the hope that it will be useful, but
13108 @c WITHOUT ANY WARRANTY; without even the implied warranty of
13109 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13110 @c General Public License for more details.
13111 @c
13112 @c You should have received a copy of the GNU General Public License
13113 @c along with this program. If not, see
13114 @c <https://www.gnu.org/licenses/>.
13115
13116 @menu
13117 * Compilation contexts: Compilation contexts<2>.
13118 * Objects: Objects<2>.
13119 * Types: Types<2>.
13120 * Expressions: Expressions<2>.
13121 * Creating and using functions: Creating and using functions<2>.
13122 * Source Locations: Source Locations<2>.
13123 * Compiling a context: Compiling a context<2>.
13124 * Using Assembly Language with libgccjit++::
13125
13126 @end menu
13127
13128 @node Compilation contexts<2>,Objects<2>,,Topic Reference<2>
13129 @anchor{cp/topics/contexts doc}@anchor{1a9}@anchor{cp/topics/contexts compilation-contexts}@anchor{1aa}
13130 @subsection Compilation contexts
13131
13132
13133 @geindex gccjit;;context (C++ class)
13134 @anchor{cp/topics/contexts _CPPv4N6gccjit7contextE}@anchor{175}@anchor{cp/topics/contexts _CPPv3N6gccjit7contextE}@anchor{1ab}@anchor{cp/topics/contexts _CPPv2N6gccjit7contextE}@anchor{1ac}@anchor{cp/topics/contexts gccjit context}@anchor{1ad}
13135 @deffn {C++ Class} gccjit::context
13136 @end deffn
13137
13138 The top-level of the C++ API is the @ref{175,,gccjit;;context} type.
13139
13140 A @ref{175,,gccjit;;context} instance encapsulates the state of a
13141 compilation.
13142
13143 You can set up options on it, and add types, functions and code.
13144 Invoking @ref{17f,,gccjit;;context;;compile()} on it gives you a
13145 @ref{16,,gcc_jit_result *}.
13146
13147 It is a thin wrapper around the C API’s @ref{8,,gcc_jit_context *}.
13148
13149 @menu
13150 * Lifetime-management: Lifetime-management<2>.
13151 * Thread-safety: Thread-safety<2>.
13152 * Error-handling: Error-handling<3>.
13153 * Debugging: Debugging<2>.
13154 * Options: Options<4>.
13155
13156 @end menu
13157
13158 @node Lifetime-management<2>,Thread-safety<2>,,Compilation contexts<2>
13159 @anchor{cp/topics/contexts lifetime-management}@anchor{1ae}
13160 @subsubsection Lifetime-management
13161
13162
13163 Contexts are the unit of lifetime-management within the API: objects
13164 have their lifetime bounded by the context they are created within, and
13165 cleanup of such objects is done for you when the context is released.
13166
13167 @geindex gccjit;;context;;acquire (C++ function)
13168 @anchor{cp/topics/contexts _CPPv4N6gccjit7context7acquireEv}@anchor{176}@anchor{cp/topics/contexts _CPPv3N6gccjit7context7acquireEv}@anchor{1af}@anchor{cp/topics/contexts _CPPv2N6gccjit7context7acquireEv}@anchor{1b0}@anchor{cp/topics/contexts gccjit context acquire}@anchor{1b1}
13169 @deffn {C++ Function} gccjit::@ref{175,,context} gccjit::@ref{175,,context}::acquire ()
13170
13171 This function acquires a new @ref{175,,gccjit;;context} instance,
13172 which is independent of any others that may be present within this
13173 process.
13174 @end deffn
13175
13176 @geindex gccjit;;context;;release (C++ function)
13177 @anchor{cp/topics/contexts _CPPv4N6gccjit7context7releaseEv}@anchor{179}@anchor{cp/topics/contexts _CPPv3N6gccjit7context7releaseEv}@anchor{1b2}@anchor{cp/topics/contexts _CPPv2N6gccjit7context7releaseEv}@anchor{1b3}@anchor{cp/topics/contexts gccjit context release}@anchor{1b4}
13178 @deffn {C++ Function} void gccjit::@ref{175,,context}::release ()
13179
13180 This function releases all resources associated with the given context.
13181 Both the context itself and all of its @code{gccjit::object *}
13182 instances are cleaned up. It should be called exactly once on a given
13183 context.
13184
13185 It is invalid to use the context or any of its “contextual” objects
13186 after calling this.
13187
13188 @example
13189 ctxt.release ();
13190 @end example
13191 @end deffn
13192
13193 @geindex gccjit;;context;;new_child_context (C++ function)
13194 @anchor{cp/topics/contexts _CPPv4N6gccjit7context17new_child_contextEv}@anchor{1b5}@anchor{cp/topics/contexts _CPPv3N6gccjit7context17new_child_contextEv}@anchor{1b6}@anchor{cp/topics/contexts _CPPv2N6gccjit7context17new_child_contextEv}@anchor{1b7}@anchor{cp/topics/contexts gccjit context new_child_context}@anchor{1b8}
13195 @deffn {C++ Function} gccjit::@ref{175,,context} gccjit::@ref{175,,context}::new_child_context ()
13196
13197 Given an existing JIT context, create a child context.
13198
13199 The child inherits a copy of all option-settings from the parent.
13200
13201 The child can reference objects created within the parent, but not
13202 vice-versa.
13203
13204 The lifetime of the child context must be bounded by that of the
13205 parent: you should release a child context before releasing the parent
13206 context.
13207
13208 If you use a function from a parent context within a child context,
13209 you have to compile the parent context before you can compile the
13210 child context, and the gccjit::result of the parent context must
13211 outlive the gccjit::result of the child context.
13212
13213 This allows caching of shared initializations. For example, you could
13214 create types and declarations of global functions in a parent context
13215 once within a process, and then create child contexts whenever a
13216 function or loop becomes hot. Each such child context can be used for
13217 JIT-compiling just one function or loop, but can reference types
13218 and helper functions created within the parent context.
13219
13220 Contexts can be arbitrarily nested, provided the above rules are
13221 followed, but it’s probably not worth going above 2 or 3 levels, and
13222 there will likely be a performance hit for such nesting.
13223 @end deffn
13224
13225 @node Thread-safety<2>,Error-handling<3>,Lifetime-management<2>,Compilation contexts<2>
13226 @anchor{cp/topics/contexts thread-safety}@anchor{1b9}
13227 @subsubsection Thread-safety
13228
13229
13230 Instances of @ref{175,,gccjit;;context} created via
13231 @ref{176,,gccjit;;context;;acquire()} are independent from each other:
13232 only one thread may use a given context at once, but multiple threads
13233 could each have their own contexts without needing locks.
13234
13235 Contexts created via @ref{1b5,,gccjit;;context;;new_child_context()} are
13236 related to their parent context. They can be partitioned by their
13237 ultimate ancestor into independent “family trees”. Only one thread
13238 within a process may use a given “family tree” of such contexts at once,
13239 and if you’re using multiple threads you should provide your own locking
13240 around entire such context partitions.
13241
13242 @node Error-handling<3>,Debugging<2>,Thread-safety<2>,Compilation contexts<2>
13243 @anchor{cp/topics/contexts error-handling}@anchor{1ba}
13244 @subsubsection Error-handling
13245
13246
13247 @c FIXME: How does error-handling work for C++ API?
13248
13249 You can only compile and get code from a context if no errors occur.
13250
13251 In general, if an error occurs when using an API entrypoint, it returns
13252 NULL. You don’t have to check everywhere for NULL results, since the
13253 API gracefully handles a NULL being passed in for any argument.
13254
13255 Errors are printed on stderr and can be queried using
13256 @ref{1bb,,gccjit;;context;;get_first_error()}.
13257
13258 @geindex gccjit;;context;;get_first_error (C++ function)
13259 @anchor{cp/topics/contexts _CPPv4N6gccjit7context15get_first_errorEPN6gccjit7contextE}@anchor{1bb}@anchor{cp/topics/contexts _CPPv3N6gccjit7context15get_first_errorEPN6gccjit7contextE}@anchor{1bc}@anchor{cp/topics/contexts _CPPv2N6gccjit7context15get_first_errorEPN6gccjit7contextE}@anchor{1bd}@anchor{cp/topics/contexts gccjit context get_first_error__gccjit contextP}@anchor{1be}
13260 @deffn {C++ Function} const char *gccjit::@ref{175,,context}::get_first_error (gccjit::context *ctxt)
13261
13262 Returns the first error message that occurred on the context.
13263
13264 The returned string is valid for the rest of the lifetime of the
13265 context.
13266
13267 If no errors occurred, this will be NULL.
13268 @end deffn
13269
13270 @node Debugging<2>,Options<4>,Error-handling<3>,Compilation contexts<2>
13271 @anchor{cp/topics/contexts debugging}@anchor{1bf}
13272 @subsubsection Debugging
13273
13274
13275 @geindex gccjit;;context;;dump_to_file (C++ function)
13276 @anchor{cp/topics/contexts _CPPv4N6gccjit7context12dump_to_fileERKNSt6stringEi}@anchor{1c0}@anchor{cp/topics/contexts _CPPv3N6gccjit7context12dump_to_fileERKNSt6stringEi}@anchor{1c1}@anchor{cp/topics/contexts _CPPv2N6gccjit7context12dump_to_fileERKNSt6stringEi}@anchor{1c2}@anchor{cp/topics/contexts gccjit context dump_to_file__ssCR i}@anchor{1c3}
13277 @deffn {C++ Function} void gccjit::@ref{175,,context}::dump_to_file (const std::string &path, int update_locations)
13278
13279 To help with debugging: dump a C-like representation to the given path,
13280 describing what’s been set up on the context.
13281
13282 If “update_locations” is true, then also set up @ref{19b,,gccjit;;location}
13283 information throughout the context, pointing at the dump file as if it
13284 were a source file. This may be of use in conjunction with
13285 @code{GCCJIT::BOOL_OPTION_DEBUGINFO} to allow stepping through the
13286 code in a debugger.
13287 @end deffn
13288
13289 @geindex gccjit;;context;;dump_reproducer_to_file (C++ function)
13290 @anchor{cp/topics/contexts _CPPv4N6gccjit7context23dump_reproducer_to_fileEP15gcc_jit_contextPKc}@anchor{1c4}@anchor{cp/topics/contexts _CPPv3N6gccjit7context23dump_reproducer_to_fileEP15gcc_jit_contextPKc}@anchor{1c5}@anchor{cp/topics/contexts _CPPv2N6gccjit7context23dump_reproducer_to_fileEP15gcc_jit_contextPKc}@anchor{1c6}@anchor{cp/topics/contexts gccjit context dump_reproducer_to_file__gcc_jit_contextP cCP}@anchor{1c7}
13291 @deffn {C++ Function} void gccjit::@ref{175,,context}::dump_reproducer_to_file (gcc_jit_context *ctxt, const char *path)
13292
13293 This is a thin wrapper around the C API
13294 @ref{5d,,gcc_jit_context_dump_reproducer_to_file()}, and hence works the
13295 same way.
13296
13297 Note that the generated source is C code, not C++; this might be of use
13298 for seeing what the C++ bindings are doing at the C level.
13299 @end deffn
13300
13301 @node Options<4>,,Debugging<2>,Compilation contexts<2>
13302 @anchor{cp/topics/contexts options}@anchor{1c8}
13303 @subsubsection Options
13304
13305
13306 @menu
13307 * String Options: String Options<2>.
13308 * Boolean options: Boolean options<2>.
13309 * Integer options: Integer options<2>.
13310 * Additional command-line options: Additional command-line options<2>.
13311
13312 @end menu
13313
13314 @node String Options<2>,Boolean options<2>,,Options<4>
13315 @anchor{cp/topics/contexts string-options}@anchor{1c9}
13316 @subsubsection String Options
13317
13318
13319 @geindex gccjit;;context;;set_str_option (C++ function)
13320 @anchor{cp/topics/contexts _CPPv4N6gccjit7context14set_str_optionE18gcc_jit_str_optionPKc}@anchor{1ca}@anchor{cp/topics/contexts _CPPv3N6gccjit7context14set_str_optionE18gcc_jit_str_optionPKc}@anchor{1cb}@anchor{cp/topics/contexts _CPPv2N6gccjit7context14set_str_optionE18gcc_jit_str_optionPKc}@anchor{1cc}@anchor{cp/topics/contexts gccjit context set_str_option__gcc_jit_str_option cCP}@anchor{1cd}
13321 @deffn {C++ Function} void gccjit::@ref{175,,context}::set_str_option (enum gcc_jit_str_option, const char *value)
13322
13323 Set a string option of the context.
13324
13325 This is a thin wrapper around the C API
13326 @ref{61,,gcc_jit_context_set_str_option()}; the options have the same
13327 meaning.
13328 @end deffn
13329
13330 @node Boolean options<2>,Integer options<2>,String Options<2>,Options<4>
13331 @anchor{cp/topics/contexts boolean-options}@anchor{1ce}
13332 @subsubsection Boolean options
13333
13334
13335 @geindex gccjit;;context;;set_bool_option (C++ function)
13336 @anchor{cp/topics/contexts _CPPv4N6gccjit7context15set_bool_optionE19gcc_jit_bool_optioni}@anchor{181}@anchor{cp/topics/contexts _CPPv3N6gccjit7context15set_bool_optionE19gcc_jit_bool_optioni}@anchor{1cf}@anchor{cp/topics/contexts _CPPv2N6gccjit7context15set_bool_optionE19gcc_jit_bool_optioni}@anchor{1d0}@anchor{cp/topics/contexts gccjit context set_bool_option__gcc_jit_bool_option i}@anchor{1d1}
13337 @deffn {C++ Function} void gccjit::@ref{175,,context}::set_bool_option (enum gcc_jit_bool_option, int value)
13338
13339 Set a boolean option of the context.
13340
13341 This is a thin wrapper around the C API
13342 @ref{1b,,gcc_jit_context_set_bool_option()}; the options have the same
13343 meaning.
13344 @end deffn
13345
13346 @geindex gccjit;;context;;set_bool_allow_unreachable_blocks (C++ function)
13347 @anchor{cp/topics/contexts _CPPv4N6gccjit7context33set_bool_allow_unreachable_blocksEi}@anchor{1d2}@anchor{cp/topics/contexts _CPPv3N6gccjit7context33set_bool_allow_unreachable_blocksEi}@anchor{1d3}@anchor{cp/topics/contexts _CPPv2N6gccjit7context33set_bool_allow_unreachable_blocksEi}@anchor{1d4}@anchor{cp/topics/contexts gccjit context set_bool_allow_unreachable_blocks__i}@anchor{1d5}
13348 @deffn {C++ Function} void gccjit::@ref{175,,context}::set_bool_allow_unreachable_blocks (int bool_value)
13349
13350 By default, libgccjit will issue an error about unreachable blocks
13351 within a function.
13352
13353 This entrypoint can be used to disable that error; it is a thin wrapper
13354 around the C API
13355 @ref{6b,,gcc_jit_context_set_bool_allow_unreachable_blocks()}.
13356
13357 This entrypoint was added in @ref{6c,,LIBGCCJIT_ABI_2}; you can test for
13358 its presence using
13359
13360 @example
13361 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks
13362 @end example
13363 @end deffn
13364
13365 @geindex gccjit;;context;;set_bool_use_external_driver (C++ function)
13366 @anchor{cp/topics/contexts _CPPv4N6gccjit7context28set_bool_use_external_driverEi}@anchor{1d6}@anchor{cp/topics/contexts _CPPv3N6gccjit7context28set_bool_use_external_driverEi}@anchor{1d7}@anchor{cp/topics/contexts _CPPv2N6gccjit7context28set_bool_use_external_driverEi}@anchor{1d8}@anchor{cp/topics/contexts gccjit context set_bool_use_external_driver__i}@anchor{1d9}
13367 @deffn {C++ Function} void gccjit::@ref{175,,context}::set_bool_use_external_driver (int bool_value)
13368
13369 libgccjit internally generates assembler, and uses “driver” code
13370 for converting it to other formats (e.g. shared libraries).
13371
13372 By default, libgccjit will use an embedded copy of the driver
13373 code.
13374
13375 This option can be used to instead invoke an external driver executable
13376 as a subprocess; it is a thin wrapper around the C API
13377 @ref{6d,,gcc_jit_context_set_bool_use_external_driver()}.
13378
13379 This entrypoint was added in @ref{6e,,LIBGCCJIT_ABI_5}; you can test for
13380 its presence using
13381
13382 @example
13383 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver
13384 @end example
13385 @end deffn
13386
13387 @node Integer options<2>,Additional command-line options<2>,Boolean options<2>,Options<4>
13388 @anchor{cp/topics/contexts integer-options}@anchor{1da}
13389 @subsubsection Integer options
13390
13391
13392 @geindex gccjit;;context;;set_int_option (C++ function)
13393 @anchor{cp/topics/contexts _CPPv4N6gccjit7context14set_int_optionE18gcc_jit_int_optioni}@anchor{182}@anchor{cp/topics/contexts _CPPv3N6gccjit7context14set_int_optionE18gcc_jit_int_optioni}@anchor{1db}@anchor{cp/topics/contexts _CPPv2N6gccjit7context14set_int_optionE18gcc_jit_int_optioni}@anchor{1dc}@anchor{cp/topics/contexts gccjit context set_int_option__gcc_jit_int_option i}@anchor{1dd}
13394 @deffn {C++ Function} void gccjit::@ref{175,,context}::set_int_option (enum gcc_jit_int_option, int value)
13395
13396 Set an integer option of the context.
13397
13398 This is a thin wrapper around the C API
13399 @ref{1e,,gcc_jit_context_set_int_option()}; the options have the same
13400 meaning.
13401 @end deffn
13402
13403 @node Additional command-line options<2>,,Integer options<2>,Options<4>
13404 @anchor{cp/topics/contexts additional-command-line-options}@anchor{1de}
13405 @subsubsection Additional command-line options
13406
13407
13408 @geindex gccjit;;context;;add_command_line_option (C++ function)
13409 @anchor{cp/topics/contexts _CPPv4N6gccjit7context23add_command_line_optionEPKc}@anchor{1df}@anchor{cp/topics/contexts _CPPv3N6gccjit7context23add_command_line_optionEPKc}@anchor{1e0}@anchor{cp/topics/contexts _CPPv2N6gccjit7context23add_command_line_optionEPKc}@anchor{1e1}@anchor{cp/topics/contexts gccjit context add_command_line_option__cCP}@anchor{1e2}
13410 @deffn {C++ Function} void gccjit::@ref{175,,context}::add_command_line_option (const char *optname)
13411
13412 Add an arbitrary gcc command-line option to the context for use
13413 when compiling.
13414
13415 This is a thin wrapper around the C API
13416 @ref{74,,gcc_jit_context_add_command_line_option()}.
13417
13418 This entrypoint was added in @ref{75,,LIBGCCJIT_ABI_1}; you can test for
13419 its presence using
13420
13421 @example
13422 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option
13423 @end example
13424 @end deffn
13425
13426 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
13427 @c Originally contributed by David Malcolm <[email protected]>
13428 @c
13429 @c This is free software: you can redistribute it and/or modify it
13430 @c under the terms of the GNU General Public License as published by
13431 @c the Free Software Foundation, either version 3 of the License, or
13432 @c (at your option) any later version.
13433 @c
13434 @c This program is distributed in the hope that it will be useful, but
13435 @c WITHOUT ANY WARRANTY; without even the implied warranty of
13436 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13437 @c General Public License for more details.
13438 @c
13439 @c You should have received a copy of the GNU General Public License
13440 @c along with this program. If not, see
13441 @c <https://www.gnu.org/licenses/>.
13442
13443 @node Objects<2>,Types<2>,Compilation contexts<2>,Topic Reference<2>
13444 @anchor{cp/topics/objects doc}@anchor{1e3}@anchor{cp/topics/objects objects}@anchor{1e4}
13445 @subsection Objects
13446
13447
13448 @geindex gccjit;;object (C++ class)
13449 @anchor{cp/topics/objects _CPPv4N6gccjit6objectE}@anchor{17a}@anchor{cp/topics/objects _CPPv3N6gccjit6objectE}@anchor{1e5}@anchor{cp/topics/objects _CPPv2N6gccjit6objectE}@anchor{1e6}@anchor{cp/topics/objects gccjit object}@anchor{1e7}
13450 @deffn {C++ Class} gccjit::object
13451 @end deffn
13452
13453 Almost every entity in the API (with the exception of
13454 @ref{175,,gccjit;;context} and @ref{16,,gcc_jit_result *}) is a
13455 “contextual” object, a @ref{17a,,gccjit;;object}.
13456
13457 A JIT object:
13458
13459 @quotation
13460
13461
13462 @itemize *
13463
13464 @item
13465 is associated with a @ref{175,,gccjit;;context}.
13466
13467 @item
13468 is automatically cleaned up for you when its context is released so
13469 you don’t need to manually track and cleanup all objects, just the
13470 contexts.
13471 @end itemize
13472 @end quotation
13473
13474 The C++ class hierarchy within the @code{gccjit} namespace looks like this:
13475
13476 @example
13477 +- object
13478 +- location
13479 +- type
13480 +- struct
13481 +- field
13482 +- function
13483 +- block
13484 +- rvalue
13485 +- lvalue
13486 +- param
13487 +- case_
13488 @end example
13489
13490 The @ref{17a,,gccjit;;object} base class has the following operations:
13491
13492 @geindex gccjit;;object;;get_context (C++ function)
13493 @anchor{cp/topics/objects _CPPv4NK6gccjit6object11get_contextEv}@anchor{1e8}@anchor{cp/topics/objects _CPPv3NK6gccjit6object11get_contextEv}@anchor{1e9}@anchor{cp/topics/objects _CPPv2NK6gccjit6object11get_contextEv}@anchor{1ea}@anchor{cp/topics/objects gccjit object get_contextC}@anchor{1eb}
13494 @deffn {C++ Function} gccjit::@ref{175,,context} gccjit::@ref{17a,,object}::get_context () const
13495
13496 Which context is the obj within?
13497 @end deffn
13498
13499 @geindex gccjit;;object;;get_debug_string (C++ function)
13500 @anchor{cp/topics/objects _CPPv4NK6gccjit6object16get_debug_stringEv}@anchor{17b}@anchor{cp/topics/objects _CPPv3NK6gccjit6object16get_debug_stringEv}@anchor{1ec}@anchor{cp/topics/objects _CPPv2NK6gccjit6object16get_debug_stringEv}@anchor{1ed}@anchor{cp/topics/objects gccjit object get_debug_stringC}@anchor{1ee}
13501 @deffn {C++ Function} std::string gccjit::@ref{17a,,object}::get_debug_string () const
13502
13503 Generate a human-readable description for the given object.
13504
13505 For example,
13506
13507 @example
13508 printf ("obj: %s\n", obj.get_debug_string ().c_str ());
13509 @end example
13510
13511 might give this text on stdout:
13512
13513 @example
13514 obj: 4.0 * (float)i
13515 @end example
13516 @end deffn
13517
13518 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
13519 @c Originally contributed by David Malcolm <[email protected]>
13520 @c
13521 @c This is free software: you can redistribute it and/or modify it
13522 @c under the terms of the GNU General Public License as published by
13523 @c the Free Software Foundation, either version 3 of the License, or
13524 @c (at your option) any later version.
13525 @c
13526 @c This program is distributed in the hope that it will be useful, but
13527 @c WITHOUT ANY WARRANTY; without even the implied warranty of
13528 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13529 @c General Public License for more details.
13530 @c
13531 @c You should have received a copy of the GNU General Public License
13532 @c along with this program. If not, see
13533 @c <https://www.gnu.org/licenses/>.
13534
13535 @node Types<2>,Expressions<2>,Objects<2>,Topic Reference<2>
13536 @anchor{cp/topics/types doc}@anchor{1ef}@anchor{cp/topics/types types}@anchor{1f0}
13537 @subsection Types
13538
13539
13540 @geindex gccjit;;type (C++ class)
13541 @anchor{cp/topics/types _CPPv4N6gccjit4typeE}@anchor{177}@anchor{cp/topics/types _CPPv3N6gccjit4typeE}@anchor{1f1}@anchor{cp/topics/types _CPPv2N6gccjit4typeE}@anchor{1f2}@anchor{cp/topics/types gccjit type}@anchor{1f3}
13542 @deffn {C++ Class} gccjit::type
13543
13544 gccjit::type represents a type within the library. It is a subclass
13545 of @ref{17a,,gccjit;;object}.
13546 @end deffn
13547
13548 Types can be created in several ways:
13549
13550
13551 @itemize *
13552
13553 @item
13554 fundamental types can be accessed using
13555 @ref{178,,gccjit;;context;;get_type()}:
13556
13557 @example
13558 gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
13559 @end example
13560
13561 or using the @code{gccjit::context::get_int_type} template:
13562
13563 @example
13564 gccjit::type t = ctxt.get_int_type <unsigned short> ();
13565 @end example
13566
13567 See @ref{b,,gcc_jit_context_get_type()} for the available types.
13568
13569 @item
13570 derived types can be accessed by using functions such as
13571 @ref{1f4,,gccjit;;type;;get_pointer()} and @ref{1f5,,gccjit;;type;;get_const()}:
13572
13573 @example
13574 gccjit::type const_int_star = int_type.get_const ().get_pointer ();
13575 gccjit::type int_const_star = int_type.get_pointer ().get_const ();
13576 @end example
13577
13578 @item
13579 by creating structures (see below).
13580 @end itemize
13581
13582 @menu
13583 * Standard types: Standard types<2>.
13584 * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
13585 * Vector types: Vector types<2>.
13586 * Structures and unions: Structures and unions<2>.
13587
13588 @end menu
13589
13590 @node Standard types<2>,Pointers const and volatile<2>,,Types<2>
13591 @anchor{cp/topics/types standard-types}@anchor{1f6}
13592 @subsubsection Standard types
13593
13594
13595 @geindex gccjit;;context;;get_type (C++ function)
13596 @anchor{cp/topics/types _CPPv4N6gccjit7context8get_typeE13gcc_jit_types}@anchor{178}@anchor{cp/topics/types _CPPv3N6gccjit7context8get_typeE13gcc_jit_types}@anchor{1f7}@anchor{cp/topics/types _CPPv2N6gccjit7context8get_typeE13gcc_jit_types}@anchor{1f8}@anchor{cp/topics/types gccjit context get_type__gcc_jit_types}@anchor{1f9}
13597 @deffn {C++ Function} gccjit::@ref{177,,type} gccjit::@ref{175,,context}::get_type (enum gcc_jit_types)
13598
13599 Access a specific type. This is a thin wrapper around
13600 @ref{b,,gcc_jit_context_get_type()}; the parameter has the same meaning.
13601 @end deffn
13602
13603 @geindex gccjit;;context;;get_int_type (C++ function)
13604 @anchor{cp/topics/types _CPPv4N6gccjit7context12get_int_typeE6size_ti}@anchor{1fa}@anchor{cp/topics/types _CPPv3N6gccjit7context12get_int_typeE6size_ti}@anchor{1fb}@anchor{cp/topics/types _CPPv2N6gccjit7context12get_int_typeE6size_ti}@anchor{1fc}@anchor{cp/topics/types gccjit context get_int_type__s i}@anchor{1fd}
13605 @deffn {C++ Function} gccjit::@ref{177,,type} gccjit::@ref{175,,context}::get_int_type (size_t num_bytes, int is_signed)
13606
13607 Access the integer type of the given size.
13608 @end deffn
13609
13610 @geindex gccjit;;context;;get_int_type<T> (C++ function)
13611 @anchor{cp/topics/types _CPPv4IEN6gccjit7context12get_int_typeI1TEEN6gccjit4typeEv}@anchor{1fe}@anchor{cp/topics/types _CPPv3IEN6gccjit7context12get_int_typeI1TEEv}@anchor{1ff}@anchor{cp/topics/types _CPPv2IEN6gccjit7context12get_int_typeI1TEEv}@anchor{200}
13612 @deffn {C++ Function} template<>gccjit::@ref{177,,type} gccjit::@ref{175,,context}::get_int_type<T> ()
13613
13614 Access the given integer type. For example, you could map the
13615 @code{unsigned short} type into a gccjit::type via:
13616
13617 @example
13618 gccjit::type t = ctxt.get_int_type <unsigned short> ();
13619 @end example
13620 @end deffn
13621
13622 @node Pointers const and volatile<2>,Vector types<2>,Standard types<2>,Types<2>
13623 @anchor{cp/topics/types pointers-const-and-volatile}@anchor{201}
13624 @subsubsection Pointers, @cite{const}, and @cite{volatile}
13625
13626
13627 @geindex gccjit;;type;;get_pointer (C++ function)
13628 @anchor{cp/topics/types _CPPv4N6gccjit4type11get_pointerEv}@anchor{1f4}@anchor{cp/topics/types _CPPv3N6gccjit4type11get_pointerEv}@anchor{202}@anchor{cp/topics/types _CPPv2N6gccjit4type11get_pointerEv}@anchor{203}@anchor{cp/topics/types gccjit type get_pointer}@anchor{204}
13629 @deffn {C++ Function} gccjit::@ref{177,,type} gccjit::@ref{177,,type}::get_pointer ()
13630
13631 Given type “T”, get type “T*”.
13632 @end deffn
13633
13634 @geindex gccjit;;type;;get_const (C++ function)
13635 @anchor{cp/topics/types _CPPv4N6gccjit4type9get_constEv}@anchor{1f5}@anchor{cp/topics/types _CPPv3N6gccjit4type9get_constEv}@anchor{205}@anchor{cp/topics/types _CPPv2N6gccjit4type9get_constEv}@anchor{206}@anchor{cp/topics/types gccjit type get_const}@anchor{207}
13636 @deffn {C++ Function} gccjit::@ref{177,,type} gccjit::@ref{177,,type}::get_const ()
13637
13638 Given type “T”, get type “const T”.
13639 @end deffn
13640
13641 @geindex gccjit;;type;;get_volatile (C++ function)
13642 @anchor{cp/topics/types _CPPv4N6gccjit4type12get_volatileEv}@anchor{208}@anchor{cp/topics/types _CPPv3N6gccjit4type12get_volatileEv}@anchor{209}@anchor{cp/topics/types _CPPv2N6gccjit4type12get_volatileEv}@anchor{20a}@anchor{cp/topics/types gccjit type get_volatile}@anchor{20b}
13643 @deffn {C++ Function} gccjit::@ref{177,,type} gccjit::@ref{177,,type}::get_volatile ()
13644
13645 Given type “T”, get type “volatile T”.
13646 @end deffn
13647
13648 @geindex gccjit;;type;;get_aligned (C++ function)
13649 @anchor{cp/topics/types _CPPv4N6gccjit4type11get_alignedE6size_t}@anchor{20c}@anchor{cp/topics/types _CPPv3N6gccjit4type11get_alignedE6size_t}@anchor{20d}@anchor{cp/topics/types _CPPv2N6gccjit4type11get_alignedE6size_t}@anchor{20e}@anchor{cp/topics/types gccjit type get_aligned__s}@anchor{20f}
13650 @deffn {C++ Function} gccjit::@ref{177,,type} gccjit::@ref{177,,type}::get_aligned (size_t alignment_in_bytes)
13651
13652 Given type “T”, get type:
13653
13654 @example
13655 T __attribute__ ((aligned (ALIGNMENT_IN_BYTES)))
13656 @end example
13657
13658 The alignment must be a power of two.
13659 @end deffn
13660
13661 @geindex gccjit;;context;;new_array_type (C++ function)
13662 @anchor{cp/topics/types _CPPv4N6gccjit7context14new_array_typeEN6gccjit4typeEiN6gccjit8locationE}@anchor{210}@anchor{cp/topics/types _CPPv3N6gccjit7context14new_array_typeEN6gccjit4typeEiN6gccjit8locationE}@anchor{211}@anchor{cp/topics/types _CPPv2N6gccjit7context14new_array_typeEN6gccjit4typeEiN6gccjit8locationE}@anchor{212}@anchor{cp/topics/types gccjit context new_array_type__gccjit type i gccjit location}@anchor{213}
13663 @deffn {C++ Function} gccjit::@ref{177,,type} gccjit::@ref{175,,context}::new_array_type (gccjit::type element_type, int num_elements, gccjit::location loc)
13664
13665 Given type “T”, get type “T[N]” (for a constant N).
13666 Param “loc” is optional.
13667 @end deffn
13668
13669 @node Vector types<2>,Structures and unions<2>,Pointers const and volatile<2>,Types<2>
13670 @anchor{cp/topics/types vector-types}@anchor{214}
13671 @subsubsection Vector types
13672
13673
13674 @geindex gccjit;;type;;get_vector (C++ function)
13675 @anchor{cp/topics/types _CPPv4N6gccjit4type10get_vectorE6size_t}@anchor{215}@anchor{cp/topics/types _CPPv3N6gccjit4type10get_vectorE6size_t}@anchor{216}@anchor{cp/topics/types _CPPv2N6gccjit4type10get_vectorE6size_t}@anchor{217}@anchor{cp/topics/types gccjit type get_vector__s}@anchor{218}
13676 @deffn {C++ Function} gccjit::@ref{177,,type} gccjit::@ref{177,,type}::get_vector (size_t num_units)
13677
13678 Given type “T”, get type:
13679
13680 @example
13681 T __attribute__ ((vector_size (sizeof(T) * num_units))
13682 @end example
13683
13684 T must be integral or floating point; num_units must be a power of two.
13685 @end deffn
13686
13687 @node Structures and unions<2>,,Vector types<2>,Types<2>
13688 @anchor{cp/topics/types structures-and-unions}@anchor{219}
13689 @subsubsection Structures and unions
13690
13691
13692 @geindex gccjit;;struct_ (C++ class)
13693 @anchor{cp/topics/types _CPPv4N6gccjit7struct_E}@anchor{21a}@anchor{cp/topics/types _CPPv3N6gccjit7struct_E}@anchor{21b}@anchor{cp/topics/types _CPPv2N6gccjit7struct_E}@anchor{21c}@anchor{cp/topics/types gccjit struct_}@anchor{21d}
13694 @deffn {C++ Class} gccjit::struct_
13695 @end deffn
13696
13697 A compound type analagous to a C @cite{struct}.
13698
13699 @ref{21a,,gccjit;;struct_} is a subclass of @ref{177,,gccjit;;type} (and thus
13700 of @ref{17a,,gccjit;;object} in turn).
13701
13702 @geindex gccjit;;field (C++ class)
13703 @anchor{cp/topics/types _CPPv4N6gccjit5fieldE}@anchor{21e}@anchor{cp/topics/types _CPPv3N6gccjit5fieldE}@anchor{21f}@anchor{cp/topics/types _CPPv2N6gccjit5fieldE}@anchor{220}@anchor{cp/topics/types gccjit field}@anchor{221}
13704 @deffn {C++ Class} gccjit::field
13705 @end deffn
13706
13707 A field within a @ref{21a,,gccjit;;struct_}.
13708
13709 @ref{21e,,gccjit;;field} is a subclass of @ref{17a,,gccjit;;object}.
13710
13711 You can model C @cite{struct} types by creating @ref{21a,,gccjit;;struct_} and
13712 @ref{21e,,gccjit;;field} instances, in either order:
13713
13714
13715 @itemize *
13716
13717 @item
13718 by creating the fields, then the structure. For example, to model:
13719
13720 @example
13721 struct coord @{double x; double y; @};
13722 @end example
13723
13724 you could call:
13725
13726 @example
13727 gccjit::field field_x = ctxt.new_field (double_type, "x");
13728 gccjit::field field_y = ctxt.new_field (double_type, "y");
13729 std::vector fields;
13730 fields.push_back (field_x);
13731 fields.push_back (field_y);
13732 gccjit::struct_ coord = ctxt.new_struct_type ("coord", fields);
13733 @end example
13734
13735 @item
13736 by creating the structure, then populating it with fields, typically
13737 to allow modelling self-referential structs such as:
13738
13739 @example
13740 struct node @{ int m_hash; struct node *m_next; @};
13741 @end example
13742
13743 like this:
13744
13745 @example
13746 gccjit::struct_ node = ctxt.new_opaque_struct_type ("node");
13747 gccjit::type node_ptr = node.get_pointer ();
13748 gccjit::field field_hash = ctxt.new_field (int_type, "m_hash");
13749 gccjit::field field_next = ctxt.new_field (node_ptr, "m_next");
13750 std::vector fields;
13751 fields.push_back (field_hash);
13752 fields.push_back (field_next);
13753 node.set_fields (fields);
13754 @end example
13755 @end itemize
13756
13757 @c FIXME: the above API doesn't seem to exist yet
13758
13759 @geindex gccjit;;context;;new_field (C++ function)
13760 @anchor{cp/topics/types _CPPv4N6gccjit7context9new_fieldEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{222}@anchor{cp/topics/types _CPPv3N6gccjit7context9new_fieldEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{223}@anchor{cp/topics/types _CPPv2N6gccjit7context9new_fieldEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{224}@anchor{cp/topics/types gccjit context new_field__gccjit type cCP gccjit location}@anchor{225}
13761 @deffn {C++ Function} gccjit::@ref{21e,,field} gccjit::@ref{175,,context}::new_field (gccjit::type type, const char *name, gccjit::location loc)
13762
13763 Construct a new field, with the given type and name.
13764 @end deffn
13765
13766 @geindex gccjit;;context;;new_struct_type (C++ function)
13767 @anchor{cp/topics/types _CPPv4N6gccjit7context15new_struct_typeERKNSt6stringERNSt6vectorI5fieldEEN6gccjit8locationE}@anchor{226}@anchor{cp/topics/types _CPPv3N6gccjit7context15new_struct_typeERKNSt6stringERNSt6vectorI5fieldEEN6gccjit8locationE}@anchor{227}@anchor{cp/topics/types _CPPv2N6gccjit7context15new_struct_typeERKNSt6stringERNSt6vectorI5fieldEEN6gccjit8locationE}@anchor{228}@anchor{cp/topics/types gccjit context new_struct_type__ssCR std vector field R gccjit location}@anchor{229}
13768 @deffn {C++ Function} gccjit::@ref{21a,,struct_} gccjit::@ref{175,,context}::new_struct_type (const std::string &name, std::vector<field> &fields, gccjit::location loc)
13769
13770 @quotation
13771
13772 Construct a new struct type, with the given name and fields.
13773 @end quotation
13774 @end deffn
13775
13776 @geindex gccjit;;context;;new_opaque_struct (C++ function)
13777 @anchor{cp/topics/types _CPPv4N6gccjit7context17new_opaque_structERKNSt6stringEN6gccjit8locationE}@anchor{22a}@anchor{cp/topics/types _CPPv3N6gccjit7context17new_opaque_structERKNSt6stringEN6gccjit8locationE}@anchor{22b}@anchor{cp/topics/types _CPPv2N6gccjit7context17new_opaque_structERKNSt6stringEN6gccjit8locationE}@anchor{22c}@anchor{cp/topics/types gccjit context new_opaque_struct__ssCR gccjit location}@anchor{22d}
13778 @deffn {C++ Function} gccjit::@ref{21a,,struct_} gccjit::@ref{175,,context}::new_opaque_struct (const std::string &name, gccjit::location loc)
13779
13780 Construct a new struct type, with the given name, but without
13781 specifying the fields. The fields can be omitted (in which case the
13782 size of the struct is not known), or later specified using
13783 @ref{93,,gcc_jit_struct_set_fields()}.
13784 @end deffn
13785
13786 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
13787 @c Originally contributed by David Malcolm <[email protected]>
13788 @c
13789 @c This is free software: you can redistribute it and/or modify it
13790 @c under the terms of the GNU General Public License as published by
13791 @c the Free Software Foundation, either version 3 of the License, or
13792 @c (at your option) any later version.
13793 @c
13794 @c This program is distributed in the hope that it will be useful, but
13795 @c WITHOUT ANY WARRANTY; without even the implied warranty of
13796 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13797 @c General Public License for more details.
13798 @c
13799 @c You should have received a copy of the GNU General Public License
13800 @c along with this program. If not, see
13801 @c <https://www.gnu.org/licenses/>.
13802
13803 @node Expressions<2>,Creating and using functions<2>,Types<2>,Topic Reference<2>
13804 @anchor{cp/topics/expressions doc}@anchor{22e}@anchor{cp/topics/expressions expressions}@anchor{22f}
13805 @subsection Expressions
13806
13807
13808 @menu
13809 * Rvalues: Rvalues<2>.
13810 * Lvalues: Lvalues<2>.
13811 * Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
13812
13813 @end menu
13814
13815 @node Rvalues<2>,Lvalues<2>,,Expressions<2>
13816 @anchor{cp/topics/expressions rvalues}@anchor{230}
13817 @subsubsection Rvalues
13818
13819
13820 @geindex gccjit;;rvalue (C++ class)
13821 @anchor{cp/topics/expressions _CPPv4N6gccjit6rvalueE}@anchor{17e}@anchor{cp/topics/expressions _CPPv3N6gccjit6rvalueE}@anchor{231}@anchor{cp/topics/expressions _CPPv2N6gccjit6rvalueE}@anchor{232}@anchor{cp/topics/expressions gccjit rvalue}@anchor{233}
13822 @deffn {C++ Class} gccjit::rvalue
13823 @end deffn
13824
13825 A @ref{17e,,gccjit;;rvalue} is an expression that can be computed. It is a
13826 subclass of @ref{17a,,gccjit;;object}, and is a thin wrapper around
13827 @ref{13,,gcc_jit_rvalue *} from the C API.
13828
13829 It can be simple, e.g.:
13830
13831 @quotation
13832
13833
13834 @itemize *
13835
13836 @item
13837 an integer value e.g. @cite{0} or @cite{42}
13838
13839 @item
13840 a string literal e.g. @cite{“Hello world”}
13841
13842 @item
13843 a variable e.g. @cite{i}. These are also lvalues (see below).
13844 @end itemize
13845 @end quotation
13846
13847 or compound e.g.:
13848
13849 @quotation
13850
13851
13852 @itemize *
13853
13854 @item
13855 a unary expression e.g. @cite{!cond}
13856
13857 @item
13858 a binary expression e.g. @cite{(a + b)}
13859
13860 @item
13861 a function call e.g. @cite{get_distance (&player_ship@comma{} &target)}
13862
13863 @item
13864 etc.
13865 @end itemize
13866 @end quotation
13867
13868 Every rvalue has an associated type, and the API will check to ensure
13869 that types match up correctly (otherwise the context will emit an error).
13870
13871 @geindex gccjit;;rvalue;;get_type (C++ function)
13872 @anchor{cp/topics/expressions _CPPv4N6gccjit6rvalue8get_typeEv}@anchor{234}@anchor{cp/topics/expressions _CPPv3N6gccjit6rvalue8get_typeEv}@anchor{235}@anchor{cp/topics/expressions _CPPv2N6gccjit6rvalue8get_typeEv}@anchor{236}@anchor{cp/topics/expressions gccjit rvalue get_type}@anchor{237}
13873 @deffn {C++ Function} gccjit::@ref{177,,type} gccjit::@ref{17e,,rvalue}::get_type ()
13874
13875 Get the type of this rvalue.
13876 @end deffn
13877
13878 @menu
13879 * Simple expressions: Simple expressions<2>.
13880 * Vector expressions: Vector expressions<2>.
13881 * Unary Operations: Unary Operations<2>.
13882 * Binary Operations: Binary Operations<2>.
13883 * Comparisons: Comparisons<2>.
13884 * Function calls: Function calls<2>.
13885 * Function pointers: Function pointers<3>.
13886 * Type-coercion: Type-coercion<2>.
13887
13888 @end menu
13889
13890 @node Simple expressions<2>,Vector expressions<2>,,Rvalues<2>
13891 @anchor{cp/topics/expressions simple-expressions}@anchor{238}
13892 @subsubsection Simple expressions
13893
13894
13895 @geindex gccjit;;context;;new_rvalue (C++ function)
13896 @anchor{cp/topics/expressions _CPPv4NK6gccjit7context10new_rvalueEN6gccjit4typeEi}@anchor{192}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context10new_rvalueEN6gccjit4typeEi}@anchor{239}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context10new_rvalueEN6gccjit4typeEi}@anchor{23a}@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type iC}@anchor{23b}
13897 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_rvalue (gccjit::type numeric_type, int value) const
13898
13899 Given a numeric type (integer or floating point), build an rvalue for
13900 the given constant @code{int} value.
13901 @end deffn
13902
13903 @geindex gccjit;;context;;new_rvalue (C++ function)
13904 @anchor{cp/topics/expressions _CPPv4NK6gccjit7context10new_rvalueEN6gccjit4typeEl}@anchor{23c}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context10new_rvalueEN6gccjit4typeEl}@anchor{23d}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context10new_rvalueEN6gccjit4typeEl}@anchor{23e}@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type lC}@anchor{23f}
13905 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_rvalue (gccjit::type numeric_type, long value) const
13906
13907 Given a numeric type (integer or floating point), build an rvalue for
13908 the given constant @code{long} value.
13909 @end deffn
13910
13911 @geindex gccjit;;context;;zero (C++ function)
13912 @anchor{cp/topics/expressions _CPPv4NK6gccjit7context4zeroEN6gccjit4typeE}@anchor{18e}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context4zeroEN6gccjit4typeE}@anchor{240}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context4zeroEN6gccjit4typeE}@anchor{241}@anchor{cp/topics/expressions gccjit context zero__gccjit typeC}@anchor{242}
13913 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::zero (gccjit::type numeric_type) const
13914
13915 Given a numeric type (integer or floating point), get the rvalue for
13916 zero. Essentially this is just a shortcut for:
13917
13918 @example
13919 ctxt.new_rvalue (numeric_type, 0)
13920 @end example
13921 @end deffn
13922
13923 @geindex gccjit;;context;;one (C++ function)
13924 @anchor{cp/topics/expressions _CPPv4NK6gccjit7context3oneEN6gccjit4typeE}@anchor{243}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context3oneEN6gccjit4typeE}@anchor{244}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context3oneEN6gccjit4typeE}@anchor{245}@anchor{cp/topics/expressions gccjit context one__gccjit typeC}@anchor{246}
13925 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::one (gccjit::type numeric_type) const
13926
13927 Given a numeric type (integer or floating point), get the rvalue for
13928 one. Essentially this is just a shortcut for:
13929
13930 @example
13931 ctxt.new_rvalue (numeric_type, 1)
13932 @end example
13933 @end deffn
13934
13935 @geindex gccjit;;context;;new_rvalue (C++ function)
13936 @anchor{cp/topics/expressions _CPPv4NK6gccjit7context10new_rvalueEN6gccjit4typeEd}@anchor{247}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context10new_rvalueEN6gccjit4typeEd}@anchor{248}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context10new_rvalueEN6gccjit4typeEd}@anchor{249}@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type doubleC}@anchor{24a}
13937 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_rvalue (gccjit::type numeric_type, double value) const
13938
13939 Given a numeric type (integer or floating point), build an rvalue for
13940 the given constant @code{double} value.
13941 @end deffn
13942
13943 @geindex gccjit;;context;;new_rvalue (C++ function)
13944 @anchor{cp/topics/expressions _CPPv4NK6gccjit7context10new_rvalueEN6gccjit4typeEPv}@anchor{24b}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context10new_rvalueEN6gccjit4typeEPv}@anchor{24c}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context10new_rvalueEN6gccjit4typeEPv}@anchor{24d}@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type voidPC}@anchor{24e}
13945 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_rvalue (gccjit::type pointer_type, void *value) const
13946
13947 Given a pointer type, build an rvalue for the given address.
13948 @end deffn
13949
13950 @geindex gccjit;;context;;new_rvalue (C++ function)
13951 @anchor{cp/topics/expressions _CPPv4NK6gccjit7context10new_rvalueERKNSt6stringE}@anchor{24f}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context10new_rvalueERKNSt6stringE}@anchor{250}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context10new_rvalueERKNSt6stringE}@anchor{251}@anchor{cp/topics/expressions gccjit context new_rvalue__ssCRC}@anchor{252}
13952 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_rvalue (const std::string &value) const
13953
13954 Generate an rvalue of type @code{GCC_JIT_TYPE_CONST_CHAR_PTR} for
13955 the given string. This is akin to a string literal.
13956 @end deffn
13957
13958 @node Vector expressions<2>,Unary Operations<2>,Simple expressions<2>,Rvalues<2>
13959 @anchor{cp/topics/expressions vector-expressions}@anchor{253}
13960 @subsubsection Vector expressions
13961
13962
13963 @geindex gccjit;;context;;new_rvalue (C++ function)
13964 @anchor{cp/topics/expressions _CPPv4NK6gccjit7context10new_rvalueEN6gccjit4typeENSt6vectorIN6gccjit6rvalueEEE}@anchor{254}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context10new_rvalueEN6gccjit4typeENSt6vectorIN6gccjit6rvalueEEE}@anchor{255}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context10new_rvalueEN6gccjit4typeENSt6vectorIN6gccjit6rvalueEEE}@anchor{256}@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type std vector gccjit rvalue C}@anchor{257}
13965 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_rvalue (gccjit::type vector_type, std::vector<gccjit::rvalue> elements) const
13966
13967 Given a vector type, and a vector of scalar rvalue elements, generate a
13968 vector rvalue.
13969
13970 The number of elements needs to match that of the vector type.
13971 @end deffn
13972
13973 @node Unary Operations<2>,Binary Operations<2>,Vector expressions<2>,Rvalues<2>
13974 @anchor{cp/topics/expressions unary-operations}@anchor{258}
13975 @subsubsection Unary Operations
13976
13977
13978 @geindex gccjit;;context;;new_unary_op (C++ function)
13979 @anchor{cp/topics/expressions _CPPv4N6gccjit7context12new_unary_opE16gcc_jit_unary_opN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{259}@anchor{cp/topics/expressions _CPPv3N6gccjit7context12new_unary_opE16gcc_jit_unary_opN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{25a}@anchor{cp/topics/expressions _CPPv2N6gccjit7context12new_unary_opE16gcc_jit_unary_opN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{25b}@anchor{cp/topics/expressions gccjit context new_unary_op__gcc_jit_unary_op gccjit type gccjit rvalue gccjit location}@anchor{25c}
13980 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_unary_op (enum gcc_jit_unary_op, gccjit::type result_type, gccjit::rvalue rvalue, gccjit::location loc)
13981
13982 Build a unary operation out of an input rvalue.
13983
13984 Parameter @code{loc} is optional.
13985
13986 This is a thin wrapper around the C API’s
13987 @ref{bf,,gcc_jit_context_new_unary_op()} and the available unary
13988 operations are documented there.
13989 @end deffn
13990
13991 There are shorter ways to spell the various specific kinds of unary
13992 operation:
13993
13994 @geindex gccjit;;context;;new_minus (C++ function)
13995 @anchor{cp/topics/expressions _CPPv4N6gccjit7context9new_minusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{25d}@anchor{cp/topics/expressions _CPPv3N6gccjit7context9new_minusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{25e}@anchor{cp/topics/expressions _CPPv2N6gccjit7context9new_minusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{25f}@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit location}@anchor{260}
13996 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
13997
13998 Negate an arithmetic value; for example:
13999
14000 @example
14001 gccjit::rvalue negpi = ctxt.new_minus (t_double, pi);
14002 @end example
14003
14004 builds the equivalent of this C expression:
14005
14006 @example
14007 -pi
14008 @end example
14009 @end deffn
14010
14011 @geindex new_bitwise_negate (C++ function)
14012 @anchor{cp/topics/expressions _CPPv418new_bitwise_negateN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{261}@anchor{cp/topics/expressions _CPPv318new_bitwise_negateN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{262}@anchor{cp/topics/expressions _CPPv218new_bitwise_negateN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{263}@anchor{cp/topics/expressions new_bitwise_negate__gccjit type gccjit rvalue gccjit location}@anchor{264}
14013 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} new_bitwise_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
14014
14015 Bitwise negation of an integer value (one’s complement); for example:
14016
14017 @example
14018 gccjit::rvalue mask = ctxt.new_bitwise_negate (t_int, a);
14019 @end example
14020
14021 builds the equivalent of this C expression:
14022
14023 @example
14024 ~a
14025 @end example
14026 @end deffn
14027
14028 @geindex new_logical_negate (C++ function)
14029 @anchor{cp/topics/expressions _CPPv418new_logical_negateN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{265}@anchor{cp/topics/expressions _CPPv318new_logical_negateN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{266}@anchor{cp/topics/expressions _CPPv218new_logical_negateN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{267}@anchor{cp/topics/expressions new_logical_negate__gccjit type gccjit rvalue gccjit location}@anchor{268}
14030 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} new_logical_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
14031
14032 Logical negation of an arithmetic or pointer value; for example:
14033
14034 @example
14035 gccjit::rvalue guard = ctxt.new_logical_negate (t_bool, cond);
14036 @end example
14037
14038 builds the equivalent of this C expression:
14039
14040 @example
14041 !cond
14042 @end example
14043 @end deffn
14044
14045 The most concise way to spell them is with overloaded operators:
14046
14047 @geindex operator- (C++ function)
14048 @anchor{cp/topics/expressions _CPPv4miN6gccjit6rvalueE}@anchor{269}@anchor{cp/topics/expressions _CPPv3miN6gccjit6rvalueE}@anchor{26a}@anchor{cp/topics/expressions _CPPv2miN6gccjit6rvalueE}@anchor{26b}@anchor{cp/topics/expressions sub-operator__gccjit rvalue}@anchor{26c}
14049 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator@w{-} (gccjit::rvalue a)
14050
14051 @example
14052 gccjit::rvalue negpi = -pi;
14053 @end example
14054 @end deffn
14055
14056 @geindex operator~ (C++ function)
14057 @anchor{cp/topics/expressions _CPPv4coN6gccjit6rvalueE}@anchor{26d}@anchor{cp/topics/expressions _CPPv3coN6gccjit6rvalueE}@anchor{26e}@anchor{cp/topics/expressions _CPPv2coN6gccjit6rvalueE}@anchor{26f}@anchor{cp/topics/expressions inv-operator__gccjit rvalue}@anchor{270}
14058 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator~ (gccjit::rvalue a)
14059
14060 @example
14061 gccjit::rvalue mask = ~a;
14062 @end example
14063 @end deffn
14064
14065 @geindex operator! (C++ function)
14066 @anchor{cp/topics/expressions _CPPv4ntN6gccjit6rvalueE}@anchor{271}@anchor{cp/topics/expressions _CPPv3ntN6gccjit6rvalueE}@anchor{272}@anchor{cp/topics/expressions _CPPv2ntN6gccjit6rvalueE}@anchor{273}@anchor{cp/topics/expressions not-operator__gccjit rvalue}@anchor{274}
14067 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator! (gccjit::rvalue a)
14068
14069 @example
14070 gccjit::rvalue guard = !cond;
14071 @end example
14072 @end deffn
14073
14074 @node Binary Operations<2>,Comparisons<2>,Unary Operations<2>,Rvalues<2>
14075 @anchor{cp/topics/expressions binary-operations}@anchor{275}
14076 @subsubsection Binary Operations
14077
14078
14079 @geindex gccjit;;context;;new_binary_op (C++ function)
14080 @anchor{cp/topics/expressions _CPPv4N6gccjit7context13new_binary_opE17gcc_jit_binary_opN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{17d}@anchor{cp/topics/expressions _CPPv3N6gccjit7context13new_binary_opE17gcc_jit_binary_opN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{276}@anchor{cp/topics/expressions _CPPv2N6gccjit7context13new_binary_opE17gcc_jit_binary_opN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{277}@anchor{cp/topics/expressions gccjit context new_binary_op__gcc_jit_binary_op gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{278}
14081 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_binary_op (enum gcc_jit_binary_op, gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14082
14083 Build a binary operation out of two constituent rvalues.
14084
14085 Parameter @code{loc} is optional.
14086
14087 This is a thin wrapper around the C API’s
14088 @ref{12,,gcc_jit_context_new_binary_op()} and the available binary
14089 operations are documented there.
14090 @end deffn
14091
14092 There are shorter ways to spell the various specific kinds of binary
14093 operation:
14094
14095 @geindex gccjit;;context;;new_plus (C++ function)
14096 @anchor{cp/topics/expressions _CPPv4N6gccjit7context8new_plusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{279}@anchor{cp/topics/expressions _CPPv3N6gccjit7context8new_plusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{27a}@anchor{cp/topics/expressions _CPPv2N6gccjit7context8new_plusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{27b}@anchor{cp/topics/expressions gccjit context new_plus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{27c}
14097 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_plus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14098 @end deffn
14099
14100 @geindex gccjit;;context;;new_minus (C++ function)
14101 @anchor{cp/topics/expressions _CPPv4N6gccjit7context9new_minusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{27d}@anchor{cp/topics/expressions _CPPv3N6gccjit7context9new_minusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{27e}@anchor{cp/topics/expressions _CPPv2N6gccjit7context9new_minusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{27f}@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{280}
14102 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14103 @end deffn
14104
14105 @geindex gccjit;;context;;new_mult (C++ function)
14106 @anchor{cp/topics/expressions _CPPv4N6gccjit7context8new_multEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{281}@anchor{cp/topics/expressions _CPPv3N6gccjit7context8new_multEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{282}@anchor{cp/topics/expressions _CPPv2N6gccjit7context8new_multEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{283}@anchor{cp/topics/expressions gccjit context new_mult__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{284}
14107 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_mult (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14108 @end deffn
14109
14110 @geindex gccjit;;context;;new_divide (C++ function)
14111 @anchor{cp/topics/expressions _CPPv4N6gccjit7context10new_divideEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{285}@anchor{cp/topics/expressions _CPPv3N6gccjit7context10new_divideEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{286}@anchor{cp/topics/expressions _CPPv2N6gccjit7context10new_divideEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{287}@anchor{cp/topics/expressions gccjit context new_divide__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{288}
14112 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_divide (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14113 @end deffn
14114
14115 @geindex gccjit;;context;;new_modulo (C++ function)
14116 @anchor{cp/topics/expressions _CPPv4N6gccjit7context10new_moduloEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{289}@anchor{cp/topics/expressions _CPPv3N6gccjit7context10new_moduloEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{28a}@anchor{cp/topics/expressions _CPPv2N6gccjit7context10new_moduloEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{28b}@anchor{cp/topics/expressions gccjit context new_modulo__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{28c}
14117 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_modulo (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14118 @end deffn
14119
14120 @geindex gccjit;;context;;new_bitwise_and (C++ function)
14121 @anchor{cp/topics/expressions _CPPv4N6gccjit7context15new_bitwise_andEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{28d}@anchor{cp/topics/expressions _CPPv3N6gccjit7context15new_bitwise_andEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{28e}@anchor{cp/topics/expressions _CPPv2N6gccjit7context15new_bitwise_andEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{28f}@anchor{cp/topics/expressions gccjit context new_bitwise_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{290}
14122 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_bitwise_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14123 @end deffn
14124
14125 @geindex gccjit;;context;;new_bitwise_xor (C++ function)
14126 @anchor{cp/topics/expressions _CPPv4N6gccjit7context15new_bitwise_xorEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{291}@anchor{cp/topics/expressions _CPPv3N6gccjit7context15new_bitwise_xorEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{292}@anchor{cp/topics/expressions _CPPv2N6gccjit7context15new_bitwise_xorEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{293}@anchor{cp/topics/expressions gccjit context new_bitwise_xor__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{294}
14127 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_bitwise_xor (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14128 @end deffn
14129
14130 @geindex gccjit;;context;;new_bitwise_or (C++ function)
14131 @anchor{cp/topics/expressions _CPPv4N6gccjit7context14new_bitwise_orEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{295}@anchor{cp/topics/expressions _CPPv3N6gccjit7context14new_bitwise_orEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{296}@anchor{cp/topics/expressions _CPPv2N6gccjit7context14new_bitwise_orEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{297}@anchor{cp/topics/expressions gccjit context new_bitwise_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{298}
14132 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_bitwise_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14133 @end deffn
14134
14135 @geindex gccjit;;context;;new_logical_and (C++ function)
14136 @anchor{cp/topics/expressions _CPPv4N6gccjit7context15new_logical_andEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{299}@anchor{cp/topics/expressions _CPPv3N6gccjit7context15new_logical_andEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{29a}@anchor{cp/topics/expressions _CPPv2N6gccjit7context15new_logical_andEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{29b}@anchor{cp/topics/expressions gccjit context new_logical_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{29c}
14137 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_logical_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14138 @end deffn
14139
14140 @geindex gccjit;;context;;new_logical_or (C++ function)
14141 @anchor{cp/topics/expressions _CPPv4N6gccjit7context14new_logical_orEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{29d}@anchor{cp/topics/expressions _CPPv3N6gccjit7context14new_logical_orEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{29e}@anchor{cp/topics/expressions _CPPv2N6gccjit7context14new_logical_orEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{29f}@anchor{cp/topics/expressions gccjit context new_logical_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{2a0}
14142 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_logical_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14143 @end deffn
14144
14145 The most concise way to spell them is with overloaded operators:
14146
14147 @geindex operator+ (C++ function)
14148 @anchor{cp/topics/expressions _CPPv4plN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a1}@anchor{cp/topics/expressions _CPPv3plN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a2}@anchor{cp/topics/expressions _CPPv2plN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a3}@anchor{cp/topics/expressions add-operator__gccjit rvalue gccjit rvalue}@anchor{2a4}
14149 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator+ (gccjit::rvalue a, gccjit::rvalue b)
14150
14151 @example
14152 gccjit::rvalue sum = a + b;
14153 @end example
14154 @end deffn
14155
14156 @geindex operator- (C++ function)
14157 @anchor{cp/topics/expressions _CPPv4miN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a5}@anchor{cp/topics/expressions _CPPv3miN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a6}@anchor{cp/topics/expressions _CPPv2miN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a7}@anchor{cp/topics/expressions sub-operator__gccjit rvalue gccjit rvalue}@anchor{2a8}
14158 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator@w{-} (gccjit::rvalue a, gccjit::rvalue b)
14159
14160 @example
14161 gccjit::rvalue diff = a - b;
14162 @end example
14163 @end deffn
14164
14165 @geindex operator* (C++ function)
14166 @anchor{cp/topics/expressions _CPPv4mlN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a9}@anchor{cp/topics/expressions _CPPv3mlN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2aa}@anchor{cp/topics/expressions _CPPv2mlN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2ab}@anchor{cp/topics/expressions mul-operator__gccjit rvalue gccjit rvalue}@anchor{2ac}
14167 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator* (gccjit::rvalue a, gccjit::rvalue b)
14168
14169 @example
14170 gccjit::rvalue prod = a * b;
14171 @end example
14172 @end deffn
14173
14174 @geindex operator/ (C++ function)
14175 @anchor{cp/topics/expressions _CPPv4dvN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2ad}@anchor{cp/topics/expressions _CPPv3dvN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2ae}@anchor{cp/topics/expressions _CPPv2dvN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2af}@anchor{cp/topics/expressions div-operator__gccjit rvalue gccjit rvalue}@anchor{2b0}
14176 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator/ (gccjit::rvalue a, gccjit::rvalue b)
14177
14178 @example
14179 gccjit::rvalue result = a / b;
14180 @end example
14181 @end deffn
14182
14183 @geindex operator% (C++ function)
14184 @anchor{cp/topics/expressions _CPPv4rmN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2b1}@anchor{cp/topics/expressions _CPPv3rmN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2b2}@anchor{cp/topics/expressions _CPPv2rmN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2b3}@anchor{cp/topics/expressions mod-operator__gccjit rvalue gccjit rvalue}@anchor{2b4}
14185 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator% (gccjit::rvalue a, gccjit::rvalue b)
14186
14187 @example
14188 gccjit::rvalue mod = a % b;
14189 @end example
14190 @end deffn
14191
14192 @geindex operator& (C++ function)
14193 @anchor{cp/topics/expressions _CPPv4anN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2b5}@anchor{cp/topics/expressions _CPPv3anN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2b6}@anchor{cp/topics/expressions _CPPv2anN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2b7}@anchor{cp/topics/expressions and-operator__gccjit rvalue gccjit rvalue}@anchor{2b8}
14194 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator& (gccjit::rvalue a, gccjit::rvalue b)
14195
14196 @example
14197 gccjit::rvalue x = a & b;
14198 @end example
14199 @end deffn
14200
14201 @geindex operator^ (C++ function)
14202 @anchor{cp/topics/expressions _CPPv4eoN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2b9}@anchor{cp/topics/expressions _CPPv3eoN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2ba}@anchor{cp/topics/expressions _CPPv2eoN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2bb}@anchor{cp/topics/expressions xor-operator__gccjit rvalue gccjit rvalue}@anchor{2bc}
14203 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator^ (gccjit::rvalue a, gccjit::rvalue b)
14204
14205 @example
14206 gccjit::rvalue x = a ^ b;
14207 @end example
14208 @end deffn
14209
14210 @geindex operator| (C++ function)
14211 @anchor{cp/topics/expressions _CPPv4orN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2bd}@anchor{cp/topics/expressions _CPPv3orN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2be}@anchor{cp/topics/expressions _CPPv2orN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2bf}@anchor{cp/topics/expressions or-operator__gccjit rvalue gccjit rvalue}@anchor{2c0}
14212 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator| (gccjit::rvalue a, gccjit::rvalue b)
14213
14214 @example
14215 gccjit::rvalue x = a | b;
14216 @end example
14217 @end deffn
14218
14219 @geindex operator&& (C++ function)
14220 @anchor{cp/topics/expressions _CPPv4aaN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2c1}@anchor{cp/topics/expressions _CPPv3aaN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2c2}@anchor{cp/topics/expressions _CPPv2aaN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2c3}@anchor{cp/topics/expressions sand-operator__gccjit rvalue gccjit rvalue}@anchor{2c4}
14221 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator&& (gccjit::rvalue a, gccjit::rvalue b)
14222
14223 @example
14224 gccjit::rvalue cond = a && b;
14225 @end example
14226 @end deffn
14227
14228 @geindex operator|| (C++ function)
14229 @anchor{cp/topics/expressions _CPPv4ooN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2c5}@anchor{cp/topics/expressions _CPPv3ooN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2c6}@anchor{cp/topics/expressions _CPPv2ooN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2c7}@anchor{cp/topics/expressions sor-operator__gccjit rvalue gccjit rvalue}@anchor{2c8}
14230 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator|| (gccjit::rvalue a, gccjit::rvalue b)
14231
14232 @example
14233 gccjit::rvalue cond = a || b;
14234 @end example
14235 @end deffn
14236
14237 These can of course be combined, giving a terse way to build compound
14238 expressions:
14239
14240 @quotation
14241
14242 @example
14243 gccjit::rvalue discriminant = (b * b) - (four * a * c);
14244 @end example
14245 @end quotation
14246
14247 @node Comparisons<2>,Function calls<2>,Binary Operations<2>,Rvalues<2>
14248 @anchor{cp/topics/expressions comparisons}@anchor{2c9}
14249 @subsubsection Comparisons
14250
14251
14252 @geindex gccjit;;context;;new_comparison (C++ function)
14253 @anchor{cp/topics/expressions _CPPv4N6gccjit7context14new_comparisonE18gcc_jit_comparisonN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{18f}@anchor{cp/topics/expressions _CPPv3N6gccjit7context14new_comparisonE18gcc_jit_comparisonN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2ca}@anchor{cp/topics/expressions _CPPv2N6gccjit7context14new_comparisonE18gcc_jit_comparisonN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2cb}@anchor{cp/topics/expressions gccjit context new_comparison__gcc_jit_comparison gccjit rvalue gccjit rvalue gccjit location}@anchor{2cc}
14254 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_comparison (enum gcc_jit_comparison, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14255
14256 Build a boolean rvalue out of the comparison of two other rvalues.
14257
14258 Parameter @code{loc} is optional.
14259
14260 This is a thin wrapper around the C API’s
14261 @ref{2c,,gcc_jit_context_new_comparison()} and the available kinds
14262 of comparison are documented there.
14263 @end deffn
14264
14265 There are shorter ways to spell the various specific kinds of binary
14266 operation:
14267
14268 @geindex gccjit;;context;;new_eq (C++ function)
14269 @anchor{cp/topics/expressions _CPPv4N6gccjit7context6new_eqEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2cd}@anchor{cp/topics/expressions _CPPv3N6gccjit7context6new_eqEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2ce}@anchor{cp/topics/expressions _CPPv2N6gccjit7context6new_eqEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2cf}@anchor{cp/topics/expressions gccjit context new_eq__gccjit rvalue gccjit rvalue gccjit location}@anchor{2d0}
14270 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_eq (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14271 @end deffn
14272
14273 @geindex gccjit;;context;;new_ne (C++ function)
14274 @anchor{cp/topics/expressions _CPPv4N6gccjit7context6new_neEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2d1}@anchor{cp/topics/expressions _CPPv3N6gccjit7context6new_neEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2d2}@anchor{cp/topics/expressions _CPPv2N6gccjit7context6new_neEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2d3}@anchor{cp/topics/expressions gccjit context new_ne__gccjit rvalue gccjit rvalue gccjit location}@anchor{2d4}
14275 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_ne (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14276 @end deffn
14277
14278 @geindex gccjit;;context;;new_lt (C++ function)
14279 @anchor{cp/topics/expressions _CPPv4N6gccjit7context6new_ltEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2d5}@anchor{cp/topics/expressions _CPPv3N6gccjit7context6new_ltEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2d6}@anchor{cp/topics/expressions _CPPv2N6gccjit7context6new_ltEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2d7}@anchor{cp/topics/expressions gccjit context new_lt__gccjit rvalue gccjit rvalue gccjit location}@anchor{2d8}
14280 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_lt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14281 @end deffn
14282
14283 @geindex gccjit;;context;;new_le (C++ function)
14284 @anchor{cp/topics/expressions _CPPv4N6gccjit7context6new_leEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2d9}@anchor{cp/topics/expressions _CPPv3N6gccjit7context6new_leEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2da}@anchor{cp/topics/expressions _CPPv2N6gccjit7context6new_leEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2db}@anchor{cp/topics/expressions gccjit context new_le__gccjit rvalue gccjit rvalue gccjit location}@anchor{2dc}
14285 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_le (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14286 @end deffn
14287
14288 @geindex gccjit;;context;;new_gt (C++ function)
14289 @anchor{cp/topics/expressions _CPPv4N6gccjit7context6new_gtEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2dd}@anchor{cp/topics/expressions _CPPv3N6gccjit7context6new_gtEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2de}@anchor{cp/topics/expressions _CPPv2N6gccjit7context6new_gtEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2df}@anchor{cp/topics/expressions gccjit context new_gt__gccjit rvalue gccjit rvalue gccjit location}@anchor{2e0}
14290 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_gt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14291 @end deffn
14292
14293 @geindex gccjit;;context;;new_ge (C++ function)
14294 @anchor{cp/topics/expressions _CPPv4N6gccjit7context6new_geEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2e1}@anchor{cp/topics/expressions _CPPv3N6gccjit7context6new_geEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2e2}@anchor{cp/topics/expressions _CPPv2N6gccjit7context6new_geEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2e3}@anchor{cp/topics/expressions gccjit context new_ge__gccjit rvalue gccjit rvalue gccjit location}@anchor{2e4}
14295 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_ge (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
14296 @end deffn
14297
14298 The most concise way to spell them is with overloaded operators:
14299
14300 @geindex operator== (C++ function)
14301 @anchor{cp/topics/expressions _CPPv4eqN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2e5}@anchor{cp/topics/expressions _CPPv3eqN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2e6}@anchor{cp/topics/expressions _CPPv2eqN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2e7}@anchor{cp/topics/expressions eq-operator__gccjit rvalue gccjit rvalue}@anchor{2e8}
14302 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator== (gccjit::rvalue a, gccjit::rvalue b)
14303
14304 @example
14305 gccjit::rvalue cond = (a == ctxt.zero (t_int));
14306 @end example
14307 @end deffn
14308
14309 @geindex operator!= (C++ function)
14310 @anchor{cp/topics/expressions _CPPv4neN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2e9}@anchor{cp/topics/expressions _CPPv3neN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2ea}@anchor{cp/topics/expressions _CPPv2neN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2eb}@anchor{cp/topics/expressions neq-operator__gccjit rvalue gccjit rvalue}@anchor{2ec}
14311 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator!= (gccjit::rvalue a, gccjit::rvalue b)
14312
14313 @example
14314 gccjit::rvalue cond = (i != j);
14315 @end example
14316 @end deffn
14317
14318 @geindex operator< (C++ function)
14319 @anchor{cp/topics/expressions _CPPv4ltN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2ed}@anchor{cp/topics/expressions _CPPv3ltN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2ee}@anchor{cp/topics/expressions _CPPv2ltN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2ef}@anchor{cp/topics/expressions lt-operator__gccjit rvalue gccjit rvalue}@anchor{2f0}
14320 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator< (gccjit::rvalue a, gccjit::rvalue b)
14321
14322 @example
14323 gccjit::rvalue cond = i < n;
14324 @end example
14325 @end deffn
14326
14327 @geindex operator<= (C++ function)
14328 @anchor{cp/topics/expressions _CPPv4leN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2f1}@anchor{cp/topics/expressions _CPPv3leN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2f2}@anchor{cp/topics/expressions _CPPv2leN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2f3}@anchor{cp/topics/expressions lte-operator__gccjit rvalue gccjit rvalue}@anchor{2f4}
14329 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator<= (gccjit::rvalue a, gccjit::rvalue b)
14330
14331 @example
14332 gccjit::rvalue cond = i <= n;
14333 @end example
14334 @end deffn
14335
14336 @geindex operator> (C++ function)
14337 @anchor{cp/topics/expressions _CPPv4gtN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2f5}@anchor{cp/topics/expressions _CPPv3gtN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2f6}@anchor{cp/topics/expressions _CPPv2gtN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2f7}@anchor{cp/topics/expressions gt-operator__gccjit rvalue gccjit rvalue}@anchor{2f8}
14338 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator> (gccjit::rvalue a, gccjit::rvalue b)
14339
14340 @example
14341 gccjit::rvalue cond = (ch > limit);
14342 @end example
14343 @end deffn
14344
14345 @geindex operator>= (C++ function)
14346 @anchor{cp/topics/expressions _CPPv4geN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2f9}@anchor{cp/topics/expressions _CPPv3geN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2fa}@anchor{cp/topics/expressions _CPPv2geN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2fb}@anchor{cp/topics/expressions gte-operator__gccjit rvalue gccjit rvalue}@anchor{2fc}
14347 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} operator>= (gccjit::rvalue a, gccjit::rvalue b)
14348
14349 @example
14350 gccjit::rvalue cond = (score >= ctxt.new_rvalue (t_int, 100));
14351 @end example
14352 @end deffn
14353
14354 @c TODO: beyond this point
14355
14356 @node Function calls<2>,Function pointers<3>,Comparisons<2>,Rvalues<2>
14357 @anchor{cp/topics/expressions function-calls}@anchor{2fd}
14358 @subsubsection Function calls
14359
14360
14361 @geindex gcc_jit_context_new_call (C++ function)
14362 @anchor{cp/topics/expressions _CPPv424gcc_jit_context_new_callP15gcc_jit_contextP16gcc_jit_locationP16gcc_jit_functioniPP14gcc_jit_rvalue}@anchor{2fe}@anchor{cp/topics/expressions _CPPv324gcc_jit_context_new_callP15gcc_jit_contextP16gcc_jit_locationP16gcc_jit_functioniPP14gcc_jit_rvalue}@anchor{2ff}@anchor{cp/topics/expressions _CPPv224gcc_jit_context_new_callP15gcc_jit_contextP16gcc_jit_locationP16gcc_jit_functioniPP14gcc_jit_rvalue}@anchor{300}@anchor{cp/topics/expressions gcc_jit_context_new_call__gcc_jit_contextP gcc_jit_locationP gcc_jit_functionP i gcc_jit_rvaluePP}@anchor{301}
14363 @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)
14364
14365 Given a function and the given table of argument rvalues, construct a
14366 call to the function, with the result as an rvalue.
14367
14368 @cartouche
14369 @quotation Note
14370 @code{gccjit::context::new_call()} merely builds a
14371 @ref{17e,,gccjit;;rvalue} i.e. an expression that can be evaluated,
14372 perhaps as part of a more complicated expression.
14373 The call @emph{won’t} happen unless you add a statement to a function
14374 that evaluates the expression.
14375
14376 For example, if you want to call a function and discard the result
14377 (or to call a function with @code{void} return type), use
14378 @ref{302,,gccjit;;block;;add_eval()}:
14379
14380 @example
14381 /* Add "(void)printf (arg0, arg1);". */
14382 block.add_eval (ctxt.new_call (printf_func, arg0, arg1));
14383 @end example
14384 @end quotation
14385 @end cartouche
14386 @end deffn
14387
14388 @node Function pointers<3>,Type-coercion<2>,Function calls<2>,Rvalues<2>
14389 @anchor{cp/topics/expressions function-pointers}@anchor{303}
14390 @subsubsection Function pointers
14391
14392
14393 @geindex gccjit;;function;;get_address (C++ function)
14394 @anchor{cp/topics/expressions _CPPv4N6gccjit8function11get_addressEN6gccjit8locationE}@anchor{304}@anchor{cp/topics/expressions _CPPv3N6gccjit8function11get_addressEN6gccjit8locationE}@anchor{305}@anchor{cp/topics/expressions _CPPv2N6gccjit8function11get_addressEN6gccjit8locationE}@anchor{306}@anchor{cp/topics/expressions gccjit function get_address__gccjit location}@anchor{307}
14395 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{18c,,function}::get_address (gccjit::location loc)
14396
14397 Get the address of a function as an rvalue, of function pointer
14398 type.
14399 @end deffn
14400
14401 @node Type-coercion<2>,,Function pointers<3>,Rvalues<2>
14402 @anchor{cp/topics/expressions type-coercion}@anchor{308}
14403 @subsubsection Type-coercion
14404
14405
14406 @geindex gccjit;;context;;new_cast (C++ function)
14407 @anchor{cp/topics/expressions _CPPv4N6gccjit7context8new_castEN6gccjit6rvalueEN6gccjit4typeEN6gccjit8locationE}@anchor{309}@anchor{cp/topics/expressions _CPPv3N6gccjit7context8new_castEN6gccjit6rvalueEN6gccjit4typeEN6gccjit8locationE}@anchor{30a}@anchor{cp/topics/expressions _CPPv2N6gccjit7context8new_castEN6gccjit6rvalueEN6gccjit4typeEN6gccjit8locationE}@anchor{30b}@anchor{cp/topics/expressions gccjit context new_cast__gccjit rvalue gccjit type gccjit location}@anchor{30c}
14408 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{175,,context}::new_cast (gccjit::rvalue rvalue, gccjit::type type, gccjit::location loc)
14409
14410 Given an rvalue of T, construct another rvalue of another type.
14411
14412 Currently only a limited set of conversions are possible:
14413
14414 @quotation
14415
14416
14417 @itemize *
14418
14419 @item
14420 int <-> float
14421
14422 @item
14423 int <-> bool
14424
14425 @item
14426 P* <-> Q*, for pointer types P and Q
14427 @end itemize
14428 @end quotation
14429 @end deffn
14430
14431 @node Lvalues<2>,Working with pointers structs and unions<2>,Rvalues<2>,Expressions<2>
14432 @anchor{cp/topics/expressions lvalues}@anchor{30d}
14433 @subsubsection Lvalues
14434
14435
14436 @geindex gccjit;;lvalue (C++ class)
14437 @anchor{cp/topics/expressions _CPPv4N6gccjit6lvalueE}@anchor{187}@anchor{cp/topics/expressions _CPPv3N6gccjit6lvalueE}@anchor{30e}@anchor{cp/topics/expressions _CPPv2N6gccjit6lvalueE}@anchor{30f}@anchor{cp/topics/expressions gccjit lvalue}@anchor{310}
14438 @deffn {C++ Class} gccjit::lvalue
14439 @end deffn
14440
14441 An lvalue is something that can of the @emph{left}-hand side of an assignment:
14442 a storage area (such as a variable). It is a subclass of
14443 @ref{17e,,gccjit;;rvalue}, where the rvalue is computed by reading from the
14444 storage area.
14445
14446 It iss a thin wrapper around @ref{24,,gcc_jit_lvalue *} from the C API.
14447
14448 @geindex gccjit;;lvalue;;get_address (C++ function)
14449 @anchor{cp/topics/expressions _CPPv4N6gccjit6lvalue11get_addressEN6gccjit8locationE}@anchor{311}@anchor{cp/topics/expressions _CPPv3N6gccjit6lvalue11get_addressEN6gccjit8locationE}@anchor{312}@anchor{cp/topics/expressions _CPPv2N6gccjit6lvalue11get_addressEN6gccjit8locationE}@anchor{313}@anchor{cp/topics/expressions gccjit lvalue get_address__gccjit location}@anchor{314}
14450 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{187,,lvalue}::get_address (gccjit::location loc)
14451
14452 Take the address of an lvalue; analogous to:
14453
14454 @example
14455 &(EXPR)
14456 @end example
14457
14458 in C.
14459
14460 Parameter “loc” is optional.
14461 @end deffn
14462
14463 @menu
14464 * Global variables: Global variables<2>.
14465
14466 @end menu
14467
14468 @node Global variables<2>,,,Lvalues<2>
14469 @anchor{cp/topics/expressions global-variables}@anchor{315}
14470 @subsubsection Global variables
14471
14472
14473 @geindex gccjit;;context;;new_global (C++ function)
14474 @anchor{cp/topics/expressions _CPPv4N6gccjit7context10new_globalE19gcc_jit_global_kindN6gccjit4typeEPKcN6gccjit8locationE}@anchor{316}@anchor{cp/topics/expressions _CPPv3N6gccjit7context10new_globalE19gcc_jit_global_kindN6gccjit4typeEPKcN6gccjit8locationE}@anchor{317}@anchor{cp/topics/expressions _CPPv2N6gccjit7context10new_globalE19gcc_jit_global_kindN6gccjit4typeEPKcN6gccjit8locationE}@anchor{318}@anchor{cp/topics/expressions gccjit context new_global__gcc_jit_global_kind gccjit type cCP gccjit location}@anchor{319}
14475 @deffn {C++ Function} gccjit::@ref{187,,lvalue} gccjit::@ref{175,,context}::new_global (enum gcc_jit_global_kind, gccjit::type type, const char *name, gccjit::location loc)
14476
14477 Add a new global variable of the given type and name to the context.
14478
14479 This is a thin wrapper around @ref{f5,,gcc_jit_context_new_global()} from
14480 the C API; the “kind” parameter has the same meaning as there.
14481 @end deffn
14482
14483 @node Working with pointers structs and unions<2>,,Lvalues<2>,Expressions<2>
14484 @anchor{cp/topics/expressions working-with-pointers-structs-and-unions}@anchor{31a}
14485 @subsubsection Working with pointers, structs and unions
14486
14487
14488 @geindex gccjit;;rvalue;;dereference (C++ function)
14489 @anchor{cp/topics/expressions _CPPv4N6gccjit6rvalue11dereferenceEN6gccjit8locationE}@anchor{31b}@anchor{cp/topics/expressions _CPPv3N6gccjit6rvalue11dereferenceEN6gccjit8locationE}@anchor{31c}@anchor{cp/topics/expressions _CPPv2N6gccjit6rvalue11dereferenceEN6gccjit8locationE}@anchor{31d}@anchor{cp/topics/expressions gccjit rvalue dereference__gccjit location}@anchor{31e}
14490 @deffn {C++ Function} gccjit::@ref{187,,lvalue} gccjit::@ref{17e,,rvalue}::dereference (gccjit::location loc)
14491
14492 Given an rvalue of pointer type @code{T *}, dereferencing the pointer,
14493 getting an lvalue of type @code{T}. Analogous to:
14494
14495 @example
14496 *(EXPR)
14497 @end example
14498
14499 in C.
14500
14501 Parameter “loc” is optional.
14502 @end deffn
14503
14504 If you don’t need to specify the location, this can also be expressed using
14505 an overloaded operator:
14506
14507 @geindex gccjit;;rvalue;;operator* (C++ function)
14508 @anchor{cp/topics/expressions _CPPv4N6gccjit6rvaluemlEv}@anchor{31f}@anchor{cp/topics/expressions _CPPv3N6gccjit6rvaluemlEv}@anchor{320}@anchor{cp/topics/expressions _CPPv2N6gccjit6rvaluemlEv}@anchor{321}@anchor{cp/topics/expressions gccjit rvalue mul-operator}@anchor{322}
14509 @deffn {C++ Function} gccjit::@ref{187,,lvalue} gccjit::@ref{17e,,rvalue}::operator* ()
14510
14511 @example
14512 gccjit::lvalue content = *ptr;
14513 @end example
14514 @end deffn
14515
14516 Field access is provided separately for both lvalues and rvalues:
14517
14518 @geindex gccjit;;lvalue;;access_field (C++ function)
14519 @anchor{cp/topics/expressions _CPPv4N6gccjit6lvalue12access_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{323}@anchor{cp/topics/expressions _CPPv3N6gccjit6lvalue12access_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{324}@anchor{cp/topics/expressions _CPPv2N6gccjit6lvalue12access_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{325}@anchor{cp/topics/expressions gccjit lvalue access_field__gccjit field gccjit location}@anchor{326}
14520 @deffn {C++ Function} gccjit::@ref{187,,lvalue} gccjit::@ref{187,,lvalue}::access_field (gccjit::field field, gccjit::location loc)
14521
14522 Given an lvalue of struct or union type, access the given field,
14523 getting an lvalue of the field’s type. Analogous to:
14524
14525 @example
14526 (EXPR).field = ...;
14527 @end example
14528
14529 in C.
14530 @end deffn
14531
14532 @geindex gccjit;;rvalue;;access_field (C++ function)
14533 @anchor{cp/topics/expressions _CPPv4N6gccjit6rvalue12access_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{327}@anchor{cp/topics/expressions _CPPv3N6gccjit6rvalue12access_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{328}@anchor{cp/topics/expressions _CPPv2N6gccjit6rvalue12access_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{329}@anchor{cp/topics/expressions gccjit rvalue access_field__gccjit field gccjit location}@anchor{32a}
14534 @deffn {C++ Function} gccjit::@ref{17e,,rvalue} gccjit::@ref{17e,,rvalue}::access_field (gccjit::field field, gccjit::location loc)
14535
14536 Given an rvalue of struct or union type, access the given field
14537 as an rvalue. Analogous to:
14538
14539 @example
14540 (EXPR).field
14541 @end example
14542
14543 in C.
14544 @end deffn
14545
14546 @geindex gccjit;;rvalue;;dereference_field (C++ function)
14547 @anchor{cp/topics/expressions _CPPv4N6gccjit6rvalue17dereference_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{32b}@anchor{cp/topics/expressions _CPPv3N6gccjit6rvalue17dereference_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{32c}@anchor{cp/topics/expressions _CPPv2N6gccjit6rvalue17dereference_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{32d}@anchor{cp/topics/expressions gccjit rvalue dereference_field__gccjit field gccjit location}@anchor{32e}
14548 @deffn {C++ Function} gccjit::@ref{187,,lvalue} gccjit::@ref{17e,,rvalue}::dereference_field (gccjit::field field, gccjit::location loc)
14549
14550 Given an rvalue of pointer type @code{T *} where T is of struct or union
14551 type, access the given field as an lvalue. Analogous to:
14552
14553 @example
14554 (EXPR)->field
14555 @end example
14556
14557 in C, itself equivalent to @code{(*EXPR).FIELD}.
14558 @end deffn
14559
14560 @geindex gccjit;;context;;new_array_access (C++ function)
14561 @anchor{cp/topics/expressions _CPPv4N6gccjit7context16new_array_accessEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{32f}@anchor{cp/topics/expressions _CPPv3N6gccjit7context16new_array_accessEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{330}@anchor{cp/topics/expressions _CPPv2N6gccjit7context16new_array_accessEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{331}@anchor{cp/topics/expressions gccjit context new_array_access__gccjit rvalue gccjit rvalue gccjit location}@anchor{332}
14562 @deffn {C++ Function} gccjit::@ref{187,,lvalue} gccjit::@ref{175,,context}::new_array_access (gccjit::rvalue ptr, gccjit::rvalue index, gccjit::location loc)
14563
14564 Given an rvalue of pointer type @code{T *}, get at the element @cite{T} at
14565 the given index, using standard C array indexing rules i.e. each
14566 increment of @code{index} corresponds to @code{sizeof(T)} bytes.
14567 Analogous to:
14568
14569 @example
14570 PTR[INDEX]
14571 @end example
14572
14573 in C (or, indeed, to @code{PTR + INDEX}).
14574
14575 Parameter “loc” is optional.
14576 @end deffn
14577
14578 For array accesses where you don’t need to specify a @ref{19b,,gccjit;;location},
14579 two overloaded operators are available:
14580
14581 @quotation
14582
14583 gccjit::lvalue gccjit::rvalue::operator[] (gccjit::rvalue index)
14584
14585 @example
14586 gccjit::lvalue element = array[idx];
14587 @end example
14588
14589 gccjit::lvalue gccjit::rvalue::operator[] (int index)
14590
14591 @example
14592 gccjit::lvalue element = array[0];
14593 @end example
14594 @end quotation
14595
14596 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
14597 @c Originally contributed by David Malcolm <[email protected]>
14598 @c
14599 @c This is free software: you can redistribute it and/or modify it
14600 @c under the terms of the GNU General Public License as published by
14601 @c the Free Software Foundation, either version 3 of the License, or
14602 @c (at your option) any later version.
14603 @c
14604 @c This program is distributed in the hope that it will be useful, but
14605 @c WITHOUT ANY WARRANTY; without even the implied warranty of
14606 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14607 @c General Public License for more details.
14608 @c
14609 @c You should have received a copy of the GNU General Public License
14610 @c along with this program. If not, see
14611 @c <https://www.gnu.org/licenses/>.
14612
14613 @node Creating and using functions<2>,Source Locations<2>,Expressions<2>,Topic Reference<2>
14614 @anchor{cp/topics/functions doc}@anchor{333}@anchor{cp/topics/functions creating-and-using-functions}@anchor{334}
14615 @subsection Creating and using functions
14616
14617
14618 @menu
14619 * Params: Params<2>.
14620 * Functions: Functions<2>.
14621 * Blocks: Blocks<2>.
14622 * Statements: Statements<2>.
14623
14624 @end menu
14625
14626 @node Params<2>,Functions<2>,,Creating and using functions<2>
14627 @anchor{cp/topics/functions params}@anchor{335}
14628 @subsubsection Params
14629
14630
14631 @geindex gccjit;;param (C++ class)
14632 @anchor{cp/topics/functions _CPPv4N6gccjit5paramE}@anchor{188}@anchor{cp/topics/functions _CPPv3N6gccjit5paramE}@anchor{336}@anchor{cp/topics/functions _CPPv2N6gccjit5paramE}@anchor{337}@anchor{cp/topics/functions gccjit param}@anchor{338}
14633 @deffn {C++ Class} gccjit::param
14634
14635 A @cite{gccjit::param} represents a parameter to a function.
14636 @end deffn
14637
14638 @geindex gccjit;;context;;new_param (C++ function)
14639 @anchor{cp/topics/functions _CPPv4N6gccjit7context9new_paramEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{17c}@anchor{cp/topics/functions _CPPv3N6gccjit7context9new_paramEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{339}@anchor{cp/topics/functions _CPPv2N6gccjit7context9new_paramEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{33a}@anchor{cp/topics/functions gccjit context new_param__gccjit type cCP gccjit location}@anchor{33b}
14640 @deffn {C++ Function} gccjit::@ref{188,,param} gccjit::@ref{175,,context}::new_param (gccjit::type type, const char *name, gccjit::location loc)
14641
14642 In preparation for creating a function, create a new parameter of the
14643 given type and name.
14644 @end deffn
14645
14646 @ref{188,,gccjit;;param} is a subclass of @ref{187,,gccjit;;lvalue} (and thus
14647 of @ref{17e,,gccjit;;rvalue} and @ref{17a,,gccjit;;object}). It is a thin
14648 wrapper around the C API’s @ref{25,,gcc_jit_param *}.
14649
14650 @node Functions<2>,Blocks<2>,Params<2>,Creating and using functions<2>
14651 @anchor{cp/topics/functions functions}@anchor{33c}
14652 @subsubsection Functions
14653
14654
14655 @geindex gccjit;;function (C++ class)
14656 @anchor{cp/topics/functions _CPPv4N6gccjit8functionE}@anchor{18c}@anchor{cp/topics/functions _CPPv3N6gccjit8functionE}@anchor{33d}@anchor{cp/topics/functions _CPPv2N6gccjit8functionE}@anchor{33e}@anchor{cp/topics/functions gccjit function}@anchor{33f}
14657 @deffn {C++ Class} gccjit::function
14658
14659 A @cite{gccjit::function} represents a function - either one that we’re
14660 creating ourselves, or one that we’re referencing.
14661 @end deffn
14662
14663 @geindex gccjit;;context;;new_function (C++ function)
14664 @anchor{cp/topics/functions _CPPv4N6gccjit7context12new_functionE21gcc_jit_function_kindN6gccjit4typeEPKcRNSt6vectorI5paramEEiN6gccjit8locationE}@anchor{340}@anchor{cp/topics/functions _CPPv3N6gccjit7context12new_functionE21gcc_jit_function_kindN6gccjit4typeEPKcRNSt6vectorI5paramEEiN6gccjit8locationE}@anchor{341}@anchor{cp/topics/functions _CPPv2N6gccjit7context12new_functionE21gcc_jit_function_kindN6gccjit4typeEPKcRNSt6vectorI5paramEEiN6gccjit8locationE}@anchor{342}@anchor{cp/topics/functions gccjit context new_function__gcc_jit_function_kind gccjit type cCP std vector param R i gccjit location}@anchor{343}
14665 @deffn {C++ Function} gccjit::@ref{18c,,function} gccjit::@ref{175,,context}::new_function (enum gcc_jit_function_kind, gccjit::type return_type, const char *name, std::vector<param> &params, int is_variadic, gccjit::location loc)
14666
14667 Create a gcc_jit_function with the given name and parameters.
14668
14669 Parameters “is_variadic” and “loc” are optional.
14670
14671 This is a wrapper around the C API’s @ref{11,,gcc_jit_context_new_function()}.
14672 @end deffn
14673
14674 @geindex gccjit;;context;;get_builtin_function (C++ function)
14675 @anchor{cp/topics/functions _CPPv4N6gccjit7context20get_builtin_functionEPKc}@anchor{344}@anchor{cp/topics/functions _CPPv3N6gccjit7context20get_builtin_functionEPKc}@anchor{345}@anchor{cp/topics/functions _CPPv2N6gccjit7context20get_builtin_functionEPKc}@anchor{346}@anchor{cp/topics/functions gccjit context get_builtin_function__cCP}@anchor{347}
14676 @deffn {C++ Function} gccjit::@ref{18c,,function} gccjit::@ref{175,,context}::get_builtin_function (const char *name)
14677
14678 This is a wrapper around the C API’s
14679 @ref{10e,,gcc_jit_context_get_builtin_function()}.
14680 @end deffn
14681
14682 @geindex gccjit;;function;;get_param (C++ function)
14683 @anchor{cp/topics/functions _CPPv4NK6gccjit8function9get_paramEi}@anchor{348}@anchor{cp/topics/functions _CPPv3NK6gccjit8function9get_paramEi}@anchor{349}@anchor{cp/topics/functions _CPPv2NK6gccjit8function9get_paramEi}@anchor{34a}@anchor{cp/topics/functions gccjit function get_param__iC}@anchor{34b}
14684 @deffn {C++ Function} gccjit::@ref{188,,param} gccjit::@ref{18c,,function}::get_param (int index) const
14685
14686 Get the param of the given index (0-based).
14687 @end deffn
14688
14689 @geindex gccjit;;function;;dump_to_dot (C++ function)
14690 @anchor{cp/topics/functions _CPPv4N6gccjit8function11dump_to_dotEPKc}@anchor{194}@anchor{cp/topics/functions _CPPv3N6gccjit8function11dump_to_dotEPKc}@anchor{34c}@anchor{cp/topics/functions _CPPv2N6gccjit8function11dump_to_dotEPKc}@anchor{34d}@anchor{cp/topics/functions gccjit function dump_to_dot__cCP}@anchor{34e}
14691 @deffn {C++ Function} void gccjit::@ref{18c,,function}::dump_to_dot (const char *path)
14692
14693 Emit the function in graphviz format to the given path.
14694 @end deffn
14695
14696 @geindex gccjit;;function;;new_local (C++ function)
14697 @anchor{cp/topics/functions _CPPv4N6gccjit8function9new_localEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{189}@anchor{cp/topics/functions _CPPv3N6gccjit8function9new_localEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{34f}@anchor{cp/topics/functions _CPPv2N6gccjit8function9new_localEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{350}@anchor{cp/topics/functions gccjit function new_local__gccjit type cCP gccjit location}@anchor{351}
14698 @deffn {C++ Function} gccjit::@ref{187,,lvalue} gccjit::@ref{18c,,function}::new_local (gccjit::type type, const char *name, gccjit::location loc)
14699
14700 Create a new local variable within the function, of the given type and
14701 name.
14702 @end deffn
14703
14704 @node Blocks<2>,Statements<2>,Functions<2>,Creating and using functions<2>
14705 @anchor{cp/topics/functions blocks}@anchor{352}
14706 @subsubsection Blocks
14707
14708
14709 @geindex gccjit;;block (C++ class)
14710 @anchor{cp/topics/functions _CPPv4N6gccjit5blockE}@anchor{18b}@anchor{cp/topics/functions _CPPv3N6gccjit5blockE}@anchor{353}@anchor{cp/topics/functions _CPPv2N6gccjit5blockE}@anchor{354}@anchor{cp/topics/functions gccjit block}@anchor{355}
14711 @deffn {C++ Class} gccjit::block
14712
14713 A @cite{gccjit::block} represents a basic block within a function i.e. a
14714 sequence of statements with a single entry point and a single exit
14715 point.
14716
14717 @ref{18b,,gccjit;;block} is a subclass of @ref{17a,,gccjit;;object}.
14718
14719 The first basic block that you create within a function will
14720 be the entrypoint.
14721
14722 Each basic block that you create within a function must be
14723 terminated, either with a conditional, a jump, a return, or
14724 a switch.
14725
14726 It’s legal to have multiple basic blocks that return within
14727 one function.
14728 @end deffn
14729
14730 @geindex gccjit;;function;;new_block (C++ function)
14731 @anchor{cp/topics/functions _CPPv4N6gccjit8function9new_blockEPKc}@anchor{356}@anchor{cp/topics/functions _CPPv3N6gccjit8function9new_blockEPKc}@anchor{357}@anchor{cp/topics/functions _CPPv2N6gccjit8function9new_blockEPKc}@anchor{358}@anchor{cp/topics/functions gccjit function new_block__cCP}@anchor{359}
14732 @deffn {C++ Function} gccjit::@ref{18b,,block} gccjit::@ref{18c,,function}::new_block (const char *name)
14733
14734 Create a basic block of the given name. The name may be NULL, but
14735 providing meaningful names is often helpful when debugging: it may
14736 show up in dumps of the internal representation, and in error
14737 messages.
14738 @end deffn
14739
14740 @node Statements<2>,,Blocks<2>,Creating and using functions<2>
14741 @anchor{cp/topics/functions statements}@anchor{35a}
14742 @subsubsection Statements
14743
14744
14745 @geindex gccjit;;block;;add_eval (C++ function)
14746 @anchor{cp/topics/functions _CPPv4N6gccjit5block8add_evalEN6gccjit6rvalueEN6gccjit8locationE}@anchor{302}@anchor{cp/topics/functions _CPPv3N6gccjit5block8add_evalEN6gccjit6rvalueEN6gccjit8locationE}@anchor{35b}@anchor{cp/topics/functions _CPPv2N6gccjit5block8add_evalEN6gccjit6rvalueEN6gccjit8locationE}@anchor{35c}@anchor{cp/topics/functions gccjit block add_eval__gccjit rvalue gccjit location}@anchor{35d}
14747 @deffn {C++ Function} void gccjit::@ref{18b,,block}::add_eval (gccjit::rvalue rvalue, gccjit::location loc)
14748
14749 Add evaluation of an rvalue, discarding the result
14750 (e.g. a function call that “returns” void).
14751
14752 This is equivalent to this C code:
14753
14754 @example
14755 (void)expression;
14756 @end example
14757 @end deffn
14758
14759 @geindex gccjit;;block;;add_assignment (C++ function)
14760 @anchor{cp/topics/functions _CPPv4N6gccjit5block14add_assignmentEN6gccjit6lvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{18d}@anchor{cp/topics/functions _CPPv3N6gccjit5block14add_assignmentEN6gccjit6lvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{35e}@anchor{cp/topics/functions _CPPv2N6gccjit5block14add_assignmentEN6gccjit6lvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{35f}@anchor{cp/topics/functions gccjit block add_assignment__gccjit lvalue gccjit rvalue gccjit location}@anchor{360}
14761 @deffn {C++ Function} void gccjit::@ref{18b,,block}::add_assignment (gccjit::lvalue lvalue, gccjit::rvalue rvalue, gccjit::location loc)
14762
14763 Add evaluation of an rvalue, assigning the result to the given
14764 lvalue.
14765
14766 This is roughly equivalent to this C code:
14767
14768 @example
14769 lvalue = rvalue;
14770 @end example
14771 @end deffn
14772
14773 @geindex gccjit;;block;;add_assignment_op (C++ function)
14774 @anchor{cp/topics/functions _CPPv4N6gccjit5block17add_assignment_opEN6gccjit6lvalueE17gcc_jit_binary_opN6gccjit6rvalueEN6gccjit8locationE}@anchor{191}@anchor{cp/topics/functions _CPPv3N6gccjit5block17add_assignment_opEN6gccjit6lvalueE17gcc_jit_binary_opN6gccjit6rvalueEN6gccjit8locationE}@anchor{361}@anchor{cp/topics/functions _CPPv2N6gccjit5block17add_assignment_opEN6gccjit6lvalueE17gcc_jit_binary_opN6gccjit6rvalueEN6gccjit8locationE}@anchor{362}@anchor{cp/topics/functions gccjit block add_assignment_op__gccjit lvalue gcc_jit_binary_op gccjit rvalue gccjit location}@anchor{363}
14775 @deffn {C++ Function} void gccjit::@ref{18b,,block}::add_assignment_op (gccjit::lvalue lvalue, enum gcc_jit_binary_op, gccjit::rvalue rvalue, gccjit::location loc)
14776
14777 Add evaluation of an rvalue, using the result to modify an
14778 lvalue.
14779
14780 This is analogous to “+=” and friends:
14781
14782 @example
14783 lvalue += rvalue;
14784 lvalue *= rvalue;
14785 lvalue /= rvalue;
14786 @end example
14787
14788 etc. For example:
14789
14790 @example
14791 /* "i++" */
14792 loop_body.add_assignment_op (
14793 i,
14794 GCC_JIT_BINARY_OP_PLUS,
14795 ctxt.one (int_type));
14796 @end example
14797 @end deffn
14798
14799 @geindex gccjit;;block;;add_comment (C++ function)
14800 @anchor{cp/topics/functions _CPPv4N6gccjit5block11add_commentEPKcN6gccjit8locationE}@anchor{19d}@anchor{cp/topics/functions _CPPv3N6gccjit5block11add_commentEPKcN6gccjit8locationE}@anchor{364}@anchor{cp/topics/functions _CPPv2N6gccjit5block11add_commentEPKcN6gccjit8locationE}@anchor{365}@anchor{cp/topics/functions gccjit block add_comment__cCP gccjit location}@anchor{366}
14801 @deffn {C++ Function} void gccjit::@ref{18b,,block}::add_comment (const char *text, gccjit::location loc)
14802
14803 Add a no-op textual comment to the internal representation of the
14804 code. It will be optimized away, but will be visible in the dumps
14805 seen via @ref{66,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}
14806 and @ref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE},
14807 and thus may be of use when debugging how your project’s internal
14808 representation gets converted to the libgccjit IR.
14809
14810 Parameter “loc” is optional.
14811 @end deffn
14812
14813 @geindex gccjit;;block;;end_with_conditional (C++ function)
14814 @anchor{cp/topics/functions _CPPv4N6gccjit5block20end_with_conditionalEN6gccjit6rvalueEN6gccjit5blockEN6gccjit5blockEN6gccjit8locationE}@anchor{190}@anchor{cp/topics/functions _CPPv3N6gccjit5block20end_with_conditionalEN6gccjit6rvalueEN6gccjit5blockEN6gccjit5blockEN6gccjit8locationE}@anchor{367}@anchor{cp/topics/functions _CPPv2N6gccjit5block20end_with_conditionalEN6gccjit6rvalueEN6gccjit5blockEN6gccjit5blockEN6gccjit8locationE}@anchor{368}@anchor{cp/topics/functions gccjit block end_with_conditional__gccjit rvalue gccjit block gccjit block gccjit location}@anchor{369}
14815 @deffn {C++ Function} void gccjit::@ref{18b,,block}::end_with_conditional (gccjit::rvalue boolval, gccjit::block on_true, gccjit::block on_false, gccjit::location loc)
14816
14817 Terminate a block by adding evaluation of an rvalue, branching on the
14818 result to the appropriate successor block.
14819
14820 This is roughly equivalent to this C code:
14821
14822 @example
14823 if (boolval)
14824 goto on_true;
14825 else
14826 goto on_false;
14827 @end example
14828
14829 block, boolval, on_true, and on_false must be non-NULL.
14830 @end deffn
14831
14832 @geindex gccjit;;block;;end_with_jump (C++ function)
14833 @anchor{cp/topics/functions _CPPv4N6gccjit5block13end_with_jumpEN6gccjit5blockEN6gccjit8locationE}@anchor{36a}@anchor{cp/topics/functions _CPPv3N6gccjit5block13end_with_jumpEN6gccjit5blockEN6gccjit8locationE}@anchor{36b}@anchor{cp/topics/functions _CPPv2N6gccjit5block13end_with_jumpEN6gccjit5blockEN6gccjit8locationE}@anchor{36c}@anchor{cp/topics/functions gccjit block end_with_jump__gccjit block gccjit location}@anchor{36d}
14834 @deffn {C++ Function} void gccjit::@ref{18b,,block}::end_with_jump (gccjit::block target, gccjit::location loc)
14835
14836 Terminate a block by adding a jump to the given target block.
14837
14838 This is roughly equivalent to this C code:
14839
14840 @example
14841 goto target;
14842 @end example
14843 @end deffn
14844
14845 @geindex gccjit;;block;;end_with_return (C++ function)
14846 @anchor{cp/topics/functions _CPPv4N6gccjit5block15end_with_returnEN6gccjit6rvalueEN6gccjit8locationE}@anchor{36e}@anchor{cp/topics/functions _CPPv3N6gccjit5block15end_with_returnEN6gccjit6rvalueEN6gccjit8locationE}@anchor{36f}@anchor{cp/topics/functions _CPPv2N6gccjit5block15end_with_returnEN6gccjit6rvalueEN6gccjit8locationE}@anchor{370}@anchor{cp/topics/functions gccjit block end_with_return__gccjit rvalue gccjit location}@anchor{371}
14847 @deffn {C++ Function} void gccjit::@ref{18b,,block}::end_with_return (gccjit::rvalue rvalue, gccjit::location loc)
14848
14849 Terminate a block.
14850
14851 Both params are optional.
14852
14853 An rvalue must be provided for a function returning non-void, and
14854 must not be provided by a function “returning” @cite{void}.
14855
14856 If an rvalue is provided, the block is terminated by evaluating the
14857 rvalue and returning the value.
14858
14859 This is roughly equivalent to this C code:
14860
14861 @example
14862 return expression;
14863 @end example
14864
14865 If an rvalue is not provided, the block is terminated by adding a
14866 valueless return, for use within a function with “void” return type.
14867
14868 This is equivalent to this C code:
14869
14870 @example
14871 return;
14872 @end example
14873 @end deffn
14874
14875 @geindex gccjit;;block;;end_with_switch (C++ function)
14876 @anchor{cp/topics/functions _CPPv4N6gccjit5block15end_with_switchEN6gccjit6rvalueEN6gccjit5blockENSt6vectorIN6gccjit5case_EEEN6gccjit8locationE}@anchor{372}@anchor{cp/topics/functions _CPPv3N6gccjit5block15end_with_switchEN6gccjit6rvalueEN6gccjit5blockENSt6vectorIN6gccjit5case_EEEN6gccjit8locationE}@anchor{373}@anchor{cp/topics/functions _CPPv2N6gccjit5block15end_with_switchEN6gccjit6rvalueEN6gccjit5blockENSt6vectorIN6gccjit5case_EEEN6gccjit8locationE}@anchor{374}@anchor{cp/topics/functions gccjit block end_with_switch__gccjit rvalue gccjit block std vector gccjit case_ gccjit location}@anchor{375}
14877 @deffn {C++ Function} void gccjit::@ref{18b,,block}::end_with_switch (gccjit::rvalue expr, gccjit::block default_block, std::vector<gccjit::case_> cases, gccjit::location loc)
14878
14879 Terminate a block by adding evalation of an rvalue, then performing
14880 a multiway branch.
14881
14882 This is roughly equivalent to this C code:
14883
14884 @example
14885 switch (expr)
14886 @{
14887 default:
14888 goto default_block;
14889
14890 case C0.min_value ... C0.max_value:
14891 goto C0.dest_block;
14892
14893 case C1.min_value ... C1.max_value:
14894 goto C1.dest_block;
14895
14896 ...etc...
14897
14898 case C[N - 1].min_value ... C[N - 1].max_value:
14899 goto C[N - 1].dest_block;
14900 @}
14901 @end example
14902
14903 @code{expr} must be of the same integer type as all of the @code{min_value}
14904 and @code{max_value} within the cases.
14905
14906 The ranges of the cases must not overlap (or have duplicate
14907 values).
14908
14909 The API entrypoints relating to switch statements and cases:
14910
14911 @quotation
14912
14913
14914 @itemize *
14915
14916 @item
14917 @ref{372,,gccjit;;block;;end_with_switch()}
14918
14919 @item
14920 @code{gccjit::context::new_case()}
14921 @end itemize
14922 @end quotation
14923
14924 were added in @ref{11f,,LIBGCCJIT_ABI_3}; you can test for their presence
14925 using
14926
14927 @example
14928 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS
14929 @end example
14930
14931 A @cite{gccjit::case_} represents a case within a switch statement, and
14932 is created within a particular @ref{175,,gccjit;;context} using
14933 @code{gccjit::context::new_case()}. It is a subclass of
14934 @ref{17a,,gccjit;;object}.
14935
14936 Each case expresses a multivalued range of integer values. You
14937 can express single-valued cases by passing in the same value for
14938 both @cite{min_value} and @cite{max_value}.
14939
14940 Here’s an example of creating a switch statement:
14941
14942 @quotation
14943
14944 @example
14945
14946 void
14947 create_code (gcc_jit_context *c_ctxt, void *user_data)
14948 @{
14949 /* Let's try to inject the equivalent of:
14950 int
14951 test_switch (int x)
14952 @{
14953 switch (x)
14954 @{
14955 case 0 ... 5:
14956 return 3;
14957
14958 case 25 ... 27:
14959 return 4;
14960
14961 case -42 ... -17:
14962 return 83;
14963
14964 case 40:
14965 return 8;
14966
14967 default:
14968 return 10;
14969 @}
14970 @}
14971 */
14972 gccjit::context ctxt (c_ctxt);
14973 gccjit::type t_int = ctxt.get_type (GCC_JIT_TYPE_INT);
14974 gccjit::type return_type = t_int;
14975 gccjit::param x = ctxt.new_param (t_int, "x");
14976 std::vector <gccjit::param> params;
14977 params.push_back (x);
14978 gccjit::function func = ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
14979 return_type,
14980 "test_switch",
14981 params, 0);
14982
14983 gccjit::block b_initial = func.new_block ("initial");
14984
14985 gccjit::block b_default = func.new_block ("default");
14986 gccjit::block b_case_0_5 = func.new_block ("case_0_5");
14987 gccjit::block b_case_25_27 = func.new_block ("case_25_27");
14988 gccjit::block b_case_m42_m17 = func.new_block ("case_m42_m17");
14989 gccjit::block b_case_40 = func.new_block ("case_40");
14990
14991 std::vector <gccjit::case_> cases;
14992 cases.push_back (ctxt.new_case (ctxt.new_rvalue (t_int, 0),
14993 ctxt.new_rvalue (t_int, 5),
14994 b_case_0_5));
14995 cases.push_back (ctxt.new_case (ctxt.new_rvalue (t_int, 25),
14996 ctxt.new_rvalue (t_int, 27),
14997 b_case_25_27));
14998 cases.push_back (ctxt.new_case (ctxt.new_rvalue (t_int, -42),
14999 ctxt.new_rvalue (t_int, -17),
15000 b_case_m42_m17));
15001 cases.push_back (ctxt.new_case (ctxt.new_rvalue (t_int, 40),
15002 ctxt.new_rvalue (t_int, 40),
15003 b_case_40));
15004 b_initial.end_with_switch (x,
15005 b_default,
15006 cases);
15007
15008 b_case_0_5.end_with_return (ctxt.new_rvalue (t_int, 3));
15009 b_case_25_27.end_with_return (ctxt.new_rvalue (t_int, 4));
15010 b_case_m42_m17.end_with_return (ctxt.new_rvalue (t_int, 83));
15011 b_case_40.end_with_return (ctxt.new_rvalue (t_int, 8));
15012 b_default.end_with_return (ctxt.new_rvalue (t_int, 10));
15013 @}
15014
15015 @end example
15016 @end quotation
15017 @end deffn
15018
15019 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
15020 @c Originally contributed by David Malcolm <[email protected]>
15021 @c
15022 @c This is free software: you can redistribute it and/or modify it
15023 @c under the terms of the GNU General Public License as published by
15024 @c the Free Software Foundation, either version 3 of the License, or
15025 @c (at your option) any later version.
15026 @c
15027 @c This program is distributed in the hope that it will be useful, but
15028 @c WITHOUT ANY WARRANTY; without even the implied warranty of
15029 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15030 @c General Public License for more details.
15031 @c
15032 @c You should have received a copy of the GNU General Public License
15033 @c along with this program. If not, see
15034 @c <https://www.gnu.org/licenses/>.
15035
15036 @node Source Locations<2>,Compiling a context<2>,Creating and using functions<2>,Topic Reference<2>
15037 @anchor{cp/topics/locations doc}@anchor{376}@anchor{cp/topics/locations source-locations}@anchor{377}
15038 @subsection Source Locations
15039
15040
15041 @geindex gccjit;;location (C++ class)
15042 @anchor{cp/topics/locations _CPPv4N6gccjit8locationE}@anchor{19b}@anchor{cp/topics/locations _CPPv3N6gccjit8locationE}@anchor{378}@anchor{cp/topics/locations _CPPv2N6gccjit8locationE}@anchor{379}@anchor{cp/topics/locations gccjit location}@anchor{37a}
15043 @deffn {C++ Class} gccjit::location
15044
15045 A @cite{gccjit::location} encapsulates a source code location, so that
15046 you can (optionally) associate locations in your language with
15047 statements in the JIT-compiled code, allowing the debugger to
15048 single-step through your language.
15049
15050 @cite{gccjit::location} instances are optional: you can always omit them
15051 from any C++ API entrypoint accepting one.
15052
15053 You can construct them using @ref{1a1,,gccjit;;context;;new_location()}.
15054
15055 You need to enable @ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
15056 @ref{175,,gccjit;;context} for these locations to actually be usable by
15057 the debugger:
15058
15059 @example
15060 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1);
15061 @end example
15062 @end deffn
15063
15064 @geindex gccjit;;context;;new_location (C++ function)
15065 @anchor{cp/topics/locations _CPPv4N6gccjit7context12new_locationEPKcii}@anchor{1a1}@anchor{cp/topics/locations _CPPv3N6gccjit7context12new_locationEPKcii}@anchor{37b}@anchor{cp/topics/locations _CPPv2N6gccjit7context12new_locationEPKcii}@anchor{37c}@anchor{cp/topics/locations gccjit context new_location__cCP i i}@anchor{37d}
15066 @deffn {C++ Function} gccjit::@ref{19b,,location} gccjit::@ref{175,,context}::new_location (const char *filename, int line, int column)
15067
15068 Create a @cite{gccjit::location} instance representing the given source
15069 location.
15070 @end deffn
15071
15072 @menu
15073 * Faking it: Faking it<2>.
15074
15075 @end menu
15076
15077 @node Faking it<2>,,,Source Locations<2>
15078 @anchor{cp/topics/locations faking-it}@anchor{37e}
15079 @subsubsection Faking it
15080
15081
15082 If you don’t have source code for your internal representation, but need
15083 to debug, you can generate a C-like representation of the functions in
15084 your context using @ref{1c0,,gccjit;;context;;dump_to_file()}:
15085
15086 @example
15087 ctxt.dump_to_file ("/tmp/something.c",
15088 1 /* update_locations */);
15089 @end example
15090
15091 This will dump C-like code to the given path. If the @cite{update_locations}
15092 argument is true, this will also set up @cite{gccjit::location} information
15093 throughout the context, pointing at the dump file as if it were a source
15094 file, giving you @emph{something} you can step through in the debugger.
15095
15096 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
15097 @c Originally contributed by David Malcolm <[email protected]>
15098 @c
15099 @c This is free software: you can redistribute it and/or modify it
15100 @c under the terms of the GNU General Public License as published by
15101 @c the Free Software Foundation, either version 3 of the License, or
15102 @c (at your option) any later version.
15103 @c
15104 @c This program is distributed in the hope that it will be useful, but
15105 @c WITHOUT ANY WARRANTY; without even the implied warranty of
15106 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15107 @c General Public License for more details.
15108 @c
15109 @c You should have received a copy of the GNU General Public License
15110 @c along with this program. If not, see
15111 @c <https://www.gnu.org/licenses/>.
15112
15113 @node Compiling a context<2>,Using Assembly Language with libgccjit++,Source Locations<2>,Topic Reference<2>
15114 @anchor{cp/topics/compilation doc}@anchor{37f}@anchor{cp/topics/compilation compiling-a-context}@anchor{380}
15115 @subsection Compiling a context
15116
15117
15118 Once populated, a @ref{175,,gccjit;;context} can be compiled to
15119 machine code, either in-memory via @ref{17f,,gccjit;;context;;compile()} or
15120 to disk via @ref{381,,gccjit;;context;;compile_to_file()}.
15121
15122 You can compile a context multiple times (using either form of
15123 compilation), although any errors that occur on the context will
15124 prevent any future compilation of that context.
15125
15126 @menu
15127 * In-memory compilation: In-memory compilation<2>.
15128 * Ahead-of-time compilation: Ahead-of-time compilation<2>.
15129
15130 @end menu
15131
15132 @node In-memory compilation<2>,Ahead-of-time compilation<2>,,Compiling a context<2>
15133 @anchor{cp/topics/compilation in-memory-compilation}@anchor{382}
15134 @subsubsection In-memory compilation
15135
15136
15137 @geindex gccjit;;context;;compile (C++ function)
15138 @anchor{cp/topics/compilation _CPPv4N6gccjit7context7compileEv}@anchor{17f}@anchor{cp/topics/compilation _CPPv3N6gccjit7context7compileEv}@anchor{383}@anchor{cp/topics/compilation _CPPv2N6gccjit7context7compileEv}@anchor{384}@anchor{cp/topics/compilation gccjit context compile}@anchor{385}
15139 @deffn {C++ Function} gcc_jit_result *gccjit::@ref{175,,context}::compile ()
15140
15141 This calls into GCC and builds the code, returning a
15142 @cite{gcc_jit_result *}.
15143
15144 This is a thin wrapper around the
15145 @ref{15,,gcc_jit_context_compile()} API entrypoint.
15146 @end deffn
15147
15148 @node Ahead-of-time compilation<2>,,In-memory compilation<2>,Compiling a context<2>
15149 @anchor{cp/topics/compilation ahead-of-time-compilation}@anchor{386}
15150 @subsubsection Ahead-of-time compilation
15151
15152
15153 Although libgccjit is primarily aimed at just-in-time compilation, it
15154 can also be used for implementing more traditional ahead-of-time
15155 compilers, via the @ref{381,,gccjit;;context;;compile_to_file()} method.
15156
15157 @geindex gccjit;;context;;compile_to_file (C++ function)
15158 @anchor{cp/topics/compilation _CPPv4N6gccjit7context15compile_to_fileE19gcc_jit_output_kindPKc}@anchor{381}@anchor{cp/topics/compilation _CPPv3N6gccjit7context15compile_to_fileE19gcc_jit_output_kindPKc}@anchor{387}@anchor{cp/topics/compilation _CPPv2N6gccjit7context15compile_to_fileE19gcc_jit_output_kindPKc}@anchor{388}@anchor{cp/topics/compilation gccjit context compile_to_file__gcc_jit_output_kind cCP}@anchor{389}
15159 @deffn {C++ Function} void gccjit::@ref{175,,context}::compile_to_file (enum gcc_jit_output_kind, const char *output_path)
15160
15161 Compile the @ref{175,,gccjit;;context} to a file of the given
15162 kind.
15163
15164 This is a thin wrapper around the
15165 @ref{4a,,gcc_jit_context_compile_to_file()} API entrypoint.
15166 @end deffn
15167
15168 @c Copyright (C) 2020-2022 Free Software Foundation, Inc.
15169 @c Originally contributed by David Malcolm <[email protected]>
15170 @c
15171 @c This is free software: you can redistribute it and/or modify it
15172 @c under the terms of the GNU General Public License as published by
15173 @c the Free Software Foundation, either version 3 of the License, or
15174 @c (at your option) any later version.
15175 @c
15176 @c This program is distributed in the hope that it will be useful, but
15177 @c WITHOUT ANY WARRANTY; without even the implied warranty of
15178 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15179 @c General Public License for more details.
15180 @c
15181 @c You should have received a copy of the GNU General Public License
15182 @c along with this program. If not, see
15183 @c <https://www.gnu.org/licenses/>.
15184
15185 @node Using Assembly Language with libgccjit++,,Compiling a context<2>,Topic Reference<2>
15186 @anchor{cp/topics/asm doc}@anchor{38a}@anchor{cp/topics/asm using-assembly-language-with-libgccjit}@anchor{38b}
15187 @subsection Using Assembly Language with libgccjit++
15188
15189
15190 libgccjit has some support for directly embedding assembler instructions.
15191 This is based on GCC’s support for inline @code{asm} in C code, and the
15192 following assumes a familiarity with that functionality. See
15193 How to Use Inline Assembly Language in C Code@footnote{https://gcc.gnu.org/onlinedocs/gcc/Using-Assembly-Language-with-C.html}
15194 in GCC’s documentation, the “Extended Asm” section in particular.
15195
15196 These entrypoints were added in @ref{151,,LIBGCCJIT_ABI_15}; you can test
15197 for their presence using
15198
15199 @quotation
15200
15201 @example
15202 #ifdef LIBGCCJIT_HAVE_ASM_STATEMENTS
15203 @end example
15204 @end quotation
15205
15206 @menu
15207 * Adding assembler instructions within a function: Adding assembler instructions within a function<2>.
15208 * Adding top-level assembler statements: Adding top-level assembler statements<2>.
15209
15210 @end menu
15211
15212 @node Adding assembler instructions within a function<2>,Adding top-level assembler statements<2>,,Using Assembly Language with libgccjit++
15213 @anchor{cp/topics/asm adding-assembler-instructions-within-a-function}@anchor{38c}
15214 @subsubsection Adding assembler instructions within a function
15215
15216
15217 @geindex gccjit;;extended_asm (C++ class)
15218 @anchor{cp/topics/asm _CPPv4N6gccjit12extended_asmE}@anchor{38d}@anchor{cp/topics/asm _CPPv3N6gccjit12extended_asmE}@anchor{38e}@anchor{cp/topics/asm _CPPv2N6gccjit12extended_asmE}@anchor{38f}@anchor{cp/topics/asm gccjit extended_asm}@anchor{390}
15219 @deffn {C++ Class} gccjit::extended_asm
15220
15221 A @cite{gccjit::extended_asm} represents an extended @code{asm} statement: a
15222 series of low-level instructions inside a function that convert inputs
15223 to outputs.
15224
15225 @ref{38d,,gccjit;;extended_asm} is a subclass of @ref{17a,,gccjit;;object}.
15226 It is a thin wrapper around the C API’s @ref{120,,gcc_jit_extended_asm *}.
15227
15228 To avoid having an API entrypoint with a very large number of
15229 parameters, an extended @code{asm} statement is made in stages:
15230 an initial call to create the @ref{38d,,gccjit;;extended_asm},
15231 followed by calls to add operands and set other properties of the
15232 statement.
15233
15234 There are two API entrypoints for creating a @ref{38d,,gccjit;;extended_asm}:
15235
15236
15237 @itemize *
15238
15239 @item
15240 @ref{391,,gccjit;;block;;add_extended_asm()} for an @code{asm} statement with
15241 no control flow, and
15242
15243 @item
15244 @ref{392,,gccjit;;block;;end_with_extended_asm_goto()} for an @code{asm goto}.
15245 @end itemize
15246
15247 For example, to create the equivalent of:
15248
15249 @example
15250 asm ("mov %1, %0\n\t"
15251 "add $1, %0"
15252 : "=r" (dst)
15253 : "r" (src));
15254 @end example
15255
15256 the following API calls could be used:
15257
15258 @example
15259 block.add_extended_asm ("mov %1, %0\n\t"
15260 "add $1, %0")
15261 .add_output_operand ("=r", dst)
15262 .add_input_operand ("r", src);
15263 @end example
15264
15265 @cartouche
15266 @quotation Warning
15267 When considering the numbering of operands within an
15268 extended @code{asm} statement (e.g. the @code{%0} and @code{%1}
15269 above), the equivalent to the C syntax is followed i.e. all
15270 output operands, then all input operands, regardless of
15271 what order the calls to
15272 @ref{393,,gccjit;;extended_asm;;add_output_operand()} and
15273 @ref{394,,gccjit;;extended_asm;;add_input_operand()} were made in.
15274 @end quotation
15275 @end cartouche
15276
15277 As in the C syntax, operands can be given symbolic names to avoid having
15278 to number them. For example, to create the equivalent of:
15279
15280 @example
15281 asm ("bsfl %[aMask], %[aIndex]"
15282 : [aIndex] "=r" (Index)
15283 : [aMask] "r" (Mask)
15284 : "cc");
15285 @end example
15286
15287 the following API calls could be used:
15288
15289 @example
15290 block.add_extended_asm ("bsfl %[aMask], %[aIndex]")
15291 .add_output_operand ("aIndex", "=r", index)
15292 .add_input_operand ("aMask", "r", mask)
15293 .add_clobber ("cc");
15294 @end example
15295 @end deffn
15296
15297 @geindex gccjit;;block;;add_extended_asm (C++ function)
15298 @anchor{cp/topics/asm _CPPv4N6gccjit5block16add_extended_asmERKNSt6stringEN6gccjit8locationE}@anchor{391}@anchor{cp/topics/asm _CPPv3N6gccjit5block16add_extended_asmERKNSt6stringEN6gccjit8locationE}@anchor{395}@anchor{cp/topics/asm _CPPv2N6gccjit5block16add_extended_asmERKNSt6stringEN6gccjit8locationE}@anchor{396}@anchor{cp/topics/asm gccjit block add_extended_asm__ssCR gccjit location}@anchor{397}
15299 @deffn {C++ Function} @ref{38d,,extended_asm} gccjit::@ref{18b,,block}::add_extended_asm (const std::string &asm_template, gccjit::location loc = location())
15300
15301 Create a @ref{38d,,gccjit;;extended_asm} for an extended @code{asm} statement
15302 with no control flow (i.e. without the @code{goto} qualifier).
15303
15304 The parameter @code{asm_template} corresponds to the @cite{AssemblerTemplate}
15305 within C’s extended @code{asm} syntax. It must be non-NULL. The call takes
15306 a copy of the underlying string, so it is valid to pass in a pointer to
15307 an on-stack buffer.
15308 @end deffn
15309
15310 @geindex gccjit;;block;;end_with_extended_asm_goto (C++ function)
15311 @anchor{cp/topics/asm _CPPv4N6gccjit5block26end_with_extended_asm_gotoERKNSt6stringENSt6vectorI5blockEEP5block8location}@anchor{392}@anchor{cp/topics/asm _CPPv3N6gccjit5block26end_with_extended_asm_gotoERKNSt6stringENSt6vectorI5blockEEP5block8location}@anchor{398}@anchor{cp/topics/asm _CPPv2N6gccjit5block26end_with_extended_asm_gotoERKNSt6stringENSt6vectorI5blockEEP5block8location}@anchor{399}@anchor{cp/topics/asm gccjit block end_with_extended_asm_goto__ssCR std vector block blockP location}@anchor{39a}
15312 @deffn {C++ Function} @ref{38d,,extended_asm} gccjit::@ref{18b,,block}::end_with_extended_asm_goto (const std::string &asm_template, std::vector<block> goto_blocks, block *fallthrough_block, location loc = location())
15313
15314 Create a @ref{38d,,gccjit;;extended_asm} for an extended @code{asm} statement
15315 that may perform jumps, and use it to terminate the given block.
15316 This is equivalent to the @code{goto} qualifier in C’s extended @code{asm}
15317 syntax.
15318
15319 For example, to create the equivalent of:
15320
15321 @example
15322 asm goto ("btl %1, %0\n\t"
15323 "jc %l[carry]"
15324 : // No outputs
15325 : "r" (p1), "r" (p2)
15326 : "cc"
15327 : carry);
15328 @end example
15329
15330 the following API calls could be used:
15331
15332 @example
15333 const char *asm_template =
15334 (use_name
15335 ? /* Label referred to by name: "%l[carry]". */
15336 ("btl %1, %0\n\t"
15337 "jc %l[carry]")
15338 : /* Label referred to numerically: "%l2". */
15339 ("btl %1, %0\n\t"
15340 "jc %l2"));
15341
15342 std::vector<gccjit::block> goto_blocks (@{b_carry@});
15343 gccjit::extended_asm ext_asm
15344 = (b_start.end_with_extended_asm_goto (asm_template,
15345 goto_blocks,
15346 &b_fallthru)
15347 .add_input_operand ("r", p1)
15348 .add_input_operand ("r", p2)
15349 .add_clobber ("cc"));
15350 @end example
15351
15352 here referencing a @code{gcc_jit_block} named “carry”.
15353
15354 @code{num_goto_blocks} corresponds to the @code{GotoLabels} parameter within C’s
15355 extended @code{asm} syntax. The block names can be referenced within the
15356 assembler template.
15357
15358 @code{fallthrough_block} can be NULL. If non-NULL, it specifies the block
15359 to fall through to after the statement.
15360
15361 @cartouche
15362 @quotation Note
15363 This is needed since each @ref{18b,,gccjit;;block} must have a
15364 single exit point, as a basic block: you can’t jump from the
15365 middle of a block. A “goto” is implicitly added after the
15366 asm to handle the fallthrough case, which is equivalent to what
15367 would have happened in the C case.
15368 @end quotation
15369 @end cartouche
15370 @end deffn
15371
15372 @geindex gccjit;;extended_asm;;set_volatile_flag (C++ function)
15373 @anchor{cp/topics/asm _CPPv4N6gccjit12extended_asm17set_volatile_flagEb}@anchor{39b}@anchor{cp/topics/asm _CPPv3N6gccjit12extended_asm17set_volatile_flagEb}@anchor{39c}@anchor{cp/topics/asm _CPPv2N6gccjit12extended_asm17set_volatile_flagEb}@anchor{39d}@anchor{cp/topics/asm gccjit extended_asm set_volatile_flag__b}@anchor{39e}
15374 @deffn {C++ Function} gccjit::@ref{38d,,extended_asm} &gccjit::@ref{38d,,extended_asm}::set_volatile_flag (bool flag)
15375
15376 Set whether the @ref{38d,,gccjit;;extended_asm} has side-effects, equivalent to the
15377 volatile@footnote{https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#Volatile}
15378 qualifier in C’s extended asm syntax.
15379
15380 For example, to create the equivalent of:
15381
15382 @example
15383 asm volatile ("rdtsc\n\t" // Returns the time in EDX:EAX.
15384 "shl $32, %%rdx\n\t" // Shift the upper bits left.
15385 "or %%rdx, %0" // 'Or' in the lower bits.
15386 : "=a" (msr)
15387 :
15388 : "rdx");
15389 @end example
15390
15391 the following API calls could be used:
15392
15393 @example
15394 gccjit::extended_asm ext_asm
15395 = block.add_extended_asm
15396 ("rdtsc\n\t" /* Returns the time in EDX:EAX. */
15397 "shl $32, %%rdx\n\t" /* Shift the upper bits left. */
15398 "or %%rdx, %0") /* 'Or' in the lower bits. */
15399 .set_volatile_flag (true)
15400 .add_output_operand ("=a", msr)
15401 .add_clobber ("rdx");
15402 @end example
15403
15404 where the @ref{38d,,gccjit;;extended_asm} is flagged as volatile.
15405 @end deffn
15406
15407 @geindex gccjit;;extended_asm;;set_inline_flag (C++ function)
15408 @anchor{cp/topics/asm _CPPv4N6gccjit12extended_asm15set_inline_flagEb}@anchor{39f}@anchor{cp/topics/asm _CPPv3N6gccjit12extended_asm15set_inline_flagEb}@anchor{3a0}@anchor{cp/topics/asm _CPPv2N6gccjit12extended_asm15set_inline_flagEb}@anchor{3a1}@anchor{cp/topics/asm gccjit extended_asm set_inline_flag__b}@anchor{3a2}
15409 @deffn {C++ Function} gccjit::@ref{38d,,extended_asm} &gccjit::@ref{38d,,extended_asm}::set_inline_flag (bool flag)
15410
15411 Set the equivalent of the
15412 inline@footnote{https://gcc.gnu.org/onlinedocs/gcc/Size-of-an-asm.html#Size-of-an-asm}
15413 qualifier in C’s extended @code{asm} syntax.
15414 @end deffn
15415
15416 @geindex gccjit;;extended_asm;;add_output_operand (C++ function)
15417 @anchor{cp/topics/asm _CPPv4N6gccjit12extended_asm18add_output_operandERKNSt6stringERKNSt6stringEN6gccjit6lvalueE}@anchor{393}@anchor{cp/topics/asm _CPPv3N6gccjit12extended_asm18add_output_operandERKNSt6stringERKNSt6stringEN6gccjit6lvalueE}@anchor{3a3}@anchor{cp/topics/asm _CPPv2N6gccjit12extended_asm18add_output_operandERKNSt6stringERKNSt6stringEN6gccjit6lvalueE}@anchor{3a4}@anchor{cp/topics/asm gccjit extended_asm add_output_operand__ssCR ssCR gccjit lvalue}@anchor{3a5}
15418 @deffn {C++ Function} gccjit::@ref{38d,,extended_asm} &gccjit::@ref{38d,,extended_asm}::add_output_operand (const std::string &asm_symbolic_name, const std::string &constraint, gccjit::lvalue dest)
15419
15420 Add an output operand to the extended @code{asm} statement. See the
15421 Output Operands@footnote{https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#OutputOperands}
15422 section of the documentation of the C syntax.
15423
15424 @code{asm_symbolic_name} corresponds to the @code{asmSymbolicName} component of
15425 C’s extended @code{asm} syntax, and specifies the symbolic name for the operand.
15426 See the overload below for an alternative that does not supply a symbolic
15427 name.
15428
15429 @code{constraint} corresponds to the @code{constraint} component of C’s extended
15430 @code{asm} syntax.
15431
15432 @code{dest} corresponds to the @code{cvariablename} component of C’s extended
15433 @code{asm} syntax.
15434
15435 @example
15436 // Example with a symbolic name ("aIndex"), the equivalent of:
15437 // : [aIndex] "=r" (index)
15438 ext_asm.add_output_operand ("aIndex", "=r", index);
15439 @end example
15440
15441 This function can’t be called on an @code{asm goto} as such instructions can’t
15442 have outputs; see the
15443 Goto Labels@footnote{https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#GotoLabels}
15444 section of GCC’s “Extended Asm” documentation.
15445 @end deffn
15446
15447 @geindex gccjit;;extended_asm;;add_output_operand (C++ function)
15448 @anchor{cp/topics/asm _CPPv4N6gccjit12extended_asm18add_output_operandERKNSt6stringEN6gccjit6lvalueE}@anchor{3a6}@anchor{cp/topics/asm _CPPv3N6gccjit12extended_asm18add_output_operandERKNSt6stringEN6gccjit6lvalueE}@anchor{3a7}@anchor{cp/topics/asm _CPPv2N6gccjit12extended_asm18add_output_operandERKNSt6stringEN6gccjit6lvalueE}@anchor{3a8}@anchor{cp/topics/asm gccjit extended_asm add_output_operand__ssCR gccjit lvalue}@anchor{3a9}
15449 @deffn {C++ Function} gccjit::@ref{38d,,extended_asm} &gccjit::@ref{38d,,extended_asm}::add_output_operand (const std::string &constraint, gccjit::lvalue dest)
15450
15451 As above, but don’t supply a symbolic name for the operand.
15452
15453 @example
15454 // Example without a symbolic name, the equivalent of:
15455 // : "=r" (dst)
15456 ext_asm.add_output_operand ("=r", dst);
15457 @end example
15458 @end deffn
15459
15460 @geindex gccjit;;extended_asm;;add_input_operand (C++ function)
15461 @anchor{cp/topics/asm _CPPv4N6gccjit12extended_asm17add_input_operandERKNSt6stringERKNSt6stringEN6gccjit6rvalueE}@anchor{394}@anchor{cp/topics/asm _CPPv3N6gccjit12extended_asm17add_input_operandERKNSt6stringERKNSt6stringEN6gccjit6rvalueE}@anchor{3aa}@anchor{cp/topics/asm _CPPv2N6gccjit12extended_asm17add_input_operandERKNSt6stringERKNSt6stringEN6gccjit6rvalueE}@anchor{3ab}@anchor{cp/topics/asm gccjit extended_asm add_input_operand__ssCR ssCR gccjit rvalue}@anchor{3ac}
15462 @deffn {C++ Function} gccjit::@ref{38d,,extended_asm} &gccjit::@ref{38d,,extended_asm}::add_input_operand (const std::string &asm_symbolic_name, const std::string &constraint, gccjit::rvalue src)
15463
15464 Add an input operand to the extended @code{asm} statement. See the
15465 Input Operands@footnote{https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#InputOperands}
15466 section of the documentation of the C syntax.
15467
15468 @code{asm_symbolic_name} corresponds to the @code{asmSymbolicName} component
15469 of C’s extended @code{asm} syntax. See the overload below for an alternative
15470 that does not supply a symbolic name.
15471
15472 @code{constraint} corresponds to the @code{constraint} component of C’s extended
15473 @code{asm} syntax.
15474
15475 @code{src} corresponds to the @code{cexpression} component of C’s extended
15476 @code{asm} syntax.
15477
15478 @example
15479 // Example with a symbolic name ("aMask"), the equivalent of:
15480 // : [aMask] "r" (Mask)
15481 ext_asm.add_input_operand ("aMask", "r", mask);
15482 @end example
15483 @end deffn
15484
15485 @geindex gccjit;;extended_asm;;add_input_operand (C++ function)
15486 @anchor{cp/topics/asm _CPPv4N6gccjit12extended_asm17add_input_operandERKNSt6stringEN6gccjit6rvalueE}@anchor{3ad}@anchor{cp/topics/asm _CPPv3N6gccjit12extended_asm17add_input_operandERKNSt6stringEN6gccjit6rvalueE}@anchor{3ae}@anchor{cp/topics/asm _CPPv2N6gccjit12extended_asm17add_input_operandERKNSt6stringEN6gccjit6rvalueE}@anchor{3af}@anchor{cp/topics/asm gccjit extended_asm add_input_operand__ssCR gccjit rvalue}@anchor{3b0}
15487 @deffn {C++ Function} gccjit::@ref{38d,,extended_asm} &gccjit::@ref{38d,,extended_asm}::add_input_operand (const std::string &constraint, gccjit::rvalue src)
15488
15489 As above, but don’t supply a symbolic name for the operand.
15490
15491 @example
15492 // Example without a symbolic name, the equivalent of:
15493 // : "r" (src)
15494 ext_asm.add_input_operand ("r", src);
15495 @end example
15496 @end deffn
15497
15498 @geindex gccjit;;extended_asm;;add_clobber (C++ function)
15499 @anchor{cp/topics/asm _CPPv4N6gccjit12extended_asm11add_clobberERKNSt6stringE}@anchor{3b1}@anchor{cp/topics/asm _CPPv3N6gccjit12extended_asm11add_clobberERKNSt6stringE}@anchor{3b2}@anchor{cp/topics/asm _CPPv2N6gccjit12extended_asm11add_clobberERKNSt6stringE}@anchor{3b3}@anchor{cp/topics/asm gccjit extended_asm add_clobber__ssCR}@anchor{3b4}
15500 @deffn {C++ Function} gccjit::@ref{38d,,extended_asm} &gccjit::@ref{38d,,extended_asm}::add_clobber (const std::string &victim)
15501
15502 Add @cite{victim} to the list of registers clobbered by the extended @code{asm}
15503 statement. See the
15504 Clobbers and Scratch Registers@footnote{https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html#Clobbers-and-Scratch-Registers#}
15505 section of the documentation of the C syntax.
15506
15507 Statements with multiple clobbers will require multiple calls, one per
15508 clobber.
15509
15510 For example:
15511
15512 @example
15513 ext_asm.add_clobber ("r0").add_clobber ("cc").add_clobber ("memory");
15514 @end example
15515 @end deffn
15516
15517 @node Adding top-level assembler statements<2>,,Adding assembler instructions within a function<2>,Using Assembly Language with libgccjit++
15518 @anchor{cp/topics/asm adding-top-level-assembler-statements}@anchor{3b5}
15519 @subsubsection Adding top-level assembler statements
15520
15521
15522 In addition to creating extended @code{asm} instructions within a function,
15523 there is support for creating “top-level” assembler statements, outside
15524 of any function.
15525
15526 @geindex gccjit;;context;;add_top_level_asm (C++ function)
15527 @anchor{cp/topics/asm _CPPv4N6gccjit7context17add_top_level_asmEPKcN6gccjit8locationE}@anchor{3b6}@anchor{cp/topics/asm _CPPv3N6gccjit7context17add_top_level_asmEPKcN6gccjit8locationE}@anchor{3b7}@anchor{cp/topics/asm _CPPv2N6gccjit7context17add_top_level_asmEPKcN6gccjit8locationE}@anchor{3b8}@anchor{cp/topics/asm gccjit context add_top_level_asm__cCP gccjit location}@anchor{3b9}
15528 @deffn {C++ Function} void gccjit::@ref{175,,context}::add_top_level_asm (const char *asm_stmts, gccjit::location loc = location())
15529
15530 Create a set of top-level asm statements, analogous to those created
15531 by GCC’s “basic” @code{asm} syntax in C at file scope.
15532
15533 For example, to create the equivalent of:
15534
15535 @example
15536 asm ("\t.pushsection .text\n"
15537 "\t.globl add_asm\n"
15538 "\t.type add_asm, @@function\n"
15539 "add_asm:\n"
15540 "\tmovq %rdi, %rax\n"
15541 "\tadd %rsi, %rax\n"
15542 "\tret\n"
15543 "\t.popsection\n");
15544 @end example
15545
15546 the following API calls could be used:
15547
15548 @example
15549 ctxt.add_top_level_asm ("\t.pushsection .text\n"
15550 "\t.globl add_asm\n"
15551 "\t.type add_asm, @@function\n"
15552 "add_asm:\n"
15553 "\tmovq %rdi, %rax\n"
15554 "\tadd %rsi, %rax\n"
15555 "\tret\n"
15556 "\t# some asm here\n"
15557 "\t.popsection\n");
15558 @end example
15559 @end deffn
15560
15561 @c Copyright (C) 2014-2022 Free Software Foundation, Inc.
15562 @c Originally contributed by David Malcolm <[email protected]>
15563 @c
15564 @c This is free software: you can redistribute it and/or modify it
15565 @c under the terms of the GNU General Public License as published by
15566 @c the Free Software Foundation, either version 3 of the License, or
15567 @c (at your option) any later version.
15568 @c
15569 @c This program is distributed in the hope that it will be useful, but
15570 @c WITHOUT ANY WARRANTY; without even the implied warranty of
15571 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15572 @c General Public License for more details.
15573 @c
15574 @c You should have received a copy of the GNU General Public License
15575 @c along with this program. If not, see
15576 @c <https://www.gnu.org/licenses/>.
15577
15578 @node Internals,Indices and tables,C++ bindings for libgccjit,Top
15579 @anchor{internals/index doc}@anchor{3ba}@anchor{internals/index internals}@anchor{3bb}
15580 @chapter Internals
15581
15582
15583 @menu
15584 * Working on the JIT library::
15585 * Running the test suite::
15586 * Environment variables::
15587 * Packaging notes::
15588 * Overview of code structure::
15589 * Design notes::
15590 * Submitting patches::
15591
15592 @end menu
15593
15594 @node Working on the JIT library,Running the test suite,,Internals
15595 @anchor{internals/index working-on-the-jit-library}@anchor{3bc}
15596 @section Working on the JIT library
15597
15598
15599 Having checked out the source code (to “src”), you can configure and build
15600 the JIT library like this:
15601
15602 @example
15603 mkdir build
15604 mkdir install
15605 PREFIX=$(pwd)/install
15606 cd build
15607 ../src/configure \
15608 --enable-host-shared \
15609 --enable-languages=jit,c++ \
15610 --disable-bootstrap \
15611 --enable-checking=release \
15612 --prefix=$PREFIX
15613 nice make -j4 # altering the "4" to however many cores you have
15614 @end example
15615
15616 This should build a libgccjit.so within jit/build/gcc:
15617
15618 @example
15619 [build] $ file gcc/libgccjit.so*
15620 gcc/libgccjit.so: symbolic link to `libgccjit.so.0'
15621 gcc/libgccjit.so.0: symbolic link to `libgccjit.so.0.0.1'
15622 gcc/libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, not stripped
15623 @end example
15624
15625 Here’s what those configuration options mean:
15626
15627 @geindex command line option; --enable-host-shared
15628 @anchor{internals/index cmdoption-enable-host-shared}@anchor{3bd}
15629 @deffn {Option} @w{-}@w{-}enable@w{-}host@w{-}shared
15630
15631 Configuring with this option means that the compiler is built as
15632 position-independent code, which incurs a slight performance hit,
15633 but it necessary for a shared library.
15634 @end deffn
15635
15636 @geindex command line option; --enable-languages=jit@comma{}c++
15637 @anchor{internals/index cmdoption-enable-languages}@anchor{3be}
15638 @deffn {Option} @w{-}@w{-}enable@w{-}languages=jit,c++
15639
15640 This specifies which frontends to build. The JIT library looks like
15641 a frontend to the rest of the code.
15642
15643 The C++ portion of the JIT test suite requires the C++ frontend to be
15644 enabled at configure-time, or you may see errors like this when
15645 running the test suite:
15646
15647 @example
15648 xgcc: error: /home/david/jit/src/gcc/testsuite/jit.dg/test-quadratic.cc: C++ compiler not installed on this system
15649 c++: error trying to exec 'cc1plus': execvp: No such file or directory
15650 @end example
15651 @end deffn
15652
15653 @geindex command line option; --disable-bootstrap
15654 @anchor{internals/index cmdoption-disable-bootstrap}@anchor{3bf}
15655 @deffn {Option} @w{-}@w{-}disable@w{-}bootstrap
15656
15657 For hacking on the “jit” subdirectory, performing a full
15658 bootstrap can be overkill, since it’s unused by a bootstrap. However,
15659 when submitting patches, you should remove this option, to ensure that
15660 the compiler can still bootstrap itself.
15661 @end deffn
15662
15663 @geindex command line option; --enable-checking=release
15664 @anchor{internals/index cmdoption-enable-checking}@anchor{3c0}
15665 @deffn {Option} @w{-}@w{-}enable@w{-}checking=release
15666
15667 The compile can perform extensive self-checking as it runs, useful when
15668 debugging, but slowing things down.
15669
15670 For maximum speed, configure with @code{--enable-checking=release} to
15671 disable this self-checking.
15672 @end deffn
15673
15674 @node Running the test suite,Environment variables,Working on the JIT library,Internals
15675 @anchor{internals/index running-the-test-suite}@anchor{3c1}
15676 @section Running the test suite
15677
15678
15679 @example
15680 [build] $ cd gcc
15681 [gcc] $ make check-jit RUNTESTFLAGS="-v -v -v"
15682 @end example
15683
15684 A summary of the tests can then be seen in:
15685
15686 @example
15687 jit/build/gcc/testsuite/jit/jit.sum
15688 @end example
15689
15690 and detailed logs in:
15691
15692 @example
15693 jit/build/gcc/testsuite/jit/jit.log
15694 @end example
15695
15696 The test executables are normally deleted after each test is run. For
15697 debugging, they can be preserved by setting
15698 @geindex PRESERVE_EXECUTABLES
15699 @geindex environment variable; PRESERVE_EXECUTABLES
15700 @code{PRESERVE_EXECUTABLES}
15701 in the environment. If so, they can then be seen as:
15702
15703 @example
15704 jit/build/gcc/testsuite/jit/*.exe
15705 @end example
15706
15707 which can be run independently.
15708
15709 You can compile and run individual tests by passing “jit.exp=TESTNAME” to RUNTESTFLAGS e.g.:
15710
15711 @example
15712 [gcc] $ PRESERVE_EXECUTABLES= \
15713 make check-jit \
15714 RUNTESTFLAGS="-v -v -v jit.exp=test-factorial.c"
15715 @end example
15716
15717 and once a test has been compiled, you can debug it directly:
15718
15719 @example
15720 [gcc] $ PATH=.:$PATH \
15721 LD_LIBRARY_PATH=. \
15722 LIBRARY_PATH=. \
15723 gdb --args \
15724 testsuite/jit/test-factorial.c.exe
15725 @end example
15726
15727 @menu
15728 * Running under valgrind::
15729
15730 @end menu
15731
15732 @node Running under valgrind,,,Running the test suite
15733 @anchor{internals/index running-under-valgrind}@anchor{3c2}
15734 @subsection Running under valgrind
15735
15736
15737 The jit testsuite detects if
15738 @geindex RUN_UNDER_VALGRIND
15739 @geindex environment variable; RUN_UNDER_VALGRIND
15740 @code{RUN_UNDER_VALGRIND} is present in the
15741 environment (with any value). If it is present, it runs the test client
15742 code under valgrind@footnote{https://valgrind.org},
15743 specifcally, the default
15744 memcheck@footnote{https://valgrind.org/docs/manual/mc-manual.html}
15745 tool with
15746 --leak-check=full@footnote{https://valgrind.org/docs/manual/mc-manual.html#opt.leak-check}.
15747
15748 It automatically parses the output from valgrind, injecting XFAIL results if
15749 any issues are found, or PASS results if the output is clean. The output
15750 is saved to @code{TESTNAME.exe.valgrind.txt}.
15751
15752 For example, the following invocation verbosely runs the testcase
15753 @code{test-sum-of-squares.c} under valgrind, showing an issue:
15754
15755 @example
15756 $ RUN_UNDER_VALGRIND= \
15757 make check-jit \
15758 RUNTESTFLAGS="-v -v -v jit.exp=test-sum-of-squares.c"
15759
15760 (...verbose log contains detailed valgrind errors, if any...)
15761
15762 === jit Summary ===
15763
15764 # of expected passes 28
15765 # of expected failures 2
15766
15767 $ less testsuite/jit/jit.sum
15768 (...other results...)
15769 XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.c.exe.valgrind.txt: definitely lost: 8 bytes in 1 blocks
15770 XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.c.exe.valgrind.txt: unsuppressed errors: 1
15771 (...other results...)
15772
15773 $ less testsuite/jit/test-sum-of-squares.c.exe.valgrind.txt
15774 (...shows full valgrind report for this test case...)
15775 @end example
15776
15777 When running under valgrind, it’s best to have configured gcc with
15778 @code{--enable-valgrind-annotations}, which automatically suppresses
15779 various known false positives.
15780
15781 @node Environment variables,Packaging notes,Running the test suite,Internals
15782 @anchor{internals/index environment-variables}@anchor{3c3}
15783 @section Environment variables
15784
15785
15786 When running client code against a locally-built libgccjit, three
15787 environment variables need to be set up:
15788
15789 @geindex environment variable; LD_LIBRARY_PATH
15790 @anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{3c4}
15791 @deffn {Environment Variable} LD_LIBRARY_PATH
15792
15793 @quotation
15794
15795 @cite{libgccjit.so} is dynamically linked into client code, so if running
15796 against a locally-built library, @code{LD_LIBRARY_PATH} needs to be set
15797 up appropriately. The library can be found within the “gcc”
15798 subdirectory of the build tree:
15799 @end quotation
15800
15801 @example
15802 $ file libgccjit.so*
15803 libgccjit.so: symbolic link to `libgccjit.so.0'
15804 libgccjit.so.0: symbolic link to `libgccjit.so.0.0.1'
15805 libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (GNU/Linux), dynamically linked, not stripped
15806 @end example
15807 @end deffn
15808
15809 @geindex environment variable; PATH
15810 @anchor{internals/index envvar-PATH}@anchor{3c5}
15811 @deffn {Environment Variable} PATH
15812
15813 The library uses a driver executable for converting from .s assembler
15814 files to .so shared libraries. Specifically, it looks for a name
15815 expanded from
15816 @code{$@{target_noncanonical@}-gcc-$@{gcc_BASEVER@}$@{exeext@}}
15817 such as @code{x86_64-unknown-linux-gnu-gcc-5.0.0}.
15818
15819 Hence @code{PATH} needs to include a directory where the library can
15820 locate this executable.
15821
15822 The executable is normally installed to the installation bindir
15823 (e.g. /usr/bin), but a copy is also created within the “gcc”
15824 subdirectory of the build tree for running the testsuite, and for ease
15825 of development.
15826 @end deffn
15827
15828 @geindex environment variable; LIBRARY_PATH
15829 @anchor{internals/index envvar-LIBRARY_PATH}@anchor{3c6}
15830 @deffn {Environment Variable} LIBRARY_PATH
15831
15832 The driver executable invokes the linker, and the latter needs to locate
15833 support libraries needed by the generated code, or you will see errors
15834 like:
15835
15836 @example
15837 ld: cannot find crtbeginS.o: No such file or directory
15838 ld: cannot find -lgcc
15839 ld: cannot find -lgcc_s
15840 @end example
15841
15842 Hence if running directly from a locally-built copy (without installing),
15843 @code{LIBRARY_PATH} needs to contain the “gcc” subdirectory of the build
15844 tree.
15845 @end deffn
15846
15847 For example, to run a binary that uses the library against a non-installed
15848 build of the library in LIBGCCJIT_BUILD_DIR you need an invocation of the
15849 client code like this, to preprend the dir to each of the environment
15850 variables:
15851
15852 @example
15853 $ LD_LIBRARY_PATH=$(LIBGCCJIT_BUILD_DIR):$(LD_LIBRARY_PATH) \
15854 PATH=$(LIBGCCJIT_BUILD_DIR):$(PATH) \
15855 LIBRARY_PATH=$(LIBGCCJIT_BUILD_DIR):$(LIBRARY_PATH) \
15856 ./jit-hello-world
15857 hello world
15858 @end example
15859
15860 @node Packaging notes,Overview of code structure,Environment variables,Internals
15861 @anchor{internals/index packaging-notes}@anchor{3c7}
15862 @section Packaging notes
15863
15864
15865 The configure-time option @ref{3bd,,--enable-host-shared} is needed when
15866 building the jit in order to get position-independent code. This will
15867 slow down the regular compiler by a few percent. Hence when packaging gcc
15868 with libgccjit, please configure and build twice:
15869
15870 @quotation
15871
15872
15873 @itemize *
15874
15875 @item
15876 once without @ref{3bd,,--enable-host-shared} for most languages, and
15877
15878 @item
15879 once with @ref{3bd,,--enable-host-shared} for the jit
15880 @end itemize
15881 @end quotation
15882
15883 For example:
15884
15885 @example
15886 # Configure and build with --enable-host-shared
15887 # for the jit:
15888 mkdir configuration-for-jit
15889 pushd configuration-for-jit
15890 $(SRCDIR)/configure \
15891 --enable-host-shared \
15892 --enable-languages=jit \
15893 --prefix=$(DESTDIR)
15894 make
15895 popd
15896
15897 # Configure and build *without* --enable-host-shared
15898 # for maximum speed:
15899 mkdir standard-configuration
15900 pushd standard-configuration
15901 $(SRCDIR)/configure \
15902 --enable-languages=all \
15903 --prefix=$(DESTDIR)
15904 make
15905 popd
15906
15907 # Both of the above are configured to install to $(DESTDIR)
15908 # Install the configuration with --enable-host-shared first
15909 # *then* the one without, so that the faster build
15910 # of "cc1" et al overwrites the slower build.
15911 pushd configuration-for-jit
15912 make install
15913 popd
15914
15915 pushd standard-configuration
15916 make install
15917 popd
15918 @end example
15919
15920 @node Overview of code structure,Design notes,Packaging notes,Internals
15921 @anchor{internals/index overview-of-code-structure}@anchor{3c8}
15922 @section Overview of code structure
15923
15924
15925 The library is implemented in C++. The source files have the @code{.c}
15926 extension for legacy reasons.
15927
15928
15929 @itemize *
15930
15931 @item
15932 @code{libgccjit.cc} implements the API entrypoints. It performs error
15933 checking, then calls into classes of the gcc::jit::recording namespace
15934 within @code{jit-recording.cc} and @code{jit-recording.h}.
15935
15936 @item
15937 The gcc::jit::recording classes (within @code{jit-recording.cc} and
15938 @code{jit-recording.h}) record the API calls that are made:
15939
15940 @quotation
15941
15942 @example
15943
15944 /* Indentation indicates inheritance: */
15945 class context;
15946 class memento;
15947 class string;
15948 class location;
15949 class type;
15950 class function_type;
15951 class compound_type;
15952 class struct_;
15953 class union_;
15954 class vector_type;
15955 class field;
15956 class bitfield;
15957 class fields;
15958 class function;
15959 class block;
15960 class rvalue;
15961 class lvalue;
15962 class local;
15963 class global;
15964 class param;
15965 class base_call;
15966 class function_pointer;
15967 class statement;
15968 class extended_asm;
15969 class case_;
15970 class top_level_asm;
15971
15972 @end example
15973 @end quotation
15974
15975 @item
15976 When the context is compiled, the gcc::jit::playback classes (within
15977 @code{jit-playback.cc} and @code{jit-playback.h}) replay the API calls
15978 within langhook:parse_file:
15979
15980 @quotation
15981
15982 @example
15983
15984 /* Indentation indicates inheritance: */
15985 class context;
15986 class wrapper;
15987 class type;
15988 class compound_type;
15989 class field;
15990 class function;
15991 class block;
15992 class rvalue;
15993 class lvalue;
15994 class param;
15995 class source_file;
15996 class source_line;
15997 class location;
15998 class case_;
15999
16000 @end example
16001
16002 @example
16003 Client Code . Generated . libgccjit.so
16004 . code .
16005 . . JIT API . JIT "Frontend". (libbackend.a)
16006 ....................................................................................
16007 │ . . . .
16008 ──────────────────────────> . .
16009 . . │ . .
16010 . . V . .
16011 . . ──> libgccjit.cc .
16012 . . │ (error-checking).
16013 . . │ .
16014 . . ──> jit-recording.cc
16015 . . (record API calls)
16016 . . <─────── .
16017 . . │ . .
16018 <─────────────────────────── . .
16019 │ . . . .
16020 │ . . . .
16021 V . . gcc_jit_context_compile .
16022 ──────────────────────────> . .
16023 . . │ start of recording::context::compile ()
16024 . . │ . .
16025 . . │ start of playback::context::compile ()
16026 . . │ (create tempdir) .
16027 . . │ . .
16028 . . │ ACQUIRE MUTEX .
16029 . . │ . .
16030 . . V───────────────────────> toplev::main (for now)
16031 . . . . │
16032 . . . . (various code)
16033 . . . . │
16034 . . . . V
16035 . . . <───────────────── langhook:parse_file
16036 . . . │ .
16037 . . . │ (jit_langhook_parse_file)
16038 . . . │ .
16039 ..........................................│..................VVVVVVVVVVVVV...
16040 . . . │ . No GC in here
16041 . . . │ jit-playback.cc
16042 . . . │ (playback of API calls)
16043 . . . ───────────────> creation of functions,
16044 . . . . types, expression trees
16045 . . . <──────────────── etc
16046 . . . │(handle_locations: add locations to
16047 . . . │ linemap and associate them with trees)
16048 . . . │ .
16049 . . . │ . No GC in here
16050 ..........................................│..................AAAAAAAAAAAAA...
16051 . . . │ for each function
16052 . . . ──> postprocess
16053 . . . │ .
16054 . . . ────────────> cgraph_finalize_function
16055 . . . <────────────
16056 . . . <── .
16057 . . . │ .
16058 . . . ──────────────────> (end of
16059 . . . . │ langhook_parse_file)
16060 . . . . │
16061 . . . . (various code)
16062 . . . . │
16063 . . . . ↓
16064 . . . <───────────────── langhook:write_globals
16065 . . . │ .
16066 . . . │ (jit_langhook_write_globals)
16067 . . . │ .
16068 . . . │ .
16069 . . . ──────────────────> finalize_compilation_unit
16070 . . . . │
16071 . . . . (the middle─end and backend)
16072 . . . . ↓
16073 . . <───────────────────────────── end of toplev::main
16074 . . │ . .
16075 . . V───────────────────────> toplev::finalize
16076 . . . . │ (purge internal state)
16077 . . <──────────────────────── end of toplev::finalize
16078 . . │ . .
16079 . . V─> playback::context::postprocess:
16080 . . │ . .
16081 . . │ (assuming an in-memory compile):
16082 . . │ . .
16083 . . --> Convert assembler to DSO, via embedded
16084 . . copy of driver:
16085 . . driver::main ()
16086 . . invocation of "as"
16087 . . invocation of "ld"
16088 . . driver::finalize ()
16089 . . <----
16090 . . │ . .
16091 . . │ . Load DSO (dlopen "fake.so")
16092 . . │ . .
16093 . . │ . Bundle it up in a jit::result
16094 . . <── . .
16095 . . │ . .
16096 . . │ RELEASE MUTEX .
16097 . . │ . .
16098 . . │ end of playback::context::compile ()
16099 . . │ . .
16100 . . │ playback::context dtor
16101 . . ──> . .
16102 . . │ Normally we cleanup the tempdir here:
16103 . . │ ("fake.so" is unlinked from the
16104 . . │ filesystem at this point)
16105 . . │ If the client code requested debuginfo, the
16106 . . │ cleanup happens later (in gcc_jit_result_release)
16107 . . │ to make it easier on the debugger (see PR jit/64206)
16108 . . <── . .
16109 . . │ . .
16110 . . │ end of recording::context::compile ()
16111 <─────────────────────────── . .
16112 │ . . . .
16113 V . . gcc_jit_result_get_code .
16114 ──────────────────────────> . .
16115 . . │ dlsym () within loaded DSO
16116 <─────────────────────────── . .
16117 Get (void*). . . .
16118 │ . . . .
16119 │ Call it . . . .
16120 ───────────────> . . .
16121 . │ . . .
16122 . │ . . .
16123 <─────────────── . . .
16124 │ . . . .
16125 etc│ . . . .
16126 │ . . . .
16127 V . . gcc_jit_result_release .
16128 ──────────────────────────> . .
16129 . . │ dlclose () the loaded DSO
16130 . . │ (code becomes uncallable)
16131 . . │ . .
16132 . . │ If the client code requested debuginfo, then
16133 . . │ cleanup of the tempdir was delayed.
16134 . . │ If that was the case, clean it up now.
16135 <─────────────────────────── . .
16136 │ . . . .
16137 @end example
16138 @end quotation
16139 @end itemize
16140
16141 Here is a high-level summary from @code{jit-common.h}:
16142
16143 @quotation
16144
16145 In order to allow jit objects to be usable outside of a compile
16146 whilst working with the existing structure of GCC’s code the
16147 C API is implemented in terms of a gcc::jit::recording::context,
16148 which records the calls made to it.
16149
16150 When a gcc_jit_context is compiled, the recording context creates a
16151 playback context. The playback context invokes the bulk of the GCC
16152 code, and within the “frontend” parsing hook, plays back the recorded
16153 API calls, creating GCC tree objects.
16154
16155 So there are two parallel families of classes: those relating to
16156 recording, and those relating to playback:
16157
16158
16159 @itemize *
16160
16161 @item
16162 Visibility: recording objects are exposed back to client code,
16163 whereas playback objects are internal to the library.
16164
16165 @item
16166 Lifetime: recording objects have a lifetime equal to that of the
16167 recording context that created them, whereas playback objects only
16168 exist within the frontend hook.
16169
16170 @item
16171 Memory allocation: recording objects are allocated by the recording
16172 context, and automatically freed by it when the context is released,
16173 whereas playback objects are allocated within the GC heap, and
16174 garbage-collected; they can own GC-references.
16175
16176 @item
16177 Integration with rest of GCC: recording objects are unrelated to the
16178 rest of GCC, whereas playback objects are wrappers around “tree”
16179 instances. Hence you can’t ask a recording rvalue or lvalue what its
16180 type is, whereas you can for a playback rvalue of lvalue (since it
16181 can work with the underlying GCC tree nodes).
16182
16183 @item
16184 Instancing: There can be multiple recording contexts “alive” at once
16185 (albeit it only one compiling at once), whereas there can only be one
16186 playback context alive at one time (since it interacts with the GC).
16187 @end itemize
16188
16189 Ultimately if GCC could support multiple GC heaps and contexts, and
16190 finer-grained initialization, then this recording vs playback
16191 distinction could be eliminated.
16192
16193 During a playback, we associate objects from the recording with
16194 their counterparts during this playback. For simplicity, we store this
16195 within the recording objects, as @code{void *m_playback_obj}, casting it to
16196 the appropriate playback object subclass. For these casts to make
16197 sense, the two class hierarchies need to have the same structure.
16198
16199 Note that the playback objects that @code{m_playback_obj} points to are
16200 GC-allocated, but the recording objects don’t own references:
16201 these associations only exist within a part of the code where
16202 the GC doesn’t collect, and are set back to NULL before the GC can
16203 run.
16204 @end quotation
16205 @anchor{internals/index example-of-log-file}@anchor{5c}
16206 Another way to understand the structure of the code is to enable logging,
16207 via @ref{5b,,gcc_jit_context_set_logfile()}. Here is an example of a log
16208 generated via this call:
16209
16210 @example
16211 JIT: libgccjit (GCC) version 6.0.0 20150803 (experimental) (x86_64-pc-linux-gnu)
16212 JIT: compiled by GNU C version 4.8.3 20140911 (Red Hat 4.8.3-7), GMP version 5.1.2, MPFR version 3.1.2, MPC version 1.0.1
16213 JIT: entering: gcc_jit_context_set_str_option
16214 JIT: GCC_JIT_STR_OPTION_PROGNAME: "./test-hello-world.c.exe"
16215 JIT: exiting: gcc_jit_context_set_str_option
16216 JIT: entering: gcc_jit_context_set_int_option
16217 JIT: GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL: 3
16218 JIT: exiting: gcc_jit_context_set_int_option
16219 JIT: entering: gcc_jit_context_set_bool_option
16220 JIT: GCC_JIT_BOOL_OPTION_DEBUGINFO: true
16221 JIT: exiting: gcc_jit_context_set_bool_option
16222 JIT: entering: gcc_jit_context_set_bool_option
16223 JIT: GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE: false
16224 JIT: exiting: gcc_jit_context_set_bool_option
16225 JIT: entering: gcc_jit_context_set_bool_option
16226 JIT: GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE: false
16227 JIT: exiting: gcc_jit_context_set_bool_option
16228 JIT: entering: gcc_jit_context_set_bool_option
16229 JIT: GCC_JIT_BOOL_OPTION_SELFCHECK_GC: true
16230 JIT: exiting: gcc_jit_context_set_bool_option
16231 JIT: entering: gcc_jit_context_set_bool_option
16232 JIT: GCC_JIT_BOOL_OPTION_DUMP_SUMMARY: false
16233 JIT: exiting: gcc_jit_context_set_bool_option
16234 JIT: entering: gcc_jit_context_get_type
16235 JIT: exiting: gcc_jit_context_get_type
16236 JIT: entering: gcc_jit_context_get_type
16237 JIT: exiting: gcc_jit_context_get_type
16238 JIT: entering: gcc_jit_context_new_param
16239 JIT: exiting: gcc_jit_context_new_param
16240 JIT: entering: gcc_jit_context_new_function
16241 JIT: exiting: gcc_jit_context_new_function
16242 JIT: entering: gcc_jit_context_new_param
16243 JIT: exiting: gcc_jit_context_new_param
16244 JIT: entering: gcc_jit_context_get_type
16245 JIT: exiting: gcc_jit_context_get_type
16246 JIT: entering: gcc_jit_context_new_function
16247 JIT: exiting: gcc_jit_context_new_function
16248 JIT: entering: gcc_jit_context_new_string_literal
16249 JIT: exiting: gcc_jit_context_new_string_literal
16250 JIT: entering: gcc_jit_function_new_block
16251 JIT: exiting: gcc_jit_function_new_block
16252 JIT: entering: gcc_jit_block_add_comment
16253 JIT: exiting: gcc_jit_block_add_comment
16254 JIT: entering: gcc_jit_context_new_call
16255 JIT: exiting: gcc_jit_context_new_call
16256 JIT: entering: gcc_jit_block_add_eval
16257 JIT: exiting: gcc_jit_block_add_eval
16258 JIT: entering: gcc_jit_block_end_with_void_return
16259 JIT: exiting: gcc_jit_block_end_with_void_return
16260 JIT: entering: gcc_jit_context_dump_reproducer_to_file
16261 JIT: entering: void gcc::jit::recording::context::dump_reproducer_to_file(const char*)
16262 JIT: exiting: void gcc::jit::recording::context::dump_reproducer_to_file(const char*)
16263 JIT: exiting: gcc_jit_context_dump_reproducer_to_file
16264 JIT: entering: gcc_jit_context_compile
16265 JIT: in-memory compile of ctxt: 0x1283e20
16266 JIT: entering: gcc::jit::result* gcc::jit::recording::context::compile()
16267 JIT: GCC_JIT_STR_OPTION_PROGNAME: "./test-hello-world.c.exe"
16268 JIT: GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL: 3
16269 JIT: GCC_JIT_BOOL_OPTION_DEBUGINFO: true
16270 JIT: GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE: false
16271 JIT: GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE: false
16272 JIT: GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE: false
16273 JIT: GCC_JIT_BOOL_OPTION_DUMP_SUMMARY: false
16274 JIT: GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING: false
16275 JIT: GCC_JIT_BOOL_OPTION_SELFCHECK_GC: true
16276 JIT: GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES: false
16277 JIT: gcc_jit_context_set_bool_allow_unreachable_blocks: false
16278 JIT: gcc_jit_context_set_bool_use_external_driver: false
16279 JIT: entering: void gcc::jit::recording::context::validate()
16280 JIT: exiting: void gcc::jit::recording::context::validate()
16281 JIT: entering: gcc::jit::playback::context::context(gcc::jit::recording::context*)
16282 JIT: exiting: gcc::jit::playback::context::context(gcc::jit::recording::context*)
16283 JIT: entering: gcc::jit::playback::compile_to_memory::compile_to_memory(gcc::jit::recording::context*)
16284 JIT: exiting: gcc::jit::playback::compile_to_memory::compile_to_memory(gcc::jit::recording::context*)
16285 JIT: entering: void gcc::jit::playback::context::compile()
16286 JIT: entering: gcc::jit::tempdir::tempdir(gcc::jit::logger*, int)
16287 JIT: exiting: gcc::jit::tempdir::tempdir(gcc::jit::logger*, int)
16288 JIT: entering: bool gcc::jit::tempdir::create()
16289 JIT: m_path_template: /tmp/libgccjit-XXXXXX
16290 JIT: m_path_tempdir: /tmp/libgccjit-CKq1M9
16291 JIT: exiting: bool gcc::jit::tempdir::create()
16292 JIT: entering: void gcc::jit::playback::context::acquire_mutex()
16293 JIT: exiting: void gcc::jit::playback::context::acquire_mutex()
16294 JIT: entering: void gcc::jit::playback::context::make_fake_args(vec<char*>*, const char*, vec<gcc::jit::recording::requested_dump>*)
16295 JIT: reusing cached configure-time options
16296 JIT: configure_time_options[0]: -mtune=generic
16297 JIT: configure_time_options[1]: -march=x86-64
16298 JIT: exiting: void gcc::jit::playback::context::make_fake_args(vec<char*>*, const char*, vec<gcc::jit::recording::requested_dump>*)
16299 JIT: entering: toplev::main
16300 JIT: argv[0]: ./test-hello-world.c.exe
16301 JIT: argv[1]: /tmp/libgccjit-CKq1M9/fake.c
16302 JIT: argv[2]: -fPIC
16303 JIT: argv[3]: -O3
16304 JIT: argv[4]: -g
16305 JIT: argv[5]: -quiet
16306 JIT: argv[6]: --param
16307 JIT: argv[7]: ggc-min-expand=0
16308 JIT: argv[8]: --param
16309 JIT: argv[9]: ggc-min-heapsize=0
16310 JIT: argv[10]: -mtune=generic
16311 JIT: argv[11]: -march=x86-64
16312 JIT: entering: bool jit_langhook_init()
16313 JIT: exiting: bool jit_langhook_init()
16314 JIT: entering: void gcc::jit::playback::context::replay()
16315 JIT: entering: void gcc::jit::recording::context::replay_into(gcc::jit::replayer*)
16316 JIT: exiting: void gcc::jit::recording::context::replay_into(gcc::jit::replayer*)
16317 JIT: entering: void gcc::jit::recording::context::disassociate_from_playback()
16318 JIT: exiting: void gcc::jit::recording::context::disassociate_from_playback()
16319 JIT: entering: void gcc::jit::playback::context::handle_locations()
16320 JIT: exiting: void gcc::jit::playback::context::handle_locations()
16321 JIT: entering: void gcc::jit::playback::function::build_stmt_list()
16322 JIT: exiting: void gcc::jit::playback::function::build_stmt_list()
16323 JIT: entering: void gcc::jit::playback::function::build_stmt_list()
16324 JIT: exiting: void gcc::jit::playback::function::build_stmt_list()
16325 JIT: entering: void gcc::jit::playback::function::postprocess()
16326 JIT: exiting: void gcc::jit::playback::function::postprocess()
16327 JIT: entering: void gcc::jit::playback::function::postprocess()
16328 JIT: exiting: void gcc::jit::playback::function::postprocess()
16329 JIT: exiting: void gcc::jit::playback::context::replay()
16330 JIT: exiting: toplev::main
16331 JIT: entering: void gcc::jit::playback::context::extract_any_requested_dumps(vec<gcc::jit::recording::requested_dump>*)
16332 JIT: exiting: void gcc::jit::playback::context::extract_any_requested_dumps(vec<gcc::jit::recording::requested_dump>*)
16333 JIT: entering: toplev::finalize
16334 JIT: exiting: toplev::finalize
16335 JIT: entering: virtual void gcc::jit::playback::compile_to_memory::postprocess(const char*)
16336 JIT: entering: void gcc::jit::playback::context::convert_to_dso(const char*)
16337 JIT: entering: void gcc::jit::playback::context::invoke_driver(const char*, const char*, const char*, timevar_id_t, bool, bool)
16338 JIT: entering: void gcc::jit::playback::context::add_multilib_driver_arguments(vec<char*>*)
16339 JIT: exiting: void gcc::jit::playback::context::add_multilib_driver_arguments(vec<char*>*)
16340 JIT: argv[0]: x86_64-unknown-linux-gnu-gcc-6.0.0
16341 JIT: argv[1]: -m64
16342 JIT: argv[2]: -shared
16343 JIT: argv[3]: /tmp/libgccjit-CKq1M9/fake.s
16344 JIT: argv[4]: -o
16345 JIT: argv[5]: /tmp/libgccjit-CKq1M9/fake.so
16346 JIT: argv[6]: -fno-use-linker-plugin
16347 JIT: entering: void gcc::jit::playback::context::invoke_embedded_driver(const vec<char*>*)
16348 JIT: exiting: void gcc::jit::playback::context::invoke_embedded_driver(const vec<char*>*)
16349 JIT: exiting: void gcc::jit::playback::context::invoke_driver(const char*, const char*, const char*, timevar_id_t, bool, bool)
16350 JIT: exiting: void gcc::jit::playback::context::convert_to_dso(const char*)
16351 JIT: entering: gcc::jit::result* gcc::jit::playback::context::dlopen_built_dso()
16352 JIT: GCC_JIT_BOOL_OPTION_DEBUGINFO was set: handing over tempdir to jit::result
16353 JIT: entering: gcc::jit::result::result(gcc::jit::logger*, void*, gcc::jit::tempdir*)
16354 JIT: exiting: gcc::jit::result::result(gcc::jit::logger*, void*, gcc::jit::tempdir*)
16355 JIT: exiting: gcc::jit::result* gcc::jit::playback::context::dlopen_built_dso()
16356 JIT: exiting: virtual void gcc::jit::playback::compile_to_memory::postprocess(const char*)
16357 JIT: entering: void gcc::jit::playback::context::release_mutex()
16358 JIT: exiting: void gcc::jit::playback::context::release_mutex()
16359 JIT: exiting: void gcc::jit::playback::context::compile()
16360 JIT: entering: gcc::jit::playback::context::~context()
16361 JIT: exiting: gcc::jit::playback::context::~context()
16362 JIT: exiting: gcc::jit::result* gcc::jit::recording::context::compile()
16363 JIT: gcc_jit_context_compile: returning (gcc_jit_result *)0x12f75d0
16364 JIT: exiting: gcc_jit_context_compile
16365 JIT: entering: gcc_jit_result_get_code
16366 JIT: locating fnname: hello_world
16367 JIT: entering: void* gcc::jit::result::get_code(const char*)
16368 JIT: exiting: void* gcc::jit::result::get_code(const char*)
16369 JIT: gcc_jit_result_get_code: returning (void *)0x7ff6b8cd87f0
16370 JIT: exiting: gcc_jit_result_get_code
16371 JIT: entering: gcc_jit_context_release
16372 JIT: deleting ctxt: 0x1283e20
16373 JIT: entering: gcc::jit::recording::context::~context()
16374 JIT: exiting: gcc::jit::recording::context::~context()
16375 JIT: exiting: gcc_jit_context_release
16376 JIT: entering: gcc_jit_result_release
16377 JIT: deleting result: 0x12f75d0
16378 JIT: entering: virtual gcc::jit::result::~result()
16379 JIT: entering: gcc::jit::tempdir::~tempdir()
16380 JIT: unlinking .s file: /tmp/libgccjit-CKq1M9/fake.s
16381 JIT: unlinking .so file: /tmp/libgccjit-CKq1M9/fake.so
16382 JIT: removing tempdir: /tmp/libgccjit-CKq1M9
16383 JIT: exiting: gcc::jit::tempdir::~tempdir()
16384 JIT: exiting: virtual gcc::jit::result::~result()
16385 JIT: exiting: gcc_jit_result_release
16386 JIT: gcc::jit::logger::~logger()
16387 @end example
16388
16389 @node Design notes,Submitting patches,Overview of code structure,Internals
16390 @anchor{internals/index design-notes}@anchor{3c9}
16391 @section Design notes
16392
16393
16394 It should not be possible for client code to cause an internal compiler
16395 error. If this @emph{does} happen, the root cause should be isolated (perhaps
16396 using @ref{5d,,gcc_jit_context_dump_reproducer_to_file()}) and the cause
16397 should be rejected via additional checking. The checking ideally should
16398 be within the libgccjit API entrypoints in libgccjit.cc, since this is as
16399 close as possible to the error; failing that, a good place is within
16400 @code{recording::context::validate ()} in jit-recording.cc.
16401
16402 @node Submitting patches,,Design notes,Internals
16403 @anchor{internals/index submitting-patches}@anchor{3ca}
16404 @section Submitting patches
16405
16406
16407 Please read the contribution guidelines for gcc at
16408 @indicateurl{https://gcc.gnu.org/contribute.html}.
16409
16410 Patches for the jit should be sent to both the
16411 @email{gcc-patches@@gcc.gnu.org} and @email{jit@@gcc.gnu.org} mailing lists,
16412 with “jit” and “PATCH” in the Subject line.
16413
16414 You don’t need to do a full bootstrap for code that just touches the
16415 @code{jit} and @code{testsuite/jit.dg} subdirectories. However, please run
16416 @code{make check-jit} before submitting the patch, and mention the results
16417 in your email (along with the host triple that the tests were run on).
16418
16419 A good patch should contain the information listed in the
16420 gcc contribution guide linked to above; for a @code{jit} patch, the patch
16421 shold contain:
16422
16423 @quotation
16424
16425
16426 @itemize *
16427
16428 @item
16429 the code itself (for example, a new API entrypoint will typically
16430 touch @code{libgccjit.h} and @code{.c}, along with support code in
16431 @code{jit-recording.[ch]} and @code{jit-playback.[ch]} as appropriate)
16432
16433 @item
16434 test coverage
16435
16436 @item
16437 documentation for the C API
16438
16439 @item
16440 documentation for the C++ API
16441 @end itemize
16442 @end quotation
16443
16444 A patch that adds new API entrypoints should also contain:
16445
16446 @quotation
16447
16448
16449 @itemize *
16450
16451 @item
16452 a feature macro in @code{libgccjit.h} so that client code that doesn’t
16453 use a “configure” mechanism can still easily detect the presence of
16454 the entrypoint. See e.g. @code{LIBGCCJIT_HAVE_SWITCH_STATEMENTS} (for
16455 a category of entrypoints) and
16456 @code{LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks}
16457 (for an individual entrypoint).
16458
16459 @item
16460 a new ABI tag containing the new symbols (in @code{libgccjit.map}), so
16461 that we can detect client code that uses them
16462
16463 @item
16464 Support for @ref{5d,,gcc_jit_context_dump_reproducer_to_file()}. Most
16465 jit testcases attempt to dump their contexts to a .c file; @code{jit.exp}
16466 then sanity-checks the generated c by compiling them (though
16467 not running them). A new API entrypoint
16468 needs to “know” how to write itself back out to C (by implementing
16469 @code{gcc::jit::recording::memento::write_reproducer} for the appropriate
16470 @code{memento} subclass).
16471
16472 @item
16473 C++ bindings for the new entrypoints (see @code{libgccjit++.h}); ideally
16474 with test coverage, though the C++ API test coverage is admittedly
16475 spotty at the moment
16476
16477 @item
16478 documentation for the new C entrypoints
16479
16480 @item
16481 documentation for the new C++ entrypoints
16482
16483 @item
16484 documentation for the new ABI tag (see @code{topics/compatibility.rst}).
16485 @end itemize
16486 @end quotation
16487
16488 Depending on the patch you can either extend an existing test case, or
16489 add a new test case. If you add an entirely new testcase: @code{jit.exp}
16490 expects jit testcases to begin with @code{test-}, or @code{test-error-} (for a
16491 testcase that generates an error on a @ref{8,,gcc_jit_context}).
16492
16493 Every new testcase that doesn’t generate errors should also touch
16494 @code{gcc/testsuite/jit.dg/all-non-failing-tests.h}:
16495
16496 @quotation
16497
16498
16499 @itemize *
16500
16501 @item
16502 Testcases that don’t generate errors should ideally be added to the
16503 @code{testcases} array in that file; this means that, in addition
16504 to being run standalone, they also get run within
16505 @code{test-combination.c} (which runs all successful tests inside one
16506 big @ref{8,,gcc_jit_context}), and @code{test-threads.c} (which runs all
16507 successful tests in one process, each one running in a different
16508 thread on a different @ref{8,,gcc_jit_context}).
16509
16510 @cartouche
16511 @quotation Note
16512 Given that exported functions within a @ref{8,,gcc_jit_context}
16513 must have unique names, and most testcases are run within
16514 @code{test-combination.c}, this means that every jit-compiled test
16515 function typically needs a name that’s unique across the entire
16516 test suite.
16517 @end quotation
16518 @end cartouche
16519
16520 @item
16521 Testcases that aren’t to be added to the @code{testcases} array should
16522 instead add a comment to the file clarifying why they’re not in that
16523 array. See the file for examples.
16524 @end itemize
16525 @end quotation
16526
16527 Typically a patch that touches the .rst documentation will also need the
16528 texinfo to be regenerated. You can do this with
16529 Sphinx 1.0@footnote{https://sphinx-doc.org/} or later by
16530 running @code{make texinfo} within @code{SRCDIR/gcc/jit/docs}. Don’t do this
16531 within the patch sent to the mailing list; it can often be relatively
16532 large and inconsequential (e.g. anchor renumbering), rather like generated
16533 “configure” changes from configure.ac. You can regenerate it when
16534 committing to svn.
16535
16536 @node Indices and tables,Index,Internals,Top
16537 @anchor{index indices-and-tables}@anchor{3cb}
16538 @unnumbered Indices and tables
16539
16540
16541
16542 @itemize *
16543
16544 @item
16545 genindex
16546
16547 @item
16548 modindex
16549
16550 @item
16551 search
16552 @end itemize
16553
16554 @c Some notes:
16555 @c
16556 @c The Sphinx C domain appears to lack explicit support for enum values,
16557 @c so I've been using :c:macro: for them.
16558 @c
16559 @c See https://sphinx-doc.org/domains.html#the-c-domain
16560
16561 @node Index,,Indices and tables,Top
16562 @unnumbered Index
16563
16564
16565 @printindex ge
16566
16567
16568 @c %**end of body
16569 @bye