Glulx

A 32-Bit Virtual Machine for IF

VM specification version 3.1.2

Andrew Plotkin <[email protected]>

Copyright 1999-2010 by Andrew Plotkin. This specification is licensed under
a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported
License: <http://creativecommons.org/licenses/by-nc-sa/3.0>

The virtual machine *described* by this document is an idea, not an
expression of an idea, and is therefore not copyrightable. Anyone is free
to write programs that run on the Glulx VM or make use of it, including
compilers, interpreters, debuggers, and so on.

This document and further Glulx information can be found
at:<http://eblong.com/zarf/glulx/>

0        Introduction
0.1      Why Bother?
0.2      Glulx and Other IF Systems
0.3      Credits
1        The Machine
1.1      Input and Output
1.2      The Memory Map
1.3      The Stack
1.3.1    The Call Frame
1.3.2    Call Stubs
1.3.3    Calling and Returning
1.3.4    Calling and Returning Within Strings
1.3.5    Calling and Returning During Output Filtering
1.4      The Header
1.5      Instruction Format
1.6      Typable Objects
1.6.1    Strings
1.6.1.1  Unencoded strings
1.6.1.2  Unencoded Unicode strings
1.6.1.3  Compressed strings
1.6.1.4  The String-Decoding Table
1.6.2    Functions
1.6.3    Other Glulx Objects
1.6.4    User-Defined Objects
1.7      Floating-Point Numbers
1.8      The Save-Game Format
1.8.1    Contents of Dynamic Memory
1.8.2    Contents of the Stack
1.8.3    Memory Allocation Heap
1.8.4    Associated Story File
1.8.5    State Not Saved
2        Dictionary of Opcodes
2.1      Integer Math
2.2      Branches
2.3      Moving Data
2.4      Array Data
2.5      The Stack
2.6      Functions
2.7      Continuations
2.8      Memory Map
2.9      Memory Allocation Heap
2.10     Game State
2.11     Output
2.12     Floating-Point Math
2.13     Floating-Point Comparisons
2.14     Random Number Generator
2.15     Block Copy and Clear
2.16     Searching
2.17     Accelerated Functions
2.18     Miscellaneous
2.19     Assembly Language


0: Introduction

Glulx is a simple solution to a fairly trivial problem. We want a virtual
machine which the Inform compiler can compile to, without the increasingly
annoying restrictions of the Z-machine.

Glulx does this, without much fuss. All arithmetic is 32-bit (although
there are opcodes to handle 8-bit and 16-bit memory access.) Input and
output are handled through the Glk API (which chops out half the Z-machine
opcodes, and most of the complexity of a Z-code interpreter.) Some care has
been taken to make the bytecode small, but simplicity and elbow room are
considered more important -- bytecode is not a majority of the bulk in
current Inform games.

0.1: Why Bother?

We're buried in IF VMs already, not to mention general VMs like Java, not
to mention other interpreters or bytecode systems like Perl.  Do we need
another one?

Well, maybe not, but Glulx is simple enough that it was easier to design
and implement it than to use something else. Really.

The Inform compiler already does most of the work of translating a
high-level language to bytecode. It has long since outgrown many of the
IF-specific features of the Z-machine (such as the object structure.) So it
makes sense to remove those features, leaving a generic VM. Furthermore,
there are enough other constraints (Inform's assumption of a flat memory
model, the desire to have a lightweight VM suitable for PDAs) that no
existing system is really ideal. So it seems worthwhile to design a new one.

Indeed, most of the effort that has gone into this system has been
modifying Inform. Glulx itself is nearly an afterthought.

0.2: Glulx and Other IF Systems

Glulx grew out of the desire to extend Inform. However, it may well be
suitable as a VM for other IF systems.

Or maybe not. Since Glulx *is* so lightweight, a compiler has to be fairly
complex to compile to it. Many IF systems take the approach of a simple
compiler, and a complex, high-level, IF-specific interpreter. Glulx is not
suitable for this.

However, if a system wants to use a simple runtime format with 32-bit data,
Glulx may be a good choice.

Note that this is entirely separate from question of the I/O layer. Glulx
uses the Glk I/O API, for the sake of simplicity and portability. Any IF
system can do the same. One can use Glk I/O without using the Glulx
game-file format.

On the obverse, one could also extend the Glulx VM to use a different I/O
system instead of Glk. One such extension is FyreVM, a commercial IF system
developed by Textfyre. FyreVM is described at
<http://textfyre.com/fyrevm/>.

Other extension projects, not yet solidified, are being developed by Dannii
Willis. See <http://curiousdannii.github.com/if/>.

This specification does not cover FyreVM and the other projects, except to
note opcodes, gestalt selectors, and iosys values that are specific to them.

0.3: Credits

Graham Nelson gets pretty much all of it. Without Inform, there would be no
reason for any of this. The entirety of Glulx is fallout from my attempt to
deconstruct Inform and rebuild its code generator in my own image, with
Graham's support.

1: The Machine

The Glulx machine consists of main memory, the stack, and a few registers
(the program counter, the stack pointer, and the call-frame pointer.)

Main memory is a simple array of bytes, numbered from zero up. When
accessing multibyte values, the most significant byte is stored first
(big-endian). Multibyte values are not necessarily aligned in memory.

