Debian Codegraph @

gcc/jit/docs/intro/tutorial02.rst

raw
1 .. Copyright (C) 2014-2023 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <[email protected]>
3
4 This is free software: you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by
6 the Free Software Foundation, either version 3 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful, but
10 WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see
16 <https://www.gnu.org/licenses/>.
17
18 .. default-domain:: c
19
20 Tutorial part 2: Creating a trivial machine code function
21 ---------------------------------------------------------
22
23 Consider this C function:
24
25 .. code-block:: c
26
27 int square (int i)
28 {
29 return i * i;
30 }
31
32 How can we construct this at run-time using libgccjit?
33
34 First we need to include the relevant header:
35
36 .. code-block:: c
37
38 #include <libgccjit.h>
39
40 All state associated with compilation is associated with a
41 :c:expr:`gcc_jit_context *`.
42
43 Create one using :c:func:`gcc_jit_context_acquire`:
44
45 .. code-block:: c
46
47 gcc_jit_context *ctxt;
48 ctxt = gcc_jit_context_acquire ();
49
50 The JIT library has a system of types. It is statically-typed: every
51 expression is of a specific type, fixed at compile-time. In our example,
52 all of the expressions are of the C `int` type, so let's obtain this from
53 the context, as a :c:expr:`gcc_jit_type *`, using
54 :c:func:`gcc_jit_context_get_type`:
55
56 .. code-block:: c
57
58 gcc_jit_type *int_type =
59 gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
60
61 :c:expr:`gcc_jit_type *` is an example of a "contextual" object: every
62 entity in the API is associated with a :c:expr:`gcc_jit_context *`.
63
64 Memory management is easy: all such "contextual" objects are automatically
65 cleaned up for you when the context is released, using
66 :c:func:`gcc_jit_context_release`:
67
68 .. code-block:: c
69
70 gcc_jit_context_release (ctxt);
71
72 so you don't need to manually track and cleanup all objects, just the
73 contexts.
74
75 Although the API is C-based, there is a form of class hierarchy, which
76 looks like this::
77
78 +- gcc_jit_object
79 +- gcc_jit_location
80 +- gcc_jit_type
81 +- gcc_jit_struct
82 +- gcc_jit_field
83 +- gcc_jit_function
84 +- gcc_jit_block
85 +- gcc_jit_rvalue
86 +- gcc_jit_lvalue
87 +- gcc_jit_param
88
89 There are casting methods for upcasting from subclasses to parent classes.
90 For example, :c:func:`gcc_jit_type_as_object`:
91
92 .. code-block:: c
93
94 gcc_jit_object *obj = gcc_jit_type_as_object (int_type);
95
96 One thing you can do with a :c:expr:`gcc_jit_object *` is
97 to ask it for a human-readable description, using
98 :c:func:`gcc_jit_object_get_debug_string`:
99
100 .. code-block:: c
101
102 printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj));
103
104 giving this text on stdout:
105
106 .. code-block:: bash
107
108 obj: int
109
110 This is invaluable when debugging.
111
112 Let's create the function. To do so, we first need to construct
113 its single parameter, specifying its type and giving it a name,
114 using :c:func:`gcc_jit_context_new_param`:
115
116 .. code-block:: c
117
118 gcc_jit_param *param_i =
119 gcc_jit_context_new_param (ctxt, NULL, int_type, "i");
120
121 Now we can create the function, using
122 :c:func:`gcc_jit_context_new_function`:
123
124 .. code-block:: c
125
126 gcc_jit_function *func =
127 gcc_jit_context_new_function (ctxt, NULL,
128 GCC_JIT_FUNCTION_EXPORTED,
129 int_type,
130 "square",
131 1, &param_i,
132 0);
133
134 To define the code within the function, we must create basic blocks
135 containing statements.
136
137 Every basic block contains a list of statements, eventually terminated
138 by a statement that either returns, or jumps to another basic block.
139
140 Our function has no control-flow, so we just need one basic block:
141
142 .. code-block:: c
143
144 gcc_jit_block *block = gcc_jit_function_new_block (func, NULL);
145
146 Our basic block is relatively simple: it immediately terminates by
147 returning the value of an expression.
148
149 We can build the expression using :c:func:`gcc_jit_context_new_binary_op`:
150
151 .. code-block:: c
152
153 gcc_jit_rvalue *expr =
154 gcc_jit_context_new_binary_op (
155 ctxt, NULL,
156 GCC_JIT_BINARY_OP_MULT, int_type,
157 gcc_jit_param_as_rvalue (param_i),
158 gcc_jit_param_as_rvalue (param_i));
159
160 A :c:expr:`gcc_jit_rvalue *` is another example of a
161 :c:expr:`gcc_jit_object *` subclass. We can upcast it using
162 :c:func:`gcc_jit_rvalue_as_object` and as before print it with
163 :c:func:`gcc_jit_object_get_debug_string`.
164
165 .. code-block:: c
166
167 printf ("expr: %s\n",
168 gcc_jit_object_get_debug_string (
169 gcc_jit_rvalue_as_object (expr)));
170
171 giving this output:
172
173 .. code-block:: bash
174
175 expr: i * i
176
177 Creating the expression in itself doesn't do anything; we have to add
178 this expression to a statement within the block. In this case, we use it
179 to build a return statement, which terminates the basic block:
180
181 .. code-block:: c
182
183 gcc_jit_block_end_with_return (block, NULL, expr);
184
185 OK, we've populated the context. We can now compile it using
186 :c:func:`gcc_jit_context_compile`:
187
188 .. code-block:: c
189
190 gcc_jit_result *result;
191 result = gcc_jit_context_compile (ctxt);
192
193 and get a :c:expr:`gcc_jit_result *`.
194
195 At this point we're done with the context; we can release it:
196
197 .. code-block:: c
198
199 gcc_jit_context_release (ctxt);
200
201 We can now use :c:func:`gcc_jit_result_get_code` to look up a specific
202 machine code routine within the result, in this case, the function we
203 created above.
204
205 .. code-block:: c
206
207 void *fn_ptr = gcc_jit_result_get_code (result, "square");
208 if (!fn_ptr)
209 {
210 fprintf (stderr, "NULL fn_ptr");
211 goto error;
212 }
213
214 We can now cast the pointer to an appropriate function pointer type, and
215 then call it:
216
217 .. code-block:: c
218
219 typedef int (*fn_type) (int);
220 fn_type square = (fn_type)fn_ptr;
221 printf ("result: %d", square (5));
222
223 .. code-block:: bash
224
225 result: 25
226
227 Once we're done with the code, we can release the result:
228
229 .. code-block:: c
230
231 gcc_jit_result_release (result);
232
233 We can't call ``square`` anymore once we've released ``result``.
234
235
236 Error-handling
237 **************
238 Various kinds of errors are possible when using the API, such as
239 mismatched types in an assignment. You can only compile and get code
240 from a context if no errors occur.
241
242 Errors are printed on stderr; they typically contain the name of the API
243 entrypoint where the error occurred, and pertinent information on the
244 problem:
245
246 .. code-block:: console
247
248 ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *)
249
250 The API is designed to cope with errors without crashing, so you can get
251 away with having a single error-handling check in your code:
252
253 .. code-block:: c
254
255 void *fn_ptr = gcc_jit_result_get_code (result, "square");
256 if (!fn_ptr)
257 {
258 fprintf (stderr, "NULL fn_ptr");
259 goto error;
260 }
261
262 For more information, see the :ref:`error-handling guide <error-handling>`
263 within the Topic eference.
264
265
266 Options
267 *******
268
269 To get more information on what's going on, you can set debugging flags
270 on the context using :c:func:`gcc_jit_context_set_bool_option`.
271
272 .. (I'm deliberately not mentioning
273 :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE` here since I think
274 it's probably more of use to implementors than to users)
275
276 Setting :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE` will dump a
277 C-like representation to stderr when you compile (GCC's "GIMPLE"
278 representation):
279
280 .. code-block:: c
281
282 gcc_jit_context_set_bool_option (
283 ctxt,
284 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE,
285 1);
286 result = gcc_jit_context_compile (ctxt);
287
288 .. code-block:: c
289
290 square (signed int i)
291 {
292 signed int D.260;
293
294 entry:
295 D.260 = i * i;
296 return D.260;
297 }
298
299 We can see the generated machine code in assembler form (on stderr) by
300 setting :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE` on the context
301 before compiling:
302
303 .. code-block:: c
304
305 gcc_jit_context_set_bool_option (
306 ctxt,
307 GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
308 1);
309 result = gcc_jit_context_compile (ctxt);
310
311 .. code-block:: gas
312
313 .file "fake.c"
314 .text
315 .globl square
316 .type square, @function
317 square:
318 .LFB6:
319 .cfi_startproc
320 pushq %rbp
321 .cfi_def_cfa_offset 16
322 .cfi_offset 6, -16
323 movq %rsp, %rbp
324 .cfi_def_cfa_register 6
325 movl %edi, -4(%rbp)
326 .L14:
327 movl -4(%rbp), %eax
328 imull -4(%rbp), %eax
329 popq %rbp
330 .cfi_def_cfa 7, 8
331 ret
332 .cfi_endproc
333 .LFE6:
334 .size square, .-square
335 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2)"
336 .section .note.GNU-stack,"",@progbits
337
338 By default, no optimizations are performed, the equivalent of GCC's
339 `-O0` option. We can turn things up to e.g. `-O3` by calling
340 :c:func:`gcc_jit_context_set_int_option` with
341 :c:macro:`GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL`:
342
343 .. code-block:: c
344
345 gcc_jit_context_set_int_option (
346 ctxt,
347 GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL,
348 3);
349
350 .. code-block:: gas
351
352 .file "fake.c"
353 .text
354 .p2align 4,,15
355 .globl square
356 .type square, @function
357 square:
358 .LFB7:
359 .cfi_startproc
360 .L16:
361 movl %edi, %eax
362 imull %edi, %eax
363 ret
364 .cfi_endproc
365 .LFE7:
366 .size square, .-square
367 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2)"
368 .section .note.GNU-stack,"",@progbits
369
370 Naturally this has only a small effect on such a trivial function.
371
372
373 Full example
374 ************
375
376 Here's what the above looks like as a complete program:
377
378 .. literalinclude:: ../examples/tut02-square.c
379 :lines: 1-
380 :language: c
381
382 Building and running it:
383
384 .. code-block:: console
385
386 $ gcc \
387 tut02-square.c \
388 -o tut02-square \
389 -lgccjit
390
391 # Run the built program:
392 $ ./tut02-square
393 result: 25