Debian Codegraph @

gcc/jit/docs/topics/functions.rst

raw
1 .. Copyright (C) 2014-2025 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 Creating and using functions
21 ============================
22
23 Params
24 ------
25 .. type:: gcc_jit_param
26
27 A `gcc_jit_param` represents a parameter to a function.
28
29 .. function:: gcc_jit_param *\
30 gcc_jit_context_new_param (gcc_jit_context *ctxt,\
31 gcc_jit_location *loc,\
32 gcc_jit_type *type,\
33 const char *name)
34
35 In preparation for creating a function, create a new parameter of the
36 given type and name.
37
38 The parameter ``type`` must be non-`void`.
39
40 The parameter ``name`` must be non-NULL. The call takes a copy of the
41 underlying string, so it is valid to pass in a pointer to an on-stack
42 buffer.
43
44 Parameters are lvalues, and thus are also rvalues (and objects), so the
45 following upcasts are available:
46
47 .. function:: gcc_jit_lvalue *\
48 gcc_jit_param_as_lvalue (gcc_jit_param *param)
49
50 Upcasting from param to lvalue.
51
52 .. function:: gcc_jit_rvalue *\
53 gcc_jit_param_as_rvalue (gcc_jit_param *param)
54
55 Upcasting from param to rvalue.
56
57 .. function:: gcc_jit_object *\
58 gcc_jit_param_as_object (gcc_jit_param *param)
59
60 Upcasting from param to object.
61
62
63 Functions
64 ---------
65
66 .. type:: gcc_jit_function
67
68 A `gcc_jit_function` represents a function - either one that we're
69 creating ourselves, or one that we're referencing.
70
71 .. function:: gcc_jit_function *\
72 gcc_jit_context_new_function (gcc_jit_context *ctxt,\
73 gcc_jit_location *loc,\
74 enum gcc_jit_function_kind kind,\
75 gcc_jit_type *return_type,\
76 const char *name,\
77 int num_params,\
78 gcc_jit_param **params,\
79 int is_variadic)
80
81 Create a gcc_jit_function with the given name and parameters.
82
83 .. enum:: gcc_jit_function_kind
84
85 This enum controls the kind of function created, and has the following
86 values:
87
88 .. macro:: GCC_JIT_FUNCTION_EXPORTED
89
90 Function is defined by the client code and visible
91 by name outside of the JIT.
92
93 This value is required if you want to extract machine code
94 for this function from a :type:`gcc_jit_result` via
95 :func:`gcc_jit_result_get_code`.
96
97 .. macro:: GCC_JIT_FUNCTION_INTERNAL
98
99 Function is defined by the client code, but is invisible
100 outside of the JIT. Analogous to a "static" function.
101
102 .. macro:: GCC_JIT_FUNCTION_IMPORTED
103
104 Function is not defined by the client code; we're merely
105 referring to it. Analogous to using an "extern" function from a
106 header file.
107
108 .. macro:: GCC_JIT_FUNCTION_ALWAYS_INLINE
109
110 Function is only ever inlined into other functions, and is
111 invisible outside of the JIT.
112
113 Analogous to prefixing with ``inline`` and adding
114 ``__attribute__((always_inline))``
115
116 Inlining will only occur when the optimization level is
117 above 0; when optimization is off, this is essentially the
118 same as GCC_JIT_FUNCTION_INTERNAL.
119
120 The parameter ``name`` must be non-NULL. The call takes a copy of the
121 underlying string, so it is valid to pass in a pointer to an on-stack
122 buffer.
123
124 .. function:: gcc_jit_function *\
125 gcc_jit_context_get_builtin_function (gcc_jit_context *ctxt,\
126 const char *name)
127
128 Get the :type:`gcc_jit_function` for the built-in function with the
129 given name. For example:
130
131 .. code-block:: c
132
133 gcc_jit_function *fn
134 = gcc_jit_context_get_builtin_function (ctxt, "__builtin_memcpy");
135
136 .. note:: Due to technical limitations with how libgccjit interacts with
137 the insides of GCC, not all built-in functions are supported. More
138 precisely, not all types are supported for parameters of built-in
139 functions from libgccjit. Attempts to get a built-in function that
140 uses such a parameter will lead to an error being emitted within
141 the context.
142
143 .. function:: gcc_jit_function *\
144 gcc_jit_context_get_target_builtin_function (gcc_jit_context *ctxt,\
145 const char *name)
146
147 Get the :type:`gcc_jit_function` for the built-in function (sometimes called
148 intrinsic functions) with the given name. For example:
149
150 .. code-block:: c
151
152 gcc_jit_function *fn
153 = gcc_jit_context_get_target_builtin_function (ctxt, "__builtin_ia32_pmuldq512_mask");
154
155 .. note:: Due to technical limitations with how libgccjit interacts with
156 the insides of GCC, not all built-in functions are supported. More
157 precisely, not all types are supported for parameters of built-in
158 functions from libgccjit. Attempts to get a built-in function that
159 uses such a parameter will lead to an error being emitted within
160 the context.
161
162 .. function:: gcc_jit_object *\
163 gcc_jit_function_as_object (gcc_jit_function *func)
164
165 Upcasting from function to object.
166
167 .. function:: gcc_jit_param *\
168 gcc_jit_function_get_param (gcc_jit_function *func, int index)
169
170 Get the param of the given index (0-based).
171
172 .. function:: void \
173 gcc_jit_function_dump_to_dot (gcc_jit_function *func,\
174 const char *path)
175
176 Emit the function in graphviz format to the given path.
177
178 .. function:: gcc_jit_lvalue *\
179 gcc_jit_function_new_local (gcc_jit_function *func,\
180 gcc_jit_location *loc,\
181 gcc_jit_type *type,\
182 const char *name)
183
184 Create a new local variable within the function, of the given type and
185 name.
186
187 The parameter ``type`` must be non-`void`.
188
189 The parameter ``name`` must be non-NULL. The call takes a copy of the
190 underlying string, so it is valid to pass in a pointer to an on-stack
191 buffer.
192
193 .. function:: gcc_jit_lvalue *\
194 gcc_jit_function_new_temp (gcc_jit_function *func,\
195 gcc_jit_location *loc,\
196 gcc_jit_type *type)
197
198 Create a new local variable within the function, of the given type.
199 This function is similar to :func:`gcc_jit_function_new_local`, but
200 it is to be used for compiler-generated variables (as opposed to
201 user-defined variables in the language to be compiled) and these
202 variables won't show up in the debug info.
203
204 The parameter ``type`` must be non-`void`.
205
206 This entrypoint was added in :ref:`LIBGCCJIT_ABI_33`; you can test
207 for its presence using
208
209 .. code-block:: c
210
211 #ifdef LIBGCCJIT_HAVE_gcc_jit_function_new_temp
212
213 .. function:: size_t \
214 gcc_jit_function_get_param_count (gcc_jit_function *func)
215
216 Get the number of parameters of the function.
217
218 .. function:: gcc_jit_type *\
219 gcc_jit_function_get_return_type (gcc_jit_function *func)
220
221 Get the return type of the function.
222
223 The API entrypoints relating to getting info about parameters and return
224 types:
225
226 * :c:func:`gcc_jit_function_get_return_type`
227
228 * :c:func:`gcc_jit_function_get_param_count`
229
230 were added in :ref:`LIBGCCJIT_ABI_16`; you can test for their presence
231 using
232
233 .. code-block:: c
234
235 #ifdef LIBGCCJIT_HAVE_REFLECTION
236
237 .. type:: gcc_jit_case
238
239 .. function:: void\
240 gcc_jit_function_add_attribute (gcc_jit_function *func,
241 enum gcc_jit_fn_attribute attribute)
242
243 Add an attribute ``attribute`` to a function ``func``.
244
245 This is equivalent to the following code:
246
247 .. code-block:: c
248
249 __attribute__((always_inline))
250
251 This entrypoint was added in :ref:`LIBGCCJIT_ABI_26`; you can test for
252 its presence using
253
254 .. code-block:: c
255
256 #ifdef LIBGCCJIT_HAVE_ATTRIBUTES
257
258 .. function:: void\
259 gcc_jit_function_add_string_attribute (gcc_jit_function *func,
260 enum gcc_jit_fn_attribute attribute,
261 const char *value)
262
263 Add a string attribute ``attribute`` with value ``value`` to a function
264 ``func``.
265
266 This is equivalent to the following code:
267
268 .. code-block:: c
269
270 __attribute__ ((alias ("xxx")))
271
272 This entrypoint was added in :ref:`LIBGCCJIT_ABI_26`; you can test for
273 its presence using
274
275 .. code-block:: c
276
277 #ifdef LIBGCCJIT_HAVE_ATTRIBUTES
278
279 .. function:: void\
280 gcc_jit_function_add_integer_array_attribute (gcc_jit_function *func,
281 enum gcc_jit_fn_attribute attribute,
282 const int *value,
283 size_t length)
284
285 Add an attribute ``attribute`` with ``length`` integer values ``value`` to a
286 function ``func``. The integer values must be the same as you would write
287 them in a C code.
288
289 This is equivalent to the following code:
290
291 .. code-block:: c
292
293 __attribute__ ((nonnull (1, 2)))
294
295 This entrypoint was added in :ref:`LIBGCCJIT_ABI_26`; you can test for
296 its presence using
297
298 .. code-block:: c
299
300 #ifdef LIBGCCJIT_HAVE_ATTRIBUTES
301
302 Blocks
303 ------
304 .. type:: gcc_jit_block
305
306 A `gcc_jit_block` represents a basic block within a function i.e. a
307 sequence of statements with a single entry point and a single exit
308 point.
309
310 The first basic block that you create within a function will
311 be the entrypoint.
312
313 Each basic block that you create within a function must be
314 terminated, either with a conditional, a jump, a return, or a
315 switch.
316
317 It's legal to have multiple basic blocks that return within
318 one function.
319
320 .. function:: gcc_jit_block *\
321 gcc_jit_function_new_block (gcc_jit_function *func,\
322 const char *name)
323
324 Create a basic block of the given name. The name may be NULL, but
325 providing meaningful names is often helpful when debugging: it may
326 show up in dumps of the internal representation, and in error
327 messages. It is copied, so the input buffer does not need to outlive
328 the call; you can pass in a pointer to an on-stack buffer, e.g.:
329
330 .. code-block:: c
331
332 for (pc = 0; pc < fn->fn_num_ops; pc++)
333 {
334 char buf[16];
335 sprintf (buf, "instr%i", pc);
336 state.op_blocks[pc] = gcc_jit_function_new_block (state.fn, buf);
337 }
338
339 .. function:: gcc_jit_object *\
340 gcc_jit_block_as_object (gcc_jit_block *block)
341
342 Upcast from block to object.
343
344 .. function:: gcc_jit_function *\
345 gcc_jit_block_get_function (gcc_jit_block *block)
346
347 Which function is this block within?
348
349
350 Statements
351 ----------
352
353 .. function:: void\
354 gcc_jit_block_add_eval (gcc_jit_block *block,\
355 gcc_jit_location *loc,\
356 gcc_jit_rvalue *rvalue)
357
358 Add evaluation of an rvalue, discarding the result
359 (e.g. a function call that "returns" void).
360
361 This is equivalent to this C code:
362
363 .. code-block:: c
364
365 (void)expression;
366
367 .. function:: void\
368 gcc_jit_block_add_assignment (gcc_jit_block *block,\
369 gcc_jit_location *loc,\
370 gcc_jit_lvalue *lvalue,\
371 gcc_jit_rvalue *rvalue)
372
373 Add evaluation of an rvalue, assigning the result to the given
374 lvalue.
375
376 This is roughly equivalent to this C code:
377
378 .. code-block:: c
379
380 lvalue = rvalue;
381
382 .. function:: void\
383 gcc_jit_block_add_assignment_op (gcc_jit_block *block,\
384 gcc_jit_location *loc,\
385 gcc_jit_lvalue *lvalue,\
386 enum gcc_jit_binary_op op,\
387 gcc_jit_rvalue *rvalue)
388
389 Add evaluation of an rvalue, using the result to modify an
390 lvalue.
391
392 This is analogous to "+=" and friends:
393
394 .. code-block:: c
395
396 lvalue += rvalue;
397 lvalue *= rvalue;
398 lvalue /= rvalue;
399
400 etc. For example:
401
402 .. code-block:: c
403
404 /* "i++" */
405 gcc_jit_block_add_assignment_op (
406 loop_body, NULL,
407 i,
408 GCC_JIT_BINARY_OP_PLUS,
409 gcc_jit_context_one (ctxt, int_type));
410
411 .. function:: void\
412 gcc_jit_block_add_comment (gcc_jit_block *block,\
413 gcc_jit_location *loc,\
414 const char *text)
415
416 Add a no-op textual comment to the internal representation of the
417 code. It will be optimized away, but will be visible in the dumps
418 seen via :macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE`
419 and :macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE`,
420 and thus may be of use when debugging how your project's internal
421 representation gets converted to the libgccjit IR.
422
423 The parameter ``text`` must be non-NULL. It is copied, so the input
424 buffer does not need to outlive the call. For example:
425
426 .. code-block:: c
427
428 char buf[100];
429 snprintf (buf, sizeof (buf),
430 "op%i: %s",
431 pc, opcode_names[op->op_opcode]);
432 gcc_jit_block_add_comment (block, loc, buf);
433
434 .. function:: void\
435 gcc_jit_block_end_with_conditional (gcc_jit_block *block,\
436 gcc_jit_location *loc,\
437 gcc_jit_rvalue *boolval,\
438 gcc_jit_block *on_true,\
439 gcc_jit_block *on_false)
440
441 Terminate a block by adding evaluation of an rvalue, branching on the
442 result to the appropriate successor block.
443
444 This is roughly equivalent to this C code:
445
446 .. code-block:: c
447
448 if (boolval)
449 goto on_true;
450 else
451 goto on_false;
452
453 block, boolval, on_true, and on_false must be non-NULL.
454
455 .. function:: void\
456 gcc_jit_block_end_with_jump (gcc_jit_block *block,\
457 gcc_jit_location *loc,\
458 gcc_jit_block *target)
459
460
461 Terminate a block by adding a jump to the given target block.
462
463 This is roughly equivalent to this C code:
464
465 .. code-block:: c
466
467 goto target;
468
469 .. function:: void\
470 gcc_jit_block_end_with_return (gcc_jit_block *block,\
471 gcc_jit_location *loc,\
472 gcc_jit_rvalue *rvalue)
473
474
475 Terminate a block by adding evaluation of an rvalue, returning the value.
476
477 This is roughly equivalent to this C code:
478
479 .. code-block:: c
480
481 return expression;
482
483 .. function:: void\
484 gcc_jit_block_end_with_void_return (gcc_jit_block *block,\
485 gcc_jit_location *loc)
486
487
488 Terminate a block by adding a valueless return, for use within a function
489 with "void" return type.
490
491 This is equivalent to this C code:
492
493 .. code-block:: c
494
495 return;
496
497 .. function:: void\
498 gcc_jit_block_end_with_switch (gcc_jit_block *block,\
499 gcc_jit_location *loc,\
500 gcc_jit_rvalue *expr,\
501 gcc_jit_block *default_block,\
502 int num_cases,\
503 gcc_jit_case **cases)
504
505 Terminate a block by adding evalation of an rvalue, then performing
506 a multiway branch.
507
508 This is roughly equivalent to this C code:
509
510 .. code-block:: c
511
512 switch (expr)
513 {
514 default:
515 goto default_block;
516
517 case C0.min_value ... C0.max_value:
518 goto C0.dest_block;
519
520 case C1.min_value ... C1.max_value:
521 goto C1.dest_block;
522
523 ...etc...
524
525 case C[N - 1].min_value ... C[N - 1].max_value:
526 goto C[N - 1].dest_block;
527 }
528
529 ``block``, ``expr``, ``default_block`` and ``cases`` must all be
530 non-NULL.
531
532 ``expr`` must be of the same integer type as all of the ``min_value``
533 and ``max_value`` within the cases.
534
535 ``num_cases`` must be >= 0.
536
537 The ranges of the cases must not overlap (or have duplicate
538 values).
539
540 The API entrypoints relating to switch statements and cases:
541
542 * :c:func:`gcc_jit_block_end_with_switch`
543
544 * :c:func:`gcc_jit_case_as_object`
545
546 * :c:func:`gcc_jit_context_new_case`
547
548 were added in :ref:`LIBGCCJIT_ABI_3`; you can test for their presence
549 using
550
551 .. code-block:: c
552
553 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS
554
555 .. type:: gcc_jit_case
556
557 A `gcc_jit_case` represents a case within a switch statement, and
558 is created within a particular :c:type:`gcc_jit_context` using
559 :c:func:`gcc_jit_context_new_case`.
560
561 Each case expresses a multivalued range of integer values. You
562 can express single-valued cases by passing in the same value for
563 both `min_value` and `max_value`.
564
565 .. function:: gcc_jit_case *\
566 gcc_jit_context_new_case (gcc_jit_context *ctxt,\
567 gcc_jit_rvalue *min_value,\
568 gcc_jit_rvalue *max_value,\
569 gcc_jit_block *dest_block)
570
571 Create a new gcc_jit_case instance for use in a switch statement.
572 `min_value` and `max_value` must be constants of an integer type,
573 which must match that of the expression of the switch statement.
574
575 `dest_block` must be within the same function as the switch
576 statement.
577
578 .. function:: gcc_jit_object *\
579 gcc_jit_case_as_object (gcc_jit_case *case_)
580
581 Upcast from a case to an object.
582
583 Here's an example of creating a switch statement:
584
585 .. literalinclude:: ../../../testsuite/jit.dg/test-switch.c
586 :start-after: /* Quote from here in docs/topics/functions.rst. */
587 :end-before: /* Quote up to here in docs/topics/functions.rst. */
588 :language: c
589
590 See also :type:`gcc_jit_extended_asm` for entrypoints for adding inline
591 assembler statements to a function.