The stack is an array of values. It is not a part of main memory; the terp
maintains it separately. The format of the stack is technically up to the
implementation. However, the needs of the machine (especially the game-save
format) leave about one good option. (See section 1.8, "The Save-Game
Format".) One important point: the stack can be kept in either byte
ordering. The program should make no assumptions about endianness on the
stack. (In fact, programs should never need to care.) Values on the stack
always have their natural alignment (16-bit values at even addresses,
32-bit values at multiples of four).

The stack consists of a set of call frames, one for each function in the
current chain. When a function is called, a new stack frame is pushed,
containing the function's local variables. The function can then push or
pull 32-bit values on top of that, to store intermediate computations.

All values are treated as unsigned integers, unless otherwise noted. Signed
integers are handled with the usual two's-complement notation. Arithmetic
overflows and underflows are truncated, also as usual.

1.1: Input and Output

No input/output facilities are built into the Glulx machine itself.
Instead, the machine has one or more opcodes which dispatch calls to an I/O
library.

At the moment, that means Glk. All Glulx interpreters support the Glk I/O
facility (via the glk opcode), and no other I/O facilities exist. However,
other I/O libraries may be adapted to Glk in the future. For best behavior,
a program should test for the presence of an I/O facility before using it,
using the IOSystem gestalt selector (see section 2.18, "Miscellaneous").

One I/O system is set as current at any given time. This does not mean that
the others are unavailable. (If the interpreter supports Glk, for example,
the glk opcode will always function.) However, the basic Glulx output
opcodes -- streamchar, streamnum, and streamstr -- always print using the
current I/O system.

Every Glulx interpreter supports at least one normal I/O facility (such as
Glk), and also two special facilities.

The "null" I/O system does nothing. If this is selected, all Glulx output
is simply discarded. [[Silly, perhaps, but I like simple base cases.]] When
the Glulx machine starts up, the null system is the current system. You
must select a different one before using the streamchar, streamnum, or
streamstr opcodes.

The "filter" I/O system allows the Glulx program itself to handle output.
The program specifies a function when selecting this I/O system. That
function is then called for every single character of output that the
machine generates (via streamchar, streamnum, or streamstr). The function
can output its character directly via the glk opcode (or one of the other
output opcodes).

[[This may all seem rather baroque, but in practice most authors can ignore
it. Most programs will want to test for the Glk facility, set it to be the
current output system immediately, and then leave the I/O system alone for
the rest of the game. All output will then automatically be handled through
Glk.]]

1.2: The Memory Map

Memory is divided into several segments. The sizes of the segments are
determined by constant values in the game-file header.


     Segment    Address (hex)

   +---------+  00000000
   | Header  |
   | - - - - |  00000024
   |         |
   |   ROM   |
   |         |
   +---------+  RAMSTART
   |         |
   |   RAM   |
   |         |
   | - - - - |  EXTSTART
   |         |
   |         |
   +---------+  ENDMEM


As you might expect, the section marked ROM never changes during execution;
it is illegal to write there. Executable code and constant data are usually
(but not necessarily) kept in ROM. Note that unlike the Z-machine, the
Glulx machine's ROM comes before RAM; the 36-byte header is part of ROM.

The boundary marked EXTSTART is a trivial gimmick for making game-files
smaller. A Glulx game-file only stores the data from 0 to EXTSTART. When
the terp loads it in, it allocates memory up to ENDMEM; everything above
EXTSTART is initialized to zeroes. Once execution starts, there is no
difference between the memory above and below EXTSTART.

For the convenience of paging interpreters, the three boundaries RAMSTART,
EXTSTART, and ENDMEM must be aligned on 256-byte boundaries.

Any of the segments of memory can be zero-length, except that ROM must be
at least 256 bytes long (so that the header fits in it).

1.3: The Stack

The stack pointer starts at zero, and the stack grows upward. The maximum
size of the stack is determined by a constant value in the game-file
header. For convenience, this must be a multiple of 256.

The stack pointer counts in bytes. If you push a 32-bit value on the stack,
the pointer increases by four.

1.3.1: The Call Frame

A call frame looks like this:


   +------------+  FramePtr
   | Frame Len  |    (4 bytes)
   | Locals Pos |    (4 bytes)
   |            |
   | Format of  |    (2*n bytes)
   |     Locals |
   |            |
   | Padding    |    (0 or 2 bytes)
   +------------+  FramePtr+LocalsPos
   | Locals     |    (1, 2, or 4 bytes each)
   |            |
   | Padding    |    (0 to 3 bytes)
   +------------+  FramePtr+FrameLen
   | Values     |    (4 bytes each)
   |      ....  |
   +------------+  StackPtr


When a function begins executing, the last segment is empty (StackPtr
equals FramePtr+FrameLen.) Computation can push and pull 32-bit values on
the stack. It is illegal to pop back beyond the original FramePtr+FrameLen
boundary.

The "locals" are a list of values which the function uses as local
variables. These also include function arguments. (The first N locals can
be used as the arguments to an N-argument function.) Locals can be 8, 16,
or 32-bit values. They are not necessarily contiguous; padding is inserted
wherever necessary to bring a value to its natural alignment (16-bit values
at even addresses, 32-bit values at multiples of four).

The "format of locals" is a series of bytes, describing the arrangement of
the "locals" section of the frame (from LocalsPos up to FrameLen). This
information is copied directly from the header of the function being
called. (See section 1.6.2, "Functions".)

Each field in this section is two bytes:

   * LocalType: 1, 2, or 4, indicating a set of locals which are that many
bytes each.
   * LocalCount: 1 to 255, indicating how many locals of LocalType to
declare.

The section is terminated by a pair of zero bytes. Another pair of zeroes
is added if necessary to reach a four-byte boundary.

(Example: if a function has three 8-bit locals followed by six 16-bit
locals, the format segment would contain eight bytes: (1, 3, 2, 6, 0, 0, 0,
0). The locals segment would then be 16 bytes long, with a padding byte
after the third local.)

The "format of locals" information is needed by the terp in two places:
when calling a function (to write in function arguments), and when saving
the game (to fix byte-ordering of the locals.) The formatting is *not*
enforced by the terp while a function is executing. The program is not
prevented from accessing locations whose size and position don't match the
formatting, or locations that overlap, or even locations in the padding
between locals. However, if a program does this, the results are undefined,
because the byte-ordering of locals is up to the terp. The save-game
algorithm will fail, if nothing else.

[[In fact, the call frame may not exist as a byte sequence during function
execution. The terp is free to maintain a more structured form, as long as
it generates valid save-game files, and correctly handles accesses to valid
(according to the format) locals.]]

[[NOTE: 8-bit and 16-bit locals have never been in common use, and this
spec has not been unambiguous in describing their handling. (By which I
mean, what I implemented in the reference interpreter didn't match the
spec.) Therefore, 8-bit and 16-bit locals are deprecated. Use of the copyb
and copys opcodes with a local-variable operand is also deprecated.]]

1.3.2: Call Stubs

Several different Glulx operations require the ability to jump back to a
previously-saved execution state. (For example: function call/return,
game-state save/restore, and exception catch/throw.)

For simplicity, all these operations store the execution state the same way
-- as a "call stub" on the stack. This is a block of four 32-bit values. It
encodes the PC and FramePtr, and also a location to store a single 32-bit
value at jump-back time. (For example, the function return value, or the
game-restore success flag.)

The values are pushed on the stack in the following order (FramePtr pushed
last):


   +-----------+
   | DestType  |  (4 bytes)
   | DestAddr  |  (4 bytes)
   | PC        |  (4 bytes)
   | FramePtr  |  (4 bytes)
   +-----------+


FramePtr is the current value of FramePtr -- the stack position of the call
frame of the function during which the call stub was generated.

PC is the current value of the program counter. This is the address of the
instruction *after* the one which caused the call stub to be generated.
(For example, for a function call, the call stub contains the address of
the first instruction to execute after the function returns.)

DestType and DestAddr describe a location in which to store a result. This
will occur after the operation is completed (function returned, game
restored, etc). It happens after the PC and FramePtr are reloaded from the
call stub, and the call stub is removed from the stack.

DestType is one of the following values:

   * 0: Do not store. The result value is discarded. DestAddr should be
zero.
   * 1: Store in main memory. The result value is stored in the
main-memory address given by DestAddr.
   * 2: Store in local variable. The result value is stored in the call
frame at position ((FramePtr+LocalsPos) + DestAddr). See section 1.5,
"Instruction Format".
   * 3: Push on stack. The result value is pushed on the stack. DestAddr
should be zero.

The string-decoding mechanism complicates matters a little, since it is
possible for a function to be called from inside a string, instead of
another function. (See section 1.3.4, "Calling and Returning Within
Strings".) The following DestType values allow this:

   * 10: Resume printing a compressed (E1) string. The PC value contains
the address of the byte (within the string) to continue printing in. The
DestAddr value contains the bit number (0 to 7) within that byte.
   * 11: Resume executing function code after a string completes. The PC
value contains the program counter as usual, but the FramePtr field is
ignored, since the string is printed in the same call frame as the function
that executed it. DestAddr should be zero.
   * 12: Resume printing a signed decimal integer. The PC value contains
the integer itself. The DestAddr value contains the position of the digit
to print next. (0 indicates the first digit, or the minus sign for negative
integers; and so on.)
   * 13: Resume printing a C-style (E0) string. The PC value contains the
address of the character to print next. The DestAddr value should be zero.
   * 14: Resume printing a Unicode (E2) string. The PC value contains the
address of the (four-byte) character to print next. The DestAddr value
should be zero.

1.3.3: Calling and Returning

When a function is called, the terp pushes a four-value call stub. (This
includes the return-value destination, the PC, and the FramePtr; see
section 1.3.2, "Call Stubs".) The terp then sets the FramePtr to the
StackPtr, and builds a new call frame. (See section 1.3.1, "The Call
Frame".) The PC moves to the first instruction of the function, and
execution continues.

Function arguments can be stored in the locals of the new call frame, or
pushed on the stack above the new call frame. This is determined by the
type of the function; see section 1.6.2, "Functions".

When a function returns, the process is reversed. First StackPtr is set
back to FramePtr, throwing away the current call frame (and any pushed
values). The FramePtr and PC are popped off the stack, and then the
return-value destination. The function's return value is stored where the
destination says it should be. Then execution continues at the restored PC.

(But note that a function can also return to a suspended string, as well as
a suspended caller function. See section 1.3.4, "Calling and Returning
Within Strings" and section 1.3.5, "Calling and Returning During Output
Filtering".)

1.3.4: Calling and Returning Within Strings

Glulx uses a Huffman string-compression scheme. This allows bit sequences
in strings to decode to large strings, or even function invocations which
generate output. This means the streamstr opcode can invoke function calls,
and we must therefore be able to represent this situation on the stack.

When the terp begins printing a string, it pushes a type-11 call stub.
(This includes only the current PC. The FramePtr is included, for
consistency's sake, but it will be ignored when the call stub is read back
off.) The terp then starts decoding the string data. The PC now indicates
the position within the string data.

If, during string decoding, the terp encounters an indirect reference to a
string or function, it pushes a type-10 call stub. This includes the
string-decoding PC, and the bit number within that address. It also
includes the current FramePtr, which has not changed since string-printing
began.

If the indirect reference is to another string, the decoding continues at
the new location after the type-10 stub is pushed. However, if the
reference is to a function, the usual call frame is pushed on top of the
type-10 stub, and the terp returns to normal function execution.

When a string completes printing, the terp pops a call stub. This will
necessarily be either a type-10 or type-11. If the former, the terp resumes
string decoding at the PC address/bit number in the stub. If the latter,
the topmost string is finished, and the terp resumes function execution at
the stub's PC.

When a function returns, it must check to see if it was called from within
a string, instead of from another function. This is the case if the call
stub it pops is type-10. (The call stub cannot be type-11.) If so, the
FramePtr is taken from the stub as usual; but the stub's PC is taken to
refer to a string data address, with the DestAddr value being the bit
number within that address. (The function's return value is discarded.)
String decoding resumes from there.

[[It may seem wasteful for the terp to push and pop a call stub every time
a string is printed. Fortunately, in the most common case -- printing a
string with no indirect references at all -- this can easily be optimized
out. (No VM code is executed between the push and pop, so it is safe to
skip them.) Similarly, when printing an unencoded (E0) string, there can be
no indirect references, so it is safe to optimize away the call stub
push/pop.]]

1.3.5: Calling and Returning During Output Filtering

The "filter" I/O system allows the terp to call a Glulx function for each
character that is printed via streamchar, streamnum, or streamstr. We must
be able to represent this situation on the call stack as well.

If filtering is the current I/O system, then when the terp executes
streamchar, it pushes a normal function call stub and begins executing the
output function. Nothing else is required; when the function returns,
execution will resume after the streamchar opcode. (A type-0 call stub is
used, so the function's return value is discarded.)

The other output opcodes are more complex. When the terp executes
streamnum, it pushes a type-11 call stub. As before, this records the
current PC. The terp then pushes a type-12 call stub, which contains the
integer being printed and the position of the next character to be printed
(namely 1). It then executes the output function.

When the output function returns, the terp pops the type-12 stub and
realizes that it should continue printing the integer contained therein. It
pushes another type-12 stub back on the stack, indicating that the next
position to print is 2, and calls the output function again.

This process continues until there are no more characters in the decimal
representation of the integer. The terp then pops the type-11 stub,
restores the PC, and resumes execution after the streamnum opcode.

The streamstr opcode works on the same principle, except that instead of
type-12 stubs, the terp uses type-10 stubs (when interrupting an encoded
string) and type-13/14 stubs (when interruping a C-style, null-terminated
string of bytes/Unicode chars). Type-13 and type-14 stubs look like the
others, except that they contain only the address of the next character to
print; no other position or bit number is necessary.

The interaction between the filter I/O system and indirect string/function
calls within encoded strings is left to the reader's imagination. [[Because
I couldn't explain it if I tried. Follow the rules; they work.]]

1.4: The Header

The header is the first 36 bytes of memory. It is always in ROM, so its
contents cannot change during execution. The header is organized as nine
32-bit values. (Recall that values in memory are always big-endian.)


   +---------------+  address 0
   | Magic Number  |  (4 bytes)
   | Glulx Version |  (4 bytes)
   | RAMSTART      |  (4 bytes)
   | EXTSTART      |  (4 bytes)
   | ENDMEM        |  (4 bytes)
   | Stack Size    |  (4 bytes)
   | Start Func    |  (4 bytes)
   | Decoding Tbl  |  (4 bytes)
   | Checksum      |  (4 bytes)
   +---------------+


   * Magic number: 47 6C 75 6C, which is to say ASCII 'Glul'.
   * Glulx version number: The upper 16 bits stores the major version
number; the next 8 bits stores the minor version number; the low 8 bits
stores an even more minor version number, if any. This specification is
version 3.1.2, so a game file generated to this spec would contain 00030102.
   * RAMSTART: The first address which the program can write to.
   * EXTSTART: The end of the game-file's stored initial memory (and
therefore the length of the game file.)
   * ENDMEM: The end of the program's memory map.
   * Stack size: The size of the stack needed by the program.
   * Address of function to execute: Execution commences by calling this
function.
   * Address of string-decoding table: This table is used to decode
compressed strings. See section 1.6.1.3, "Compressed strings". This may be
zero, indicating that no compressed strings are to be decoded. [[Note that
the game can change which table the terp is using, with the setstringtbl
opcode. See section 2.11, "Output".]]
   * Checksum: A simple sum of the entire initial contents of memory,
considered as an array of big-endian 32-bit integers. The checksum should
be computed with this field set to zero.

The interpreter should validate the magic number and the Glulx version
number. An interpreter which is written to version X.Y.Z of this
specification should accept game files whose Glulx version between X.0.0
and X.Y.*. (That is, the major version number should match; the minor
version number should be less than or equal to Y; the subminor version
number does not matter.)

EXCEPTION: A version 3.* interpreter should accept version 2.0 game files.
The only difference between spec 2.0 and spec 3.0 is that 2.0 lacks Unicode
functionality. Therefore, an interpreter written to this version of the
spec (3.1.2) should accept game files whose version is between 2.0.0 and
3.1.* (0x00020000 and 0x000301FF inclusive).

[[These rules mean, in the vernacular, that minor version changes are
backwards compatible, and subminor version changes are backwards and
forwards compatible. If I add a feature which I expect every terp to
implement (e.g. mzero and mcopy), then I bump the minor version number, and
your game can use that feature without worrying about availability. If I
add a feature which not all terps will implement (e.g. floating point),
then I bump the subminor version number, and your game should only use the
feature after doing a gestalt test for availability.]]

[[The header is conventionally followed by a 32-bit word which describes
the layout of data in the rest of the file. This value is *not* a part of
the Glulx specification; it is the first ROM word after the header, not a
part of the header. It is an option that compilers can insert, when
generating Glulx files, to aid debuggers and decompilers.

For Inform-generated Glulx files, this descriptive value is 49 6E 66 6F,
which is to say ASCII 'Info'. There then follow several more bytes of data
relevant to the Inform compiler. See the Glulx chapter of the Inform
Technical Manual.]]

1.5: Instruction Format

There are 2^28 Glulx opcodes, numbered from 0 to 0FFFFFFF. If this proves
insufficient, more may be added in the future.

An instruction is encoded as follows:


   +--------------+
   | Opcode Num   |  (1 to 4 bytes)
   |              |
   | Operand      |  (two per byte)
   |   Addr Modes |
   |              |
   | Operand Data |  (as defined by
   |        ....  |      addr modes)
   +--------------+


The opcode number OP, which can be anything up to 0FFFFFFF, may be packed
into fewer than four bytes:

   * 00..7F: One byte, OP
   * 0000..3FFF: Two bytes, OP+8000
   * 00000000..0FFFFFFF: Four bytes, OP+C0000000

Note that the length of this field can be decoded by looking at the top two
bits of the first byte. Also note that, for example, 01 and 8001 and
C0000001 all represent the same opcode.

The operand addressing modes are a list of fields which tell where opcode
arguments are read from or written to. Each is four bits long, and they are
packed two to a byte. (They occur in the same order as the arguments, low
bits first. If there are an odd number, the high bits of the last byte are
left zero.)

Since each addressing mode is a four-bit number, there are sixteen
addressing modes. Each is associated with a fixed number of bytes in the
"operand data" segment of the instruction. These bytes appear after the
addressing modes, in the same order. (There is no alignment padding.)

   * 0: Constant zero. (Zero bytes)
   * 1: Constant, -80 to 7F. (One byte)
   * 2: Constant, -8000 to 7FFF. (Two bytes)
   * 3: Constant, any value. (Four bytes)
   * 4: (Unused)
   * 5: Contents of address 00 to FF. (One byte)
   * 6: Contents of address 0000 to FFFF. (Two bytes)
   * 7: Contents of any address. (Four bytes)
   * 8: Value popped off stack. (Zero bytes)
   * 9: Call frame local at address 00 to FF. (One byte)
   * A: Call frame local at address 0000 to FFFF. (Two bytes)
   * B: Call frame local at any address. (Four bytes)
   * C: (Unused)
   * D: Contents of RAM address 00 to FF. (One byte)
   * E: Contents of RAM address 0000 to FFFF. (Two bytes)
   * F: Contents of RAM, any address. (Four bytes)

Things to note:

The "constant" modes sign-extend their data into a 32-bit value; the other
modes do not. This is just because negative constants occur more frequently
than negative addresses.

The indirect modes (all except "constant") access 32-bit fields, either in
the stack or in memory. This means four bytes starting at the given
address. A few opcodes are exceptions: copyb and copys (copy byte and copy
short) access 8-bit and 16-bit fields (one or two bytes starting at the
given address.)

The "call frame local" modes access a field on the stack, starting at byte
((FramePtr+LocalsPos) + address). As described in section 1.3.1, "The Call
Frame", this must be aligned with (and the same size as) one of the fields
described in the function's locals format. It must not point outside the
range of the current function's locals segment.

The "contents of address" modes access a field in main memory, starting at
byte (addr). The "contents of RAM" modes access a field in main memory,
starting at byte (RAMSTART + addr). Since the byte-ordering of main memory
is well-defined, these need not have any particular alignment or position.

All address addition is truncated to 32 bits, and addresses are unsigned.
So, for example, "contents of RAM" address FFFFFFFC (RAMSTART + FFFFFFFC)
accesses the last 32-bit value in ROM, since it effectively subtracts 4
from RAMSTART. "Contents of address" FFFFFFFC would access the very last
32-bit value in main memory, assuming you can find a terp which handles
four-gigabyte games. "Call frame local" FFFFFFFC is illegal; whether you
interpret it as a negative number or a large positive number, it's outside
the current call frame's locals segment.

Some opcodes store values as well as reading them in. Store operands use
the same addressing modes, with a few exceptions:

   * 8: The value is pushed into the stack, instead of being popped off.
   * 3, 2, 1: These modes cannot be used, since it makes no sense to store
to a constant. [[We delicately elide the subject of Fortran. And rule-based
property algebras.]]
   * 0: This mode means "throw the value away"; it is not stored at all.

Operands are evaluated from left to right. (This is important if there are
several push/pop operands.)

1.6: Typable Objects

It is convenient for a program to store object references as 32-bit
pointers, and still determine the type of a reference at run-time.

To facilitate this, structured objects in Glulx main memory follow a simple
convention: the first byte indicates the type of the object.

At the moment, there are only two kinds of Glulx objects: functions and
strings. A program (or compiler, or library) may declare more, but the
Glulx VM does not have to know about them.

Of course, not every byte in memory is the start of the legitimate object.
It is the program's responsibility to keep track of which values validly
refer to typable objects.

1.6.1: Strings

Strings have a type byte of E0 (for unencoded, C-style strings), E2 (for
unencoded strings of Unicode values), or E1 (for compressed strings.) Types
E3 to FF are reserved for future expansion of string types.

1.6.1.1: Unencoded strings

An unencoded string consists of an E0 byte, followed by all the bytes of
the string, followed by a zero byte.

1.6.1.2: Unencoded Unicode strings

An unencoded Unicode string consists of an E2 byte, followed by three
padding 0 bytes, followed by the Unicode character values (each one being a
four-byte integer). Finally, there is a terminating value (four 0 bytes).


   Unencoded Unicode string
   +----------------+
   | Type: E2       |  (1 byte)
   | Padding: 00    |  (3 bytes)
   | Characters.... |  (any length, multiple of 4)
   | NUL: 00000000  |  (4 bytes)
   +----------------+


Note that the character data is not encoded in UTF-8, UTF-16, or any other
peculiar encoding. It is treated as an array of 32-bit integers (which are,
as always in Glulx, stored big-endian). Each integer is a Unicode code
point.

1.6.1.3: Compressed strings

A compressed string consists of an E1 byte, followed by a block of
Huffman-encoded data. This should be read as a stream of bits, starting
with the low bit (the 1 bit) of the first byte after the E1, proceeding
through the high bit (the 128 bit), and so on with succeeding bytes.

Decoding compressed strings requires looking up data in a Huffman table.
The address of this table is normally found in the header. However, the
program can select a different decompression table at run-time; see section
2.11, "Output".

The Huffman table is logically a binary tree. Internal nodes are branch
points; leaf nodes represent printable entities. To decode a string, begin
at the root node. Read one bit from the bit stream, and go to the left or
right child depending on its value. Continue reading bits and branching
left or right, until you reach a leaf node. Print that entity. Then jump
back to the root, and repeat the process. One particular leaf node
indicates the end of the string (rather than any printable entity), and
when the bit stream leads you to that node, you stop.

[[This is a fairly slow process, with VM memory reads and a conditional
test for every *bit* of the string. A terp can speed it up considerably by
reading the Huffman table all at once, and caching it as native data
structures. A binary tree is the obvious choice, but one can do even better
(at the cost of some space) by looking up four-bit chunks at a time in a
16-branching tree.]]

[[Note that decompression tables are not necessarily in ROM. This is
particularly important for tables that are generated and selected at
run-time. Furthermore, it is technically legal for a table in RAM to be
altered at runtime -- possibly even when it is the currently-selected
table. Therefore, an interpreter that caches or preloads this decompression
data must be careful. If it caches data from RAM, it must watch for writes
to that RAM space, and invalidate its cache upon seeing such a write.]]

1.6.1.4: The String-Decoding Table

The decoding table has the following format:


   +-----------------+
   | Table Length    |  (4 bytes)
   | Number of Nodes |  (4 bytes)
   | Root Node Addr  |  (4 bytes)
   | Node Data ....  |  (table length - 12 bytes)
   +-----------------+


The table length is measured in bytes, from the beginning of the table to
the end of the last node. The node count includes both branch and leaf
nodes. [[There will, of course, be an odd number of nodes, and (N+1)/2 of
them will be leaves.]] The root address indicates which node is the root of
the tree; it is not necessarily the first node. This is an absolute
address, not an offset from the beginning of the table.

There then follow all the nodes, with no extra data before, between, or
after them. They need not be in any particular order. There are several
possible types of nodes, distinguished by their first byte.


   Branch (non-leaf node)
   +----------------+
   | Type: 00       |  (1 byte)
   | Left  (0) Node |  (4 bytes)
   | Right (1) Node |  (4 bytes)
   +----------------+


The left and right node fields are addresses (again, absolute addresses) of
the nodes to go to given a 0 or 1 bit from the bit stream.


   String terminator
   +----------------+
   | Type: 01       |  (1 byte)
   +----------------+


This ends the string-decoding process.


   Single character
   +----------------+
   | Type: 02       |  (1 byte)
   | Character      |  (1 byte)
   +----------------+


This prints a single character. [[The encoding scheme is the business of
the I/O system; in Glk, it will be the Latin-1 character set.]]


   C-style string
   +----------------+
   | Type: 03       |  (1 byte)
   | Characters.... |  (any length)
   | NUL: 00        |  (1 byte)
   +----------------+


This prints an array of characters. Note that the array cannot contain a
zero byte, since that is reserved to terminate the array. [[A zero byte can
be printed using the single-character node type.]]


   Single Unicode character
   +----------------+
   | Type: 04       |  (1 byte)
   | Character      |  (4 bytes)
   +----------------+


This prints a single Unicode character. [[To be precise, it prints a 32-bit
character, which will be interpreted as Unicode if the I/O system is Glk.]]


   C-style Unicode string
   +----------------+
   | Type: 05       |  (1 byte)
   | Characters.... |  (any length, multiple of 4)
   | NUL: 00000000  |  (4 bytes)
   +----------------+


This prints an array of Unicode characters. Note that the array cannot
contain a zero word, since that is reserved to terminate the array. Also
note that, unlike an E2-encoded string object, there is no padding.

[[If the Glk library is unable to handle Unicode, node types 04 and 05 are
still legal. However, characters beyond FF will be printed as 3F ("?").]]


   Indirect reference
   +----------------+
   | Type: 08       |  (1 byte)
   | Address        |  (4 bytes)
   +----------------+


This prints a string or calls a function, which is not actually part of the
decoding table. The address may refer to a location anywhere in memory
(including RAM.) It must be a valid Glulx string (see section 1.6.1,
"Strings") or function (see section 1.6.2, "Functions"). If it is a string,
it is printed. If a function, it is called (with no arguments) and the
result is discarded.

The management of the stack during an indirect string/function call is a
bit tricky. See section 1.3.4, "Calling and Returning Within Strings".


   Double-indirect reference
   +----------------+
   | Type: 09       |  (1 byte)
   | Address        |  (4 bytes)
   +----------------+


This is similar to the indirect-reference node, but the address refers to a
four-byte field in memory, and *that* contains the address of a string or
function. The extra layer of indirection can be useful. For example, if the
four-byte field is in RAM, its contents can be changed during execution,
pointing to a new typable object, without modifying the decoding table
itself.


   Indirect reference with arguments
   +----------------+
   | Type: 0A       |  (1 byte)
   | Address        |  (4 bytes)
   | Argument Count |  (4 bytes)
   | Arguments....  |  (4*N bytes)
   +----------------+

   Double-indirect reference with arguments
   +----------------+
   | Type: 0B       |  (1 byte)
   | Address        |  (4 bytes)
   | Argument Count |  (4 bytes)
   | Arguments....  |  (4*N bytes)
   +----------------+


These work the same as the indirect and double-indirect nodes, but if the
object found is a function, it will be called with the given argument list.
If the object is a string, the arguments are ignored.

1.6.2: Functions

Functions have a type byte of C0 (for stack-argument functions) or C1 (for
local-argument functions). Types C2 to DF are reserved for future expansion
of function types.

A Glulx function always takes a list of 32-bit arguments, and returns
exactly one 32-bit value. (If you want a function which returns no value,
discard or ignore it. Store operand mode zero is convenient.)

If the type is C0, the arguments are passed on the stack, and are made
available on the stack. After the function's call frame is constructed, all
the argument values are pushed -- last argument pushed first, first
argument topmost. Then the number of arguments is pushed on top of that.
All locals in the call frame itself are initialized to zero.

If the type is C1, the arguments are passed on the stack, and are written
into the locals according to the "format of locals" list of the function.
Arguments passed into 8-bit or 16-bit locals are truncated. It is
legitimate for there to be too many or too few arguments. Extras are
discarded silently; any locals left unfilled are initialized to zero.

A function has the following structure:


   +------------+
   |  C0 or C1  |  Type (1 byte)
   +------------+
   | Format of  |    (2*n bytes)
   |     Locals |
   +------------+
   |  Opcodes   |
   |      ....  |
   +------------+


The locals-format list is encoded the same way it is on the stack; see
section 1.3.1, "The Call Frame". This is a list of LocalType/LocalCount
byte pairs, terminated by a zero/zero pair. (There is, however, no extra
padding to reach four-byte alignment.)

Note that although a LocalType/LocalCount pair can only describe up to 255
locals, there is no restriction on how many locals the function can have.
It is legitimate to encode several pairs in a row with the same LocalType.

Immediately following the two zero bytes, the instructions start. There is
no explicit terminator for the function.

1.6.3: Other Glulx Objects

There are no other Glulx objects at this time, but type 80 to BF are
reserved for future expansion. Type 00 is also reserved; it indicates "no
object", and should not be used by any typable object. A null reference's
type would be considered 00. (Even though byte 00000000 of main memory is
not in fact 00.)

1.6.4: User-Defined Objects

Types 01 to 7F are available for use by the compiler, the library, or the
program. Glulx will not use them.

[[Inform uses 60 for dictionary words, and 70 for objects and classes. It
reserves types 40 to 7F. Types 01 to 3F remain available for use by Inform
programmers.]]

1.7: Floating-Point Numbers

Glulx values are 32-bit integers, big-endian when stored in memory. To
handle floating-point math, we must be able to encode float values as
32-bit values. Unsurprisingly, Glulx uses the big-endian, single-precision
IEEE-754 encoding. (See
<http://www.psc.edu/general/software/packages/ieee/ieee.php>.) This allows
floats to be stored in memory, on the stack, in local variables, and in any
other place that a 32-bit value appears.

However, float values and integer values are *not* interchangable. You
cannot pass floats to the normal arithmetic opcodes, or vice versa, and
expect to get meaningful answers. Always pass floats to the float opcodes
and integers to the int opcodes, with the appropriate conversion opcodes to
convert back and forth. (See section 2.12, "Floating-Point Math".)

Floats have limited precision; they cannot represent all real values
exactly. They can't even represent all integers exactly. (Integers between
-1000000 and 1000000 (hex) have exact representations. Beyond that, the
rounding error can be greater than 1. But when you get into fractions,
errors are possible anywhere: 1/3 cannot be stored exactly.)

Therefore, you must be careful when comparing results. A series of float
operations may produce a result fractionally different from what you
expect. When comparing float values, you will most often want to use the
jfeq opcode, which tests whether two values are *near* each other (within a
specified range).

A float value has three fields in its 32 bits, from highest (the sign bit)
to lowest:


   +---------------+
   | Sign Bit (S)  |  (1 bit)
   | Exponent (E)  |  (8 bits)
   | Mantissa (M)  |  (23 bits)
   +---------------+


The interpretation of the value depends on the exponent value:

   * If E is FF and M is zero, the value is positive or negative infinity,
depending on S. Infinite values represent overflows. (+Inf is 7F800000;
-Inf is FF800000.)
   * If E is FF and M is nonzero, the value is a positive or negative NaN
("not a number"), depending on S. NaN values represent arithmetic failures.
(+NaN values are in the range 7F800001 to 7FFFFFFF; -NaN are FF800001 to
FFFFFFFF.)
   * If E is 00 and M is zero, the value is a positive or negative zero,
depending on S. Zero values represent underflows, and also, you know, zero.
(+0 is 00000000; -0 is 80000000.)
   * If E is 00 and M is nonzero, the value is a "denormalized" number,
very close to zero: plus or minus 2^(-149)*M.
   * If E is anything else, the value is a "normalized" number: plus or
minus 2^(E-150)*(800000+M).

[[I'm using decimal exponents there amid all the hex constants. -149 is hex
-95; -150 is hex -96. Sorry about that.]]

The numeric formulas may look more familiar if you write them as
2^(-126)*(0.MMMM...) and 2^(E-127)*(1.MMMM...), where "0.MMMM..." is a
fraction between zero and one (23 mantissa bits after the binal point) and
"1.MMMM...." is a fraction beween one and two.

Some example values:

   * 0.0   =  00000000 (S=0, E=00, M=0)
   * 1.0   =  3F800000 (S=0, E=7F, M=0)
   * -2.0  =  C0000000 (S=1, E=80, M=0)
   * 100.0 =  42C80000 (S=0, E=85, M=480000)
   * pi    =  40490FDB (S=0, E=80, M=490FDB)
   * 2*pi  =  40C90FDB (S=0, E=81, M=490FDB)
   * e     =  402DF854 (S=0, E=80, M=2DF854)

To give you an idea of the behavior of the special values:

   * 1 / 0    =  +Inf
   * -1 / 0   =  -Inf
   * 1 / Inf  =  0
   * 1 / -Inf =  -0
   * 0 / 0    =  NaN
   * 2 * 0    =  0
   * 2 * -0   =  -0
   * +Inf * 0 =  NaN
   * +Inf * 1 =  +Inf
   * +Inf + +Inf =  +Inf
   * +Inf * +Inf =  +Inf
   * +Inf - +Inf =  NaN
   * +Inf / +Inf =  NaN

NaN is sticky; almost *any* mathematical operation involving a NaN produces
NaN. (There are a few exceptions.)

However, Glulx does not guarantee *which* NaN value you will get from such
operations. The underlying platform may try to encode information about
what operation failed in the mantissa field of the NaN. Or, contrariwise,
it may return the same value for every NaN. The sign bit, similarly, is
never guaranteed. (The sign may be preserved if that's meaningful for the
failed operation, but it may not be.) You should not test for NaN by
comparing to a fixed encoded value; instead, use the jisnan opcode.

1.8: The Save-Game Format

(Or, if you like, "serializing the machine state".)

This is a variant of Quetzal, the standard Z-machine save file format. (See
<http://ifarchive.org/if-archive/infocom/interpreters/specification/savefile
_14.txt>.)

Everything in the Quetzal specification applies, with the following
exceptions:

1.8.1: Contents of Dynamic Memory

In both compressed and uncompressed form, the memory chunk ('CMem' or
'UMem') starts with a four-byte value, which is the current size of memory.
The memory data then follows. During a restore, the size of memory is
changed to this position.

The memory area to be saved does not start at address zero, but at
RAMSTART. It continues to the current end of memory (which may not be the
ENDMEM value in the header.) When generating or reading compressed data
('CMem' chunk), the data above EXTSTART is handled as if the game file were
extended with as many zeroes as necessary.

1.8.2: Contents of the Stack

Before the stack is written out, a four-value call stub is pushed on --
result destination, PC, and FramePtr. (See section 1.3.2, "Call Stubs".)
Then the entire stack can be written out, with all of its values (of
whatever size) transformed to big-endian. (Padding is not skipped; it's
written out as the appropriate number of zero bytes.)

When the game-state is loaded back in -- or, for that matter, when
continuing after a game-save -- the four values are read back off the
stack, a result code for the operation is stored in the appropriate
destination, and execution continues.

[[Remember that in a call stub, the PC contains the address of the
instruction *after* the one being executed.]]

1.8.3: Memory Allocation Heap

If the heap is active (see section 2.9, "Memory Allocation Heap"), an
allocation heap chunk is written ('MAll'). This chunk contains two
four-byte values, plus two more for each extant memory block:

   * Heap start address
   * Number of extant blocks
   * Address of first block
   * Length of first block
   * Address of second block
   * Length of second block
   * ...

The blocks need not be listed in any particular order.

If the heap is not active, the 'MAll' chunk can contain 0,0 or it may be
omitted.

1.8.4: Associated Story File

The contents of the game-file identifier ('IFhd' chunk) are simply the
first 128 bytes of memory. This is within ROM (since RAMSTART is at least
256), so it does not vary during play. It includes the story file length
and checksum, as well as any compiler-specific information that may be
stored immediately after the header.

1.8.5: State Not Saved

Some aspects of Glulx execution are not part of the save process, and
therefore are not changed during a restart, restore, or restoreundo
operation. The program is responsible for checking these values after a
restore to see if they have (from the program's point of view) changed
unexpectedly.

Examples of information which is not saved:

   * Glk library state. This includes Glk opaque objects (windows,
filerefs, streams). It also includes I/O state such as the current output
stream, contents of windows, and cursor positions. Accounting for Glk
object changes after restore/restoreundo is tricky, but absolutely
necessary.
   * The protected-memory range (position, length, and whether it exists
at all). Note that the *contents* of the range (if it exists) are not
treated specially during saving, and are therefore saved normally.
   * The random number generator's internal state.
   * The I/O system mode and current string-decoding table address.

2: Dictionary of Opcodes

Opcodes are written here in the format:

   opname L1 L2 S1

..where "L1" and "L2" are operands using the load addressing modes, and
"S1" is an operand using the store addressing modes. (See section 1.5,
"Instruction Format".)

The table of opcodes:

   * 0x00: nop
   * 0x10: add
   * 0x11: sub
   * 0x12: mul
   * 0x13: div
   * 0x14: mod
   * 0x15: neg
   * 0x18: bitand
   * 0x19: bitor
   * 0x1A: bitxor
   * 0x1B: bitnot
   * 0x1C: shiftl
   * 0x1D: sshiftr
   * 0x1E: ushiftr
   * 0x20: jump
   * 0x22: jz
   * 0x23: jnz
   * 0x24: jeq
   * 0x25: jne
   * 0x26: jlt
   * 0x27: jge
   * 0x28: jgt
   * 0x29: jle
   * 0x2A: jltu
   * 0x2B: jgeu
   * 0x2C: jgtu
   * 0x2D: jleu
   * 0x30: call
   * 0x31: return
   * 0x32: catch
   * 0x33: throw
   * 0x34: tailcall
   * 0x40: copy
   * 0x41: copys
   * 0x42: copyb
   * 0x44: sexs
   * 0x45: sexb
   * 0x48: aload
   * 0x49: aloads
   * 0x4A: aloadb
   * 0x4B: aloadbit
   * 0x4C: astore
   * 0x4D: astores
   * 0x4E: astoreb
   * 0x4F: astorebit
   * 0x50: stkcount
   * 0x51: stkpeek
   * 0x52: stkswap
   * 0x53: stkroll
   * 0x54: stkcopy
   * 0x70: streamchar
   * 0x71: streamnum
   * 0x72: streamstr
   * 0x73: streamunichar
   * 0x100: gestalt
   * 0x101: debugtrap
   * 0x102: getmemsize
   * 0x103: setmemsize
   * 0x104: jumpabs
   * 0x110: random
   * 0x111: setrandom
   * 0x120: quit
   * 0x121: verify
   * 0x122: restart
   * 0x123: save
   * 0x124: restore
   * 0x125: saveundo
   * 0x126: restoreundo
   * 0x127: protect
   * 0x130: glk
   * 0x140: getstringtbl
   * 0x141: setstringtbl
   * 0x148: getiosys
   * 0x149: setiosys
   * 0x150: linearsearch
   * 0x151: binarysearch
   * 0x152: linkedsearch
   * 0x160: callf
   * 0x161: callfi
   * 0x162: callfii
   * 0x163: callfiii
   * 0x170: mzero
   * 0x171: mcopy
   * 0x178: malloc
   * 0x179: mfree
   * 0x180: accelfunc
   * 0x181: accelparam
   * 0x190: numtof
   * 0x191: ftonumz
   * 0x192: ftonumn
   * 0x198: ceil
   * 0x199: floor
   * 0x1A0: fadd
   * 0x1A1: fsub
   * 0x1A2: fmul
   * 0x1A3: fdiv
   * 0x1A4: fmod
   * 0x1A8: sqrt
   * 0x1A9: exp
   * 0x1AA: log
   * 0x1AB: pow
   * 0x1B0: sin
   * 0x1B1: cos
   * 0x1B2: tan
   * 0x1B3: asin
   * 0x1B4: acos
   * 0x1B5: atan
   * 0x1B6: atan2
   * 0x1C0: jfeq
   * 0x1C1: jfne
   * 0x1C2: jflt
   * 0x1C3: jfle
   * 0x1C4: jfgt
   * 0x1C5: jfge
   * 0x1C8: jisnan
   * 0x1C9: jisinf

Opcodes 0x1000 to 0x10FF are reserved for use by FyreVM. Opcodes 0x1100 to
0x11FF are reserved for extension projects by Dannii Willis. These are not
documented here. See section 0.2, "Glulx and Other IF Systems".

2.1: Integer Math

   add L1 L2 S1

Add L1 and L2, using standard 32-bit addition. Truncate the result to 32
bits if necessary. Store the result in S1.

   sub L1 L2 S1

Compute (L1 - L2), and store the result in S1.

   mul L1 L2 S1

Compute (L1 * L2), and store the result in S1. Truncate the result to 32
bits if necessary.

   div L1 L2 S1

Compute (L1 / L2), and store the result in S1. This is signed integer
division.

   mod L1 L2 S1

Compute (L1 % L2), and store the result in S1. This is the remainder from
signed integer division.

In division and remainer, signs are annoying. Rounding is towards zero. The
sign of a remainder equals the sign of the dividend. It is always true that
(A / B) * B + (A % B) == A. Some examples (in decimal):


    11 /  2 =  5
   -11 /  2 = -5
    11 / -2 = -5
   -11 / -2 =  5
    13 %  5 =  3
   -13 %  5 = -3
    13 % -5 =  3
   -13 % -5 = -3


   neg L1 S1

Compute the negative of L1.

   bitand L1 L2 S1

Compute the bitwise AND of L1 and L2.

   bitor L1 L2 S1

Compute the bitwise OR of L1 and L2.

   bitxor L1 L2 S1

Compute the bitwise XOR of L1 and L2.

   bitnot L1 S1

Compute the bitwise negation of L1.

   shiftl L1 L2 S1

Shift the bits of L1 to the left (towards more significant bits) by L2
places. The bottom L2 bits are filled in with zeroes. If L2 is 32 or more,
the result is always zero.

   ushiftr L1 L2 S1

Shift the bits of L1 to the right by L2 places. The top L2 bits are filled
in with zeroes. If L2 is 32 or more, the result is always zero.

   sshiftr L1 L2 S1

Shift the bits of L1 to the right by L2 places. The top L2 bits are filled
in with copies of the top bit of L1. If L2 is 32 or more, the result is
always zero or FFFFFFFF, depending on the top bit of L1.

Notes on the shift opcodes: If L2 is zero, the result is always equal to
L1. L2 is considered unsigned, so 80000000 or greater is "more than 32".

2.2: Branches

All branches (except jumpabs) specify their destinations with an offset
value. The actual destination address of the branch is computed as (Addr +
Offset - 2), where Addr is the address of the instruction *after* the
branch opcode, and offset is the branch's operand. The special offset
values 0 and 1 are interpreted as "return 0" and "return 1" respectively.
[[This odd hiccup is inherited from the Z-machine. Inform uses it heavily
for code optimization.]]

It is legal to branch to code that is in another function. [[Indeed, there
is no well-defined notion of where a function ends.]] However, this does
not affect the current stack frame; that remains set up according to the
same function call as before the branch. Similarly, it is legal to branch
to code which is not associated with any function -- e.g., code compiled on
the fly in RAM.

   jump L1

Branch unconditionally to offset L1.

   jz L1 L2

If L1 is equal to zero, branch to L2.

   jnz L1 L2

If L1 is not equal to zero, branch to L2.

   jeq L1 L2 L3

If L1 is equal to L2, branch to L3.

   jne L1 L2 L3

If L1 is not equal to L2, branch to L3.

   jlt L1 L2 L3
   jle L1 L2 L3
   jgt L1 L2 L3
   jge L1 L2 L3

Branch is L1 is less than, less than or equal to, greater than, greater
than or equal to L2. The values are compared as signed 32-bit values.

   jltu L1 L2 L3
   jleu L1 L2 L3
   jgtu L1 L2 L3
   jgeu L1 L2 L3

The same, except that the values are compared as unsigned 32-bit values.

[[Since the address space can span the full 32-bit range, it is wiser to
compare addresses with the unsigned comparison operators.]]

   jumpabs L1

Branch unconditionally to address L1. Unlike the other branch opcodes, this
takes an absolute address, not an offset. The special cases 0 and 1 (for
returning) do not apply; jumpabs 0 would branch to memory address 0, if
that were ever a good idea, which it isn't.

2.3: Moving Data

   copy L1 S1

Read L1 and store it at S1, without change.

   copys L1 S1

Read a 16-bit value from L1 and store it at S1.

   copyb L1 S1

Read an 8-bit value from L1 and store it at S1.

Since copys and copyb can access chunks smaller than the usual four bytes,
they require some comment. When reading from main memory or the call-frame
locals, they access two or one bytes, instead of four. However, when
popping or pushing values on the stack, these opcodes pull or push a full
32-bit value.

Therefore, if copyb (for example) copies a byte from main memory to the
stack, a 32-bit value will be pushed, whose value will be from 0 to 255.
Sign-extension *does not* occur. Conversely, if copyb copies a byte from
the stack to memory, a 32-bit value is popped, and the bottom 8 bits are
written at the given address. The upper 24 bits are lost. Constant values
are truncated as well.

If copys or copyb are used with both L1 and S1 in pop/push mode, the 32-bit
value is popped, truncated, and pushed.

[[NOTE: Since a call frame has no specified endianness, it is unwise to use
these opcodes to pull out one or two bytes from a four-byte local variable.
The result will be implementation-dependent. Therefore, use of the copyb
and copys opcodes with a local-variable operand of different size is
deprecated. Since locals of less than four bytes are *also* deprecated, you
should not use copyb or copys with local-variable operands at all.]]

   sexs L1 S1

Sign-extend a value, considered as a 16-bit value. If the value's 8000 bit
is set, the upper 16 bits are all set; otherwise, the upper 16 bits are all
cleared.

   sexb L1 S1

Sign-extend a value, considered as an 8-bit value. If the value's 80 bit is
set, the upper 24 bits are all set; otherwise, the upper 24 bits are all
cleared.

Note that these opcodes, like most, work on 32-bit values. Although (for
example) sexb is commonly used in conjunction with copyb, it does not share
copyb's behavior of reading a single byte from memory or the locals.

Also note that the upper bits, 16 or 24 of them, are entirely ignored and
overwritten with ones or zeroes.

2.4: Array Data

   astore L1 L2 L3

Store L3 into the 32-bit field at main memory address (L1+4*L2).

   aload L1 L2 S1

Load a 32-bit value from main memory address (L1+4*L2), and store it in S1.

   astores L1 L2 L3

Store L3 into the 16-bit field at main memory address (L1+2*L2).

   aloads L1 L2 S1

Load an 16-bit value from main memory address (L1+2*L2), and store it in S1.

   astoreb L1 L2 L3

Store L3 into the 8-bit field at main memory address (L1+L2).

   aloadb L1 L2 S1

Load an 8-bit value from main memory address (L1+L2), and store it in S1.

Note that these opcodes cannot access call-frame locals, or the stack. (Not
with the L1 and L2 opcodes, that is.) L1 and L2 provide a main-memory
address. Be not confused by the fact that L1 and L2 can be any addressing
mode, including call-frame or stack-pop modes. That controls where the
values come from which are used to *compute* the main-memory address.

The other end of the transfer (S1 or L3) is always a 32-bit value. The
"store" opcodes truncate L3 to 8 or 16 bits if necessary. The "load"
opcodes expand 8-bit or 16-bit values *without* sign extension. (If signed
values are appropriate, you can follow aloads/aloadb with sexs/sexb.)

L2 is considered signed, so you can access addresses before L1 as well as
after.

   astorebit L1 L2 L3

Set or clear a single bit. This is bit number (L2 mod 8) of memory address
(L1+L2/8). It is cleared if L3 is zero, set if nonzero.

   aloadbit L1 L2 S1

Test a single bit, similarly. If it is set, 1 is stored at S1; if clear, 0
is stored.

For these two opcodes, bits are effectively numbered sequentially, starting
with the least significant bit of address L1. L2 is considered signed, so
this numbering extends both positively and negatively. For example:


   astorebit  1002  0  1:  Set bit 0 of address 1002. (The 1's place.)
   astorebit  1002  7  1:  Set bit 7 of address 1002. (The 128's place.)
   astorebit  1002  8  1:  Set bit 0 of address 1003.
   astorebit  1002  9  1:  Set bit 1 of address 1003.
   astorebit  1002 -1  1:  Set bit 7 of address 1001.
   astorebit  1002 -3  1:  Set bit 5 of address 1001.
   astorebit  1002 -8  1:  Set bit 0 of address 1001.
   astorebit  1002 -9  1:  Set bit 7 of address 1000.


Like the other aload and astore opcodes, these opcodes cannot access
call-frame locals, or the stack.

2.5: The Stack

   stkcount S1

Store a count of the number of values on the stack. This counts only values
above the current call-frame. In other words, it is always zero when a C1
function starts executing, and (numargs+1) when a C0 function starts
executing. It then increases and decreases thereafter as values are pushed
and popped; it is always the number of values that can be popped legally.
(If S1 uses the stack push mode, the count is done before the result is
pushed.)

   stkpeek L1 S1

Peek at the L1'th value on the stack, without actually popping anything. If
L1 is zero, this is the top value; if one, it's the value below that; etc.
L1 must be less than the current stack-count. (If L1 or S1 use the stack
pop/push modes, the peek is counted after L1 is popped, but before the
result is pushed.)

   stkswap

Swap the top two values on the stack. The current stack-count must be at
least two.

   stkcopy L1

Peek at the top L1 values in the stack, and push duplicates onto the stack
in the same order. If L1 is zero, nothing happens. L1 must not be greater
than the current stack-count. (If L1 uses the stack pop mode, the stkcopy
is counted after L1 is popped.)

An example of stkcopy, starting with six values on the stack:


   5 4 3 2 1 0 <top>
   stkcopy 3
   5 4 3 2 1 0 2 1 0 <top>


   stkroll L1 L2

Rotate the top L1 values on the stack. They are rotated up or down L2
places, with positive values meaning up and negative meaning down. The
current stack-count must be at least L1. If either L1 or L2 is zero,
nothing happens. (If L1 and/or L2 use the stack pop mode, the roll occurs
after they are popped.)

An example of two stkrolls, starting with nine values on the stack:


   8 7 6 5 4 3 2 1 0 <top>
   stkroll 5 1
   8 7 6 5 0 4 3 2 1 <top>
   stkroll 9 -3
   5 0 4 3 2 1 8 7 6 <top>


Note that stkswap is equivalent to stkroll 2 1, or for that matter stkroll
2 -1. Also, stkcopy 1 is equivalent to stkpeek 0 sp.

These opcodes can only access the values pushed on the stack above the
current call-frame. It is illegal to stkswap, stkpeek, stkcopy, or stkroll
values below that -- i.e, the locals segment or any previous function call
frames.

2.6: Functions

   call L1 L2 S1

Call function whose address is L1, passing in L2 arguments, and store the
return result at S1.

The arguments are taken from the stack. Before you execute the call opcode,
you must push the arguments on, in backward order (last argument pushed
first, first argument topmost on the stack.) The L2 arguments are removed
before the new function's call frame is constructed. (If L1, L2, or S1 use
the stack pop/push modes, the arguments are taken after L1 or L2 is popped,
but before the result is pushed.)

Recall that all functions in Glulx have a single 32-bit return value. If
you do not care about the return value, you can use operand mode 0
("discard value") for operand S1.

   callf L1 S1
   callfi L1 L2 S1
   callfii L1 L2 L3 S1
   callfiii L1 L2 L3 L4 S1

Call function whose address is L1, passing zero, one, two, or three
arguments. Store the return result at S1.

These opcodes behave the same as call, except that the arguments are given
in the usual opcode format instead of being found on the stack. (If L2, L3,
etc. all use the stack pop mode, then the behavior is exactly the same as
call.)

   return L1

Return from the current function, with the given return value. If this is
the top-level function, Glulx execution is over.

Note that all the branch opcodes (jump, jz, jeq, and so on) have an option
to return 0 or 1 instead of branching. These behave exactly as if the
return opcode had been executed.

   tailcall L1 L2

Call function whose address is L1, passing in L2 arguments, and pass the
return result out to whoever called the current function.

This destroys the current call-frame, as if a return had been executed, but
does not touch the call stub below that. It then immediately calls L1,
creating a new call-frame. The effect is the same as a call immediately
followed by a return, but takes less stack space.

It is legal to use tailcall from the top-level function. L1 becomes the
top-level function.

[[This opcode can be used to implement tail recursion, without forcing the
stack to grow with every call.]]

2.7: Continuations

   catch S1 L1

Generates a "catch token", which can be used to jump back to this execution
point from a throw opcode. The token is stored in S1, and then execution
branches to offset L1. If execution is proceeding from this point because
of a throw, the thrown value is stored instead, and the branch is ignored.

Remember if the branch value is not 0 or 1, the branch is to to (Addr + L1
- 2), where Addr is the address of the instruction *after* the catch. If
the value *is* 0 or 1, the function returns immediately, invalidating the
catch token.

If S1 or L1 uses the stack push/pop modes, note that the precise order of
execution is: evaluate L1 (popping if appropriate); generate a call stub
and compute the token; store S1 (pushing if appropriate).

   throw L1 L2

Jump back to a previously-executed catch opcode, and store the value L1. L2
must be a valid catch token.

The exact catch/throw procedure is as follows:

When catch is executed, a four-value call stub is pushed on the stack --
result destination, PC, and FramePtr. (See section 1.3.2, "Call Stubs". The
PC is the address of the next instruction after the catch.) The catch token
is the value of the stack pointer after these are pushed. The token value
is stored in the result destination, and execution proceeds, branching to
L1.

When throw is executed, the stack is popped down until the stack pointer
equals the given token. Then the four values are read back off the stack,
the thrown value is stored in the destination, and execution proceeds with
the instruction after the catch.

If the call stub (or any part of it) is removed from the stack, the catch
token becomes invalid, and must not be used. This will certainly occur when
you return from the function containing the catch opcode. It will also
occur if you pop too many values from the stack after executing the catch.
(You may wish to do this to "cancel" the catch; if you pop and discard
those four values, the token is invalidated, and it is as if you had never
executed the catch at all.) The catch token is also invalidated if any part
of the call stub is overwritten (e.g. with stkswap or stkroll).

[[Why is the catch branch taken at catch time, and ignored after a throw?
Because it's easier to write the interpreter that way, that's why. If it
had to branch after a throw, either the call stub would have to contain the
branch offset, or the terp would have to re-parse the catch instruction.
Both are ugly.]]

2.8: Memory Map

   getmemsize S1

Store the current size of the memory map. This is originally the ENDMEM
value from the header, but you can change it with the setmemsize opcode.
(The malloc and mfree opcodes may also cause this value to change; see
section 2.9, "Memory Allocation Heap".) It will always be greater than or
equal to ENDMEM, and will always be a multiple of 256.

   setmemsize L1 S1

Set the current size of the memory map. The new value must be a multiple of
256, like all memory boundaries in Glulx. It must be greater than or equal
to ENDMEM (the initial memory-size value which is stored in the header.) It
does not have to be greater than the previous memory size. The memory size
may grow and shrink over time, as long as it never gets smaller than the
initial size.

When the memory size grows, the new space is filled with zeroes. When it
shrinks, the contents of the old space are lost.

If the allocation heap is active (see section 2.9, "Memory Allocation
Heap") you may not use setmemsize -- the memory map is under the control of
the heap system. If you free all heap objects, the heap will then no longer
be active, and you can use setmemsize.

Since memory allocation is never guaranteed, you must be prepared for the
possibility that setmemsize will fail. The opcode stores the value zero if
it succeeded, and 1 if it failed. If it failed, the memory size is
unchanged.

Some interpreters do not have the capability to resize memory at all. On
such interpreters, setmemsize will *always* fail. You can check this in
advance with the ResizeMem gestalt selector.

Note that the memory size is considered part of the game state. If you
restore a saved game, the current memory size is changed to the size that
was in effect when the game was saved. If you restart, the current memory
size is reset to its initial value.

2.9: Memory Allocation Heap

Manage the memory allocation heap.

Glulx is able to maintain a list of dynamically-allocated memory objects.
These objects exist in the memory map, above ENDMEM. The malloc and mfree
opcodes allow the game to request the allocation and destruction of these
objects.

Some interpreters do not have the capability to manage an allocation heap.
On such interpreters, malloc will always fail. You can check this in
advance with the MAlloc gestalt selector.

When you first allocate a block of memory, the heap becomes active. The
current end of memory -- that is, the current getmemsize value -- becomes
the beginning address of the heap. The memory map is then extended to
accomodate the memory block.

Subsequent memory allocations and deallocations are done within the heap.
The interpreter may extend or reduce the memory map, as needed, when
allocations and deallocations occur. While the heap is active, you may not
manually resize the memory map with setmemsize; the heap system is
responsible for doing that.

When you free the last extant memory block, the heap becomes inactive. The
interpreter will reduce the memory map size down to the heap-start address.
(That is, the getmemsize value returns to what it was before you allocated
the first block.) Thereafter, it is legal to call setmemsize again.

It is legitimate to read or write any memory address in the heap range
(from ENDMEM to the end of the memory map). You are not restricted to
extant blocks. [[The VM's heap state is not stored in its own memory map.
So, unlike the familiar C heap, you cannot damage it by writing outside
valid blocks.]]

The heap state (whether it is active, its starting address, and the
addresses and sizes of all extant blocks) *is* part of the saved game state.

These opcodes were added in Glulx version 3.1.

   malloc L1 S1

Allocate a memory block of L1 bytes. (L1 must be positive.) This stores the
address of the new memory block, which will be within the heap and will not
overlap any other extant block. The interpreter may have to extend the
memory map (see section 2.8, "Memory Map") to accomodate the new block.

This operation does not change the contents of the memory block (or,
indeed, the contents of the memory map at all). If you want the memory
block to be initialized, you must do it yourself.

If the allocation fails, this stores zero.

   mfree L1

Free the memory block at address L1. This *must* be the address of an
extant block -- that is, a value returned by malloc and not previously
freed.

This operation does not change the contents of the memory block (or,
indeed, the contents of the memory map at all).

2.10: Game State

   quit

Shut down the terp and exit. This is equivalent to returning from the
top-level function, or for that matter calling glk_exit().

Note that (in the Glk I/O system) Glk is responsible for any "hit any key
to exit" prompt. It is safe for you to print a bunch of final text and then
exit immediately.

   restart

Restore the VM to its initial state (memory, stack, and registers). Note
that the current memory size is reset, as well as the contents of memory.

   save L1 S1

Save the VM state to the output stream L1. It is your responsibility to
prompt the player for a filespec, open the stream, and then destroy these
objects afterward. S1 is set to zero if the operation succeeded, 1 if it
failed, and -1 if the VM has just been restored and is continuing from this
instruction.

(In the Glk I/O system, L1 should be the ID of a writable Glk stream. In
other I/O systems, it will mean something different. In the "filter" and
"null" I/O systems, the save opcode is illegal, as the interpreter has
nowhere to write the state.)

   restore L1 S1

Restore the VM state from the input stream L1. S1 is set to 1 if the
operation failed. If it succeeded, of course, this instruction never
returns a value.

   saveundo S1

Save the VM state in a temporary location. The terp will choose a location
appropriate for rapid access, so this may be called once per turn. S1 is
set to zero if the operation succeeded, 1 if it failed, and -1 if the VM
state has just been restored.

   restoreundo S1

Restore the VM state from temporary storage. S1 is set to 1 if the
operation failed.

   protect L1 L2

Protect a range of memory from restart, restore, restoreundo. The protected
range starts at address L1 and has a length of L2 bytes. This memory is
silently unaffected by the state-restoring operations. (However, if the
result-storage S1 is directed into the protected range, that is not
blocked.)

When the VM starts up, there is no protection range. Only one range can be
protected at a time. Calling protect cancels any previous range. To turn
off protection, call protect with L1 and L2 set to zero.

It is important to note that the protection range itself (its existence,
location, and length) is *not* part of the saved game state! If you save a
game, move the protection range to a new location, and then restore that
game, it is the new range that will be protected, and the range will remain
there afterwards.

   verify S1

Perform sanity checks on the game file, using its length and checksum. S1
is set to zero if everything looks good, 1 if there seems to be a problem.
(Many interpreters will do this automatically, before the game starts
executing. This opcode is provided mostly for slower interpreters, where
auto-verify might cause an unacceptable delay.)

Notes:

All the save and restore opcodes can generate diagnostic information on the
current output stream.

A terp may support several levels of temporary storage. You should not make
any assumptions about how many times restoreundo can be called. If the
player so requests, you should keep calling it until it fails.

Glk opaque objects (windows, streams, filespecs) are not part of the saved
game state. Therefore, when you restore a game, all the object IDs you have
in Glulx memory must be considered invalid. (This includes both IDs in main
memory and on the stack.) You must use the Glk iteration calls to go
through all the opaque objects in existence, and recognize them by their
rocks.

The same applies after restoreundo, to a lesser extent. Since
saveundo/restoreundo only operate within a single play session, you can
rely on the IDs of objects created before the first saveundo. However, if
you have created any objects since then, you must iterate and recognize
them.

The restart opcode is a similar case. You must do an iteration as soon as
your program starts, to find objects created in an earlier incarnation.
Alternatively, you can be careful to close all opaque objects before
invoking restart.

[[Another approach is to use the protect opcode, to preserve global
variables containing your object IDs. This will work within a play session
-- that is, with saveundo, restoreundo, and restart. You must still deal
with save and restore.]]

2.11: Output

   getiosys S1 S2

Return the current I/O system mode and rock.

Due to a long-standing bug in the reference interpreter, the two store
operands must be of the same general type: both main-memory/global stores,
both local variable stores, or both stack pushes.

   setiosys L1 L2

Set the I/O system mode and rock. If the system L1 is not supported by the
interpreter, it will default to the "null" system (0).

These systems are currently defined:

   * 0: The null system. All output is discarded. (When the Glulx machine
starts up, this is the current system.)
   * 1: The filtering system. The rock (L2) value should be the address of
a Glulx function. This function will be called for every character output
(with the character value as its sole argument). The function's return
value is ignored.
   * 2: The Glk system. All output will be handled through Glk function
calls, sent to the current Glk stream.
   * 20: The FyreVM channel system. See section 0.2, "Glulx and Other IF
Systems".

It is important to recall that when Glulx starts up, the Glk I/O system is
*not* set. And when Glk starts up, there are no windows and no current
output stream. To make anything appear to the user, you must first do three
things: select the Glk I/O system, open a Glk window, and set its stream as
the current one. (It is illegal in Glk to send output when there is no
stream set. Sending output to Glulx's "null" I/O system is legal, but
pointless.)

   streamchar L1

Send L1 to the current stream. This sends a single character; the value L1
is truncated to eight bits.

   streamunichar L1

Send L1 to the current stream. This sends a single (32-bit) character.

This opcode was added in Glulx version 3.0.

   streamnum L1

Send L1 to the current stream, represented as a signed decimal number in
ASCII.

   streamstr L1

Send a string object to the current stream. L1 must be the address of a
Glulx string object (type E0, E1, or E2.) The string is decoded and sent as
a sequence of characters.

When the Glk I/O system is set, these opcodes are implemented using the Glk
API. You can bypass them and directly call glk_put_char(),
glk_put_buffer(), and so on. Remember, however, that glk_put_string() only
accepts unencoded string (E0) objects; glk_put_string_uni() only accepts
unencoded Unicode (E2) objects.

Note that it is illegal to decode a compressed string (E1) if there is no
string-decoding table set.

   getstringtbl S1

Return the address the terp is currently using for its string-decoding
table. If there is no table, set, this returns zero.

   setstringtbl L1

Change the address the terp is using for its string-decoding table. This
may be zero, indicating that there is no table (in which case it is illegal
to print any compressed string). Otherwise, it must be the address of a
*valid* string-decoding table.

[[This does not change the value in the header field at address 001C. The
header is in ROM, and never changes. To determine the current table
address, use the getstringtbl opcode.]]

A string-decoding table may be in RAM or ROM, but there may be speed
penalties if it is in RAM. See section 1.6.1.4, "The String-Decoding Table".

2.12: Floating-Point Math

Recall that floating-point values are encoded as single-precision (32-bit)
IEEE-754 values (see section 1.7, "Floating-Point Numbers"). The
interpreter must convert values (from memory or the stack) before
performing a floating-point operation, and unconvert them afterwards.

[[In other words, passing a float value to an integer arithmetic opcode
will operate on the IEEE-754-encoded 32-bit value. Such an operation would
be deterministic, albeit mathematically meaningless. The same is true for
passing an integer to a float opcode.]]

Float operations which produce inexact results are not guaranteed to be
identical on every platform. That is, 1.0 plus 1.0 will always be 2.0,
because that can be represented exactly. But acos(-1.0), which should be
pi, may generate either 40490FDA (3.14159250...) or 40490FDB
(3.14159274...). Both are approximations of the correct result, but which
one you get depends on the interpreter's underlying math library.

If any argument to a float operation is a NaN ("not a number") value, the
result will be a NaN value. (Except for the pow opcode, which has some
special cases.)

[[Speaking of special cases: I have tried to describe all the important
ones for these operations. However, you should also consult the Glulxercise
unit test (available on the Glulx web site). Consider it definitive if this
document is unclear.]]

These opcodes were added in Glulx version 3.1.2. However, not all
interpreters may support them. You can test for their availability with the
Float gestalt selector.

   numtof L1 S1

Convert an integer value to the closest equivalent float. (That is, if L1
is 1, then 3F800000 -- the float encoding of 1.0 -- will be stored in S1.)
Integer zero is converted to (positive) float zero.

If the value is less than -1000000 or greater than 1000000 (hex), the
conversion may not be exact. (More specifically, it may round to a nearby
multiple of a power of 2.)

   ftonumz L1 S1

Convert a float value to an integer, rounding towards zero (i.e.,
truncating the fractional part). If the value is outside the 32-bit integer
range, or is NaN or infinity, the result will be 7FFFFFFF (for positive
values) or 80000000 (for negative values).

   ftonumn L1 S1

Convert a float value to an integer, rounding towards the nearest integer.
Again, overflows become 7FFFFFFF or 80000000.

   fadd L1 L2 S1
   fsub L1 L2 S1
   fmul L1 L2 S1
   fdiv L1 L2 S1

Perform floating-point arithmetic. Overflows produce infinite values (with
the appropriate sign); underflows produce zero values (ditto). 0/0 is NaN.
Inf/Inf, or Inf-Inf, is NaN. Any finite number added to infinity is
infinity. Any nonzero number divided by an infinity, or multiplied by zero,
is a zero. Any nonzero number multiplied by an infinity, or divided by
zero, is an infinity.

   fmod L1 L2 S1 S2

Perform a floating-point modulo operation. S1 is the remainder (or
modulus); S2 is the quotient.

S2 is L1/L2, rounded (towards zero) to an integral value. S1 is L1-(S2*L2).
Note that S1 always has the same sign as L1; S2 has the appropriate sign
for L1/L2.

If L2 is 1, this gives you the fractional and integer parts of L1. If L1 is
zero, both results are zero. If L2 is infinite, S1 is L1 and S2 is zero. If
L1 is infinite or L2 is zero, both results are NaN.

   ceil L1 S1
   floor L1 S1

Round L1 up (towards +Inf) or down (towards -Inf) to the nearest integral
value. (The result is still in float format, however.) These opcodes are
idempotent.

The result keeps the sign of L1; in particular, floor(0.5) is 0 and
ceil(-0.5) is -0. Rounding -0 up or down gives -0. Rounding an infinite
value gives infinity.

   sqrt L1 S1
   exp L1 S1
   log L1 S1

Compute the square root of L1, e^L1, and log of L1 (base e).

sqrt(-0) is -0. sqrt returns NaN for all other negative values. exp(+0) and
exp(-0) are 1; exp(-Inf) is +0. log(+0) and log(-0) are -Inf. log returns
NaN for all other negative values.

   pow L1 L2 S1

Compute L1 raised to the L2 power.

The special cases are breathtaking. The following is quoted (almost)
directly from the libc man page:

   * pow(+-0, y) returns +-Inf for y an odd integer < 0.
   * pow(+-0, y) returns +Inf for y < 0 and not an odd integer.
   * pow(+-0, y) returns +-0 for y an odd integer > 0.
   * pow(+-0, y) returns +0 for y > 0 and not an odd integer.
   * pow(-1, +-Inf) returns 1.
   * pow(1, y) returns 1 for any y, even a NaN.
   * pow(x, +-0) returns 1 for any x, even a NaN.
   * pow(x, y) returns a NaN for finite x < 0 and finite non-integer y.
   * pow(x, -Inf) returns +Inf for |x| < 1.
   * pow(x, -Inf) returns +0 for |x| > 1.
   * pow(x, +Inf) returns +0 for |x| < 1.
   * pow(x, +Inf) returns +Inf for |x| > 1.
   * pow(-Inf, y) returns -0 for y an odd integer < 0.
   * pow(-Inf, y) returns +0 for y < 0 and not an odd integer.
   * pow(-Inf, y) returns -Inf for y an odd integer > 0.
   * pow(-Inf, y) returns +Inf for y > 0 and not an odd integer.
   * pow(+Inf, y) returns +0 for y < 0.
   * pow(+Inf, y) returns +Inf for y > 0.
   * pow(x, y) returns NaN if x is negative and y is not an integer (both
finite).

   sin L1 S1
   cos L1 S1
   tan L1 S1
   acos L1 S1
   asin L1 S1
   atan L1 S1

Compute the standard trigonometric functions.

sin and cos return values in the range -1 to 1. sin, cos, and tan of
infinity are NaN.

asin is always in the range -pi/2 to pi/2; acos is always in the range 0 to
pi. asin and acos of values greater than 1, or less than -1, are NaN.
atan(+-Inf) is +-pi/2.

   atan2 L1 L2 S1

Computes the arctangent of L1/L2, using the signs of both arguments to
determine the quadrant of the return value. (Note that the Y argument is
first and the X argument is second.)

Again with the special cases:

   * atan2(+-0, -0) returns +-pi.
   * atan2(+-0, +0) returns +-0.
   * atan2(+-0, x) returns +-pi for x < 0.
   * atan2(+-0, x) returns +-0 for x > 0.
   * atan2(y, +-0) returns +pi/2 for y > 0.
   * atan2(y, +-0) returns -pi/2 for y < 0.
   * atan2(+-y, -Inf) returns +-pi for finite y.
   * atan2(+-y, +Inf) returns +-0 for finite y.
   * atan2(+-Inf, x) returns +-pi/2 for finite x.
   * atan2(+-Inf, -Inf) returns +-3*pi/4.
   * atan2(+-Inf, +Inf) returns +-pi/4.

2.13: Floating-Point Comparisons

All these branch opcodes specify their destinations with an offset value.
See section 2.2, "Branches".

Most of these opcodes never branch if any argument is NaN. (Exceptions are
jisnan and jfne.) In particular, NaN is neither less than, greater than,
nor equal to NaN.

These opcodes were added in Glulx version 3.1.2. However, not all
interpreters may support them. You can test for their availability with the
Float gestalt selector.

   jisnan L1 L2

Branch to L2 if the floating-point value L1 is a NaN value. (See section
1.7, "Floating-Point Numbers".)

   jisinf L1 L2

Branch to L2 if the floating-point value L1 is an infinity (7F800000 or
FF800000).

   jfeq L1 L2 L3 L4

Branch to L4 if the difference between L1 and L2 is less than or equal to
(plus or minus) L3. The sign of L3 is ignored.

If any of the arguments are NaN, this will not branch. If L3 is infinite,
this will always branch -- unless L1 and L2 are opposite infinities.
(Opposite infinities are never equal, regardless of L3. Infinities of the
same sign are always equal.)

If L3 is (plus or minus) zero, this tests for exact equality. Note that +0
is considered exactly equal to -0.

   jfne L1 L2 L3 L4

The reverse of jfeq. This *will* branch if *any* of the arguments is NaN.

   jflt L1 L2 L3
   jfle L1 L2 L3
   jfgt L1 L2 L3
   jfge L1 L2 L3

Branch to L3 if L1 is less than (less than or equal to, greater than,
greater than or equal to) L2.

+0 and -0 behave identically in comparisons. In particular, +0 is
considered equal to -0, not greater than -0.

2.14: Random Number Generator

   random L1 S1

Return a random number in the range 0 to (L1-1); or, if L1 is negative, the
range (L1+1) to 0. If L1 is zero, return a random number in the full 32-bit
integer range. (Remember that this may be either positive or negative.)

   setrandom L1

Seed the random-number generator with the value L1. If L1 is zero,
subsequent random numbers will be as genuinely unpredictable as the terp
can provide; it may include timing data or other random sources in its
generation. If L1 is nonzero, subsequent random numbers will follow a
deterministic sequence, always the same for a given nonzero seed.

The terp starts up in the "nondeterministic" mode (as if setrandom 0 had
been invoked.)

The random-number generator is not part of the saved-game state.

2.15: Block Copy and Clear

   mzero L1 L2

Write L1 zero bytes, starting at address L2. This is exactly equivalent to:


   for (ix=0: ix<L1: ix++) L2->ix = 0;


   mcopy L1 L2 L3

Copy L1 bytes from address L2 to address L3. It is safe to copy a block to
an overlapping block. This is exactly equivalent to:


   if (L3 < L2)
     for (ix=0: ix<L1: ix++) L3->ix = L2->ix;
   else
     for (ix=L1-1: ix>=0: ix--) L3->ix = L2->ix;


For both of these opcodes, L1 may be zero, in which case the opcodes do
nothing. The operands are considered unsigned, so a "negative" L1 is a very
large number (and almost certainly a mistake).

These opcodes were added in Glulx version 3.1. You can test for their
availability with the MemCopy gestalt selector.

2.16: Searching

Perform a generic linear, binary, or linked-list search.

[[These are outrageously CISC for an hardware CPU, but easy enough to add
to a software terp; and taking advantage of them can speed up a program
considerably. Advent, under the Inform library, runs 15-20% faster when
property-table lookup is handled with a binary-search opcode instead of
Inform code. A similar change in the dictionary lookup trims another
percent or so.]]

All three of these opcodes operate on a collection of fixed-size data
structures in memory. A key, which is a fixed-length array of bytes, is
found at a known position within each data structure. The opcodes search
the collection of structures, and find one whose key matches a given key.

The following flags may be set in the Options argument. Note that not all
flags can be used with all types of searches.

   * KeyIndirect (0x01): This flag indicates that the Key argument passed
to the opcode is the address of the actual key. If this flag is not used,
the Key argument is the key value itself. (In this case, the KeySize *must*
be 1, 2, or 4 -- the native sizes of Glulx values. If the KeySize is 1 or
2, the lower bytes of the Key are used and the upper bytes ignored.)
   * ZeroKeyTerminates (0x02): This flag indicates that the search should
stop (and return failure) if it encounters a structure whose key is all
zeroes. If the searched-for key happens to also be all zeroes, the success
takes precedence.
   * ReturnIndex (0x04): This flag indicates that search should return the
array index of the structure that it finds, or -1 (0xFFFFFFFF) for failure.
If this flag is not used, the search returns the address of the structure
that it finds, or 0 for failure.

   linearsearch L1 L2 L3 L4 L5 L6 L7 S1

   * L1: Key
   * L2: KeySize
   * L3: Start
   * L4: StructSize
   * L5: NumStructs
   * L6: KeyOffset
   * L7: Options
   * S1: Result

An array of data structures is stored in memory, beginning at Start, each
structure being StructSize bytes. Within each struct, there is a key value
KeySize bytes long, starting at position KeyOffset (from the start of the
structure.) Search through these in order. If one is found whose key
matches, return it. If NumStructs are searched with no result, the search
fails.

NumStructs may be -1 (0xFFFFFFFF) to indicate no upper limit to the number
of structures to search. The search will continue until a match is found,
or (if ZeroKeyTerminates is used) a zero key.

The KeyIndirect, ZeroKeyTerminates, and ReturnIndex options may be used.

   binarysearch L1 L2 L3 L4 L5 L6 L7 S1

   * L1: Key
   * L2: KeySize
   * L3: Start
   * L4: StructSize
   * L5: NumStructs
   * L6: KeyOffset
   * L7: Options
   * S1: Result

An array of data structures is in memory, as above. However, the structs
must be stored in forward order of their keys (taking each key to be a
big-endian unsigned integer.) There can be no duplicate keys. NumStructs
must indicate the exact length of the array; it cannot be -1.

The KeyIndirect and ReturnIndex options may be used.

   linkedsearch L1 L2 L3 L4 L5 L6 S1

   * L1: Key
   * L2: KeySize
   * L3: Start
   * L4: KeyOffset
   * L5: NextOffset
   * L6: Options
   * S1: Result

The structures need not be consecutive; they may be anywhere in memory, in
any order. They are linked by a four-byte address field, which is found in
each struct at position NextOffset. If this field contains zero, it
indicates the end of the linked list.

The KeyIndirect and ZeroKeyTerminates options may be used.

2.17: Accelerated Functions

To improve performance, Glulx incorporates some complex functions which
replicate code in the Inform library. [[Yes, this is even more outrageously
CISC than the search opcodes.]]

Rather than allocating a new opcode for each function, Glulx offers an
expandable function acceleration system. Two functions are defined below.
The game may request that a particular address -- the address of a VM
function -- be replaced by one of the available functions. This does not
alter memory; but any subsequent call to that address might invoke the
terp's built-in version of the function, instead of the VM code at that
address.

(A "call" includes any function invocation of that address, including the
call, tailcall, and callf (etc.) opcodes. It also includes invocation via
the filter I/O system, and function nodes in the string-decoding table.
Branches to the address are *not* affected; neither are returns, throws, or
other ways the terp might reach it.)

A terp may implement any, all, or none of the functions on the list. If the
game requests an accelerated function which is not available, the request
is ignored. Therefore, the game *must* be sure that it only requests an
accelerated function at an address which actually matches the requested
function.

Some functions may require values (or addresses) which are compiled into
the game file, or otherwise stored by the game. The interpreter maintains a
table of these parameters -- whichever ones are needed by the functions it
supports. All parameters in the table are initially zero; the game may
supply values as needed.

The set of active acceleration requests, and the values in the parameter
table, are *not* part of the saved-game state.

The behavior of an accelerated function is somewhat limited. The state of
the VM during the function is not defined, so there is no way for an
accelerated function to call a normal VM function. The normal printing
mechanism (as in the streamchar opcode, etc) is not available, since that
can call VM functions via the filter I/O system. [[Not that I/O functions
are likely to be worth accelerating in any case.]]

Errors encountered during an accelerated function will be displayed to the
user by some convenient means. For example, an interpreter may send the
error message to the current Glk output stream. However, the terp may have
no recourse but to invoke a *fatal* error. (For example, if there is no
current Glk output stream.) Therefore, accelerated functions are defined
with no error conditions that must be recoverable.

These opcodes were added in Glulx version 3.1.1. Since a 3.1.1 game file
ought to run in a 3.1.0 interpreter, you *may not* use these opcodes
without first testing the Acceleration gestalt selector. If it returns
zero, your game is running on a 3.1.0 terp (or earlier), and it is your
responsibility to avoid executing these opcodes. [[Of course, the way the
opcodes are defined should ensure that skipping them does not affect the
behavior of your game.]]

   accelfunc L1 L2

Request that the VM function with address L2 be replaced by the accelerated
function whose number is L1. If L1 is zero, the acceleration for address L2
is cancelled.

If the terp does not offer accelerated function L1, this does nothing.

If you request acceleration at an address which is already accelerated, the
previous request is cancelled before the new one is considered. If you
cancel at an unaccelerated address, nothing happens.

A given accelerated function L1 may replace several VM functions (at
different addresses) at the same time. Each request is considered separate,
and must be cancelled separately.

   accelparam L1 L2

Store the value L2 in the parameter table at position L1. If the terp does
not know about parameter L1, this does nothing.

The list of accelerated functions is as follows. They are defined as if in
Inform source code. (Consider Inform's "strict" mode to be off, for the
purposes of operators such as .& and -->.) ERROR() represents code which
displays an error, as described above.

(Functions may be added to this list in future versions of the Glulx spec.
Existing functions will not be removed or altered.)


   Constant PARAM_0_classes_table = #classes_table;
   Constant PARAM_1_indiv_prop_start = INDIV_PROP_START;
   Constant PARAM_2_class_metaclass = Class;
   Constant PARAM_3_object_metaclass = Object;
   Constant PARAM_4_routine_metaclass = Routine;
   Constant PARAM_5_string_metaclass = String;
   Constant PARAM_6_self = #globals_array + WORDSIZE * #g$self;
   Constant PARAM_7_num_attr_bytes = NUM_ATTR_BYTES;
   Constant PARAM_8_cpv__start = #cpv__start;

   ! OBJ_IN_CLASS: utility function; implements "obj in Class".
   [ OBJ_IN_CLASS obj;
     return ((obj + 13 + PARAM_7_num_attr_bytes)-->0
       == PARAM_2_class_metaclass);
   ];

   ! FUNC_1_Z__Region: implements Z__Region() as of Inform 6.31.
   [ FUNC_1_Z__Region addr
     tb endmem; ! locals
     if (addr<36) rfalse;
     @getmemsize endmem;
     @jgeu addr endmem?outrange;  ! branch if addr >= endmem (unsigned)
     tb=addr->0;
     if (tb >= $E0) return 3;
     if (tb >= $C0) return 2;
     if (tb >= $70 && tb <= $7F && addr >= (0-->2)) return 1;
   .outrange;
     rfalse;
   ];

   ! FUNC_2_CP__Tab: implements CP__Tab() as of Inform 6.31.
   [ FUNC_2_CP__Tab obj id
     otab max res; ! locals
     if (FUNC_1_Z__Region(obj)~=1) {
       ERROR("[** Programming error: tried to find the ~.~ of (something)
**]");
       rfalse;
     }
     otab = obj-->4;
     if (otab == 0) return 0;
     max = otab-->0;
     otab = otab+4;
     @binarysearch id 2 otab 10 max 0 0 res;
     return res;
   ];

   ! FUNC_3_RA__Pr: implements RA__Pr() as of Inform 6.31.
   [ FUNC_3_RA__Pr obj id
     cla prop ix; ! locals
     if (id & $FFFF0000) {
       cla = PARAM_0_classes_table-->(id & $FFFF);
       if (~~FUNC_5_OC__Cl(obj, cla)) return 0;
       @ushiftr id 16 id;
       obj = cla;
     }
     prop = FUNC_2_CP__Tab(obj, id);
     if (prop==0) return 0;
     if (OBJ_IN_CLASS(obj) && cla == 0) {
       if (id < PARAM_1_indiv_prop_start
           || id >= PARAM_1_indiv_prop_start+8)
         return 0;
     }
     if (PARAM_6_self-->0 ~= obj) {
       @aloadbit prop 72 ix;
       if (ix) return 0;
     }
     return prop-->1;
   ];

   ! FUNC_4_RL__Pr: implements RL__Pr() as of Inform 6.31.
   [ FUNC_4_RL__Pr obj id
     cla prop ix; ! locals
     if (id & $FFFF0000) {
       cla = PARAM_0_classes_table-->(id & $FFFF);
       if (~~FUNC_5_OC__Cl(obj, cla)) return 0;
       @ushiftr id 16 id;
       obj = cla;
     }
     prop = FUNC_2_CP__Tab(obj, id);
     if (prop==0) return 0;
     if (OBJ_IN_CLASS(obj) && cla == 0) {
       if (id < PARAM_1_indiv_prop_start
           || id >= PARAM_1_indiv_prop_start+8)
         return 0;
     }
     if (PARAM_6_self-->0 ~= obj) {
       @aloadbit prop 72 ix;
       if (ix) return 0;
     }
     @aloads prop 1 ix;
     return WORDSIZE * ix;
   ];

   ! FUNC_5_OC__Cl: implements OC__Cl() as of Inform 6.31.
   [ FUNC_5_OC__Cl obj cla
     zr jx inlist inlistlen; ! locals
     zr = FUNC_1_Z__Region(obj);
     if (zr == 3) {
       if (cla == PARAM_5_string_metaclass) rtrue;
       rfalse;
     }
     if (zr == 2) {
       if (cla == PARAM_4_routine_metaclass) rtrue;
       rfalse;
     }
     if (zr ~= 1) rfalse;
     if (cla == PARAM_2_class_metaclass) {
       if (OBJ_IN_CLASS(obj)
         || obj == PARAM_2_class_metaclass or PARAM_5_string_metaclass
            or PARAM_4_routine_metaclass or PARAM_3_object_metaclass)
         rtrue;
       rfalse;
     }
     if (cla == PARAM_3_object_metaclass) {
       if (OBJ_IN_CLASS(obj)
         || obj == PARAM_2_class_metaclass or PARAM_5_string_metaclass
            or PARAM_4_routine_metaclass or PARAM_3_object_metaclass)
         rfalse;
       rtrue;
     }
     if (cla == PARAM_5_string_metaclass or PARAM_4_routine_metaclass)
       rfalse;
     if (~~OBJ_IN_CLASS(cla)) {
       ERROR("[** Programming error: tried to apply 'ofclass' with
non-class **]");
       rfalse;
     }
     inlist = FUNC_3_RA__Pr(obj, 2);
     if (inlist == 0) rfalse;
     inlistlen = FUNC_4_RL__Pr(obj, 2) / WORDSIZE;
     for (jx=0 : jx<inlistlen : jx++) {
       if (inlist-->jx == cla) rtrue;
     }
     rfalse;
   ];

   ! FUNC_6_RV__Pr: implements RV__Pr() as of Inform 6.31.
   [ FUNC_6_RV__Pr obj id
     addr; ! locals
     addr = FUNC_3_RA__Pr(obj, id);
     if (addr == 0) {
       if (id > 0 && id < PARAM_1_indiv_prop_start) {
         return PARAM_8_cpv__start-->id;
       }
       ERROR("[** Programming error: tried to read (something) **]");
       return 0;
     }
     return addr-->0;
   ];

   ! FUNC_7_OP__Pr: implements OP__Pr() as of Inform 6.31.
   [ FUNC_7_OP__Pr obj id
     zr; ! locals
     zr = FUNC_1_Z__Region(obj);
     if (zr == 3) {
       if (id == print or print_to_array) rtrue;
       rfalse;
     }
     if (zr == 2) {
       if (id == call) rtrue;
       rfalse;
     }
     if (zr ~= 1) rfalse;
     if (id >= PARAM_1_indiv_prop_start
         && id < PARAM_1_indiv_prop_start+8) {
       if (OBJ_IN_CLASS(obj)) rtrue;
     }
     if (FUNC_3_RA__Pr(obj, id) ~= 0)
       rtrue;
     rfalse;
   ];


2.18: Miscellaneous

   nop

Do nothing.

   gestalt L1 L2 S1

Test the Gestalt selector number L1, with optional extra argument L2, and
store the result in S1. If the selector is not known, store zero.

The reasoning behind the design of a Gestalt system is, I hope, too obvious
to explain.

[[This list of Gestalt selectors has nothing to do with the list in the Glk
library.]]

The list of L1 selectors is as follows. Note that if a selector does not
mention L2, you should always set that argument to zero. [[This will ensure
future compatibility, in case the selector definition is extended.]]

   * GlulxVersion (0): Returns the version of the Glulx spec which the
interpreter implements. The upper 16 bits of the value contain a major
version number; the next 8 bits contain a minor version number; and the
lowest 8 bits contain an even more minor version number, if any. This
specification is version 3.1.2, so a terp implementing it would return
0x00030102. I will try to maintain the convention that minor version
changes are backwards compatible, and subminor version changes are
backwards and forwards compatible.
   * TerpVersion (1): Returns the version of the interpreter. The format
is the same as the GlulxVersion. [[Each interpreter has its own version
numbering system, defined by its author, so this information is not
terribly useful. But it is convenient for the game to be able to display
it, in case the player is capturing version information for a bug report.]]
   * ResizeMem (2): Returns 1 if the terp has the potential to resize the
memory map, with the setmemsize opcode. If this returns 0, setmemsize will
always fail. [[But remember that setmemsize might fail in any case.]]
   * Undo (3): Returns 1 if the terp has the potential to undo. If this
returns 0, saveundo and restoreundo will always fail.
   * IOSystem (4): Returns 1 if the terp supports the I/O system given in
L2. (The constants are the same as for the setiosys opcode: 0 for null, 1
for filter, 2 for Glk, 20 for FyreVM. 0 and 1 will always succeed.)
   * Unicode (5): Returns 1 if the terp supports Unicode operations. These
are: the E2 Unicode string type; the 04 and 05 string node types (in
compressed strings); the streamunichar opcode; the type-14 call stub. If
the Unicode selector returns 0, encountering any of these will cause a
fatal interpreter error.
   * MemCopy (6): Returns 1 if the interpreter supports the mzero and
mcopy opcodes. (This must true for any terp supporting Glulx 3.1.)
   * MAlloc (7): Returns 1 if the interpreter supports the malloc and
mfree opcodes. (If this is true, MemCopy and ResizeMem must also both be
true, so there is no need to check all three.)
   * MAllocHeap (8): Returns the start address of the heap. This is the
value that getmemsize had when the first memory block was allocated. If the
heap is not active (no blocks are extant), this returns zero.
   * Acceleration (9): Returns 1 if the interpreter supports the accelfunc
and accelparam opcodes. (This must true for any terp supporting Glulx
3.1.1.)
   * AccelFunc (10): Returns 1 if the terp implements the accelerated
function given in L2.
   * Float (11): Returns 1 if the interpreter supports the floating-point
arithmetic opcodes.

Selectors 0x1000 to 0x10FF are reserved for use by FyreVM. Selectors 0x1100
to 0x11FF are reserved for extension projects by Dannii Willis. These are
not documented here. See section 0.2, "Glulx and Other IF Systems".

[[The Unicode selector is slightly redundant. Since the Unicode operations
exist in Glulx spec 3.0 and higher, you can get the same information by
testing GlulxVersion against 0x00030000. However, it's clearer to have a
separate selector. Similarly, the MemCopy selector is true exactly when
GlulxVersion is 0x00030100 or higher.]]

[[The Unicode selector does *not* guarantee that your Glk library supports
Unicode. For that, you must check the Glk gestalt selector gestalt_Unicode.
If the Glk library is non-Unicode, the Glulx Unicode operations are still
legal; however, Unicode characters (beyond FF) will be printed as 3F
("?").]]

   debugtrap L1

Interrupt execution to do something interpreter-specific with L1. If the
interpreter has nothing in mind, it should halt with a visible error
message.

[[This is intended for use by debugging interpreters. The program might be
sprinkled with consistency tests, set to call debugtrap if an assertion
failed. The interpreter could then be set to halt, display a warning, or
ignore the debugtrap.]]

This should *not* be used as an arbitrary interpreter trap-door in a
finished (non-debugging) program. If you really want to add interpreter
functionality to your program, and you're willing to support an alternate
interpreter to run it, you should add an entirely new opcode. There are
still 2^28 of them available, give or take.

   glk L1 L2 S1

Call the Glk API function whose identifier is L1, passing in L2 arguments.
The return value is stored at S1. (If the Glk function has no return value,
zero is stored at S1.)

The arguments are passed on the stack, last argument pushed first, just as
for the call opcode.

Arguments should be represented in the obvious way. Integers and character
are passed as integers. Glk opaque objects are passed as integer
identifiers, with zero representing NULL. Strings and Unicode strings are
passed as the addresses of Glulx string objects (see section 1.6.1,
"Strings".) References to values are passed by their addresses. Arrays are
passed by their addresses; note that an array argument, unlike a string
argument, is always followed by an array length argument.

Reference arguments require more explanation. A reference to an integer or
opaque object is the address of a 32-bit value (which, being in main
memory, does not have to be aligned, but must be big-endian.)
Alternatively, the value -1 (FFFFFFFF) may be passed; this is a special
case, which means that the value is read from or written to the stack.
Arguments are always evaluated left to right, which means that input
arguments are popped from the stack first-topmost, but output arguments are
pushed on last-topmost.

A reference to a Glk structure is the address of an array of 32-bit values
in main memory. Again, -1 means that all the values are written to the
stack. Also again, an input structure is popped off first-topmost, and an
output structure is pushed on last-topmost.

All stack input references (-1 addresses) are popped after the Glk argument
list is popped. [[This should be obvious, since the -1 occurs *in* the Glk
argument list.]] Stack output references are pushed after the Glk call, but
before the S1 result value is stored.

[[The difference between strings and character arrays is somewhat
confusing. These are the same type in the C Glk API, but different in
Glulx. Calls such as glk_put_buffer() and glk_request_line_event() take
character arrays; this is the address of a byte array containing character
values, followed by an integer array length. The byte array itself has
neither a length field or a terminator. In contrast, calls such as
glk_put_string() and glk_fileref_create_by_name() take string arguments,
which must be unencoded Glulx string objects. An unencoded Glulx string
object is nearly a byte array, but not quite; it has an E0 byte at the
beginning and a zero byte at the end. Similarly, calls such as
glk_put_string_uni() take unencoded (E2) Unicode objects.]]

[[Previous versions of this spec said that string arguments could be
unencoded *or encoded* string objects. This use of encoded strings has
never been supported, however, and it is withdrawn from the spec.]]

[[The convention that "address" -1 refers to the stack is a feature of the
Glk invocation mechanism; it applies only to Glk arguments. It is *not*
part of the general Glulx definition. When instruction operands are being
evaluated, -1 has no special meaning. This includes the L1, L2, and S1
arguments of the glk opcode.]]

2.19: Assembly Language

The format used by Inform is acceptable for now:


   @opcode [ op op op ... ] ;


Where each "op" is a constant, the name of a local variable, the name of a
global variable, or "sp" (for stack push/pop modes).

[[It would be convenient to have a one-line form for the opcodes that pass
arguments on the stack (call and glk).]]

To make life a little easier for cross-platform I6 code, Inform accepts the
macro "@push val" for "@copy val sp", and "@pull val" for "@copy sp val".
Supporting these forms is recommended.

You can synthesize opcodes that the compiler does not know about:


   @"FlagsCount:Code" [ op op op ... ] ;


The optional Flags can include "S" if the last operand is a store; "SS" if
the last two operands are stores; "B" for branch format; "R" if execution
never continues after the opcode. The Count is the number of arguments (0
to 9). The Code is a decimal integer representing the opcode number. So
these two lines generate the same code:


   @add x 1 y;
   @"S3:16" x 1 y;


..because the @add opcode has number 16 (decimal), and has format "@add L1
L2 S1".

You are viewing proxied material from gopher.661.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.