Tutorial part 2: Creating a trivial machine code function¶
Consider this C function:
int square (int i)
{
return i * i;
}
How can we construct this at run-time using libgccjit’s C++ API?
First we need to include the relevant header:
#include <libgccjit++.h>
All state associated with compilation is associated with a
gccjit::context
, which is a thin C++ wrapper around the C API’s
gcc_jit_context *
.
Create one using gccjit::context::acquire()
:
gccjit::context ctxt;
ctxt = gccjit::context::acquire ();
The JIT library has a system of types. It is statically-typed: every
expression is of a specific type, fixed at compile-time. In our example,
all of the expressions are of the C int type, so let’s obtain this from
the context, as a gccjit::type
, using
gccjit::context::get_type()
:
gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
gccjit::type
is an example of a “contextual” object: every
entity in the API is associated with a gccjit::context
.
Memory management is easy: all such “contextual” objects are automatically
cleaned up for you when the context is released, using
gccjit::context::release()
:
ctxt.release ();
so you don’t need to manually track and cleanup all objects, just the contexts.
All of the C++ classes in the API are thin wrappers around pointers to types in the C API.
The C++ class hierarchy within the gccjit
namespace looks like this:
+- object
+- location
+- type
+- struct
+- field
+- function
+- block
+- rvalue
+- lvalue
+- param
One thing you can do with a gccjit::object
is
to ask it for a human-readable description as a std::string
, using
gccjit::object::get_debug_string()
:
printf ("obj: %s\n", obj.get_debug_string ().c_str ());
giving this text on stdout:
obj: int
This is invaluable when debugging.
Let’s create the function. To do so, we first need to construct
its single parameter, specifying its type and giving it a name,
using gccjit::context::new_param()
:
gccjit::param param_i = ctxt.new_param (int_type, "i");
and we can then make a vector of all of the params of the function, in this case just one:
std::vector<gccjit::param> params;
params.push_back (param_i);
Now we can create the function, using
gccjit::context::new_function()
:
gccjit::function func =
ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
int_type,
"square",
params,
0);
To define the code within the function, we must create basic blocks containing statements.
Every basic block contains a list of statements, eventually terminated by a statement that either returns, or jumps to another basic block.
Our function has no control-flow, so we just need one basic block:
gccjit::block block = func.new_block ();
Our basic block is relatively simple: it immediately terminates by returning the value of an expression.
We can build the expression using gccjit::context::new_binary_op()
:
gccjit::rvalue expr =
ctxt.new_binary_op (
GCC_JIT_BINARY_OP_MULT, int_type,
param_i, param_i);
A gccjit::rvalue
is another example of a
gccjit::object
subclass. As before, we can print it with
gccjit::object::get_debug_string()
.
printf ("expr: %s\n", expr.get_debug_string ().c_str ());
giving this output:
expr: i * i
Note that gccjit::rvalue
provides numerous overloaded operators
which can be used to dramatically reduce the amount of typing needed.
We can build the above binary operation more directly with this one-liner:
gccjit::rvalue expr = param_i * param_i;
Creating the expression in itself doesn’t do anything; we have to add this expression to a statement within the block. In this case, we use it to build a return statement, which terminates the basic block:
block.end_with_return (expr);
OK, we’ve populated the context. We can now compile it using
gccjit::context::compile()
:
gcc_jit_result *result;
result = ctxt.compile ();
and get a gcc_jit_result *
.
We can now use gcc_jit_result_get_code()
to look up a specific
machine code routine within the result, in this case, the function we
created above.
void *fn_ptr = gcc_jit_result_get_code (result, "square");
if (!fn_ptr)
{
fprintf (stderr, "NULL fn_ptr");
goto error;
}
We can now cast the pointer to an appropriate function pointer type, and then call it:
typedef int (*fn_type) (int);
fn_type square = (fn_type)fn_ptr;
printf ("result: %d", square (5));
result: 25
Options¶
To get more information on what’s going on, you can set debugging flags
on the context using gccjit::context::set_bool_option()
.
Setting GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE
will dump a
C-like representation to stderr when you compile (GCC’s “GIMPLE”
representation):
ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1);
result = ctxt.compile ();
square (signed int i)
{
signed int D.260;
entry:
D.260 = i * i;
return D.260;
}
We can see the generated machine code in assembler form (on stderr) by
setting GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE
on the context
before compiling:
ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 1);
result = ctxt.compile ();
.file "fake.c"
.text
.globl square
.type square, @function
square:
.LFB6:
.cfi_startproc
pushq %rbp
.cfi_def_cfa_offset 16
.cfi_offset 6, -16
movq %rsp, %rbp
.cfi_def_cfa_register 6
movl %edi, -4(%rbp)
.L14:
movl -4(%rbp), %eax
imull -4(%rbp), %eax
popq %rbp
.cfi_def_cfa 7, 8
ret
.cfi_endproc
.LFE6:
.size square, .-square
.ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
.section .note.GNU-stack,"",@progbits
By default, no optimizations are performed, the equivalent of GCC’s
-O0 option. We can turn things up to e.g. -O3 by calling
gccjit::context::set_int_option()
with
GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL
:
ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3);
.file "fake.c"
.text
.p2align 4,,15
.globl square
.type square, @function
square:
.LFB7:
.cfi_startproc
.L16:
movl %edi, %eax
imull %edi, %eax
ret
.cfi_endproc
.LFE7:
.size square, .-square
.ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
.section .note.GNU-stack,"",@progbits
Naturally this has only a small effect on such a trivial function.
Full example¶
Here’s what the above looks like as a complete program:
/* Usage example for libgccjit.so's C++ API Copyright (C) 2014-2019 Free Software Foundation, Inc. This file is part of GCC. GCC is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. GCC is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GCC; see the file COPYING3. If not see <http://www.gnu.org/licenses/>. */ #include <libgccjit++.h> #include <stdlib.h> #include <stdio.h> void create_code (gccjit::context ctxt) { /* Let's try to inject the equivalent of this C code: int square (int i) { return i * i; } */ gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT); gccjit::param param_i = ctxt.new_param (int_type, "i"); std::vector<gccjit::param> params; params.push_back (param_i); gccjit::function func = ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED, int_type, "square", params, 0); gccjit::block block = func.new_block (); gccjit::rvalue expr = ctxt.new_binary_op (GCC_JIT_BINARY_OP_MULT, int_type, param_i, param_i); block.end_with_return (expr); } int main (int argc, char **argv) { /* Get a "context" object for working with the library. */ gccjit::context ctxt = gccjit::context::acquire (); /* Set some options on the context. Turn this on to see the code being generated, in assembler form. */ ctxt.set_bool_option ( GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 0); /* Populate the context. */ create_code (ctxt); /* Compile the code. */ gcc_jit_result *result = ctxt.compile (); /* We're done with the context; we can release it: */ ctxt.release (); if (!result) { fprintf (stderr, "NULL result"); return 1; } /* Extract the generated code from "result". */ void *fn_ptr = gcc_jit_result_get_code (result, "square"); if (!fn_ptr) { fprintf (stderr, "NULL fn_ptr"); gcc_jit_result_release (result); return 1; } typedef int (*fn_type) (int); fn_type square = (fn_type)fn_ptr; printf ("result: %d\n", square (5)); gcc_jit_result_release (result); return 0; }
Building and running it:
$ gcc \
tut02-square.cc \
-o tut02-square \
-lgccjit
# Run the built program:
$ ./tut02-square
result: 25