Next: , Previous: , Up: Top  


3 GNU lightning’s instruction set

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:

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.

Binary ALU operations

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)
Unary ALU operations

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.

Compare instructions

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)
Transfer operations

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
Network extensions

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 
Load operations

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)
Store operations

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.

Argument management

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.

Branch instructions

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
Jump and return operations

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.

Labels

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

label is normally used as patch_at argument for backward jumps.

        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 note and name because it is a valid argument to address.

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 patch with the movi, but on some special conditions it is required to create an "unbound" label.

Function prolog

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

Footnotes

(1)

The sign bit is propagated unless using the _u modifier.

(2)

The sign bit is propagated unless using the _u modifier.

(3)

“Return a value” means that GNU lightning code that compile these instructions return a value when expanded.

(4)

These mnemonics mean, respectively, branch if mask set and branch if mask cleared.


Next: , Previous: , Up: Top