Alien-LibJIT

 view release on metacpan or  search on metacpan

libjit/doc/libjit.texi  view on Meta::CPAN

\input texinfo	@c -*-texinfo-*-
@c %** start of header
@setfilename libjit.info
@settitle Just-In-Time Compiler Library
@setchapternewpage off
@c %** end of header

@dircategory Libraries
@direntry
* Libjit: (libjit).                Just-In-Time Compiler Library
@end direntry

@ifinfo
The libjit library assists with the process of building
Just-In-Time compilers for languages, virtual machines,
and emulators.

Copyright @copyright{} 2004 Southern Storm Software, Pty Ltd
@end ifinfo

@titlepage
@sp 10
@center @titlefont{Just-In-Time Compiler Library}

@vskip 0pt plus 1fill
@center{Copyright @copyright{} 2004 Southern Storm Software, Pty Ltd}
@end titlepage

@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex tp cp

@c -----------------------------------------------------------------------

@node Top, Introduction, , (dir)
@menu
* Introduction::            Introduction and rationale for libjit
* Features::                Features of libjit
* Tutorials::               Tutorials in using libjit
* Initialization::          Initializing the JIT
* Functions::               Building and compiling functions with the JIT
* Types::                   Manipulating system types
* Values::                  Working with temporary values in the JIT
* Instructions::            Working with instructions in the JIT
* Basic Blocks::            Working with basic blocks in the JIT
* Intrinsics::              Intrinsic functions available to libjit users
* Exceptions::              Handling exceptions
* Breakpoint Debugging::    Hooking a breakpoint debugger into libjit
* ELF Binaries::            Manipulating ELF binaries
* Utility Routines::        Miscellaneous utility routines
* Diagnostic Routines::     Diagnostic routines
* C++ Interface::           Using libjit from C++
* Porting::                 Porting libjit to new architectures
* Index::                   Index of concepts and facilities
@end menu

@c -----------------------------------------------------------------------

@node Introduction, Features, Top, Top
@chapter Introduction and rationale for libjit
@cindex Introduction

Just-In-Time compilers are becoming increasingly popular for executing
dynamic languages like Perl and Python and for semi-dynamic languages
like Java and C#.  Studies have shown that JIT techniques can get close to,
and sometimes exceed, the performance of statically-compiled native code.

However, there is a problem with current JIT approaches.  In almost every
case, the JIT is specific to the object model, runtime support library,
garbage collector, or bytecode peculiarities of a particular system.
This inevitably leads to duplication of effort, where all of the good
JIT work that has gone into one virtual machine cannot be reused in another.

JIT's are not only useful for implementing languages.  They can also be used
in other programming fields.  Graphical applications can achieve greater
performance if they can compile a special-purpose rendering routine
on the fly, customized to the rendering task at hand, rather than using
static routines.  Needless to say, such applications have no need for
object models, garbage collectors, or huge runtime class libraries.

Most of the work on a JIT is concerned with arithmetic, numeric type
conversion, memory loads/stores, looping, performing data flow analysis,
assigning registers, and generating the executable machine code.
Only a very small proportion of the work is concerned with language specifics.

The goal of the @code{libjit} project is to provide an extensive set of
routines that takes care of the bulk of the JIT process, without tying the
programmer down with language specifics.  Where we provide support for
common object models, we do so strictly in add-on libraries,
not as part of the core code.

Unlike other systems such as the JVM, .NET, and Parrot, @code{libjit}
is not a virtual machine in its own right.  It is the foundation upon which a
number of different virtual machines, dynamic scripting languages,
or customized rendering routines can be built.

