1 .. Copyright (C) 2014-2020 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 <http://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 ``name`` must be non-NULL. The call takes a copy of the
39 underlying string, so it is valid to pass in a pointer to an on-stack
42 Parameters are lvalues, and thus are also rvalues (and objects), so the
43 following upcasts are available:
45 .. function:: gcc_jit_lvalue *\
46 gcc_jit_param_as_lvalue (gcc_jit_param *param)
48 Upcasting from param to lvalue.
50 .. function:: gcc_jit_rvalue *\
51 gcc_jit_param_as_rvalue (gcc_jit_param *param)
53 Upcasting from param to rvalue.
55 .. function:: gcc_jit_object *\
56 gcc_jit_param_as_object (gcc_jit_param *param)
58 Upcasting from param to object.
64 .. type:: gcc_jit_function
66 A `gcc_jit_function` represents a function - either one that we're
67 creating ourselves, or one that we're referencing.
69 .. function:: gcc_jit_function *\
70 gcc_jit_context_new_function (gcc_jit_context *ctxt,\
71 gcc_jit_location *loc,\
72 enum gcc_jit_function_kind kind,\
73 gcc_jit_type *return_type,\
76 gcc_jit_param **params,\
79 Create a gcc_jit_function with the given name and parameters.
81 .. type:: enum gcc_jit_function_kind
83 This enum controls the kind of function created, and has the following
86 .. macro:: GCC_JIT_FUNCTION_EXPORTED
88 Function is defined by the client code and visible
89 by name outside of the JIT.
91 This value is required if you want to extract machine code
92 for this function from a :type:`gcc_jit_result` via
93 :func:`gcc_jit_result_get_code`.
95 .. macro:: GCC_JIT_FUNCTION_INTERNAL
97 Function is defined by the client code, but is invisible
98 outside of the JIT. Analogous to a "static" function.
100 .. macro:: GCC_JIT_FUNCTION_IMPORTED
102 Function is not defined by the client code; we're merely
103 referring to it. Analogous to using an "extern" function from a
106 .. macro:: GCC_JIT_FUNCTION_ALWAYS_INLINE
108 Function is only ever inlined into other functions, and is
109 invisible outside of the JIT.
111 Analogous to prefixing with ``inline`` and adding
112 ``__attribute__((always_inline))``
114 Inlining will only occur when the optimization level is
115 above 0; when optimization is off, this is essentially the
116 same as GCC_JIT_FUNCTION_INTERNAL.
118 The parameter ``name`` must be non-NULL. The call takes a copy of the
119 underlying string, so it is valid to pass in a pointer to an on-stack
122 .. function:: gcc_jit_function *\
123 gcc_jit_context_get_builtin_function (gcc_jit_context *ctxt,\
126 .. function:: gcc_jit_object *\
127 gcc_jit_function_as_object (gcc_jit_function *func)
129 Upcasting from function to object.
131 .. function:: gcc_jit_param *\
132 gcc_jit_function_get_param (gcc_jit_function *func, int index)
134 Get the param of the given index (0-based).
137 gcc_jit_function_dump_to_dot (gcc_jit_function *func,\
140 Emit the function in graphviz format to the given path.
142 .. function:: gcc_jit_lvalue *\
143 gcc_jit_function_new_local (gcc_jit_function *func,\
144 gcc_jit_location *loc,\
148 Create a new local variable within the function, of the given type and
151 The parameter ``name`` must be non-NULL. The call takes a copy of the
152 underlying string, so it is valid to pass in a pointer to an on-stack
157 .. type:: gcc_jit_block
159 A `gcc_jit_block` represents a basic block within a function i.e. a
160 sequence of statements with a single entry point and a single exit
163 The first basic block that you create within a function will
166 Each basic block that you create within a function must be
167 terminated, either with a conditional, a jump, a return, or a
170 It's legal to have multiple basic blocks that return within
173 .. function:: gcc_jit_block *\
174 gcc_jit_function_new_block (gcc_jit_function *func,\
177 Create a basic block of the given name. The name may be NULL, but
178 providing meaningful names is often helpful when debugging: it may
179 show up in dumps of the internal representation, and in error
180 messages. It is copied, so the input buffer does not need to outlive
181 the call; you can pass in a pointer to an on-stack buffer, e.g.:
185 for (pc = 0; pc < fn->fn_num_ops; pc++)
188 sprintf (buf, "instr%i", pc);
189 state.op_blocks[pc] = gcc_jit_function_new_block (state.fn, buf);
192 .. function:: gcc_jit_object *\
193 gcc_jit_block_as_object (gcc_jit_block *block)
195 Upcast from block to object.
197 .. function:: gcc_jit_function *\
198 gcc_jit_block_get_function (gcc_jit_block *block)
200 Which function is this block within?
207 gcc_jit_block_add_eval (gcc_jit_block *block,\
208 gcc_jit_location *loc,\
209 gcc_jit_rvalue *rvalue)
211 Add evaluation of an rvalue, discarding the result
212 (e.g. a function call that "returns" void).
214 This is equivalent to this C code:
221 gcc_jit_block_add_assignment (gcc_jit_block *block,\
222 gcc_jit_location *loc,\
223 gcc_jit_lvalue *lvalue,\
224 gcc_jit_rvalue *rvalue)
226 Add evaluation of an rvalue, assigning the result to the given
229 This is roughly equivalent to this C code:
236 gcc_jit_block_add_assignment_op (gcc_jit_block *block,\
237 gcc_jit_location *loc,\
238 gcc_jit_lvalue *lvalue,\
239 enum gcc_jit_binary_op op,\
240 gcc_jit_rvalue *rvalue)
242 Add evaluation of an rvalue, using the result to modify an
245 This is analogous to "+=" and friends:
258 gcc_jit_block_add_assignment_op (
261 GCC_JIT_BINARY_OP_PLUS,
262 gcc_jit_context_one (ctxt, int_type));
265 gcc_jit_block_add_comment (gcc_jit_block *block,\
266 gcc_jit_location *loc,\
269 Add a no-op textual comment to the internal representation of the
270 code. It will be optimized away, but will be visible in the dumps
271 seen via :macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE`
272 and :macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE`,
273 and thus may be of use when debugging how your project's internal
274 representation gets converted to the libgccjit IR.
276 The parameter ``text`` must be non-NULL. It is copied, so the input
277 buffer does not need to outlive the call. For example:
282 snprintf (buf, sizeof (buf),
284 pc, opcode_names[op->op_opcode]);
285 gcc_jit_block_add_comment (block, loc, buf);
288 gcc_jit_block_end_with_conditional (gcc_jit_block *block,\
289 gcc_jit_location *loc,\
290 gcc_jit_rvalue *boolval,\
291 gcc_jit_block *on_true,\
292 gcc_jit_block *on_false)
294 Terminate a block by adding evaluation of an rvalue, branching on the
295 result to the appropriate successor block.
297 This is roughly equivalent to this C code:
306 block, boolval, on_true, and on_false must be non-NULL.
309 gcc_jit_block_end_with_jump (gcc_jit_block *block,\
310 gcc_jit_location *loc,\
311 gcc_jit_block *target)
314 Terminate a block by adding a jump to the given target block.
316 This is roughly equivalent to this C code:
323 gcc_jit_block_end_with_return (gcc_jit_block *block,\
324 gcc_jit_location *loc,\
325 gcc_jit_rvalue *rvalue)
328 Terminate a block by adding evaluation of an rvalue, returning the value.
330 This is roughly equivalent to this C code:
337 gcc_jit_block_end_with_void_return (gcc_jit_block *block,\
338 gcc_jit_location *loc)
341 Terminate a block by adding a valueless return, for use within a function
342 with "void" return type.
344 This is equivalent to this C code:
351 gcc_jit_block_end_with_switch (gcc_jit_block *block,\
352 gcc_jit_location *loc,\
353 gcc_jit_rvalue *expr,\
354 gcc_jit_block *default_block,\
356 gcc_jit_case **cases)
358 Terminate a block by adding evalation of an rvalue, then performing
361 This is roughly equivalent to this C code:
370 case C0.min_value ... C0.max_value:
373 case C1.min_value ... C1.max_value:
378 case C[N - 1].min_value ... C[N - 1].max_value:
379 goto C[N - 1].dest_block;
382 ``block``, ``expr``, ``default_block`` and ``cases`` must all be
385 ``expr`` must be of the same integer type as all of the ``min_value``
386 and ``max_value`` within the cases.
388 ``num_cases`` must be >= 0.
390 The ranges of the cases must not overlap (or have duplicate
393 The API entrypoints relating to switch statements and cases:
395 * :c:func:`gcc_jit_block_end_with_switch`
397 * :c:func:`gcc_jit_case_as_object`
399 * :c:func:`gcc_jit_context_new_case`
401 were added in :ref:`LIBGCCJIT_ABI_3`; you can test for their presence
406 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS
408 .. type:: gcc_jit_case
410 A `gcc_jit_case` represents a case within a switch statement, and
411 is created within a particular :c:type:`gcc_jit_context` using
412 :c:func:`gcc_jit_context_new_case`.
414 Each case expresses a multivalued range of integer values. You
415 can express single-valued cases by passing in the same value for
416 both `min_value` and `max_value`.
418 .. function:: gcc_jit_case *\
419 gcc_jit_context_new_case (gcc_jit_context *ctxt,\
420 gcc_jit_rvalue *min_value,\
421 gcc_jit_rvalue *max_value,\
422 gcc_jit_block *dest_block)
424 Create a new gcc_jit_case instance for use in a switch statement.
425 `min_value` and `max_value` must be constants of an integer type,
426 which must match that of the expression of the switch statement.
428 `dest_block` must be within the same function as the switch
431 .. function:: gcc_jit_object *\
432 gcc_jit_case_as_object (gcc_jit_case *case_)
434 Upcast from a case to an object.
436 Here's an example of creating a switch statement:
438 .. literalinclude:: ../../../testsuite/jit.dg/test-switch.c
439 :start-after: /* Quote from here in docs/topics/functions.rst. */
440 :end-before: /* Quote up to here in docs/topics/functions.rst. */