DCPU-32 Documentation

--------------------------------------------------------------------------------
DCPU-32 Specification
Copyright 1989 Maraver
Version 1.0


=== SUMMARY =====================================================================

* 16-bit words, 32-bit dwords
* 0x10000 dwords of ram

When working with the DCPU-32, a words is always a 16-bit unsigned number and a
dword is always a signed (two's-complement) 32-bit number.

In this table T is the type of regiser, either D for data or A for address. All
data registers are dwords, and all adress registers are words. NAME(S) is the
mnemonic of the register, or registers, avaliable of that type and description.
DESCRIPTION is a short text that describes either the type of data, or use of the
address, depending on the register type.

--- Registers (16/32 bits) ------------------------------------------------------
 T | NAME(S)      | DESCRIPTION
---+--------------+--------------------------------------------------------------
 D | A, B, C, X,  | integer registers
 D |  Y, Z, I, J  |
 D | FA, FB, FC   | floating-point registers
 A | PC           | program counter
 A | SP           | stack pointer
 A | IA           | interrupt address
---+--------------+--------------------------------------------------------------

In this document, anything within [brackets] is shorthand for "the value of the
RAM at the location of the value inside the brackets". For example, SP means
stack pointer, but [SP] means the value of the RAM at the location the stack
pointer is pointing at.

Whenever the CPU needs to read a word, it reads [PC], then increases PC by one.
Shorthand for this is [PC++]. In some cases, the CPU will modify a value before
reading it, in this case the shorthand is [++PC].

The DCPU-32 is intended to be backwards compatiable with the DCPU-16 inorder
to make the migration between the systems as easy as possible. However, for
security and additional protection from accidental harm, it is recommended
that all DCPU-32 applications use big endian wherever possible.


=== INSTRUCTIONS ================================================================

Instructions are 1-3 words long and are fully defined by the first word.
In a basic instruction, the lower eight bits of the first word of the instruction
are the opcode, the next sixteen bits are shared between the a and b values. The
remaining eight bits are reserved for future expansion. The b value is always
handled by the processor after a, and is the lower eight bits.
In bits (in LSB-0 format), a basic instruction has the format:
RRRRRRRRaaaaaaaabbbbbbbboooooooo

In the tables below, C is the time required in cycles to look up the value, or
perform the opcode, VALUE is the numerical value, NAME is the mnemonic, and
DESCRIPTION is a short text that describes the opcode or value.


--- Values: (5/6 bits) ----------------------------------------------------------
 C | VALUE     | DESCRIPTION
---+-----------+-----------------------------------------------------------------
 0 | 0x00-0x07 | register (A, B, C, X, Y, Z, I or J, in that order)
 0 | 0x08-0x0f | [register]
 1 | 0x10-0x17 | [register + next word]
 0 |      0x18 | (PUSH / [--SP]) if in b, or (POP / [SP++]) if in a
 0 |      0x19 | [SP] / PEEK
 1 |      0x1a | [SP + next word] / PICK n
 0 |      0x1b | SP
 0 |      0x1c | PC
 0 |      0x1d | EX
 1 |      0x1e | [next word]
 1 |      0x1f | next word (literal)
 0 | 0x20-0x22 | float register (FA, FB, or FC, in that order)
 0 | 0x23-0xff | literal value -0x6e..0x6e (-110..110) (literal) (only for a)
 --+-----------+-----------------------------------------------------------------

* Attempting to access a location in ram with a value past 0xffff, which includes
  all negative numbers, may cause unexpected results due to the value being masked
  Example: 80000 is 14464 after being masked (80000 & 0xffff).

* "next word" means "[PC++] & 0xffff". This increases the dword length of the
  instruction by 1, but returns a word value.

* By using 0x18, 0x19, 0x1a as PEEK, POP/PUSH, and PICK there's a reverse stack
  starting at memory location 0xffff. Example: "SET PUSH, 10", "SET X, POP"

* Attempting to write to a literal value fails silently


--- Basic opcodes (5 bits) -----------------------------------------------------
 C | VAL  | NAME     | DESCRIPTION
---+------+----------+----------------------------------------------------------
 - | 0x00 | n/a      | special instruction - see below
 1 | 0x01 | SET b, a | sets b to a
 2 | 0x02 | ADD b, a | sets b to b+a, sets EX to 0x0001 if there's an overflow,
   |      |          | 0x0 otherwise
 2 | 0x03 | SUB b, a | sets b to b-a, sets EX to 0xffff if there's an underflow,
   |      |          | 0x0 otherwise
 2 | 0x04 | MUL b, a | sets b to b*a, sets EX to ((b*a)&gt;&gt;16)&amp;0xffff
 2 | 0x05 | MLI b, a | compatibility alias for MUL, as all values are signed
 3 | 0x06 | DIV b, a | sets b to b/a, sets EX to ((b&lt;&lt;16)/a)&amp;0xffff. if a==0,
   |      |          | sets b and EX to 0 instead. Rounds towards 0
 3 | 0x07 | DVI b, a | compatibility alias for DIV (always signed)
 3 | 0x08 | MOD b, a | sets b to b%a. if a==0, sets b to 0 instead.
 3 | 0x09 | MDI b, a | compatibility alias for MOD (always signed; MOD -7, 16 == -7)
 1 | 0x0a | AND b, a | sets b to b&amp;a
 1 | 0x0b | BOR b, a | sets b to b|a
 1 | 0x0c | XOR b, a | sets b to b^a
 1 | 0x0d | SHR b, a | sets b to b&gt;&gt;&gt;a, sets EX to ((b&lt;&lt;16)&gt;&gt;a)&amp;0xffff
   |      |          | (logical shift)
 1 | 0x0e | ASR b, a | sets b to b&gt;&gt;a, sets EX to ((b&lt;&lt;16)&gt;&gt;&gt;a)&amp;0xffff
   |      |          | (arithmetic shift) (treats b as signed)
 1 | 0x0f | SHL b, a | sets b to b&lt;&lt;a, sets EX to ((b&lt;&lt;a)&gt;&gt;16)&amp;0xffff
 2+| 0x10 | IFB b, a | performs next instruction only if (b&amp;a)!=0
 2+| 0x11 | IFC b, a | performs next instruction only if (b&amp;a)==0
 2+| 0x12 | IFE b, a | performs next instruction only if b==a
 2+| 0x13 | IFN b, a | performs next instruction only if b!=a
 2+| 0x14 | IFG b, a | performs next instruction only if b&gt;a
 2+| 0x15 | IFA b, a | performs next instruction only if b&gt;a (signed)
 2+| 0x16 | IFL b, a | performs next instruction only if b&lt;a
 2+| 0x17 | IFU b, a | performs next instruction only if b&lt;a (signed)
 - | 0x18 | -        |
 - | 0x19 | -        |
 3 | 0x1a | ADX b, a | sets b to b+a+EX, sets EX to 0x1 if there is an over-
   |      |          | flow, -0x1 if there is an underflow, 0x0 otherwise
 3 | 0x1b | SBX b, a | sets b to b-a+EX, sets EX to 0x1 if there is an over-
   |      |          | flow, -0x1 if there is an underflow, 0x0 otherwise
 - | 0x1c | -        |
 - | 0x1d | -        |
 2 | 0x1e | STI b, a | sets b to a, then increases I and J by 1
 2 | 0x1f | STD b, a | sets b to a, then decreases I and J by 1
---+------+----------+-----------------------------------------------------------

* The conditional opcodes take one cycle longer to perform if the test fails.
  When they skip a conditional instruction, they will skip an additional
  instruction at the cost of one extra cycle. This continues until a non-
  conditional instruction has been skipped. This lets you easily chain
  conditionals. Interrupts are not triggered while the DCPU-16 is skipping.

* How the result of an operation is stored in determined by the data type of b.
  If b is a float the value is stored as a float, otherwise it is converted to
  an integer by rounding towards 0.

* All values are treated as signed dwords when doing operations. For compatibility
  unsigned DCPU-16 operators are included as aliases for the signed operation.


Special opcodes always have their lower eight bits unset, have one value and an
eight bit opcode. In binary, they have the format:
aaaaaaaaoooooooo00000000
The value (a) is in the same eight bit format as defined earlier.

--- Special opcodes: (5 bits) --------------------------------------------------
 C | VAL  | NAME  | DESCRIPTION
---+------+-------+-------------------------------------------------------------
 - | 0x00 | n/a   | reserved for future expansion
 3 | 0x01 | JSR a | pushes the address of the next instruction to the stack,
   |      |       | then sets PC to a
 - | 0x02 | -     |
 - | 0x03 | -     |
 - | 0x04 | -     |
 - | 0x05 | -     |
 - | 0x06 | -     |
 - | 0x07 | -     |
 4 | 0x08 | INT a | triggers a software interrupt with message a
 1 | 0x09 | IAG a | sets a to IA
 1 | 0x0a | IAS a | sets IA to a
 3 | 0x0b | RFI a | disables interrupt queueing, pops A from the stack, then
   |      |       | pops PC from the stack
 2 | 0x0c | IAQ a | if a is nonzero, interrupts will be added to the queue
   |      |       | instead of triggered. if a is zero, interrupts will be
   |      |       | triggered as normal again
 - | 0x0d | -     |
 - | 0x0e | -     |
 - | 0x0f | -     |
 2 | 0x10 | HWN a | sets a to number of connected hardware devices
 4 | 0x11 | HWQ a | sets A, B, and C registers to information about hardware a
   |      |       | A is a 32 bit word identifying the hardware id
   |      |       | B is a 32 bit word identifying the manufacturer
   |      |       | the lowest 16 bits of C is the hardware version
 4+| 0x12 | HWI a | sends an interrupt to hardware a
 - | 0x13 | -     |
 - | 0x14 | -     |
 - | 0x15 | -     |
 - | 0x16 | -     |
 - | 0x17 | -     |
 - | 0x18 | -     |
 - | 0x19 | -     |
 - | 0x1a | -     |
 - | 0x1b | -     |
 - | 0x1c | -     |
 - | 0x1d | -     |
 - | 0x1e | -     |
 - | 0x1f | -     |
---+------+-------+-------------------------------------------------------------


=== INTERRUPTS =================================================================

The DCPU-32 will perform at most one interrupt between each instruction. If
multiple interrupts are triggered at the same time, they are added to a queue.
If the queue grows longer than 256 interrupts, the DCPU-32 will catch fire.

When IA is set to something other than 0, interrupts triggered on the DCPU-32
will turn on interrupt queueing, push PC to the stack, followed by pushing A to
the stack, then set the PC to IA, and A to the interrupt message.

If IA is set to 0, a triggered interrupt does nothing. Software interrupts still
take up four clock cycles, but immediately return, incoming hardware interrupts
are ignored. Note that a queued interrupt is considered triggered when it leaves
the queue, not when it enters it.

Interrupt handlers should end with RFI, which will disable interrupt queueing
and pop A and PC from the stack as a single atomic instruction.
IAQ is normally not needed within an interrupt handler, but is useful for time
critical code.


=== HARDWARE ===================================================================

The DCPU-32 supports up to 65535 connected hardware devices, attempting to
connect more than that will cause it to catch fire. These devices can be
anything from additional storage, monitors, processors or speakers. How to control
the hardware is specified per hardware device, but the DCPU-32 supports a standard
enumeration method for detecting connected hardware via the HWN, HWQ and HWI
instructions.

Interrupts sent to hardware can't contain messages, can take additional cycles,
and can read or modify any registers or memory adresses on the DCPU-32. This
behavior changes per hardware device and is described in the hardware's
documentation.

The DPCU-32 does not support hot swapping hardware. The behavior of connecting
or disconnecting hardware while the DCPU-32 is running is undefined.