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)"
      .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)"
      .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-2022 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