Each operation in the binary Fasload language is an eight-bit
(one-byte) opcode. Each has a name beginning with “FOP-”. In
the following descriptions, the name is followed by operand
descriptors. Each descriptor denotes operands that follow the opcode
in the input stream. A quantity in parentheses indicates the number
of bytes of data from the stream making up the operand. Operands
which implicitly come from the stack are noted in the text. The
notation “⇒ stack” means that the result is pushed onto the
stack; “⇒ table” similarly means that the result is added to the
table. A construction like “n(1) value(n)” means that
first a single byte n is read from the input stream, and this
byte specifies how many bytes to read as the operand named value.
All numeric values are unsigned binary integers unless otherwise
specified. Values described as “signed” are in two’s-complement form
unless otherwise specified. When an integer read from the stream
occupies more than one byte, the first byte read is the least
significant byte, and the last byte read is the most significant (and
contains the sign bit as its high-order bit if the entire integer is
signed).
Some of the operations are not necessary, but are rather special cases of or combinations of others. These are included to reduce the size of the file or to speed up important cases. As an example, nearly all strings are less than 256 bytes long, and so a special form of string operation might take a one-byte length rather than a four-byte length. As another example, some implementations may choose to store bits in an array in a left-to-right format within each word, rather than right-to-left. The Fasload file format may support both formats, with one being significantly more efficient than the other for a given implementation. The compiler for any implementation may generate the more efficient form for that implementation, and yet compatibility can be maintained by requiring all implementations to support both formats in Fasload files.
Measurements are to be made to determine which operation codes are worthwhile; little-used operations may be discarded and new ones added. After a point the definition will be “frozen”, meaning that existing operations may not be deleted (though new ones may be added; some operations codes will be reserved for that purpose).
FOP-NOPNo operation. (This is included because it is recognized that some implementations may benefit from alignment of operands to some operations, for example to 32-bit boundaries. This operation can be used to pad the instruction stream to a desired boundary.)
FOP-POP ⇒ tableOne item is popped from the stack and added to the table.
FOP-PUSH index(4) ⇒ stackItem number index of the table is pushed onto the stack. The first element of the table is item number zero.
FOP-BYTE-PUSH index(1) ⇒ stackItem number index of the table is pushed onto the stack. The first element of the table is item number zero.
FOP-EMPTY-LIST ⇒ stackThe empty list (()) is pushed onto the stack.
FOP-TRUTH ⇒ stackThe standard truth value (T) is pushed onto the stack.
FOP-SYMBOL-SAVE n(4) name(n)⇒ stack & table The four-byte operand n specifies the length of the print name of a symbol. The name follows, one character per byte, with the first byte of the print name being the first read. The name is interned in the default package, and the resulting symbol is both pushed onto the stack and added to the table.
FOP-SMALL-SYMBOL-SAVE n(1) name(n) ⇒ stack & tableThe one-byte operand n specifies the length of the print name of a symbol. The name follows, one character per byte, with the first byte of the print name being the first read. The name is interned in the default package, and the resulting symbol is both pushed onto the stack and added to the table.
FOP-SYMBOL-IN-PACKAGE-SAVE index(4)n(4) name(n) ⇒ stack & table The four-byte index specifies a package stored in the table. The four-byte operand n specifies the length of the print name of a symbol. The name follows, one character per byte, with the first byte of the print name being the first read. The name is interned in the specified package, and the resulting symbol is both pushed onto the stack and added to the table.
FOP-SMALL-SYMBOL-IN-PACKAGE-SAVE index(4)n(1) name(n) ⇒ stack & table The four-byte index specifies a package stored in the table. The one-byte operand n specifies the length of the print name of a symbol. The name follows, one character per byte, with the first byte of the print name being the first read. The name is interned in the specified package, and the resulting symbol is both pushed onto the stack and added to the table.
FOP-SYMBOL-IN-BYTE-PACKAGE-SAVE index(1)n(4) name(n) ⇒ stack & table The one-byte index specifies a package stored in the table. The four-byte operand n specifies the length of the print name of a symbol. The name follows, one character per byte, with the first byte of the print name being the first read. The name is interned in the specified package, and the resulting symbol is both pushed onto the stack and added to the table.
FOP-SMALL-SYMBOL-IN-BYTE-PACKAGE-SAVE index(1) n(1) name(n) ⇒ stack & tableThe one-byte index specifies a package stored in the table. The one-byte operand n specifies the length of the print name of a symbol. The name follows, one character per byte, with the first byte of the print name being the first read. The name is interned in the specified package, and the resulting symbol is both pushed onto the stack and added to the table.
FOP-UNINTERNED-SYMBOL-SAVE n(4) name(n) ⇒ stack & tableLike FOP-SYMBOL-SAVE, except that it creates an uninterned symbol.
FOP-UNINTERNED-SMALL-SYMBOL-SAVE n(1) name(n) ⇒ stack & tableLike FOP-SMALL-SYMBOL-SAVE, except that it creates an uninterned symbol.
FOP-PACKAGE ⇒ tableAn item is popped from the stack; it must be a symbol. The package of that name is located and pushed onto the table.
FOP-LIST length(1) ⇒ stackThe unsigned operand length specifies a number of
operands to be popped from the stack. These are made into a list
of that length, and the list is pushed onto the stack.
The first item popped from the stack becomes the last element of
the list, and so on. Hence an iterative loop can start with
the empty list and perform “pop an item and cons it onto the list”
length times.
(Lists of length greater than 255 can be made by using FOP-LIST*
repeatedly.)
FOP-LIST* length(1) ⇒ stackThis is like FOP-LIST except that the constructed list is terminated
not by () (the empty list), but by an item popped from the stack
before any others are. Therefore length+1 items are popped in all.
Hence an iterative loop can start with
a popped item and perform “pop an item and cons it onto the list”
length+1 times.
FOP-LIST-1, FOP-LIST-2, ..., FOP-LIST-8FOP-LIST-k is like FOP-LIST with a byte containing k
following it. These exist purely to reduce the size of Fasload files.
Measurements need to be made to determine the useful values of k.
FOP-LIST*-1, FOP-LIST*-2, ..., FOP-LIST*-8FOP-LIST*-k is like FOP-LIST* with a byte containing k
following it. These exist purely to reduce the size of Fasload files.
Measurements need to be made to determine the useful values of k.
FOP-INTEGER n(4) value(n)⇒ stack A four-byte unsigned operand specifies the number of following bytes. These bytes define the value of a signed integer in two’s-complement form. The first byte of the value is the least significant byte.
FOP-SMALL-INTEGER n(1) value(n)⇒ stack A one-byte unsigned operand specifies the number of following bytes. These bytes define the value of a signed integer in two’s-complement form. The first byte of the value is the least significant byte.
FOP-WORD-INTEGER value(4) ⇒ stackA four-byte signed integer (in the range -2^{31} to 2^{31}-1) follows the operation code. A LISP integer (fixnum or bignum) with that value is constructed and pushed onto the stack.
FOP-BYTE-INTEGER value(1) ⇒ stackA one-byte signed integer (in the range -128 to 127) follows the operation code. A LISP integer (fixnum or bignum) with that value is constructed and pushed onto the stack.
FOP-STRING n(4) name(n)⇒ stack The four-byte operand n specifies the length of a string to construct. The characters of the string follow, one per byte. The constructed string is pushed onto the stack.
FOP-SMALL-STRING n(1) name(n) ⇒ stackThe one-byte operand n specifies the length of a string to construct. The characters of the string follow, one per byte. The constructed string is pushed onto the stack.
FOP-VECTOR n(4) ⇒ stackThe four-byte operand n specifies the length of a vector of LISP objects to construct. The elements of the vector are popped off the stack; the first one popped becomes the last element of the vector. The constructed vector is pushed onto the stack.
FOP-SMALL-VECTOR n(1) ⇒ stackThe one-byte operand n specifies the length of a vector of LISP objects to construct. The elements of the vector are popped off the stack; the first one popped becomes the last element of the vector. The constructed vector is pushed onto the stack.
FOP-UNIFORM-VECTOR n(4) ⇒ stackThe four-byte operand n specifies the length of a vector of LISP objects to construct. A single item is popped from the stack and used to initialize all elements of the vector. The constructed vector is pushed onto the stack.
FOP-SMALL-UNIFORM-VECTOR n(1) ⇒ stackThe one-byte operand n specifies the length of a vector of LISP objects to construct. A single item is popped from the stack and used to initialize all elements of the vector. The constructed vector is pushed onto the stack.
FOP-INT-VECTOR len(4) size(1) data(\left\lceil len*count/8\right\rceil ⇒ stackThe four-byte operand n specifies the length of a vector of unsigned integers to be constructed. Each integer is size bits long, and is packed according to the machine’s native byte ordering. size must be a directly supported i-vector element size. Currently supported values are 1,2,4,8,16 and 32.
FOP-UNIFORM-INT-VECTOR n(4) size(1) value(\lceil size/8\rceil) ⇒ stackThe four-byte operand n specifies the length of a vector of unsigned integers to construct. Each integer is size bits big, and is initialized to the value of the operand value. The constructed vector is pushed onto the stack.
FOP-LAYOUTPops the stack four times to get the name, length, inheritance and depth for a layout object.
FOP-SINGLE-FLOAT data(4)⇒ stack
The data bytes are read as an integer, then turned into an IEEE single
float (as though by make-single-float).
FOP-DOUBLE-FLOAT data(8)⇒ stack
The data bytes are read as an integer, then turned into an IEEE double
float (as though by make-double-float).
FOP-STRUCT n(4) ⇒ stackThe four-byte operand n specifies the length structure to construct. The elements of the vector are popped off the stack; the first one popped becomes the last element of the structure. The constructed vector is pushed onto the stack.
FOP-SMALL-STRUCT n(1) ⇒ stackThe one-byte operand n specifies the length structure to construct. The elements of the vector are popped off the stack; the first one popped becomes the last element of the structure. The constructed vector is pushed onto the stack.
FOP-EVAL ⇒ stackPop an item from the stack and evaluate it (give it to EVAL).
Push the result back onto the stack.
FOP-EVAL-FOR-EFFECTPop an item from the stack and evaluate it (give it to EVAL).
The result is ignored.
FOP-FUNCALL nargs(1) ⇒ stackPop nargs+1 items from the stack and apply the last one popped as a function to all the rest as arguments (the first one popped being the last argument). Push the result back onto the stack.
FOP-FUNCALL-FOR-EFFECT nargs(1)Pop nargs+1 items from the stack and apply the last one popped as a function to all the rest as arguments (the first one popped being the last argument). The result is ignored.
FOP-CODE-FORMAT implementation(1)version(1)
This FOP specifiers the code format for following code objects. The operations
FOP-CODE and its relatives may not occur in a group until after FOP-CODE-FORMAT has appeared; there is no default format. The implementation is an integer indicating the target hardware and environment.
See compiler/generic/vm-macs.lisp for the currently defined
implementations. version for an implementation is increased whenever
there is a change that renders old fasl files unusable.
FOP-CODE nitems(4) size(4)code(size) ⇒ stack
A compiled function is constructed and pushed onto the stack.
This object is in the format specified by the most recent
occurrence of FOP-CODE-FORMAT.
The operand nitems specifies a number of items to pop off
the stack to use in the “boxed storage” section. The operand code
is a string of bytes constituting the compiled executable code.
FOP-SMALL-CODE nitems(1) size(2)code(size) ⇒ stack
A compiled function is constructed and pushed onto the stack.
This object is in the format specified by the most recent
occurrence of FOP-CODE-FORMAT.
The operand nitems specifies a number of items to pop off
the stack to use in the “boxed storage” section. The operand code
is a string of bytes constituting the compiled executable code.
FOP-FDEFINITIONPops the stack to get an fdefinition.
FOP-SANCTIFY-FOR-EXECUTIONA code component is popped from the stack, and the necessary magic is applied to the code so that it can be executed.
FOP-VERIFY-TABLE-SIZE size(4)If the current size of the table is not equal to size, then an inconsistency has been detected. This operation is inserted into a Fasload file purely for error-checking purposes. It is good practice for a compiler to output this at least at the end of every group, if not more often.
FOP-VERIFY-EMPTY-STACKIf the stack is not currently empty, then an inconsistency has been detected. This operation is inserted into a Fasload file purely for error-checking purposes. It is good practice for a compiler to output this at least at the end of every group, if not more often.
FOP-END-GROUPThis is the last operation of a group. If this is not the
last byte of the file, then a new group follows; the next
nine bytes must be “FASL FILE”.
FOP-POP-FOR-EFFECT stack ⇒One item is popped from the stack.
FOP-MISC-TRAP ⇒ stackA trap object is pushed onto the stack.
FOP-DOUBLE-DOUBLE-FLOAT double-double-float(8) ⇒ stackThe next 8 bytes are read, and a double-double-float number is constructed.
FOP-CHARACTER character(3) ⇒ stackThe three bytes are read as an integer then converted to a character. This FOP is currently rather useless, as extended characters are not supported.
FOP-SHORT-CHARACTER character(1)⇒ stack The one byte specifies the code of a Common Lisp character object. A character is constructed and pushed onto the stack.
FOP-RATIO ⇒ stackCreates a ratio from two integers popped from the stack. The denominator is popped first, the numerator second.
FOP-COMPLEX ⇒ stackCreates a complex number from two numbers popped from the stack. The imaginary part is popped first, the real part second.
FOP-COMPLEX-SINGLE-FLOAT real(4) imag(4) ⇒ stackCreates a complex single-float number from the following 8 bytes.
FOP-COMPLEX-DOUBLE-FLOAT real(8) imag(8) ⇒ stackCreates a complex double-float number from the following 16 bytes.
FOP-FSETExcept in the cold loader (Genesis), this is a no-op with two stack arguments. In the initial core this is used to make DEFUN functions defined at cold-load time so that global functions can be called before top-level forms are run (which normally installs definitions.) Genesis pops the top two things off of the stack and effectively does (SETF SYMBOL-FUNCTION).
FOP-LISP-SYMBOL-SAVE n(4) name(n)⇒ stack & table
Like FOP-SYMBOL-SAVE, except that it creates a symbol in the LISP
package.
FOP-LISP-SMALL-SYMBOL-SAVE n(1)name(n) ⇒ stack & table
Like FOP-SMALL-SYMBOL-SAVE, except that it creates a symbol in the LISP
package.
FOP-KEYWORD-SYMBOL-SAVE n(4) name(n)⇒ stack & table
Like FOP-SYMBOL-SAVE, except that it creates a symbol in the
KEYWORD package.
FOP-KEYWORD-SMALL-SYMBOL-SAVE n(1)name(n) ⇒ stack & table
Like FOP-SMALL-SYMBOL-SAVE, except that it creates a symbol in the
KEYWORD package.
FOP-NORMAL-LOADThis FOP is used in conjunction with the cold loader (Genesis) to read top-level package manipulation forms. These forms are to be read as though by the normal loaded, so that they can be evaluated at cold load time, instead of being dumped into the initial core image. A no-op in normal loading.
FOP-MAYBE-COLD-LOADUndoes the effect of FOP-NORMAL-LOAD.
FOP-ARRAY rank(4) ⇒ stackThis operation creates a simple array header (used for simple-arrays with rank /= 1). The data vector is popped off of the stack, and then rank dimensions are popped off of the stack (the highest dimensions is on top.)
FOP-SINGLE-FLOAT-VECTOR length(4) data(n) ⇒ stackCreates a (simple-array single-float (*)) object. The number of single-floats is length.
FOP-DOUBLE-FLOAT-VECTOR length(4) data(n) ⇒ stackCreates a (simple-array double-float (*)) object. The number of double-floats is length.
FOP-COMPLEX-SINGLE-FLOAT-VECTOR length(4) data(n) ⇒ stackCreates a (simple-array (complex single-float) (*)) object. The number of complex single-floats is length.
FOP-COMPLEX-DOUBLE-FLOAT-VECTOR length(4) data(n) ⇒ stackCreates a (simple-array (complex double-float) (*)) object. The number of complex double-floats is length.
FOP-DOUBLE-DOUBLE-FLOAT-VECTOR length(4) data(n) ⇒ stackCreates a (simple-array double-double-float (*)) object. The number of double-double-floats is length.
FOP-COMPLEX-DOUBLE-DOUBLE-FLOAT data(32) ⇒ stackCreates a (complex double-double-float) object from the following 32 bytes of data.
FOP-COMPLEX-DOUBLE-DOUBLE-FLOAT-VECTOR length(4) data(n) ⇒ stackCreates a (simple-arra (complex double-double-float) (*)) object. The number of complex double-double-floats is length.
FOP-ALTER-CODE index(4)This operation modifies the constants part of a code object (necessary for creating certain circular function references.) It pops the new value and code object are off of the stack, storing the new value at the specified index.
FOP-BYTE-ALTER-CODE index(1)Like FOP-ALTER-CODE, but has only a one byte offset.
FOP-FUNCTION-ENTRY index(4) ⇒ stackInitializes a function-entry header inside of a pre-existing code object, and returns the corresponding function descriptor. index is the byte offset inside of the code object where the header should be plunked down. The stack arguments to this operation are the code object, function name, function debug arglist and function type.
FOP-MAKE-BYTE-COMPILED-FUNCTION size(1) ⇒ stackCreate a byte-compiled function. FIXME: describe what’s on the stack.
FOP-ASSEMBLER-CODE length(4) ⇒ stackThis operation creates a code object holding assembly routines. length bytes of code are read and placed in the code object, and the code object descriptor is pushed on the stack. This FOP is only recognized by the cold loader (Genesis.)
FOP-ASSEMBLER-ROUTINE offset(4) ⇒ stackThis operation records an entry point into an assembler code object (for use
with FOP-ASSEMBLER-FIXUP). The routine name (a symbol) is on stack top.
The code object is underneath. The entry point is defined at offset
bytes inside the code area of the code object, and the code object is left on
stack top (allowing multiple uses of this FOP to be chained.) This FOP is only
recognized by the cold loader (Genesis.)
FOP-FOREIGN-FIXUP len(1) name(len) offset(4) ⇒ stackThis operation resolves a reference to a foreign (C) symbol. len bytes are read and interpreted as the symbol name. First the kind and the code-object to patch are popped from the stack. The kind is a target-dependent symbol indicating the instruction format of the patch target (at offset bytes from the start of the code area.) The code object is left on stack top (allowing multiple uses of this FOP to be chained.)
FOP-ASSEMBLER-FIXUP offset(4) ⇒ stackThis operation resolves a reference to an assembler routine. The stack args are (routine-name, kind and code-object). The kind is a target-dependent symbol indicating the instruction format of the patch target (at offset bytes from the start of the code area.) The code object is left on stack top (allowing multiple uses of this FOP to be chained.)
FOP-CODE-OBJECT-FIXUP ⇒ stackFIXME: Describe what this does!
FOP-FOREIGN-DATA-FIXUP ⇒ stackFIXME: Describe what this does!
FOP-LONG-CODE-FORMAT implementation(1) version(4)Like FOP-CODE-FORMAT, except that the version is 32 bits long.
FOP-RPLACA table-idx(4) cdr-offset(4)FOP-RPLACD table-idx(4) cdr-offset(4)These operations destructively modify a list entered in the table.
table-idx is the table entry holding the list, and cdr-offset designates
the cons in the list to modify (like the argument to nthcdr.) The new
value is popped off of the stack, and stored in the car or cdr,
respectively.
FOP-SVSET table-idx(4) vector-idx(4)Destructively modifies a simple-vector entered in the table. Pops the
new value off of the stack, and stores it in the vector-idx element of
the contents of the table entry table-idx.
FOP-NTHCDR cdr-offset(4) ⇒ stackDoes nthcdr on the top-of stack, leaving the result there.
FOP-STRUCTSET table-idx(4) vector-idx(4)Like FOP-SVSET, except it alters structure slots.
FOP-END-HEADERIndicates the end of a group header, as described above.