6.2.1 Explicit stack access

This feature is not needed and not supported in the 0.6.2 version of vmgen that is documented here (and that is invoked by default).

Not all stack effects can be specified using the stack effect specifications above. For VM instructions that have other stack effects, you can specify them explicitly by accessing the stack pointer in the C code; however, you have to notify Vmgen of such explicit stack accesses, otherwise Vmgens optimizations could conflict with your explicit stack accesses.

You notify Vmgen by putting ... with the appropriate stack prefix into the stack comment. Then the VM instruction will first take the other stack items specified in the stack effect into C variables, then make sure that all other stack items for that stack are in memory, and that the stack pointer for the stack points to the top-of-stack (by default, unless you change the stack access transformation: see Stack growth direction).

The general rule is: If you mention a stack pointer in the C code of a VM instruction, you should put a ... for that stack in the stack effect.

Consider this example:

return ( #iadjust S:... target afp i1 -- i2 )
SET_IP(target);
sp = (Cell *)(((char *)sp)+iadjust);
fp = afp;
i2=i1;

First the variables target afp i1 are popped off the stack, then the stack pointer sp is set correctly for the new stack depth, then the C code changes the stack depth and does other things, and finally i2 is pushed on the stack with the new depth.

The position of the ... within the stack effect does not matter. You can use several ...s, for different stacks, and also several for the same stack (that has no additional effect). If you use ... without a stack prefix, this specifies all the stacks except the instruction stream.

You cannot use ... for the instruction stream, but that is not necessary: At the start of the C code, IP points to the start of the next VM instruction (i.e., right beyond the end of the current VM instruction), and you can change the instruction pointer with SET_IP (see VM engine).