Node:Simple instructions, Next:Superinstructions, Previous:Input File Grammar, Up:Input File Format
We will use the following simple VM instruction description as example:
sub ( i1 i2 -- i ) i = i1-i2;
The first line specifies the name of the VM instruction (sub) and
its stack effect (i1 i2 -- i). The rest of the description is
just plain C code.
The stack effect specifies that sub pulls two integers from the
data stack and puts them in the C variables i1 and i2
(with the rightmost item (i2) taken from the top of stack;
intuition: if you push i1, then i2 on the stack, the
resulting stack picture is i1 i2) and later pushes one integer
(i) on the data stack (the rightmost item is on the top
afterwards).
How do we know the type and stack of the stack items? Vmgen uses
prefixes, similar to Fortran; in contrast to Fortran, you have to
define the prefix first:
\E s" Cell" single data-stack type-prefix i
This defines the prefix i to refer to the type Cell
(defined as long in mini.h) and, by default, to the
data-stack. It also specifies that this type takes one stack
item (single). The type prefix is part of the variable name.
Before we can use data-stack in this way, we have to define it:
\E stack data-stack sp Cell
This line defines the stack data-stack, which uses the stack
pointer sp, and each item has the basic type Cell; other
types have to fit into one or two Cells (depending on whether the
type is single or double wide), and are cast from and to
Cells on accessing the data-stack with type cast macros
(see VM engine). By default, stacks grow towards lower addresses in
Vmgen-erated interpreters (see Stack growth direction).
We can override the default stack of a stack item by using a stack
prefix. E.g., consider the following instruction:
lit ( #i -- i )
The VM instruction lit takes the item i from the
instruction stream (indicated by the prefix #), and pushes it on
the (default) data stack. The stack prefix is not part of the variable
name. Stack prefixes are defined like this:
\E inst-stream stack-prefix #
This definition defines that the stack prefix # specifies the
"stack" inst-stream. Since the instruction stream behaves a
little differently than an ordinary stack, it is predefined, and you do
not need to define it.
The instruction stream contains instructions and their immediate
arguments, so specifying that an argument comes from the instruction
stream indicates an immediate argument. Of course, instruction stream
arguments can only appear to the left of -- in the stack effect.
If there are multiple instruction stream arguments, the leftmost is the
first one (just as the intuition suggests).