1 .. Copyright (C) 2014-2022 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <dmalcolm@redhat.com>
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.
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.
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/>.
20 Creating and using functions
21 ============================
25 .. type:: gcc_jit_param
27 A `gcc_jit_param` represents a parameter to a function.
29 .. function:: gcc_jit_param *\
30 gcc_jit_context_new_param (gcc_jit_context *ctxt,\
31 gcc_jit_location *loc,\
35 In preparation for creating a function, create a new parameter of the
38 The parameter ``type`` must be non-`void`.
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
44 Parameters are lvalues, and thus are also rvalues (and objects), so the
45 following upcasts are available:
47 .. function:: gcc_jit_lvalue *\
48 gcc_jit_param_as_lvalue (gcc_jit_param *param)
50 Upcasting from param to lvalue.
52 .. function:: gcc_jit_rvalue *\
53 gcc_jit_param_as_rvalue (gcc_jit_param *param)
55 Upcasting from param to rvalue.
57 .. function:: gcc_jit_object *\
58 gcc_jit_param_as_object (gcc_jit_param *param)
60 Upcasting from param to object.
66 .. type:: gcc_jit_function
68 A `gcc_jit_function` represents a function - either one that we're
69 creating ourselves, or one that we're referencing.
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,\
78 gcc_jit_param **params,\
81 Create a gcc_jit_function with the given name and parameters.
83 .. type:: enum gcc_jit_function_kind
85 This enum controls the kind of function created, and has the following
88 .. macro:: GCC_JIT_FUNCTION_EXPORTED
90 Function is defined by the client code and visible
91 by name outside of the JIT.
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`.
97 .. macro:: GCC_JIT_FUNCTION_INTERNAL
99 Function is defined by the client code, but is invisible
100 outside of the JIT. Analogous to a "static" function.
102 .. macro:: GCC_JIT_FUNCTION_IMPORTED
104 Function is not defined by the client code; we're merely
105 referring to it. Analogous to using an "extern" function from a
108 .. macro:: GCC_JIT_FUNCTION_ALWAYS_INLINE
110 Function is only ever inlined into other functions, and is
111 invisible outside of the JIT.
113 Analogous to prefixing with ``inline`` and adding
114 ``__attribute__((always_inline))``
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.
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
124 .. function:: gcc_jit_function *\
125 gcc_jit_context_get_builtin_function (gcc_jit_context *ctxt,\
128 Get the :type:`gcc_jit_function` for the built-in function with the
129 given name. For example:
134 = gcc_jit_context_get_builtin_function (ctxt, "__builtin_memcpy");
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
143 .. function:: gcc_jit_object *\
144 gcc_jit_function_as_object (gcc_jit_function *func)
146 Upcasting from function to object.
148 .. function:: gcc_jit_param *\
149 gcc_jit_function_get_param (gcc_jit_function *func, int index)
151 Get the param of the given index (0-based).
154 gcc_jit_function_dump_to_dot (gcc_jit_function *func,\
157 Emit the function in graphviz format to the given path.
159 .. function:: gcc_jit_lvalue *\
160 gcc_jit_function_new_local (gcc_jit_function *func,\
161 gcc_jit_location *loc,\
165 Create a new local variable within the function, of the given type and
168 The parameter ``type`` must be non-`void`.
170 The parameter ``name`` must be non-NULL. The call takes a copy of the
171 underlying string, so it is valid to pass in a pointer to an on-stack
174 .. function:: size_t \
175 gcc_jit_function_get_param_count (gcc_jit_function *func)
177 Get the number of parameters of the function.
179 .. function:: gcc_jit_type *\
180 gcc_jit_function_get_return_type (gcc_jit_function *func)
182 Get the return type of the function.
184 The API entrypoints relating to getting info about parameters and return
187 * :c:func:`gcc_jit_function_get_return_type`
189 * :c:func:`gcc_jit_function_get_param_count`
191 were added in :ref:`LIBGCCJIT_ABI_16`; you can test for their presence
196 #ifdef LIBGCCJIT_HAVE_REFLECTION
198 .. type:: gcc_jit_case
202 .. type:: gcc_jit_block
204 A `gcc_jit_block` represents a basic block within a function i.e. a
205 sequence of statements with a single entry point and a single exit
208 The first basic block that you create within a function will
211 Each basic block that you create within a function must be
212 terminated, either with a conditional, a jump, a return, or a
215 It's legal to have multiple basic blocks that return within
218 .. function:: gcc_jit_block *\
219 gcc_jit_function_new_block (gcc_jit_function *func,\
222 Create a basic block of the given name. The name may be NULL, but
223 providing meaningful names is often helpful when debugging: it may
224 show up in dumps of the internal representation, and in error
225 messages. It is copied, so the input buffer does not need to outlive
226 the call; you can pass in a pointer to an on-stack buffer, e.g.:
230 for (pc = 0; pc < fn->fn_num_ops; pc++)
233 sprintf (buf, "instr%i", pc);
234 state.op_blocks[pc] = gcc_jit_function_new_block (state.fn, buf);
237 .. function:: gcc_jit_object *\
238 gcc_jit_block_as_object (gcc_jit_block *block)
240 Upcast from block to object.
242 .. function:: gcc_jit_function *\
243 gcc_jit_block_get_function (gcc_jit_block *block)
245 Which function is this block within?
252 gcc_jit_block_add_eval (gcc_jit_block *block,\
253 gcc_jit_location *loc,\
254 gcc_jit_rvalue *rvalue)
256 Add evaluation of an rvalue, discarding the result
257 (e.g. a function call that "returns" void).
259 This is equivalent to this C code:
266 gcc_jit_block_add_assignment (gcc_jit_block *block,\
267 gcc_jit_location *loc,\
268 gcc_jit_lvalue *lvalue,\
269 gcc_jit_rvalue *rvalue)
271 Add evaluation of an rvalue, assigning the result to the given
274 This is roughly equivalent to this C code:
281 gcc_jit_block_add_assignment_op (gcc_jit_block *block,\
282 gcc_jit_location *loc,\
283 gcc_jit_lvalue *lvalue,\
284 enum gcc_jit_binary_op op,\
285 gcc_jit_rvalue *rvalue)
287 Add evaluation of an rvalue, using the result to modify an
290 This is analogous to "+=" and friends:
303 gcc_jit_block_add_assignment_op (
306 GCC_JIT_BINARY_OP_PLUS,
307 gcc_jit_context_one (ctxt, int_type));
310 gcc_jit_block_add_comment (gcc_jit_block *block,\
311 gcc_jit_location *loc,\
314 Add a no-op textual comment to the internal representation of the
315 code. It will be optimized away, but will be visible in the dumps
316 seen via :macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE`
317 and :macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE`,
318 and thus may be of use when debugging how your project's internal
319 representation gets converted to the libgccjit IR.
321 The parameter ``text`` must be non-NULL. It is copied, so the input
322 buffer does not need to outlive the call. For example:
327 snprintf (buf, sizeof (buf),
329 pc, opcode_names[op->op_opcode]);
330 gcc_jit_block_add_comment (block, loc, buf);
333 gcc_jit_block_end_with_conditional (gcc_jit_block *block,\
334 gcc_jit_location *loc,\
335 gcc_jit_rvalue *boolval,\
336 gcc_jit_block *on_true,\
337 gcc_jit_block *on_false)
339 Terminate a block by adding evaluation of an rvalue, branching on the
340 result to the appropriate successor block.
342 This is roughly equivalent to this C code:
351 block, boolval, on_true, and on_false must be non-NULL.
354 gcc_jit_block_end_with_jump (gcc_jit_block *block,\
355 gcc_jit_location *loc,\
356 gcc_jit_block *target)
359 Terminate a block by adding a jump to the given target block.
361 This is roughly equivalent to this C code:
368 gcc_jit_block_end_with_return (gcc_jit_block *block,\
369 gcc_jit_location *loc,\
370 gcc_jit_rvalue *rvalue)
373 Terminate a block by adding evaluation of an rvalue, returning the value.
375 This is roughly equivalent to this C code:
382 gcc_jit_block_end_with_void_return (gcc_jit_block *block,\
383 gcc_jit_location *loc)
386 Terminate a block by adding a valueless return, for use within a function
387 with "void" return type.
389 This is equivalent to this C code:
396 gcc_jit_block_end_with_switch (gcc_jit_block *block,\
397 gcc_jit_location *loc,\
398 gcc_jit_rvalue *expr,\
399 gcc_jit_block *default_block,\
401 gcc_jit_case **cases)
403 Terminate a block by adding evalation of an rvalue, then performing
406 This is roughly equivalent to this C code:
415 case C0.min_value ... C0.max_value:
418 case C1.min_value ... C1.max_value:
423 case C[N - 1].min_value ... C[N - 1].max_value:
424 goto C[N - 1].dest_block;
427 ``block``, ``expr``, ``default_block`` and ``cases`` must all be
430 ``expr`` must be of the same integer type as all of the ``min_value``
431 and ``max_value`` within the cases.
433 ``num_cases`` must be >= 0.
435 The ranges of the cases must not overlap (or have duplicate
438 The API entrypoints relating to switch statements and cases:
440 * :c:func:`gcc_jit_block_end_with_switch`
442 * :c:func:`gcc_jit_case_as_object`
444 * :c:func:`gcc_jit_context_new_case`
446 were added in :ref:`LIBGCCJIT_ABI_3`; you can test for their presence
451 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS
453 .. type:: gcc_jit_case
455 A `gcc_jit_case` represents a case within a switch statement, and
456 is created within a particular :c:type:`gcc_jit_context` using
457 :c:func:`gcc_jit_context_new_case`.
459 Each case expresses a multivalued range of integer values. You
460 can express single-valued cases by passing in the same value for
461 both `min_value` and `max_value`.
463 .. function:: gcc_jit_case *\
464 gcc_jit_context_new_case (gcc_jit_context *ctxt,\
465 gcc_jit_rvalue *min_value,\
466 gcc_jit_rvalue *max_value,\
467 gcc_jit_block *dest_block)
469 Create a new gcc_jit_case instance for use in a switch statement.
470 `min_value` and `max_value` must be constants of an integer type,
471 which must match that of the expression of the switch statement.
473 `dest_block` must be within the same function as the switch
476 .. function:: gcc_jit_object *\
477 gcc_jit_case_as_object (gcc_jit_case *case_)
479 Upcast from a case to an object.
481 Here's an example of creating a switch statement:
483 .. literalinclude:: ../../../testsuite/jit.dg/test-switch.c
484 :start-after: /* Quote from here in docs/topics/functions.rst. */
485 :end-before: /* Quote up to here in docs/topics/functions.rst. */
488 See also :type:`gcc_jit_extended_asm` for entrypoints for adding inline
489 assembler statements to a function.