view release on metacpan or  search on metacpan

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

@chapter Values in C++
@cindex C++ values

@include libjitext-plus-value.texi

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

@node C++ Functions, Porting, C++ Values, C++ Interface
@chapter Functions in C++
@cindex C++ functions

@include libjitext-plus-function.texi

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

@node Porting, Porting Apply, C++ Functions, Top
@chapter Porting libjit to new architectures
@cindex Porting libjit

This chapter describes what needs to be done to port @code{libjit}
to a new CPU architecture.  It is assumed that the reader is familiar
with compiler implementation techniques and the particulars of their
target CPU's instruction set.

We will use @code{ARCH} to represent the name of the architecture
in the sections that follow.  It is usually the name of the CPU in
lower case (e.g. @code{x86}, @code{arm}, @code{ppc}, etc).  By
convention, all back end functions should be prefixed with @code{_jit},
because they are not part of the public API.

@menu
* Porting Apply::           Porting the function apply facility
* Instruction Generation::  Creating the instruction generation macros
* Architecture Rules::      Writing the architecture definition rules
* Register Allocation::     Allocating registers in the back end
@end menu

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

@node Porting Apply, Instruction Generation, Porting, Porting
@section Porting the function apply facility
@cindex Porting apply

The first step in porting @code{libjit} to a new architecture is to port
the @code{jit_apply} facility.  This provides support for calling
arbitrary C functions from your application or from JIT'ed code.
If you are familiar with @code{libffi} or @code{ffcall}, then
@code{jit_apply} provides a similar facility.

Even if you don't intend to write a native code generator, you will
probably still need to port @code{jit_apply} to each new architecture.

The @code{libjit} library makes use of gcc's @code{__builtin_apply}
facility to do most of the hard work of function application.
This gcc facility takes three arguments: a pointer to the function
to invoke, a structure containing register arguments, and a size
value that indicates the number of bytes to push onto the stack
for the call.

Unfortunately, the register argument structure is very system dependent.
There is no standard format for it, but it usually looks something
like this:

@table @code
@item stack_args
Pointer to an array of argument values to push onto the stack.

@item struct_ptr
Pointer to the buffer to receive a @code{struct} return value.
The @code{struct_ptr} field is only present if the architecture
passes @code{struct} pointers in a special register.

@item word_reg[0..N]
Values for the word registers.  Platforms that pass values in
registers will populate these fields.  Not present if the architecture
does not use word registers for function calls.

@item float_reg[0..N]
Values for the floating-point registers.  Not present if the architecture
does not use floating-point registers for function calls.
@end table

It is possible to automatically detect the particulars of this structure
by making test function calls and inspecting where the arguments end up
in the structure.  The @code{gen-apply} program in @code{libjit/tools}
takes care of this.  It outputs the @code{jit-apply-rules.h} file,
which tells @code{jit_apply} how to operate.

The @code{gen-apply} program will normally "just work", but it is possible
that some architectures will be stranger than usual.  You will need to modify
@code{gen-apply} to detect this additional strangeness, and perhaps
also modify @code{libjit/jit/jit-apply.c}.

If you aren't using gcc to compile @code{libjit}, then things may
not be quite this easy.  You may have to write some inline assembly
code to emulate @code{__builtin_apply}.  See the file
@code{jit-apply-x86.h} for an example of how to do this.
Be sure to add an @code{#include} line to @code{jit-apply-func.h}
once you do this.

The other half of @code{jit_apply} is closure and redirector support.
Closures are used to wrap up interpreted functions so that they can be
called as regular C functions.  Redirectors are used to help compile a
JIT'ed function on-demand, and then redirect control to it.

Unfortunately, you will have to write some assembly code to support
closures and redirectors.  The builtin gcc facilities are not complete
enough to handle the task.  See @code{jit-apply-x86.c} and
@code{jit-apply-arm.c} for some examples from existing architectures.
You may be able to get some ideas from the @code{libffi} and
@code{ffcall} libraries as to what you need to do on your architecture.

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

@node Instruction Generation, Architecture Rules, Porting Apply, Porting
@section Creating the instruction generation macros
@cindex Instruction generation macros

You will need a large number of macros and support functions to
generate the raw instructions for your chosen CPU.  These macros are
fairly generic and are not necessarily specific to @code{libjit}.