The CLISP bytecode specification

The CLISP compiler compiles Lisp programs into an instruction code for a virtual processor. This bytecode is optimized for saving space in the most common cases of Lisp programs. The main advantages/drawbacks of this approach, compared to native code compilation, are:

Bytecode compiled programs are a lot smaller than when compiled to native code. This results in better use of CPU caches, and in less virtual memory paging. Users perceive this as good responsiveness.
Maximum execution speed (throughput in tight loops) is limited.
Since no bytecode instructions are provided for "unsafe" operations (like unchecked array accesses, or "fast" car/cdr), programs run with all safety checks enabled even when compiled.
Execution speed of a program can easily be understood by looking at the output of the disassemble function. A rule of thumb is that every elementary instruction costs 1 time unit, whereas a function call costs 3 to 4 time units.
Needing to do no type inference, the compiler is pretty straightforward and fast. As a consequence, the definition of CLOS generic functions, which needs to compile small pieces of generated code, is not perceived to be slow.
The compiler is independent from the hardware CPU. Different backends, one for each hardware CPU, are not needed. As a consequence, the compiler is fairly small (and would be easily maintainable if written in a less kludgy way...), and it is impossible for the compiler writer to introduce CPU dependent bugs.

The virtual machine

The bytecode can be thought as being interpreted by a virtual processor. The engine which actually interprets the bytecode (the "implementation of the virtual machine") is actually a C function, but it could as well be a just-in-time compiler which translates a function's bytecode into hardware CPU instructions the first time said function is called.

The virtual machine is a stack machine with two stacks:

STACK, a stack for Lisp objects and frames.
SP, a stack for other data and pointers.

This two-stack architecture permits to save an unlimited number of Lisp objects on the STACK (needed for handling of Common Lisp multiple values), without consing. Also, in a world with a compacting no-ambiguous-roots garbage collector, STACK must only hold Lisp objects, and SP can hold all the other data belonging to a frame, which would not fit into STACK without tagging/untagging overhead.

