Changed BRZ behavior to chomp a test word from stack instead of checking PSW_Z bit.

[ned1] / docs / architecture_manual.md

NED - Architecture Manual
=========================

Overview
--------

* Stack based
* Twos-complement
* Big-endian
* Simplicity above all else. See what we can achieve with minimal hardware
  that's as fast as we can make it. Essentially, let the compiler target the
  'microcode' level.
* Explicitly no kernel/user mode.
* Explicitly no MMU, just a flat, shared memory space. Think threads, not
  processes.

Version: 2

Instruction Word Formats
------------------------

All instruction words in NED are 32-bits long and fall into one of three
possible formats.

    +---------+-----+-----+--------+--------+--------+--------+--------+
    |  Format |  31 |  30 | 29..24 | 23..18 | 17..12 |  11..6 |  5..0  |
    +---------+-----+-----+--------+--------+--------+--------+--------+
    |    A    |  1  |                  31-bit Immediate                |
    +---------+-----+-----+--------------------------------------------+
    |    B    |  0  |  1  |               Unassigned                   |
    +---------+-----+-----+--------+--------+--------+--------+--------+
    |    C    |  0  |  0  | Syl. 1 | Syl. 2 | Syl. 3 | Syl. 4 | Syl. 5 |
    +---------+-----+-----+--------+--------+--------+--------+--------+

Format A contains a 31-bit field which is placed on the stack after shifting
left one position and padding with a zero. For example, the instruction

    11000000 01000000 01000000 01000000

will place the value

    10000000 10000000 10000000 10000000 

on the TOS.

Format B is reserved for future instructions.

Format C packs five syllables per instruction word, executed in order from 1 to 5.
Syllables are defined as follows.

|  Bits  |  Name  |  Description                                               |
| ------ | ------ | ---------------------------------------------------------- |
| 1xxxxx | IM_x   | Push a 5-bit immediate to TOS.                             |
| 011xxx | LDSP+x | Copy the value stored at TOS+x and push to TOS.            |
| 010xxx | STSP+x | Pop from TOS and overwrite value at TOS+x.                 |
| 001000 | AND    | Logical AND of TOS and NOS, pushed to TOS.                 |
| 001001 | OR     | Logical OR of TOS and NOS, pushed to TOS.                  |
| 001010 | NOT    | Logical NOT of TOS, pushed to TOS.                         |
| 001011 | XOR    | Logical XOR of TOS and NOS, pushed to TOS.                 |
| 001100 | ADD    | Signed, twos-complement addition. TOS <- TOS + NOS         |
| 001101 | SWAP   | Swap TOS and NOS.                                          |
| 001110 | JMP    | Pop TOS and set PC to popped value.                        |
| 001111 | MVSTCK | Pop the TOS and context switch to that state ID.           |
| 000100 | SHIFT  | Pop TOS & NOS. Shift NOS by TOS bits to the left/right.    |
| 000101 | CMPSWP | Compare-and-swap with ptr, old_val & new_val on stack.     |
| 000110 | TEST   | Pop TOS and set PSW according to value.                    |
| 000111 | BRZ    | Pop TOS & NOS. If NOS==0, then set PC to TOS value.        |
| 000010 | LOAD   | Pop address from TOS, dereference and store to TOS.        |
| 000011 | STORE  | Pop address from TOS, pop data from NOS, deref and store.  |
| 000001 | NOP    | Do nothing.                                                |
| 000000 | HALT   | Halt the CPU.                                              |

The Instruction Reference contains a more complete description of these operations.

Processor State
---------------

The Processor Status Word (PSW) contains *N*egative and *Z*ero flags in the
following bit positions.  See the Instruction Reference for details on which
operations set these flags.

    +-------+------------+-----+-----+
    |  Bits |    31..2   |  1  |  0  |
    +-------+------------+-----+-----+
    | Flags | Unassigned |  N  |  Z  |
    +-------+------------+-----+-----+

In addition to a traditional Program Counter (PC), the processor also includes
a Syllable Counter (SC) which ranges from 0 to 4. Both the PC and SC point to
the next instruction to be executed. Thus, when executing the middle syllable
of a word located at address 0x200, the PC is 0x204 and the SC is 3.

Since the CPU is stack based, it includes a Stack Pointer (SP).

Memory Map
----------

The address space is laid out with memory mapped I/O below 512 MB and RAM above.

    4 GB
    |-------- Data
    512 MB
    |-------- I/O (general purpose)
    128 MB
    |-------- I/O (reserved for processors in 16 MB chucks x 8 CPUs)
    0 Mb

Temporarily, there are four read-only registers accessible in the lowest four
words of memory. Writes to these registers are ignored.

| Address |       Name        |  Description                    |
| ------- | ----------------- | ------------------------------- |
|     0x0 | Zero Register     | Constant 0x0                    |
|     0x4 | Negative Register | Constant 0x80000000             |
|     0x8 | PC Register       | PC of currently active thread.  |
|     0xC | PSW Register      | PSW of currently active thread. |

Also temporarily, a UART-like peripheral is present with the following registers.

|  Address  |     Name        |  Description                                    |
| --------- | --------------- | ----------------------------------------------- |
| 0x8000000 | Transmit Buffer | Accepts one byte and transmits to stdout.       |
| 0x8000004 | Transmit Status | Bit 0 is set when UART is ready to send a byte. |
| 0x8000008 | Receive Buffer  | Contains one byte from stdin.                   |
| 0x800000C | Receive Status  | Bit 0 is set when a byte is ready to be read.   |