pali/README.md

# Overview

The pali assembler is used to create images for the ilo virtual
computer. It use the literate [unu format](http://unu.retroforth.org),
with the assembly code in dedicated code blocks, and commentary
outside these blocks.

Code blocks start and end with a ~~~ sequence. They contain a
series of lines, each of which consists of a single character
directive, a space, and any parameters the directive requires.

The directives are:

~~~
+---+----------------------------------------------------------+
| i | process parameter as instruction bundle                  |
| o | set origin/offset in memory space                        |
| * | reserve parameter cells of data in memory                |
| r | parameter is a named item, assemble a pointer to it      |
| R | parameter is a named immediate item, assemble a pointer  |
|   | to it                                                    |
| - | alias for `r`                                            |
| d | parameter is a decimal value, assemble it inline         |
| c | parameter is a comment to be ignored                     |
| : | parameter is a label name                                |
| s | parameter is a string, assemble as length prefixed       |
| z | parameter is a string, assemble as null-terminated       |
+---+----------------------------------------------------------+
~~~

The pali assembler is a two pass design. The first pass will
scan through the code, recording any labels and their offsets
in the image. The second pass actually assembles the data,
instructions, and resolves any references to labels.

# The ilo Instruction Set

ilo has 30 instructions. In short, these are:

~~~
+----+----+--------+-------------------------------------------+
| Op | Nm |  Stack | Description                               |
+====+====+========+===========================================+
| 00 | .. |    -   | non-op                                    |
| 01 | li |    -n  | push value in following cell to stack     |
| 02 | du |   n-nn | duplicate top stack item                  |
| 03 | dr |   n-   | discard top stack item                    |
| 04 | sw |  ab-ba | swap top two stack items                  |
| 05 | pu |   n-   | move top stack item to address stack      |
| 06 | po |    -n  | move top address stack item to data stack |
| 07 | ju |   a-   | jump to an address                        |
| 08 | ca |   a-   | call a function                           |
| 09 | cc |  fa-   | call a function if the flag is non-zero   |
| 10 | cj |  fa-   | jump to a function if the flag is non-zero|
| 11 | re |    -   | return from a call or conditional call    |
| 12 | eq |  ab-f  | compare two values for equality.   a == b |
| 13 | ne |  ab-f  | compare two values for inequality. a != b |
| 14 | lt |  ab-f  | compare two values for less than.  a < b  |
| 15 | gt |  ab-f  | compare two values for greater than. a > b|
| 16 | fe |   a-n  | fetch a stored value in memory            |
| 17 | st |  na-   | store a value into memory                 |
| 18 | ad |  ab-c  | add two numbers. a + b                    |
| 19 | su |  ab-c  | subtract two numbers. a - b               |
| 20 | mu |  ab-c  | multiply two numbers. a * b               |
| 21 | di |  ab-cd | divide and get remainder. a % b, a / b    |
| 22 | an |  ab-c  | bitwise and                               |
| 23 | or |  ab-c  | bitwise or                                |
| 24 | xo |  ab-c  | bitwise xor                               |
| 25 | sl |  ab-c  | shift left. a << b                        |
| 26 | sr |  ab-c  | shift right. a >> b                       |
| 27 | cp | sdn-f  | compare two memory regions                |
| 28 | cy | sdn-   | copy memory                               |
| 29 | io |   n-   | perform i/o operation                     |
+----+----+--------+-------------------------------------------+
~~~

A condensed summary table:

~~~
  Opode  Instruction Names  Data Stack Effects
  =====  =================  ====================================
  00-05  .. li du dr sw pu  -     -n    n-nn   n-    nm-mn  n-
  06-11  po ju ca cc cj re  -n    a-    a-     fa-   fa-    -
  12-17  eq ne lt gt fe st  nn-f  nn-f  nn-f   nn-f  a-n    na-
  18-23  ad su mu di an or  nn-n  nn-n  nn-n   nn-nn nn-n   nn-n
  24-29  xo sl sr cp cy io  nn-n  nn-n  nn-n   nnn-  nnn-   n-
  =====  =================  ====================================
~~~

ilo expects four instructions to be packed into a single memory
location. These are processed in order. Instructions that modify
the instruction pointer (other than `li`) can not be followed by
anything other than a non-op to avoid unpredictable behavior.

Instructions are unpacked from right to left.