The scope of STACK and SP is only valid for a given function invocation. Whereas the amount of STACK space needed for executing a function (excluding other function calls) is unlimited, the amount of SP space needed is known a priori, at compile time. When a function is called, no relation is specified between the caller's STACK and the callee's STACK, and between the caller's SP and the callee's SP. The bytecode is designed so that outgoing arguments on the caller's STACK can be shared by the caller's incoming arguments area (on the callee's STACK), but a virtual machine implementation may also copy outgoing arguments to incoming arguments instead of sharing them.

The virtual machine has a special data structure, values, containing the "top of stack", specially adapted to Common Lisp multiple values:

mv_count, an unsigned integer.
value1, the first value, a Lisp object. If mv_count = 0, this is nil.
mv_space, all values except the first one, an array of Lisp objects.

The contents of values is short-lived. It does not survive a function call, not even a garbage collection.

The interpretation of some bytecode instructions depends on a constant, jmpbufsize. This is a CPU dependent number, the value of system::*jmpbuf-size*. In C, it is defined as ceiling(sizeof(jmp_buf),sizeof(void*)).

The structure of compiled functions

A compiled function consists of two objects: The function itself, containing the references to all Lisp objects needed for the bytecode, and a byte vector containing only immediate data, including the bytecode proper.

Typically, the byte vector is about twice as large as the function vector. The separation thus helps the garbage collector (since the byte vector does not need to be scanned for pointers).

The function looks like this (cf. the C type Cclosure):

name: This is the name of the function, normally a symbol or a list of the form (setf symbol). It is used for printing the function and for error messages. This field is immutable.
codevec: This is the byte vector. It is a simple-bit-vector (because that's the simplest type in CLISP which contains immediate data -- note that (simple-vector (unsigned-byte 8)) is more complex than this). This field is immutable.
consts[]: The remaining fields in the function object are references to other Lisp objects. These references are immutable, which is why they are called "constants". (The referenced Lisp objects can be mutable objects, such as conses or vectors, however.)

There is actually one exception to the immutability rule: When a generic function's dispatch code is installed, the codevec and consts fields are destructively modified.

Some of the consts can play special roles. A function's looks like this, in more detail:

name: see above
codevec: see above
venv-const*: At most one object, representing the closed-up variables, representing the variables of the lexical environment in which this function was defined. It is a simple-vector, looking like this: #(next value₁ ... value_n) where value₁, ..., value_n are the values of the closed-up variables, and next is either nil or a simple-vector having the same structure.
block-const*: Objects representing closed-up block tags, representing the block tags of the lexical environment in which this function was defined. Each is a cons containing in the cdr part: either a frame pointer to the block frame, or #<DISABLED> if the block has already been left. The car is the block's name, only for error message purposes.
tagbody-const*: Objects representing closed-up tagbody tags, representing the tagbody tags of the lexical environment in which this function was defined. Each is a cons containing in the cdr part: either a frame pointer to the tagbody frame, or #<DISABLED> if the tagbody has already been left. The car is a simple-vector containing the names of the tagbody tags, only for error message purposes.
keyword-const*: If the function was defined with a lambda list containing &key, here come the symbols ("keywords"), in their correct order. They are used by the interpreter during function call.
other-const*: Other objects needed by the function's bytecode.

If venv-const, block-const, tagbody-const are all absent, the function is called autonomous. This is the case if the function does not refer to lexical variables, blocks or tags defined in compile code outside of the function. In particular, it is the case if the function is defined in a null lexical environment.

If some venv-const, block-const, or tagbody-const are present, the function (a "closure") is created at runtime. The compiler only generates a prototype, containing nil values instead of each venv-const, block-const, tagbody-const. At runtime, a function is created by copying this prototype and replacing the nil values by the definitive ones.

The list (keyword-const* other-const*) normally doesn't contain duplicates, because the compiler removes duplicates when possible. (Duplicates can occur nevertheless, through the use of load-time-value.)

The codevec looks like this (cf. C type Codevec):

spdepth_1 (2 bytes)

The 1 part of the maximal SP depth.

spdepth_jmpbufsize (2 bytes)

The jmpbufsize part of the maximal SP depth. The maximal SP depth (precomputed by the compiler) is given by spdepth_1 + spdepth_jmpbufsize * jmpbufsize.

numreq (2 bytes)

Number of required parameters.

numopt (2 bytes)

Number of optional parameters.

flags (1 byte)

bit 0: set if the function has an &rest parameter
bit 7: set if the function has &key parameters
bit 6: set if the function has &allow-other-keys
bit 4: set if the function is a generic function
bit 3: set if the function is a generic function and its effective method shall be returned (instead of being executed)

signature (1 byte)

An abbreviation code depending on numreq, numopt, flags. It is used for speeding up the function call.

numkey (2 bytes, only if the function has &key)

The number of &key parameters.

keyconsts (2 bytes, only if the function has &key)

The offset of the keyword-const in the function.

byte* (any number of bytes)

The bytecode instructions.

The general structure of the instructions

All instructions consist of one byte, denoting the opcode, and some number of operands.

The conversion from a byte (in the range 0..255) to the opcode is performed by lookup in the table contained in the file bytecode.d.

There are the following types of operands, denoted by different letters:

k, n, m, l: A (nonnegative) numeric operand. The next byte is read. If its bit 7 is zero, then the bits 6..0 give the value (7 bits). If its bit 7 is one, then the bits 6..0 and the subsequent byte together form the value (15 bits).
b: A (nonnegative) 1-byte operand. The next byte is read and is the value.
label: A label operand. A signed numeric operand is read: The next byte is read. If its bit 7 is zero, then the bits 6..0 give the value (7 bits, sign-extended). If its bit 7 is one, then the bits 6..0 and the subsequent byte together form the value (15 bits, sign-extended). If the latter 15-bit result is zero, then four more bytes are read and put together (32 bits, sign-extended). Finally, the bytecode pointer for the target is computed as the current bytecode pointer (pointing after the operand just read), plus the signed numeric operand.

The instruction set

1. Instructions for constants

mnemonic	description	semantics
`(NIL)`	Load `nil` into values.	value1 := `nil`, mv_count := 1
`(PUSH-NIL n)`	Push `n` `nil`s into the STACK.	`n` times do: *--STACK := `nil`, values undefined
`(T)`	Load `t` into values.	value1 := `t`, mv_count := 1
`(CONST n)`	Load the function's `n`th constant into values.	value1 := `consts`[`n`], mv_count := 1

2. Instructions for lexical variables

mnemonic	description	semantics
`(LOAD n)`	Load a directly accessible local variable into values.	value1 := *(STACK+`n`), mv_count := 1
`(LOADI k₁ k₂ n)`	Load an indirectly accessible local variable into values.	`k` := `k₁` + jmpbufsize * `k₂`, value1 := ((SP+`k`)+`n`), mv_count := 1
`(LOADC n m)`	Load a closed-up variable, defined in the same function and directly accessible, into values.	value1 := svref(*(STACK+`n`),1+m), mv_count := 1
`(LOADV k m)`	Load a closed-up variable, defined in an outer function, into values.	`vector` := `venv-const`, `m` times do: `vector` := svref(`vector`,0), value1 := svref(`vector`,m), mv_count := 1
`(LOADIC k₁ k₂ n m)`	Load a closed-up variable, defined in the same function and indirectly accessible, into values.	`k` := `k₁` + jmpbufsize * `k₂`, value1 := svref(((SP+`k`)+`n`),1+m), mv_count := 1
`(STORE n)`	Store values into a directly accessible local variable.	*(STACK+`n`) := value1, mv_count := 1
`(STOREI k₁ k₂ n)`	Store values into an indirectly accessible local variable.	`k` := `k₁` + jmpbufsize * `k₂`, ((SP+`k`)+`n`) := value1, mv_count := 1
`(STOREC n m)`	Store values into a closed-up variable, defined in the same function and directly accessible.	svref(*(STACK+`n`),1+m) := value1, mv_count := 1
`(STOREV k m)`	Store values into a closed-up variable, defined in an outer function.	`vector` := `venv-const`, `m` times do: `vector` := svref(`vector`,0), svref(`vector`,m) := value1, mv_count := 1
`(STOREIC k₁ k₂ n m)`	Store values into a closed-up variable, defined in the same function and indirectly accessible.	`k` := `k₁` + jmpbufsize * `k₂`, svref(((SP+`k`)+`n`),1+m) := value1, mv_count := 1

3. Instructions for dynamic variables

mnemonic	description	semantics
`(GETVALUE n)`	Load a symbol's value into values.	value1 := symbol-value(`consts`[`n`]), mv_count := 1
`(SETVALUE n)`	Store values into a symbol's value.	symbol-value(`consts`[`n`]) := value1, mv_count := 1
`(BIND n)`	Bind a symbol dynamically.	Bind the value of the symbol `consts`[`n`] to value1, implicitly STACK -= 3, values undefined
`(UNBIND1)`	Dissolve one binding frame.	Unbind the binding frame STACK is pointing to, implicitly STACK += 1+2*`x`
`(UNBIND n)`	Dissolve `n` binding frames.	`n` times do: Unbind the binding frame STACK is pointing to, thereby incrementing STACK
`(PROGV)`	Bind a set of symbols dynamically to a set of values.	`symbols` := STACK++, --SP := STACK, build a single binding frame binding the symbols in `symbols` to the values in `value1`, values undefined

4. Instructions for stack operations

mnemonic	description	semantics
`(PUSH)`	Push one object onto the STACK.	*--STACK := value1, values undefined
`(POP)`	Pop one object from the STACK, into values.	value1 := *STACK++, mv_count := 1
`(SKIP n)`	Restore a previous STACK pointer. Remove `n` objects from the STACK.	STACK := STACK + `n`
`(SKIPI k₁ k₂ n)`	Restore a previous STACK pointer. Remove an unknown number of objects from the STACK.	`k` := `k₁` + jmpbufsize * `k₂`, STACK := *(SP+`k`), SP := SP+`k`+1
`(SKIPSP k₁ k₂)`	Restore a previous SP pointer.	`k` := `k₁` + jmpbufsize * `k₂`, SP := SP+`k`

5. Instructions for control flow, jumps

mnemonic	description	semantics
`(SKIP&RET n)`	Clean up the STACK, and return from the function.	STACK := STACK+`n`, return from the function, returning values.
`(SKIP&RETGF n)`	Clean up the STACK, and return from the generic function.	If bit 3 is set in the function's `flags`, then STACK := STACK+`n`, mv_count := 1, and return from the function. Otherwise: if the current function has no `&rest` argument, then STACK := STACK+`n`-`numreq`, apply value1 to the `numreq` arguments still on the STACK, and return from the function. Else STACK := STACK+`n`-`numreq`-1, apply value1 to the `numreq` arguments and the `&rest` argument, all still on the STACK, and return from the function.
`(JMP label)`	Jump to `label`.	PC := `label`.
`(JMPIF label)`	Jump to `label`, if value1 is true.	If value1 is not `nil`, PC := `label`.
`(JMPIFNOT label)`	Jump to `label`, if value1 is false.	If value1 is `nil`, PC := `label`.
`(JMPIF1 label)`	Jump to `label` and forget secondary values, if value1 is true.	If value1 is not `nil`, mv_count := 1, PC := `label`.
`(JMPIFNOT1 label)`	Jump to `label` and forget secondary values, if value1 is false.	If value1 is `nil`, mv_count := 1, PC := `label`.
`(JMPIFATOM label)`	Jump to `label`, if value1 is not a cons.	If value1 is not a cons, PC := `label`. values undefined
`(JMPIFCONSP label)`	Jump to `label`, if value1 is a cons.	If value1 is a cons, PC := `label`. values undefined
`(JMPIFEQ label)`	Jump to `label`, if value1 is `eq` to the top-of-stack.	If eq(value1,*STACK++), PC := `label`. values undefined
`(JMPIFNOTEQ label)`	Jump to `label`, if value1 is not `eq` to the top-of-stack.	If not eq(value1,*STACK++), PC := `label`. values undefined
`(JMPIFEQTO n label)`	Jump to `label`, if the top-of-stack is `eq` to a constant.	If eq(*STACK++,`consts`[`n`]), PC := `label`. values undefined
`(JMPIFNOTEQTO n label)`	Jump to `label`, if the top-of-stack is not `eq` to a constant.	If not eq(*STACK++,`consts`[`n`]), PC := `label`. values undefined
`(JMPHASH n label)`	Table-driven jump, depending on value1.	Lookup value1 in the hash table `consts`[`n`]. (The hash table's test is either EQ or EQL.) If found, the hash table value is a signed fixnum, jump to it: PC := PC + value. Else jump to `label`. values undefined
`(JMPHASHV n label)`	Table-driven jump, depending on value1, inside a generic function.	Lookup value1 in the hash table svref(`consts`[0],`n`). (The hash table's test is either EQ or EQL.) If found, the hash table value is a signed fixnum, jump to it: PC := PC + value. Else jump to `label`. values undefined
`(JSR label)`	Subroutine call.	*--STACK := function. Then start interpreting the bytecode at `label`, with values undefined. When a `(RET)` is encountered, program execution is resumed at the instruction after `(JSR label)`.
`(JMPTAIL m n label)`	Tail subroutine call.	`n` >= `m`. The STACK frame of size `n` is reduced to size `m`: {(STACK+`n`-`m`), ..., (STACK+`n`-1)} := {STACK, ..., (STACK+`m`-1)}. STACK += n-m. *--STACK := function. Then jump to `label`, with values undefined.

6. Instructions for lexical environment, creation of closures

mnemonic	description	semantics
`(VENV)`	Load the `venv-const` into values.	value1 := `consts`[0], mv_count := 1.
`(MAKE-VECTOR1&PUSH n)`	Create a simple-vector used for closed-up variables.	`vector` := new simple-vector of size `n`+1. svref(`vector`,0) := value1. *--STACK := `vector`. values undefined
`(COPY-CLOSURE m n)`	Create a closure by copying the prototype and filling in the lexical environment.	`func` := copy-function(`consts`[`m`]). For `i`=0,..,`n`-1: `func_consts`[i] := *(STACK+`n`-1-`i`). STACK += `n`. value1 := `func`, mv_count := 1

7. Instructions for function calls

mnemonic	description	semantics
`(CALL k n)`	Calls a constant function with `k` arguments.	The function `consts`[`n`] is called with the arguments (STACK+`k`-1), ..., (STACK+0). STACK += `k`. The returned values go into values.
`(CALL0 n)`	Calls a constant function with 0 arguments.	The function `consts`[`n`] is called with 0 arguments. The returned values go into values.
`(CALL1 n)`	Calls a constant function with 1 argument.	The function `consts`[`n`] is called with one argument *STACK. STACK += 1. The returned values go into values.
`(CALL2 n)`	Calls a constant function with 2 arguments.	The function `consts`[`n`] is called with two arguments (STACK+1) and (STACK+0). STACK += 2. The returned values go into values.
`(CALLS1 b)`	Calls a system function with no `&rest`.	Calls the system function FUNTAB[`b`]. The right number of arguments is already on the STACK (including `#<UNBOUND>`s in place of absent `&optional` or `&key` parameters). The arguments are removed from the STACK. The returned values go into values.
`(CALLS2 b)`	Calls a system function with no `&rest`.	Calls the system function FUNTAB[256+`b`]. The right number of arguments is already on the STACK (including `#<UNBOUND>`s in place of absent `&optional` or `&key` parameters). The arguments are removed from the STACK. The returned values go into values.
`(CALLSR m b)`	Calls a system function with `&rest`.	Calls the system function FUNTABR[`b`]. The minimum number of arguments is already on the STACK, and `m` additional arguments as well. The arguments are removed from the STACK. The returned values go into values.
`(CALLC)`	Calls a computed compiled function with no `&key`.	Calls the compiled function value1. The right number of arguments is already on the STACK (including `#<UNBOUND>`s in place of absent `&optional` parameters). The arguments are removed from the STACK. The returned values go into values.
`(CALLCKEY)`	Calls a computed compiled function with `&key`.	Calls the compiled function value1. The right number of arguments is already on the STACK (including `#<UNBOUND>`s in place of absent `&optional` or `&key` parameters). The arguments are removed from the STACK. The returned values go into values.
`(FUNCALL n)`	Calls a computed function.	Calls the function (STACK+`n`) with the arguments (STACK+`n`-1), ..., *(STACK+0). STACK += `n`+1. The returned values go into values.
`(APPLY n)`	Calls a computed function with an unknown number of arguments.	Calls the function (STACK+`n`) with the arguments (STACK+`n`-1), ..., *(STACK+0) and a list of additional arguments value1. STACK += `n`+1. The returned values go into values.

8. Instructions for optional and keyword parameters

mnemonic	description	semantics
`(PUSH-UNBOUND n)`	Push `n` `#<UNBOUND>`s into the STACK.	`n` times do: *--STACK := `#<UNBOUND>`. values undefined
`(UNLIST n m)`	Destructure a proper list.	0 <= `m` <= `n`. `n` times do: --STACK := car(value1), value1 := cdr(value1). During the last `m` iterations, the list value1 may already have reached its end; in this case, --STACK := `#<UNBOUND>`. At the end, value1 must be `nil`. values undefined
`(UNLIST* n m)`	Destructure a proper or dotted list.	0 <= `m` <= `n`, `n` > 0. `n` times do: --STACK := car(value1), value1 := cdr(value1). During the last `m` iterations, the list value1 may already have reached its end; in this case, --STACK := `#<UNBOUND>`. At the end, after `n` cdrs, *--STACK := value1. values undefined
`(JMPIFBOUNDP n label)`	Jump to `label`, if a local variable is not unbound.	If (STACK+`n`) is not `#<UNBOUND>`, value1 := (STACK+`n`), mv_count := 1, PC := `label`. Else: values undefined.
`(BOUNDP n)`	Load `t` or `nil` into values, depending on whether a local variables is not unbound.	If *(STACK+`n`) is not `#<UNBOUND>`, value1 := `t`, mv_count := 1. Else: value1 := `nil`, mv_count := 1.
`(UNBOUND->NIL n)`	If a local variable is unbound, assign a default value `nil` to it.	If (STACK+`n`) is `#<UNBOUND>`, (STACK+`n`) := `nil`.

9. Instructions for multiple values

mnemonic	description	semantics
`(VALUES0)`	Load no values into values.	value1 := `nil`, mv_count := 0
`(VALUES1)`	Forget secondary values.	mv_count := 1
`(STACK-TO-MV n)`	Pop the first `n` objects from STACK into values.	Load values((STACK+`n`-1),...,(STACK+0)) into values. STACK += `n`.
`(MV-TO-STACK)`	Save values on STACK.	Push the mv_count values onto the STACK (in order: value1 comes first). STACK -= mv_count. values undefined
`(NV-TO-STACK n)`	Save `n` values on STACK.	Push the first `n` values onto the STACK (in order: value1 comes first). STACK -= `n`. values undefined
`(MV-TO-LIST)`	Convert multiple values into a list.	value1 := list of values, mv_count := 1
`(LIST-TO-MV)`	Convert a list into multiple values.	Call the function `values-list` with value1 as argument. The returned values go into values.
`(MVCALLP)`	Start a multiple-value-call invocation.	--SP := STACK. --STACK := value1.
`(MVCALL)`	Finish a multiple-value-call invocation.	newSTACK := SP++. Call the function (newSTACK-1), passing it (newSTACK-2), ..., (STACK+0) as arguments. STACK := newSTACK. The returned values go into values.

10. Instructions for block and return-from

mnemonic	description	semantics
`(BLOCK-OPEN n label)`	Create a block frame.	Create a block frame, STACK -= 3, SP -= 2+jmpbufsize. The topmost (third) object in the block frame is cons(`consts`[`n`],frame-pointer). Upon a return-from to this frame, execution will continue at `label`.
`(BLOCK-CLOSE)`	Dissolve a block frame.	Dissolve the block frame at STACK, STACK += 3, SP += 2+jmpbufsize. Mark the block-cons as invalid.
`(RETURN-FROM n)`	Leave a block whose block-cons is given.	block-cons := `consts`[`n`]. If cdr(block-cons) = `#<DISABLED>`, signal an error. Else cdr(block-cons) is a frame-pointer. Unwind the stack up to this frame, pass it values.
`(RETURN-FROM-I k₁ k₂ n)`	Leave a block whose block-cons is indirectly accessible.	`k` := `k₁` + jmpbufsize * `k₂`, block-cons := ((SP+`k`)+`n`). If cdr(block-cons) = `#<DISABLED>`, signal an error. Else cdr(block-cons) is a frame-pointer. Unwind the stack up to this frame, pass it values.

11. Instructions for tagbody and go

mnemonic	description	semantics
`(TAGBODY-OPEN n label₁ ... label_m)`	Create a tagbody frame.	Fetch `consts`[`n`], this is a simple-vector with `m` elements, then decode `m` label operands. Create a tagbody frame, STACK -= 3+`m`, SP -= 1+jmpbufsize. The third object in the tagbody frame is cons(`consts`[`n`],frame-pointer). Upon a go to tag `l` of this frame, execution will continue at `label_l`. values undefined
`(TAGBODY-CLOSE-NIL)`	Dissolve a tagbody frame, and load `nil` into values.	Dissolve the tagbody frame at STACK, STACK += 3+`m`, SP += 1+jmpbufsize. Mark the tagbody-cons as invalid. value1 := `nil`, mv_count := 1.
`(TAGBODY-CLOSE)`	Dissolve a tagbody frame.	Dissolve the tagbody frame at STACK, STACK += 3+`m`, SP += 1+jmpbufsize. Mark the tagbody-cons as invalid.
`(GO n l)`	Jump into a tagbody whose tagbody-cons is given.	tagbody-cons := `consts`[`n`]. If cdr(tagbody-cons) = `#<DISABLED>`, signal an error. Else cdr(tagbody-cons) is a frame-pointer. Unwind the stack up to this frame, pass it the number `l`.
`(GO-I k₁ k₂ n l)`	Jump into a tagbody whose tagbody-cons is indirectly accessible.	`k` := `k₁` + jmpbufsize * `k₂`, tagbody-cons := ((SP+`k`)+`n`). If cdr(tagbody-cons) = `#<DISABLED>`, signal an error. Else cdr(tagbody-cons) is a frame-pointer. Unwind the stack up to this frame, pass it the number `l`.

12. Instructions for catch and throw

mnemonic	description	semantics
`(CATCH-OPEN label)`	Create a catch frame.	Create a catch frame, with value1 as tag. STACK -= 3, SP -= 2+jmpbufsize. Upon a throw to this tag execution continues at `label`.
`(CATCH-CLOSE)`	Dissolve a catch frame.	Dissolve the catch frame at STACK. STACK += 3, SP += 2+jmpbufsize.
`(THROW)`	Non-local exit to a catch frame.	`tag` := *STACK++. Search the innermost catch frame with tag `tag` on the STACK, unwind the stack up to it, pass it values.

13. Instructions for unwind-protect

mnemonic	description	semantics
`(UNWIND-PROTECT-OPEN label)`	Create an unwind-protect frame.	Create an unwind-protect frame. STACK -= 2, SP -= 2+jmpbufsize. When the stack will be unwound by a non-local exit, values will be saved on STACK, and execution will be transferred to `label`.
`(UNWIND-PROTECT-NORMAL-EXIT)`	Dissolve an unwind-protect frame, and start the cleanup code.	Dissolve the unwind-protect frame at STACK. STACK += 2, SP += 2+jmpbufsize. --SP := 0, --SP := 0, *--SP := STACK. Save the values on the STACK, STACK -= mv_count.
`(UNWIND-PROTECT-CLOSE)`	Terminate the cleanup code.	newSTACK := SP++. Load values((newSTACK-1), ..., (STACK+0)) into values. STACK := newSTACK. SPword1 := SP++, SPword2 := *SP++. Continue depending on SPword1 and SPword2. If both are 0, simply continue execution. If SPword2 is 0 but SPword1 is nonzero, interpret it as a label and jump to it.
`(UNWIND-PROTECT-CLEANUP)`	Dissolve an unwind-protect frame, and execute the cleanup code like a subroutine call.	Dissolve the unwind-protect frame at STACK, get `label` out of the frame. STACK += 2, SP += 2+jmpbufsize. --SP := 0, --SP := PC, *--SP := STACK. Save the values on the STACK, STACK -= mv_count. PC := `label`.

14. Instructions for handler-bind

mnemonic	description	semantics
`(HANDLER-OPEN n)`	Create a handler frame.	Create a handler frame, using `consts`[`n`] which contains the condition types, the corresponding labels and the current SP depth (= function entry SP - current SP).
`(HANDLER-BEGIN&PUSH)`	Start a handler.	Restore the same SP state as after the HANDLER-OPEN. value1 := the condition that was passed to the handler, mv_count := 1. *--STACK := value1.

15. Instructions for some inlined functions

mnemonic	description	semantics
`(NOT)`	Inlined call to NOT.	value1 := not(value1), mv_count := 1.
`(EQ)`	Inlined call to EQ.	value1 := eq(*STACK++,value1), mv_count := 1.
`(CAR)`	Inlined call to CAR.	value1 := car(value1), mv_count := 1.
`(CDR)`	Inlined call to CDR.	value1 := cdr(value1), mv_count := 1.
`(CONS)`	Inlined call to CONS.	value1 := cons(*STACK++,value1), mv_count := 1.
`(SYMBOL-FUNCTION)`	Inlined call to SYMBOL-FUNCTION.	value1 := symbol-function(value1), mv_count := 1.
`(SVREF)`	Inlined call to SVREF.	value1 := svref(*STACK++,value1), mv_count := 1.
`(SVSET)`	Inlined call to SYSTEM::SVSTORE.	`arg1` := (STACK+1), `arg2` := (STACK+0), STACK += 2. svref(`arg2`,value1) := `arg1`. value1 := `arg1`, mv_count := 1.
`(LIST n)`	Inlined call to LIST.	value1 := list((STACK+`n`-1),...,(STACK+0)), mv_count := 1, STACK += `n`.
`(LIST* n)`	Inlined call to LIST*.	value1 := list((STACK+`n`-1),...,*(STACK+0),value1), mv_count := 1, STACK += `n`.

16. Combined instructions

The most frequent short sequences of instructions have an equivalent combined instruction. They are only present for space and speed optimization. The only exception is FUNCALL&SKIP&RETGF, whose existence is needed for generic functions.

mnemonic equivalent
(NIL&PUSH) (NIL) (PUSH)
(T&PUSH) (T) (PUSH)
(CONST&PUSH n) (CONST n) (PUSH)
(LOAD&PUSH n) (LOAD n) (PUSH)
(LOADI&PUSH k₁ k₂ n) (LOADI k₁ k₂ n) (PUSH)
(LOADC&PUSH n m) (LOADC n m) (PUSH)
(LOADV&PUSH k m) (LOADV k m) (PUSH)
(POP&STORE n) (POP) (STORE n)
(GETVALUE&PUSH n) (GETVALUE n) (PUSH)
(JSR&PUSH label) (JSR label) (PUSH)
(COPY-CLOSURE&PUSH m n) (COPY-CLOSURE m n) (PUSH)
(CALL&PUSH k n) (CALL k n) (PUSH)
(CALL1&PUSH n) (CALL1 n) (PUSH)
(CALL2&PUSH n) (CALL2 n) (PUSH)
(CALLS1&PUSH b) (CALLS1 b) (PUSH)
(CALLS2&PUSH b) (CALLS2 b) (PUSH)
(CALLSR&PUSH m n) (CALLSR m n) (PUSH)
(CALLC&PUSH) (CALLC) (PUSH)
(CALLCKEY&PUSH) (CALLCKEY) (PUSH)
(FUNCALL&PUSH n) (FUNCALL n) (PUSH)
(APPLY&PUSH n) (APPLY n) (PUSH)
(CAR&PUSH) (CAR) (PUSH)
(CDR&PUSH) (CDR) (PUSH)
(CONS&PUSH) (CONS) (PUSH)
(LIST&PUSH n) (LIST n) (PUSH)
(LIST*&PUSH n) (LIST* n) (PUSH)
(NIL&STORE n) (NIL) (STORE n)
(T&STORE n) (T) (STORE n)
(LOAD&STOREC k n m) (LOAD k) (STOREC n m)
(CALLS1&STORE b k) (CALLS1 b) (STORE k)
(CALLS2&STORE b k) (CALLS2 b) (STORE k)
(CALLSR&STORE m n k) (CALLSR m n) (STORE k)
(LOAD&CDR&STORE n) (LOAD n) (CDR) (STORE n)
(LOAD&CONS&STORE n) (LOAD n+1) (CONS) (STORE n)
(LOAD&INC&STORE n) (LOAD n) (CALL1 #'1+) (STORE n)
(LOAD&DEC&STORE n) (LOAD n) (CALL1 #'1-) (STORE n)
(LOAD&CAR&STORE m n) (LOAD m) (CAR) (STORE n)
(CALL1&JMPIF n label) (CALL1 n) (JMPIF label)
(CALL1&JMPIFNOT n label) (CALL1 n) (JMPIFNOT label)
(CALL2&JMPIF n label) (CALL2 n) (JMPIF label)
(CALL2&JMPIFNOT n label) (CALL2 n) (JMPIFNOT label)
(CALLS1&JMPIF b label) (CALLS1 b) (JMPIF label)
(CALLS1&JMPIFNOT b label) (CALLS1 b) (JMPIFNOT label)
(CALLS2&JMPIF b label) (CALLS2 b) (JMPIF label)
(CALLS2&JMPIFNOT b label) (CALLS2 b) (JMPIFNOT label)
(CALLSR&JMPIF m n label) (CALLSR m n) (JMPIF label)
(CALLSR&JMPIFNOT m n label) (CALLSR m n) (JMPIFNOT label)
(LOAD&JMPIF n label) (LOAD n) (JMPIF label)
(LOAD&JMPIFNOT n label) (LOAD n) (JMPIFNOT label)
(LOAD&CAR&PUSH n) (LOAD n) (CAR) (PUSH)
(LOAD&CDR&PUSH n) (LOAD n) (CDR) (PUSH)
(LOAD&INC&PUSH n) (LOAD n) (CALL1 #'1+) (PUSH)
(LOAD&DEC&PUSH n) (LOAD n) (CALL1 #'1-) (PUSH)
(CONST&SYMBOL-FUNCTION n) (CONST n) (SYMBOL-FUNCTION)
(CONST&SYMBOL-FUNCTION&PUSH n) (CONST n) (SYMBOL-FUNCTION) (PUSH)
(CONST&SYMBOL-FUNCTION&STORE n k) (CONST n) (SYMBOL-FUNCTION) (STORE k)
(APPLY&SKIP&RET n k) (APPLY n) (SKIP&RET k)
(FUNCALL&SKIP&RETGF n k) (FUNCALL n) (SKIP&RETGF k)

mnemonic	equivalent
`(NIL&PUSH)`	`(NIL) (PUSH)`
`(T&PUSH)`	`(T) (PUSH)`
`(CONST&PUSH n)`	`(CONST n) (PUSH)`
`(LOAD&PUSH n)`	`(LOAD n) (PUSH)`
`(LOADI&PUSH k₁ k₂ n)`	`(LOADI k₁ k₂ n) (PUSH)`
`(LOADC&PUSH n m)`	`(LOADC n m) (PUSH)`
`(LOADV&PUSH k m)`	`(LOADV k m) (PUSH)`
`(POP&STORE n)`	`(POP) (STORE n)`
`(GETVALUE&PUSH n)`	`(GETVALUE n) (PUSH)`
`(JSR&PUSH label)`	`(JSR label) (PUSH)`
`(COPY-CLOSURE&PUSH m n)`	`(COPY-CLOSURE m n) (PUSH)`
`(CALL&PUSH k n)`	`(CALL k n) (PUSH)`
`(CALL1&PUSH n)`	`(CALL1 n) (PUSH)`
`(CALL2&PUSH n)`	`(CALL2 n) (PUSH)`
`(CALLS1&PUSH b)`	`(CALLS1 b) (PUSH)`
`(CALLS2&PUSH b)`	`(CALLS2 b) (PUSH)`
`(CALLSR&PUSH m n)`	`(CALLSR m n) (PUSH)`
`(CALLC&PUSH)`	`(CALLC) (PUSH)`
`(CALLCKEY&PUSH)`	`(CALLCKEY) (PUSH)`
`(FUNCALL&PUSH n)`	`(FUNCALL n) (PUSH)`
`(APPLY&PUSH n)`	`(APPLY n) (PUSH)`
`(CAR&PUSH)`	`(CAR) (PUSH)`
`(CDR&PUSH)`	`(CDR) (PUSH)`
`(CONS&PUSH)`	`(CONS) (PUSH)`
`(LIST&PUSH n)`	`(LIST n) (PUSH)`
`(LIST*&PUSH n)`	`(LIST* n) (PUSH)`
`(NIL&STORE n)`	`(NIL) (STORE n)`
`(T&STORE n)`	`(T) (STORE n)`
`(LOAD&STOREC k n m)`	`(LOAD k) (STOREC n m)`
`(CALLS1&STORE b k)`	`(CALLS1 b) (STORE k)`
`(CALLS2&STORE b k)`	`(CALLS2 b) (STORE k)`
`(CALLSR&STORE m n k)`	`(CALLSR m n) (STORE k)`
`(LOAD&CDR&STORE n)`	`(LOAD n) (CDR) (STORE n)`
`(LOAD&CONS&STORE n)`	`(LOAD n+1) (CONS) (STORE n)`
`(LOAD&INC&STORE n)`	`(LOAD n) (CALL1 #'1+) (STORE n)`
`(LOAD&DEC&STORE n)`	`(LOAD n) (CALL1 #'1-) (STORE n)`
`(LOAD&CAR&STORE m n)`	`(LOAD m) (CAR) (STORE n)`
`(CALL1&JMPIF n label)`	`(CALL1 n) (JMPIF label)`
`(CALL1&JMPIFNOT n label)`	`(CALL1 n) (JMPIFNOT label)`
`(CALL2&JMPIF n label)`	`(CALL2 n) (JMPIF label)`
`(CALL2&JMPIFNOT n label)`	`(CALL2 n) (JMPIFNOT label)`
`(CALLS1&JMPIF b label)`	`(CALLS1 b) (JMPIF label)`
`(CALLS1&JMPIFNOT b label)`	`(CALLS1 b) (JMPIFNOT label)`
`(CALLS2&JMPIF b label)`	`(CALLS2 b) (JMPIF label)`
`(CALLS2&JMPIFNOT b label)`	`(CALLS2 b) (JMPIFNOT label)`
`(CALLSR&JMPIF m n label)`	`(CALLSR m n) (JMPIF label)`
`(CALLSR&JMPIFNOT m n label)`	`(CALLSR m n) (JMPIFNOT label)`
`(LOAD&JMPIF n label)`	`(LOAD n) (JMPIF label)`
`(LOAD&JMPIFNOT n label)`	`(LOAD n) (JMPIFNOT label)`
`(LOAD&CAR&PUSH n)`	`(LOAD n) (CAR) (PUSH)`
`(LOAD&CDR&PUSH n)`	`(LOAD n) (CDR) (PUSH)`
`(LOAD&INC&PUSH n)`	`(LOAD n) (CALL1 #'1+) (PUSH)`
`(LOAD&DEC&PUSH n)`	`(LOAD n) (CALL1 #'1-) (PUSH)`
`(CONST&SYMBOL-FUNCTION n)`	`(CONST n) (SYMBOL-FUNCTION)`
`(CONST&SYMBOL-FUNCTION&PUSH n)`	`(CONST n) (SYMBOL-FUNCTION) (PUSH)`
`(CONST&SYMBOL-FUNCTION&STORE n k)`	`(CONST n) (SYMBOL-FUNCTION) (STORE k)`
`(APPLY&SKIP&RET n k)`	`(APPLY n) (SKIP&RET k)`
`(FUNCALL&SKIP&RETGF n k)`	`(FUNCALL n) (SKIP&RETGF k)`

17. Shortcut instructions

There are special one-byte instructions (without explicit operands) for the following frequent instructions:

mnemonic	operand range
`(LOAD n)`	0 <= `n` < 15
`(LOAD&PUSH n)`	0 <= `n` < 25
`(CONST n)`	0 <= `n` < 21
`(CONST&PUSH n)`	0 <= `n` < 30
`(STORE n)`	0 <= `n` < 8

The CLISP bytecode specification
Bruno Haible <haible@clisp.cons.org>

Last modified: 19 September 1998.