diff --git a/docs/aam-specification-1.0.adoc b/docs/aam-specification-1.0.adoc index 2b9443a..609dc6c 100644 --- a/docs/aam-specification-1.0.adoc +++ b/docs/aam-specification-1.0.adoc @@ -55,7 +55,7 @@ The notation `a..b` means the range of integers from a to b, inclusive. The notation `a-b` means the range of characters from a to b, inclusive. -In the following description, `BYTE` always means eight bits, `SHORT` +`BYTE` always means eight bits, `SHORT` always means 16 bits (two bytes), and `LONG` always means 32 bits (four bytes). `WORD` means either `SHORT` or `LONG`, depending on the word size specified in <>. @@ -68,7 +68,7 @@ The notation: Means that the "whatsit data" appears "number of whatsits" times in sequence. Throughout this document, numbers used to count things (like "16 bits" or -"`WORD[64]`") are decimal (base 10), while numbers used as values (like "80" or +"``WORD[64]``") are decimal (base 10), while numbers used as values (like "80" or "7fff") are hexadecimal (base 16). In ambiguous cases, hexadecimal numbers are marked with a `$` symbol. In pseudocode, hexadecimal numbers start with `0x`; all other numbers are decimal. @@ -111,7 +111,7 @@ with flag numbers. * ``8000..9fff`` Indirect reference (word index into heap) * ``a000..bfff`` reserved * ``c000..dffe`` Pair (word index into heap) -* ``e000..fffe`` Dict word, extended (word index into heap) +* ``e000..fffe`` Extended dict word (word index into heap) Live values only exist in registers or on the heap, and can be invalidated when the heap shrinks. @@ -134,7 +134,7 @@ of upper bits of the word, as follows (v is the value): The tag `001vvvvv vvvvvvvv` may also be referred to as a "dict" to avoid ambiguity with the other meaning of -"word" (a two-byte or four-byte value). +"word" (any two-byte value). A pair is a pointer to a two-word cell on the heap. The first word of that cell is the head of the list (can be @@ -232,7 +232,7 @@ free to work with a different internal representation at runtime. ==== Special-purpose registers -**Byte pointers into <> chunk: +**Byte pointers into <> chunk:** * `LONG`: `INST`, Instruction pointer * `LONG`: `CONT`, Continuation pointer @@ -247,7 +247,7 @@ free to work with a different internal representation at runtime. **Word pointers into aux heap:** * `WORD`: `AUX`, aux stack pointer (grows upwards) -* `WORD`: `TRL`, trl stack pointer (grows downwards) +* `WORD`: `TRL`, trail stack pointer (grows downwards) * `WORD`: `STA`, stoppable aux pointer * `WORD`: `STC`, stoppable choice pointer @@ -270,7 +270,7 @@ Values for SPC: * `WORD[64]`: R00-R3f, general registers (args, temps, constants, globals) -R3f is also known as IDX and is treated specially by certain instructions. +R3f is also known as `IDX` and is treated specially by certain instructions. This is how dialogc uses these 64 registers: @@ -278,6 +278,7 @@ This is how dialogc uses these 64 registers: * ``R0d..R3c`` Temporary values * ``R3d     `` Quick temporary register (always available) * ``R3e     `` Constant `[]` (3f00) +* ``R3f `` Only used as `IDX` Since registers take only one byte to encode and a large immediate value takes two, storing frequently-needed constants in @@ -287,12 +288,12 @@ With a few exceptions, all of the registers (special-purpose and general-purpose) are initialized to zero when the virtual machine starts or restarts. The exceptions are: -* `INST = 1` -* `ENV = <>.heapsz` -* `CHO = <>.heapsz` -* `TRL = <>.auxsz` -* `SIM = ffff` -* `SPC = line` +* `INST` = 1 +* `ENV` = <>.heapsz +* `CHO` = <>.heapsz +* `TRL` = <>.auxsz +* `SIM` = ffff +* `SPC` = line In case of a runtime error, the machine is restarted with R00 initialized to a tagged integer according to the following table: @@ -314,7 +315,7 @@ Error code 5 is not used by the Å-machine. ==== Initialized registers The main chunk of saved data follows. The game state must conform to -this format during restart, save and restore operations (including the +this format during restart, save, and restore operations (including the big-endian byte ordering). * `WORD`: `NOB`, Number of objects @@ -327,7 +328,7 @@ This memory is word-addressable, and it may contain pointers in the form of word offsets into itself. * `WORD`: Word offset of global data -* `WORD[<>]`: Word offset of per-object data +* `WORD[<>]`: Word offsets of per-object data * `WORD[<>.ramsz - <> - 1]`: Data The word offset of a data field is given by the following @@ -471,8 +472,8 @@ chunks. <> must be the first chunk inside the form. In the following table * <> (*): Character set, bitstream decoder, word endings * <> (*): Style sheet * <> (*): Word-to-object maps -* <> (optional): Story metadata -* <> (optional): Internal object names +* <> (optional): Story metadata +* <> (optional): Internal object names * <>: Table of resources * <> (*): Compressed text @@ -485,13 +486,13 @@ address space. === HEAD * `BYTE[2]`: "version", File format version (major, minor) -* `BYTE`: "wordsz", Word size (currently always 2) -* `BYTE`: "shift", Shift amount for short/long string pointers +* `BYTE`: "wordsz", Word size in bytes (currently always 2) +* `BYTE`: "shift", Shift amount for short/long <> * `SHORT`: "release", Story release number * `BYTE[6]`: "serial", Story serial number (ASCII) -* `LONG`: "crc", Running CRC-32 of the contents of <>, <>, <>, <>, <>, <>, and <>, in that specific order +* `LONG`: "crc", Running CRC-32 of the contents of <>, <>, <>, <>, <>, <>, and <>, in that specific order * `WORD`: "heapsz", Size (in words) of heap/env/choice area * `WORD`: "auxsz", Size (in words) of aux/trail area @@ -720,7 +721,7 @@ instruction. Operand types (always big-endian byte ordering): -[[0,0]] +[[ZERO,0]] **0**: implicit constant zero, not encoded [[BYTE,BYTE]] @@ -772,7 +773,7 @@ Operand types (always big-endian byte ordering): * `10xxxxxx`: Index 80..bf * `11xxxxxx xxxxxxxx`: Index 0000..3fff -[[CODE]] +[[CODE,CODE]] *CODE*: byte address in <> chunk * `00000000`: Absolute address 0 (known to contain the <> opcode) @@ -835,14 +836,14 @@ Opcode Mnemonic Args Version 87 <> {empty} {empty} {empty} {empty} {empty} {empty} -08/88 <> <>/<<0>> {empty} +08/88 <> <>/<> {empty} 09 <> {empty} {empty} 89 <> {empty} {empty} {empty} {empty} {empty} {empty} -0a/8a <> <>/<<0>> <> {empty} -0b/8b <> <>/<<0>> {empty} -0c/8c <> <>/<<0>> <> {empty} +0a/8a <> <>/<> <> {empty} +0b/8b <> <>/<> {empty} +0c/8c <> <>/<> <> {empty} {empty} {empty} {empty} {empty} 0d <> {empty} {empty} @@ -862,7 +863,7 @@ Opcode Mnemonic Args Version {empty} {empty} {empty} {empty} 14 <> <> {empty} -94 <> <<0>> ≥ 0.5 +94 <> <> ≥ 0.5 15/95 <> <>/<> {empty} 16 AUX_POP_VAL <> < 1.0 17 <> <> {empty} @@ -882,28 +883,28 @@ Opcode Mnemonic Args Version 9f <> <> <> ≥ 0.4 {empty} {empty} {empty} {empty} -20/a0 <> <>/<<0>> <> <> {empty} -21/a1 <> <>/<<0>> <> <> {empty} -22/a2 <> <>/<<0>> <> <> {empty} +20/a0 <> <>/<> <> <> {empty} +21/a1 <> <>/<> <> <> {empty} +22/a2 <> <>/<> <> <> {empty} {empty} {empty} {empty} {empty} -24/a4 <> <>/<<0>> <> <> {empty} -25/a5 <> <>/<<0>> <> <> {empty} -26/a6 <> <>/<<0>> <> <> {empty} +24/a4 <> <>/<> <> <> {empty} +25/a5 <> <>/<> <> <> {empty} +26/a6 <> <>/<> <> <> {empty} {empty} {empty} {empty} {empty} -28/a8 <> <>/<<0>> <> {empty} -29/a9 <> <>/<<0>> <> {empty} +28/a8 <> <>/<> <> {empty} +29/a9 <> <>/<> <> {empty} {empty} {empty} {empty} {empty} -2d/ad <> <>/<<0>> <> <> <> {empty} +2d/ad <> <>/<> <> <> <> {empty} {empty} {empty} {empty} {empty} 2e/ae <> <>/<> <> {empty} 2f/af <> <>/<> <> {empty} {empty} {empty} {empty} {empty} -30/b0 <> <>/<<0>> <> <> {empty} +30/b0 <> <>/<> <> <> {empty} 31 <> <> <> {empty} 32 <> <> <> {empty} 33 <> <> <> {empty} @@ -914,13 +915,13 @@ b6 <> <> <> ≥ 0.4 37 <> <> <> <> {empty} 38 <> <> <> <> {empty} 39/b9 <> <>/<> <> <> {empty} -3a/ba <> <>/<<0>> <> <> <> {empty} -3b/bb <> <>/<<0>> <> <> {empty} +3a/ba <> <>/<> <> <> <> {empty} +3b/bb <> <>/<> <> <> {empty} 3c <> <> {empty} -3d/bd <> <>/<<0>> <> <> <> ≥ 0.4 +3d/bd <> <>/<> <> <> <> ≥ 0.4 {empty} {empty} {empty} {empty} -40/c0 <> <>/<<0>> <> <> {empty} +40/c0 <> <>/<> <> <> {empty} 41 <> <> <> {empty} 42 <> <> <> {empty} 43 <> <> <> {empty} @@ -931,10 +932,10 @@ c6 <> <> <> ≥ 0.4 47 <> <> <> <> {empty} 48 <> <> <> <> {empty} 49/c9 <> <>/<> <> <> {empty} -4a/ca <> <>/<<0>> <> <> <> {empty} -4b/cb <> <>/<<0>> <> <> {empty} +4a/ca <> <>/<> <> <> <> {empty} +4b/cb <> <>/<> <> <> {empty} 4c <> <> {empty} -4d/cd <> <>/<<0>> <> <> <> ≥ 0.4 +4d/cd <> <>/<> <> <> <> ≥ 0.4 {empty} {empty} {empty} {empty} 50 <> <> <> <> {empty} @@ -976,7 +977,7 @@ e3 <> {empty} {empty} e6 <> {empty} {empty} {empty} {empty} {empty} {empty} -67 <> <<0>> <> < 1.0 +67 <> <> <> < 1.0 e7 <> {empty} < 1.0 {empty} {empty} {empty} {empty}