1.2 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?

First we need to include the relevant header:

#include <libgccjit.h>

All state associated with compilation is associated with a gcc_jit_context *.

Create one using gcc_jit_context_acquire():

gcc_jit_context *ctxt;
ctxt = gcc_jit_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 gcc_jit_type *, using gcc_jit_context_get_type():

gcc_jit_type *int_type =
  gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);

gcc_jit_type * is an example of a “contextual” object: every entity in the API is associated with a gcc_jit_context *.

Memory management is easy: all such “contextual” objects are automatically cleaned up for you when the context is released, using gcc_jit_context_release():

gcc_jit_context_release (ctxt);

so you don’t need to manually track and cleanup all objects, just the contexts.

Although the API is C-based, there is a form of class hierarchy, which looks like this:

+- gcc_jit_object
    +- gcc_jit_location
    +- gcc_jit_type
       +- gcc_jit_struct
    +- gcc_jit_field
    +- gcc_jit_function
    +- gcc_jit_block
    +- gcc_jit_rvalue
        +- gcc_jit_lvalue
           +- gcc_jit_param

There are casting methods for upcasting from subclasses to parent classes. For example, gcc_jit_type_as_object():

gcc_jit_object *obj = gcc_jit_type_as_object (int_type);

One thing you can do with a gcc_jit_object * is to ask it for a human-readable description, using gcc_jit_object_get_debug_string():

printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj));

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 gcc_jit_context_new_param():

gcc_jit_param *param_i =
  gcc_jit_context_new_param (ctxt, NULL, int_type, "i");

Now we can create the function, using gcc_jit_context_new_function():

gcc_jit_function *func =
  gcc_jit_context_new_function (ctxt, NULL,
                                GCC_JIT_FUNCTION_EXPORTED,
                                int_type,
                                "square",
                                1, &param_i,
                                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:

gcc_jit_block *block = gcc_jit_function_new_block (func, NULL);

Our basic block is relatively simple: it immediately terminates by returning the value of an expression.

We can build the expression using gcc_jit_context_new_binary_op():

gcc_jit_rvalue *expr =
  gcc_jit_context_new_binary_op (
    ctxt, NULL,
    GCC_JIT_BINARY_OP_MULT, int_type,
    gcc_jit_param_as_rvalue (param_i),
    gcc_jit_param_as_rvalue (param_i));

A gcc_jit_rvalue * is another example of a gcc_jit_object * subclass. We can upcast it using gcc_jit_rvalue_as_object() and as before print it with gcc_jit_object_get_debug_string().

printf ("expr: %s\n",
        gcc_jit_object_get_debug_string (
          gcc_jit_rvalue_as_object (expr)));

giving this output:

expr: i * 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:

gcc_jit_block_end_with_return (block, NULL, expr);

OK, we’ve populated the context. We can now compile it using gcc_jit_context_compile():

gcc_jit_result *result;
result = gcc_jit_context_compile (ctxt);

and get a gcc_jit_result *.

At this point we’re done with the context; we can release it:

gcc_jit_context_release (ctxt);

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

Once we’re done with the code, we can release the result:

gcc_jit_result_release (result);

We can’t call square anymore once we’ve released result.

• Error-handling
• Options
• Full example