GNU lightning’s instruction set was designed by deriving instructions that closely match those of most existing RISC architectures, or that can be easily syntesized if absent. Each instruction is composed of:
u), a type identifier or two, when applicable.
Examples of legal mnemonics are
addr (integer add, with three
register operands) and
muli (integer multiply, with two
register operands and an immediate operand). Each instruction takes
two or three operands; in most cases, one of them can be an immediate
value instead of a register.
Most GNU lightning integer operations are signed wordsize operations, with the exception of operations that convert types, or load or store values to/from memory. When applicable, the types and C types are as follow:
_c signed char _uc unsigned char _s short _us unsigned short _i int _ui unsigned int _l long _f float _d double
Most integer operations do not need a type modifier, and when loading or
storing values to memory there is an alias to the proper operation
using wordsize operands, that is, if ommited, the type is int on
32-bit architectures and long on 64-bit architectures. Note
that lightning also expects
sizeof(void*) to match the wordsize.
When an unsigned operation result differs from the equivalent signed
operation, there is a the
There are at least seven integer registers, of which six are
general-purpose, while the last is used to contain the frame pointer
FP). The frame pointer can be used to allocate and access local
variables on the stack, using the
Of the general-purpose registers, at least three are guaranteed to be
preserved across function calls (
V2) and at least three are not (
R2). Six registers are not very much, but this
restriction was forced by the need to target CISC architectures
which, like the x86, are poor of registers; anyway, backends can
specify the actual number of available registers with the calls
JIT_R_NUM (for caller-save registers) and
(for callee-save registers).
There are at least six floating-point registers, named
F5. These are usually caller-save and are separate from the integer
registers on the supported architectures; on Intel architectures,
in 32 bit mode if SSE2 is not available or use of X87 is forced,
the register stack is mapped to a flat register file. As for the
integer registers, the macro
JIT_F_NUM yields the number of
The complete instruction set follows; as you can see, most non-memory operations only take integers (either signed or unsigned) as operands; this was done in order to reduce the instruction set, and because most architectures only provide word and long word operations on registers. There are instructions that allow operands to be extended to fit a larger data type, both in a signed and in an unsigned way.
These accept three operands; the last one can be an immediate.
addx operations must directly follow
subx must follow
subc; otherwise, results are undefined.
Most, if not all, architectures do not support float or double
immediate operands; lightning emulates those operations by moving the
immediate to a temporary register and emiting the call with only
addr _f _d O1 = O2 + O3 addi _f _d O1 = O2 + O3 addxr O1 = O2 + (O3 + carry) addxi O1 = O2 + (O3 + carry) addcr O1 = O2 + O3, set carry addci O1 = O2 + O3, set carry subr _f _d O1 = O2 - O3 subi _f _d O1 = O2 - O3 subxr O1 = O2 - (O3 + carry) subxi O1 = O2 - (O3 + carry) subcr O1 = O2 - O3, set carry subci O1 = O2 - O3, set carry rsbr _f _d O1 = O3 - O1 rsbi _f _d O1 = O3 - O1 mulr _f _d O1 = O2 * O3 muli _f _d O1 = O2 * O3 divr _u _f _d O1 = O2 / O3 divi _u _f _d O1 = O2 / O3 remr _u O1 = O2 % O3 remi _u O1 = O2 % O3 andr O1 = O2 & O3 andi O1 = O2 & O3 orr O1 = O2 | O3 ori O1 = O2 | O3 xorr O1 = O2 ^ O3 xori O1 = O2 ^ O3 lshr O1 = O2 << O3 lshi O1 = O2 << O3 rshr _u O1 = O2 >> O3(1) rshi _u O1 = O2 >> O3(2) movzr O1 = O3 ? O1 : O2 movnr O1 = O3 ? O2 : O1
These accept two result registers, and two operands; the last one can be an immediate. The first two arguments cannot be the same register.
qmul stores the low word of the result in
O1 and the
high word in
O2. For unsigned multiplication,
means there was no overflow. For signed multiplication, no overflow
check is based on sign, and can be detected if
O2 is zero or
qdiv stores the quotient in
O1 and the remainder in
O2. It can be used as quick way to check if a division is
exact, in which case the remainder is zero.
qmulr _u O1 O2 = O3 * O4 qmuli _u O1 O2 = O3 * O4 qdivr _u O1 O2 = O3 / O4 qdivi _u O1 O2 = O3 / O4
These accept two operands, both of which must be registers.
negr _f _d O1 = -O2 comr O1 = ~O2
These unary ALU operations are only defined for float operands.
absr _f _d O1 = fabs(O2) sqrtr O1 = sqrt(O2)
Besides requiring the
r modifier, there are no unary operations
with an immediate operand.
These accept three operands; again, the last can be an immediate. The last two operands are compared, and the first operand, that must be an integer register, is set to either 0 or 1, according to whether the given condition was met or not.
The conditions given below are for the standard behavior of C, where the “unordered” comparison result is mapped to false.
ltr _u _f _d O1 = (O2 < O3) lti _u _f _d O1 = (O2 < O3) ler _u _f _d O1 = (O2 <= O3) lei _u _f _d O1 = (O2 <= O3) gtr _u _f _d O1 = (O2 > O3) gti _u _f _d O1 = (O2 > O3) ger _u _f _d O1 = (O2 >= O3) gei _u _f _d O1 = (O2 >= O3) eqr _f _d O1 = (O2 == O3) eqi _f _d O1 = (O2 == O3) ner _f _d O1 = (O2 != O3) nei _f _d O1 = (O2 != O3) unltr _f _d O1 = !(O2 >= O3) unler _f _d O1 = !(O2 > O3) ungtr _f _d O1 = !(O2 <= O3) unger _f _d O1 = !(O2 < O3) uneqr _f _d O1 = !(O2 < O3) && !(O2 > O3) ltgtr _f _d O1 = !(O2 >= O3) || !(O2 <= O3) ordr _f _d O1 = (O2 == O2) && (O3 == O3) unordr _f _d O1 = (O2 != O2) || (O3 != O3)
These accept two operands; for
ext both of them must be
mov accepts an immediate value as the second
movi, the other instructions are used
to truncate a wordsize operand to a smaller integer data type or to
convert float data types. You can also use
extr to convert an
integer to a floating point value: the usual options are
movr _f _d O1 = O2 movi _f _d O1 = O2 extr _c _uc _s _us _i _ui _f _d O1 = O2 truncr _f _d O1 = trunc(O2)
In 64-bit architectures it may be required to use
truncr_d_l to match
the equivalent C code. Only the
_i modifier is available in
truncr_f_i = <int> O1 = <float> O2 truncr_f_l = <long>O1 = <float> O2 truncr_d_i = <int> O1 = <double>O2 truncr_d_l = <long>O1 = <double>O2
The float conversion operations are destination first, source second, but the order of the types is reversed. This happens for historical reasons.
extr_f_d = <double>O1 = <float> O2 extr_d_f = <float> O1 = <double>O2
These accept two operands, both of which must be registers; these
two instructions actually perform the same task, yet they are
assigned to two mnemonics for the sake of convenience and
completeness. As usual, the first operand is the destination and
the second is the source.
_ul variant is only available in 64-bit architectures.
htonr _us _ui _ul Host-to-network (big endian) order ntohr _us _ui _ul Network-to-host order
bswapr can be used to unconditionally byte-swap an operand.
On little-endian architectures,
_ul variant is only available in 64-bit architectures.
bswapr _us _ui _ul 01 = byte_swap(02)
ld accepts two operands while
ldx accepts three;
in both cases, the last can be either a register or an immediate
value. Values are extended (with or without sign, according to
the data type specification) to fit a whole register.
_l types are only available in 64-bit
architectures. For convenience, there is a version without a
type modifier for integer or pointer operands that uses the
appropriate wordsize call.
ldr _c _uc _s _us _i _ui _l _f _d O1 = *O2 ldi _c _uc _s _us _i _ui _l _f _d O1 = *O2 ldxr _c _uc _s _us _i _ui _l _f _d O1 = *(O2+O3) ldxi _c _uc _s _us _i _ui _l _f _d O1 = *(O2+O3)
st accepts two operands while
stx accepts three; in
both cases, the first can be either a register or an immediate
value. Values are sign-extended to fit a whole register.
str _c _s _i _l _f _d *O1 = O2 sti _c _s _i _l _f _d *O1 = O2 stxr _c _s _i _l _f _d *(O1+O2) = O3 stxi _c _s _i _l _f _d *(O1+O2) = O3
Note that the unsigned type modifier is not available, as the store
only writes to the 1, 2, 4 or 8 sized memory address.
_l type is only available in 64-bit architectures, and for
convenience, there is a version without a type modifier for integer or
pointer operands that uses the appropriate wordsize call.
prepare (not specified) va_start (not specified) pushargr _c _uc _s _us _i _ui _l _f _d pushargi _c _uc _s _us _i _ui _l _f _d va_push (not specified) arg _c _uc _s _us _i _ui _l _f _d getarg _c _uc _s _us _i _ui _l _f _d va_arg _d putargr _c _uc _s _us _i _ui _l _f _d putargi _c _uc _s _us _i _ui _l _f _d ret (not specified) retr _c _uc _s _us _i _ui _l _f _d reti _c _uc _s _us _i _ui _l _f _d reti _f _d va_end (not specified) retval _c _uc _s _us _i _ui _l _f _d epilog (not specified)
As with other operations that use a type modifier, the
_l types are only available in 64-bit architectures, but there
are operations without a type modifier that alias to the appropriate
integer operation with wordsize operands.
retval are used by the caller,
ret are used by the callee.
A code snippet that wants to call another procedure and has to pass
arguments must, in order: use the
prepare instruction and use
pushargi to push the arguments in
left to right order; and use
call (explained below)
to perform the actual call.
handling integer types can be used without a type modifier.
It is suggested to use matching type modifiers to
getarg otherwise problems will happen if generating jit for
environments that require arguments to be truncated and zero or sign
extended by the caller and/or excess arguments might be passed packed
in the stack. Currently only Apple systems with
aarch64 cpus are
known to have this restriction.
va_start returns a
va_list. To fetch
va_arg for integers and
va_arg_d for doubles.
va_push is required when passing a
va_list to another function,
because not all architectures expect it as a single pointer. Known case
is DEC Alpha, that requires it as a structure passed by value.
putarg are used by the callee.
arg is different from other instruction in that it does not
actually generate any code: instead, it is a function which returns
a value to be passed to
putarg. 3 You should call
arg as soon as possible, before any function call or, more
easily, right after the
(which is treated later).
getarg accepts a register argument and a value returned by
arg, and will move that argument to the register, extending
it (with or without sign, according to the data type specification)
to fit a whole register. These instructions are more intimately
related to the usage of the GNU lightning instruction set in code
that generates other code, so they will be treated more
specifically in Generating code at
putarg is a mix of
pusharg in that
it accepts as first argument a register or immediate, and as
second argument a value returned by
arg. It allows changing,
or restoring an argument to the current function, and is a
construct required to implement tail call optimization. Note that
arguments in registers are very cheap, but will be overwritten
at any moment, including on some operations, for example division,
that on several ports is implemented as a function call.
retval instruction fetches the return value of a
called function in a register. The
retval instruction takes a
register argument and copies the return value of the previously called
function in that register. A function with a return value should use
reti to put the return value in the return register
before returning. See the Fibonacci numbers, for an example.
epilog is an optional call, that marks the end of a function
body. It is automatically generated by GNU lightning if starting a new
function (what should be done after a
ret call) or finishing
It is very important to note that the fact that
optional may cause a common mistake. Consider this:
fun1: prolog ... ret fun2: prolog
epilog is added when finding a new
this will cause the
fun2 label to actually be before the
fun1. Because GNU lightning will actually
understand it as:
fun1: prolog ... ret fun2: epilog prolog
You should observe a few rules when using these macros. First of
all, if calling a varargs function, you should use the
call to mark the position of the ellipsis in the C prototype.
You should not nest calls to
prepare inside a
prepare/finish block. Doing this will result in undefined
behavior. Note that for functions with zero arguments you can use
arg, these also return a value which, in this case,
is to be used to compile forward branches as explained in
Fibonacci numbers. They accept two operands to be
compared; of these, the last can be either a register or an immediate.
bltr _u _f _d if (O2 < O3) goto O1 blti _u _f _d if (O2 < O3) goto O1 bler _u _f _d if (O2 <= O3) goto O1 blei _u _f _d if (O2 <= O3) goto O1 bgtr _u _f _d if (O2 > O3) goto O1 bgti _u _f _d if (O2 > O3) goto O1 bger _u _f _d if (O2 >= O3) goto O1 bgei _u _f _d if (O2 >= O3) goto O1 beqr _f _d if (O2 == O3) goto O1 beqi _f _d if (O2 == O3) goto O1 bner _f _d if (O2 != O3) goto O1 bnei _f _d if (O2 != O3) goto O1 bunltr _f _d if !(O2 >= O3) goto O1 bunler _f _d if !(O2 > O3) goto O1 bungtr _f _d if !(O2 <= O3) goto O1 bunger _f _d if !(O2 < O3) goto O1 buneqr _f _d if !(O2 < O3) && !(O2 > O3) goto O1 bltgtr _f _d if !(O2 >= O3) || !(O2 <= O3) goto O1 bordr _f _d if (O2 == O2) && (O3 == O3) goto O1 bunordr _f _d if !(O2 != O2) || (O3 != O3) goto O1 bmsr if O2 & O3 goto O1 bmsi if O2 & O3 goto O1 bmcr if !(O2 & O3) goto O1 bmci if !(O2 & O3) goto O1(4) boaddr _u O2 += O3, goto O1 if overflow boaddi _u O2 += O3, goto O1 if overflow bxaddr _u O2 += O3, goto O1 if no overflow bxaddi _u O2 += O3, goto O1 if no overflow bosubr _u O2 -= O3, goto O1 if overflow bosubi _u O2 -= O3, goto O1 if overflow bxsubr _u O2 -= O3, goto O1 if no overflow bxsubi _u O2 -= O3, goto O1 if no overflow
These accept one argument except
have none; the difference between
is that the latter does not clean the stack from pushed parameters
(if any) and the former must always follow a
callr (not specified) function call to register O1 calli (not specified) function call to immediate O1 finishr (not specified) function call to register O1 finishi (not specified) function call to immediate O1 jmpr (not specified) unconditional jump to register jmpi (not specified) unconditional jump ret (not specified) return from subroutine retr _c _uc _s _us _i _ui _l _f _d reti _c _uc _s _us _i _ui _l _f _d retval _c _uc _s _us _i _ui _l _f _d move return value to register
Like branch instruction,
jmpi also returns a value which is to
be used to compile forward branches. See Fibonacci
There are 3 GNU lightning instructions to create labels:
label (not specified) simple label forward (not specified) forward label indirect (not specified) special simple label
The following instruction is used to specify a minimal alignment for the next instruction, usually with a label:
align (not specified) align code
align is the next instruction, also usually used with
skip (not specified) skip code
It is used to specify a minimal number of bytes of nops to be inserted before the next instruction.
label is normally used as
patch_at argument for backward
jit_node_t *jump, *label; label = jit_label(); ... jump = jit_beqr(JIT_R0, JIT_R1); jit_patch_at(jump, label);
forward is used to patch code generation before the actual
position of the label is known.
jit_node_t *jump, *label; label = jit_forward(); jump = jit_beqr(JIT_R0, JIT_R1); jit_patch_at(jump, label); ... jit_link(label);
indirect is useful when creating jump tables, and tells
GNU lightning to not optimize out a label that is not the target of
any jump, because an indirect jump may land where it is defined.
jit_node_t *jump, *label; ... jmpr(JIT_R0); /* may jump to label */ ... label = jit_indirect();
indirect is an special case of
because it is a valid argument to
Note that the usual idiom to write the previous example is
jit_node_t *addr, *jump; addr = jit_movi(JIT_R0, 0); /* immediate is ignored */ ... jmpr(JIT_R0); ... jit_patch(addr); /* implicit label added */
that automatically binds the implicit label added by
movi, but on some special conditions it is required to create
an "unbound" label.
align is useful for creating multiple entry points to a
(trampoline) function that are all accessible through a single
align receives an integer argument that
defines the minimal alignment of the address of a label directly
align instruction. The integer argument must be
a power of two and the effective alignment will be a power of two no
less than the argument to
align. If the argument to
align is 16 or more, the effective alignment will match the
specified minimal alignment exactly.
jit_node_t *forward, *label1, *label2, *jump; unsigned char *addr1, *addr2; forward = jit_forward(); jit_align(16); label1 = jit_indirect(); /* first entry point */ jump = jit_jmpi(); /* jump to first handler */ jit_patch_at(jump, forward); jit_align(16); label2 = jit_indirect(); /* second entry point */ ... /* second handler */ jit_jmpr(...); jit_link(forward); ... /* first handler /* jit_jmpr(...); ... jit_emit(); addr1 = jit_address(label1); addr2 = jit_address(label2); assert(addr2 - addr1 == 16); /* only one of the addresses needs to be remembered */
skip is useful for reserving space in the code buffer that can
later be filled (possibly with the help of the pair of functions
These macros are used to set up a function prolog. The
call accept a single integer argument and returns an offset value
for stack storage access. The
allocar accepts two registers
arguments, the first is set to the offset for stack access, and the
second is the size in bytes argument.
prolog (not specified) function prolog allocai (not specified) reserve space on the stack allocar (not specified) allocate space on the stack
allocai receives the number of bytes to allocate and returns
the offset from the frame pointer register
FP to the base of
allocar receives two register arguments. The first is where
to store the offset from the frame pointer register
FP to the
base of the area. The second argument is the size in bytes. Note
allocar is dynamic allocation, and special attention
should be taken when using it. If called in a loop, every iteration
will allocate stack space. Stack space is aligned from 8 to 64 bytes
depending on backend requirements, even if allocating only one byte.
It is advisable to not use it with
should work with
frame with special care to call only once,
but is not supported if used in
tramp, even if called only
As a small appetizer, here is a small function that adds 1 to the input
int). I’m using an assembly-like syntax here which
is a bit different from the one used when writing real subroutines with
GNU lightning; the real syntax will be introduced in See Generating code at run-time.
incr: prolog in = arg ! We have an integer argument getarg R0, in ! Move it to R0 addi R0, R0, 1 ! Add 1 retr R0 ! And return the result
And here is another function which uses the
printf function from
the standard C library to write a number in hexadecimal notation:
printhex: prolog in = arg ! Same as above getarg R0, in prepare ! Begin call sequence for printf pushargi "%x" ! Push format string ellipsis ! Varargs start here pushargr R0 ! Push second argument finishi printf ! Call printf ret ! Return to caller
During code generation, GNU lightning occasionally needs scratch registers or needs to use architecture-defined registers. For that, GNU lightning internally maintains register liveness information.
In the following example,
qdivr will need special registers like
R0 on some architectures. As GNU lightning understands that
R0 is used in the subsequent instruction, it will create
save/restore code for
R0 in case.
... qdivr V0, V1, V2, V3 movr V3, R0 ...
The same is not true in the example that follows. Here,
not alive after the division operation because
R0 is neither an
argument register nor a callee-save register. Thus, no save/restore
R0 will be created in case.
... qdivr V0, V1, V2, V3 jmpr R1 ...
live instruction can be used to mark a register as live after
it as in the following example. Here,
R0 will be preserved
across the division.
... qdivr V0, V1, V2, V3 live R0 jmpr R1 ...
live instruction is useful at code entry and exit points,
like after and before a
Frequently it is required to generate jit code that must jump to
code generated later, possibly from another
These require compatible stack frames.
GNU lightning provides two primitives from where trampolines, continuations and tail call optimization can be implemented.
frame (not specified) create stack frame tramp (not specified) assume stack frame
frame receives an integer argument5 that defines the size in
bytes for the stack frame of the current,
jit function. To calculate this value, a good formula is maximum
number of arguments to any called native function times
eight6, plus the sum of the arguments to any call to
jit_allocai. GNU lightning automatically adjusts this value
for any backend specific stack memory it may need, or any
frame also instructs GNU lightning to save all callee
save registers in the prolog and reload in the epilog.
main: ! jit entry point prolog ! function prolog frame 256 ! save all callee save registers and ! reserve at least 256 bytes in stack main_loop: ... jmpi handler ! jumps to external code ... ret ! return to the caller
tramp differs from
frame only that a prolog and epilog
will not be generated. Note that
prolog must still be used.
The code under
tramp must be ready to be entered with a jump
at the prolog position, and instead of a return, it must end with
a non conditional jump.
tramp exists solely for the fact
that it allows optimizing out prolog and epilog code that would
never be executed.
handler: ! handler entry point prolog ! function prolog tramp 256 ! assumes all callee save registers ! are saved and there is at least ! 256 bytes in stack ... jmpi main_loop ! return to the main loop
GNU lightning only supports Tail Call Optimization using the
tramp construct. Any other way is not guaranteed to
work on all ports.
An example of a simple (recursive) tail call optimization:
factorial: ! Entry point of the factorial function prolog in = arg ! Receive an integer argument getarg R0, in ! Move argument to RO prepare pushargi 1 ! This is the accumulator pushargr R0 ! This is the argument finishi fact ! Call the tail call optimized function retval R0 ! Fetch the result retr R0 ! Return it epilog ! Epilog *before* label before prolog fact: ! Entry point of the helper function prolog frame 16 ! Reserve 16 bytes in the stack fact_entry: ! This is the tail call entry point ac = arg ! The accumulator is the first argument in = arg ! The factorial argument getarg R0, ac ! Move the accumulator to R0 getarg R1, in ! Move the argument to R1 blei fact_out, R1, 1 ! Done if argument is one or less mulr R0, R0, R1 ! accumulator *= argument putargr R0, ac ! Update the accumulator subi R1, R1, 1 ! argument -= 1 putargr R1, in ! Update the argument jmpi fact_entry ! Tail Call Optimize it! fact_out: retr R0 ! Return the accumulator
forward_p (not specified) forward label predicate indirect_p (not specified) indirect label predicate target_p (not specified) used label predicate arg_register_p (not specified) argument kind predicate callee_save_p (not specified) callee save predicate pointer_p (not specified) pointer predicate
forward_p expects a
jit_node_t* argument, and
returns non zero if it is a forward label reference, that is,
a label returned by
forward, that still needs a
indirect_p expects a
jit_node_t* argument, and returns
non zero if it is an indirect label reference, that is, a label that
was returned by
target_p expects a
jit_node_t* argument, that is any
kind of label, and will return non zero if there is at least one
jump or move referencing it.
arg_register_p expects a
jit_node_t* argument, that must
have been returned by
will return non zero if the argument lives in a register. This call
is useful to know the live range of register arguments, as those
are very fast to read and write, but have volatile values.
callee_save_p expects a valid
JIT_Fn, and will return non zero if the register is callee
save. This call is useful because on several ports, the
JIT_Fn registers are actually callee save; no need
to save and load the values when making function calls.
pointer_p expects a pointer argument, and will return non
zero if the pointer is inside the generated jit code. Must be
jit_emit and before
Only compare-and-swap is implemented. It accepts four operands; the second can be an immediate.
The first argument is set with a boolean value telling if the operation did succeed.
Arguments must be different, cannot use the result register to also pass an argument.
The second argument is the address of a machine word.
The third argument is the old value.
The fourth argument is the new value.
casr 01 = (*O2 == O3) ? (*O2 = O4, 1) : 0 casi 01 = (*O2 == O3) ? (*O2 = O4, 1) : 0
If value at the address in the second argument is equal to the third argument, the address value is atomically modified to the value of the fourth argument and the first argument is set to a non zero value.
If the value at the address in the second argument is not equal to the third argument nothing is done and the first argument is set to zero.
The sign bit is propagated unless using the
The sign bit is propagated unless using the
“Return a value” means that GNU lightning code that compile these instructions return a value when expanded.
These mnemonics mean, respectively, branch if mask set and branch if mask cleared.
It is not automatically computed because it does not know about the requirement of later generated code.
Times eight so that it works for double arguments. And would not need conditionals for ports that pass arguments in the stack.