Each import is a fully qualified reference to a closure in another module. The list of imports is provided so that .pz files can then refer to each import by an Import ID. The import section of the .pz file maps these IDs to names for looking up in other module’s symbol tables.

A struct is a record type, and has a lot in common with a C struct. Each struct has a fixed number of fields and each field has a width (as above). Structs allow the bytecode interpreter to make its own data layout decisions. Which it may do differently on different platforms.

Data items come in three types:

Procedures contain executable code. A procedure’s signature is a "stack transformation" it represents the top of stack values before and after a call to this procedure. This is explained above.

Procedures are made up of blocks which are used for control flow. The first block in each procedure is executed when the procedure is called. Within each procedure blocks are numbered sequentially starting at 0. Jump instructions refer to their destination by block ID.

Note that execution can never "fall through" a block, the last instruction in every block must be an unconditional control flow instruction.

Closures can be created by code by bundling a procedure reference with an environment. The environment is a heap allocated struct. See make_closure below.

When calling a closure the environment is placed into the ENV register and the previous one is pushed onto the stack to be restored after the procedure call.

Closures are also created with the closure declaration, the procedure and data ids are specified.

The PZ format also contains options. Only one option of each type is allowed, and the only type (now) is the entrypoint. The entrypoint option specifies the ID of the closure that should be executed to run the module.

Zero extends, sign extends or truncates the value on the top of the stack. By truncate we mean discard the most significant bytes. While most instructions work on a single operand width, these instructions use two operand widths. For example.

Note that it is not necessary (or advised) to use these instructions to convert to and from pointer data, for example to manipulate tagged pointers.

Integer addition, subtraction, multiplication, division and modulus.

Bitwise operations. Note that right shift is unsigned. A signed version will be added later.

Logical negation

Less than and greater than on unsigned and signed data. Note that the result is always fast word width. Likewise conditional instructions always take their argument in the fast word width.

Stack manipulation instructions don’t care about data width, the machine conceptually places all data in the same sized slots.

Drop the top N items from the stack.

Rotate the top N items on the stack. The top N-1 items move to the down, the lowest item becomes the highest. Note that roll 2 is the same as swap.

Push the _N_th item on the stack to the top of the stack. Note that pick 1 is the same as "dup"

Call the given item as follows:

The order of the return address and environment on the stack are not specified, provided that the call instructions and ret instruction agree about the order.

Because the Proc version does not change the ENV register, it is slightly faster. It is only possible for intra-module calls.

There are tailcall versions of each of the above:

These are defined the same as above except they skip step 1.

Pop two values off the return stack, place the return address into the instruction pointer register, and the saved environment in the environment address register.

Jump unconditionally to the indicated block by loading the address of the first instruction of the block into the instruction pointer.

Note that only blocks can be the target of jump instructions, this way all jmp targets are known.

Pop a value of the expression stack, if it is non-zero load the address of the first instruction of the given block into the instruction pointer.

Note that this instruction always consumes the value on the stack.

TODO: indirect jumps or some mechanism for computed gotos.

Form a closure from the given procedure and the structure pointed to by the TOS. Return the new closure on the TOS.

It would be possible to make closures a special type of struct, such as a struct whose first argument is a function pointer. This would use less memory and could be used by further optimisations. However we’ve chosen to get closures working with this more naive method and probably change it later.

Also, closures could be implemented entirely within the compiler. However by making them a PZ machine construct we can take advantage of them for code loading and potentially other things.

TODO: Some loops may be handled differently than using blocks and jumps,

The objects' bitfields can easily be stored together, as mark bits are already stored in a GC. To save further on memory usage objects with particular layouts can be allocated in particular heap regions. These heap regions themselves provide this information. If a heap layout stores object sizes with the object, the bitfields for most object sizes could easily be packed with the object size.

Some of the information required for stack frames is implicit within the instruction stream. Requiring it to be made explicit makes writing pzrun easier, but some of it could be omitted in a later version.

The stack cannot be used to store complex data, neither can it be intermediate in the instruction stream. Complex data (structs and arrays) must be either statically allocated or allocated on the heap. In either case the PZ machine needs to know about the structure or array being used.