Next: GNU lightning examples, Previous: Installation, Up: Top
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:
sub or mul
r or i)
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 _u modifier.
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 allocai instruction.
Of the general-purpose registers, at least three are guaranteed to be
preserved across function calls (V0, V1 and
V2) and at least three are not (R0, R1 and
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 JIT_V_NUM
(for callee-save registers).
There are at least six floating-point registers, named F0 to
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
floating-point registers.
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 addc, and
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
register operands.
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 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)
These accept two operands, both of which must be registers.
negr _f _d O1 = -O2 comr O1 = ~O2
There 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
registers, while mov accepts an immediate value as the second
operand.
Unlike movr and 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 extr_f
and extr_d.
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_f_i,
truncr_f_l, truncr_d_i and truncr_d_l to match
the equivalent C code. Only the _i modifier is available in
32-bit architectures.
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.
htonr Host-to-network (big endian) order ntohr Network-to-host order
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.
The _ui and _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 _uc _s _us _i _ui _l _f _d *O1 = O2 sti _c _uc _s _us _i _ui _l _f _d *O1 = O2 stxr _c _uc _s _us _i _ui _l _f _d *(O1+O2) = O3 stxi _c _uc _s _us _i _ui _l _f _d *(O1+O2) = O3
As for the load operations, the _ui and _l types are
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.
These are:
prepare (not specified) pushargr _c _uc _s _us _i _ui _l _f _d pushargi _c _uc _s _us _i _ui _l _f _d arg _c _uc _s _us _i _ui _l _f _d getarg _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 retval _c _uc _s _us _i _ui _l _f _d epilog (not specified)
As with other operations that use a type modifier, the _ui and
_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.
prepare, pusharg, and retval are used by the caller,
while arg, getarg and 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
the pushargr or pushargi to push the arguments in
left to right order; and use finish or call (explained below)
to perform the actual call.
arg and getarg 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 getarg.3 You should call
arg as soon as possible, before any function call or, more
easily, right after the prolog instructions
(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
run-time.
Finally, the 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
retr or 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 lightning if starting a new
function (what should be done after a ret call) or finishing
generating jit.
You should observe a few rules when using these macros. First of
all, if calling a varargs function, you should use the ellipsis
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
just call.
Like 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.
They are:
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 ret which has none; the
difference between finishi and calli is that the
latter does not clean the stack from pushed parameters (if any)
and the former must always follow a prepare
instruction.
callr (not specified) function call to a register calli (not specified) function call to O1 finishr (not specified) function call to a register finishi (not specified) function call to 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
numbers.
These macros are used to set up a function prolog. The allocai
call accept a single integer argument and returns an offset value
for stack storage access.
prolog (not specified) function prolog allocai (not specified) reserve 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
the area.
As a small appetizer, here is a small function that adds 1 to the input
parameter (an 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
The sign bit is propagated unless using the _u modifier.
The sign bit is propagated unless using the _u modifier.
“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.
Next: GNU lightning examples, Previous: Installation, Up: Top