The LLVM project (@uref{http://www.llvm.org/}) has some similar
characteristics to @code{libjit} in that its intermediate format is
generic across front-end languages.  It is written in C++ and provides
a large set of compiler development and optimization components;
much larger than @code{libjit} itself provides.  According to its author,
Chris Lattner, a subset of its capabilities can be used to build JIT's.

Libjit should free developers to think about the design of their front
ends, and not get bogged down in the details of code execution.
Meanwhile, experts in the design and implementation of JIT's can concentrate
on solving code execution problems, instead of front end support issues.

libjit/doc/libjit.texi  view on Meta::CPAN

This is very similar to our previous tutorial, except that we are using
the @code{eq} operator this time.  If the condition is not true, we
want to skip the @code{return} statement.  We achieve this with the
@code{jit_insn_branch_if_not} instruction:

@example
jit_label_t label1 = jit_label_undefined;
...
jit_insn_branch_if_not(function, temp1, &label1);
@end example

The label must be initialized to @code{jit_label_undefined}.  It will be
updated by @code{jit_insn_branch_if_not} to refer to a future position in
the code that we haven't seen yet.

If the condition is true, then execution falls through to the next
instruction where we return @code{x} to the caller:

@example
jit_insn_return(function, x);
@end example

If the condition was not true, then we branched to @code{label1} above.
We fix the location of the label using @code{jit_insn_label}:

@example
jit_insn_label(function, &label1);
@end example

@noindent
We use similar code to check the condition @code{x < y}, and branch
to @code{label2} if it is not true:

@example
jit_value_t temp2;
jit_label_t label2 = jit_label_undefined;
...
temp2 = jit_insn_lt(function, x, y);
jit_insn_branch_if_not(function, temp2, &label2);
@end example

At this point, we need to call the @code{gcd} function with the
arguments @code{x} and @code{y - x}.  The code for this is
fairly straight-forward.  The @code{jit_insn_call} instruction calls
the function listed in its third argument.  In this case, we are calling
ourselves recursively:

@example
jit_value_t temp_args[2];
jit_value_t temp3;
...
temp_args[0] = x;
temp_args[1] = jit_insn_sub(function, y, x);
temp3 = jit_insn_call
    (function, "gcd", function, 0, temp_args, 2, 0);
jit_insn_return(function, temp3);
@end example

The string @code{"gcd"} in the second argument is for diagnostic purposes
only.  It can be helpful when debugging, but the @code{libjit} library
otherwise makes no use of it.  You can set it to NULL if you wish.

In general, @code{libjit} does not maintain mappings from names to
@code{jit_function_t} objects.  It is assumed that the front end will
take care of that, using whatever naming scheme is appropriate to
its needs.

@noindent
The final part of the @code{gcd} function is similar to the previous one:

@example
jit_value_t temp4;
...
jit_insn_label(function, &label2);
temp_args[0] = jit_insn_sub(function, x, y);
temp_args[1] = y;
temp4 = jit_insn_call
    (function, "gcd", function, 0, temp_args, 2, 0);
jit_insn_return(function, temp4);
@end example

@noindent
We can now compile the function and execute it in the usual manner.

@c -----------------------------------------------------------------------

@node Tutorial 3, Tutorial 4, Tutorial 2, Tutorials
@section Tutorial 3 - compiling on-demand
@cindex On-demand compilation tutorial

In the previous tutorials, we compiled everything that we needed
at startup time, and then entered the execution phase.  The real power
of a JIT becomes apparent when you use it to compile functions
only as they are called.  You can thus avoid compiling functions
that are never called in a given program run, saving memory and
startup time.

We demonstrate how to do on-demand compilation by rewriting Tutorial 1.
The source code for the modified version is in @code{tutorial/t3.c}.

When the @code{mul_add} function is created, we don't create its function
body or call @code{jit_function_compile}.  We instead provide a
C function called @code{compile_mul_add} that performs on-demand
compilation:

@example
jit_function_t function;
...
function = jit_function_create(context, signature);
jit_function_set_on_demand_compiler(function, compile_mul_add);
@end example

We can now call this function with @code{jit_function_apply}, and the
system will automatically call @code{compile_mul_add} for us if the
function hasn't been built yet.  The contents of @code{compile_mul_add}
are fairly obvious:

@example
int compile_mul_add(jit_function_t function)
@{

libjit/doc/libjit.texi  view on Meta::CPAN

@c -----------------------------------------------------------------------

@node Functions, Types, Initialization, Top
@chapter Building and compiling functions with the JIT
@cindex Building functions
@cindex Compiling functions

@include libjitext-function.texi

@c -----------------------------------------------------------------------

@node Types, Values, Functions, Top
@chapter Manipulating system types
@cindex Manipulating system types

@include libjitext-type.texi

@c -----------------------------------------------------------------------

@node Values, Instructions, Types, Top
@chapter Working with temporary values in the JIT
@cindex Working with values

@include libjitext-value.texi

@c -----------------------------------------------------------------------

@node Instructions, Basic Blocks, Values, Top
@chapter Working with instructions in the JIT
@cindex Working with instructions

@include libjitext-insn.texi

@c -----------------------------------------------------------------------

@node Basic Blocks, Intrinsics, Instructions, Top
@chapter Working with basic blocks in the JIT
@cindex Working with basic blocks

@include libjitext-block.texi

@c -----------------------------------------------------------------------

@node Intrinsics, Exceptions, Basic Blocks, Top
@chapter Intrinsic functions available to libjit users
@cindex Intrinsics

@include libjitext-intrinsic.texi

@c -----------------------------------------------------------------------

@node Exceptions, Breakpoint Debugging, Intrinsics, Top
@chapter Handling exceptions
@cindex Handling exceptions

@include libjitext-except.texi

@c -----------------------------------------------------------------------

@node Breakpoint Debugging, ELF Binaries, Exceptions, Top
@chapter Hooking a breakpoint debugger into libjit
@cindex Breakpoint debugging

@include libjitext-debugger.texi

@c -----------------------------------------------------------------------

@node ELF Binaries, Utility Routines, Breakpoint Debugging, Top
@chapter Manipulating ELF binaries
@cindex ELF binaries

@include libjitext-elf-read.texi

@c -----------------------------------------------------------------------

@node Utility Routines, Diagnostic Routines, ELF Binaries, Top
@chapter Miscellaneous utility routines
@cindex Utility routines
@cindex jit-util.h

The @code{libjit} library provides a number of utility routines
that it itself uses internally, but which may also be useful to front ends.

@include libjitext-util.texi
@include libjitext-meta.texi
@include libjitext-apply.texi
@include libjitext-walk.texi
@include libjitext-dynlib.texi
@include libjitext-cpp-mangle.texi

@c -----------------------------------------------------------------------

@node Diagnostic Routines, C++ Interface, Utility Routines, Top
@chapter Diagnostic routines
@cindex Diagnostic routines

@include libjitext-dump.texi

@c -----------------------------------------------------------------------

@node C++ Interface, C++ Contexts, Diagnostic Routines, Top
@chapter Using libjit from C++
@cindex Using libjit from C++

This chapter describes the classes and methods that are available
in the @code{libjitplus} library.  To use this library, you must
include the header @code{<jit/jit-plus.h>} and link with the
@code{-ljitplus} and @code{-ljit} options.

@menu
* C++ Contexts::            Contexts in C++
* C++ Values::              Values in C++
* C++ Functions::           Functions in C++
@end menu

@c -----------------------------------------------------------------------

@node C++ Contexts, C++ Values, C++ Interface, C++ Interface
@chapter Contexts in C++
@cindex C++ contexts

@include libjitext-plus-context.texi

@c -----------------------------------------------------------------------