aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDimitri Sokolyuk <demon@dim13.org>2012-04-25 23:15:02 +0000
committerDimitri Sokolyuk <demon@dim13.org>2012-04-25 23:15:02 +0000
commit4e946e3c1783e48133b861ee5542c88647d1eb6d (patch)
tree9d43acd11ae5981395f5c8abc86e0166a0527f8e /doc
parentbb6cb77863e2b6d0e84c698b5b0530d86b6f985c (diff)
move docs to doc/
Diffstat (limited to 'doc')
-rw-r--r--doc/clock.txt17
-rw-r--r--doc/dcpu-16.txt143
-rw-r--r--doc/dcpu16.txt205
-rw-r--r--doc/dcpu16_1_3.txt204
-rw-r--r--doc/keyboard.txt31
-rw-r--r--doc/lem1802.txt106
-rw-r--r--doc/notes.txt1
7 files changed, 707 insertions, 0 deletions
diff --git a/doc/clock.txt b/doc/clock.txt
new file mode 100644
index 0000000..71bbc8b
--- /dev/null
+++ b/doc/clock.txt
@@ -0,0 +1,17 @@
+Name: Generic Clock (compatible)
+ID: 0x12d0b402
+Version: 1
+
+Interrupts do different things depending on contents of the A register:
+
+ A | BEHAVIOR
+---+----------------------------------------------------------------------------
+ 0 | The B register is read, and the clock will tick 60/B times per second.
+ | If B is 0, the clock is turned off.
+ 1 | Store number of ticks elapsed since last call to 0 in C register
+ 2 | If register B is non-zero, turn on interrupts with message B. If B is zero,
+ | disable interrupts
+---+----------------------------------------------------------------------------
+
+When interrupts are enabled, the clock will trigger an interrupt whenever it
+ticks.
diff --git a/doc/dcpu-16.txt b/doc/dcpu-16.txt
new file mode 100644
index 0000000..6b7a070
--- /dev/null
+++ b/doc/dcpu-16.txt
@@ -0,0 +1,143 @@
+DCPU-16 Specification
+Copyright 2012 Mojang
+Version 1.1 (Check 0x10c.com for updated versions)
+
+* 16 bit unsigned words
+* 0x10000 words of ram
+* 8 registers (A, B, C, X, Y, Z, I, J)
+* program counter (PC)
+* stack pointer (SP)
+* overflow (O)
+
+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].
+
+Instructions are 1-3 words long and are fully defined by the first word.
+In a basic instruction, the lower four bits of the first word of the instruction are the opcode,
+and the remaining twelve bits are split into two six bit values, called a and b.
+a is always handled by the processor before b, and is the lower six bits.
+In bits (with the least significant being last), a basic instruction has the format: bbbbbbaaaaaaoooo
+
+
+
+Values: (6 bits)
+ 0x00-0x07: register (A, B, C, X, Y, Z, I or J, in that order)
+ 0x08-0x0f: [register]
+ 0x10-0x17: [next word + register]
+ 0x18: POP / [SP++]
+ 0x19: PEEK / [SP]
+ 0x1a: PUSH / [--SP]
+ 0x1b: SP
+ 0x1c: PC
+ 0x1d: O
+ 0x1e: [next word]
+ 0x1f: next word (literal)
+ 0x20-0x3f: literal value 0x00-0x1f (literal)
+
+* "next word" really means "[PC++]". These increase the word length of the instruction by 1.
+* If any instruction tries to assign a literal value, the assignment fails silently. Other than that, the instruction behaves as normal.
+* All values that read a word (0x10-0x17, 0x1e, and 0x1f) take 1 cycle to look up. The rest take 0 cycles.
+* By using 0x18, 0x19, 0x1a as POP, PEEK and PUSH, there's a reverse stack starting at memory location 0xffff. Example: "SET PUSH, 10", "SET X, POP"
+
+
+
+Basic opcodes: (4 bits)
+ 0x0: non-basic instruction - see below
+ 0x1: SET a, b - sets a to b
+ 0x2: ADD a, b - sets a to a+b, sets O to 0x0001 if there's an overflow, 0x0 otherwise
+ 0x3: SUB a, b - sets a to a-b, sets O to 0xffff if there's an underflow, 0x0 otherwise
+ 0x4: MUL a, b - sets a to a*b, sets O to ((a*b)>>16)&0xffff
+ 0x5: DIV a, b - sets a to a/b, sets O to ((a<<16)/b)&0xffff. if b==0, sets a and O to 0 instead.
+ 0x6: MOD a, b - sets a to a%b. if b==0, sets a to 0 instead.
+ 0x7: SHL a, b - sets a to a<<b, sets O to ((a<<b)>>16)&0xffff
+ 0x8: SHR a, b - sets a to a>>b, sets O to ((a<<16)>>b)&0xffff
+ 0x9: AND a, b - sets a to a&b
+ 0xa: BOR a, b - sets a to a|b
+ 0xb: XOR a, b - sets a to a^b
+ 0xc: IFE a, b - performs next instruction only if a==b
+ 0xd: IFN a, b - performs next instruction only if a!=b
+ 0xe: IFG a, b - performs next instruction only if a>b
+ 0xf: IFB a, b - performs next instruction only if (a&b)!=0
+
+* SET, AND, BOR and XOR take 1 cycle, plus the cost of a and b
+* ADD, SUB, MUL, SHR, and SHL take 2 cycles, plus the cost of a and b
+* DIV and MOD take 3 cycles, plus the cost of a and b
+* IFE, IFN, IFG, IFB take 2 cycles, plus the cost of a and b, plus 1 if the test fails
+
+
+
+Non-basic opcodes always have their lower four bits unset, have one value and a six bit opcode.
+In binary, they have the format: aaaaaaoooooo0000
+The value (a) is in the same six bit format as defined earlier.
+
+Non-basic opcodes: (6 bits)
+ 0x00: reserved for future expansion
+ 0x01: JSR a - pushes the address of the next instruction to the stack, then sets PC to a
+ 0x02-0x3f: reserved
+
+* JSR takes 2 cycles, plus the cost of a.
+
+
+
+FAQ:
+
+Q: Why is there no JMP or RET?
+A: They're not needed! "SET PC, <target>" is a one-instruction JMP.
+ For small relative jumps in a single word, you can even do "ADD PC, <dist>" or "SUB PC, <dist>".
+ For RET, simply do "SET PC, POP"
+
+
+Q: How does the overflow (O) work?
+A: O is set by certain instructions (see above), but never automatically read. You can use its value in instructions, however.
+ For example, to do a 32 bit add of 0x12345678 and 0xaabbccdd, do this:
+ SET [0x1000], 0x5678 ; low word
+ SET [0x1001], 0x1234 ; high word
+ ADD [0x1000], 0xccdd ; add low words, sets O to either 0 or 1 (in this case 1)
+ ADD [0x1001], O ; add O to the high word
+ ADD [0x1001], 0xaabb ; add high words, sets O again (to 0, as 0xaabb+0x1235 is lower than 0x10000)
+
+Q: How do I do 32 or 64 bit division using O?
+A: This is left as an exercise for the reader.
+
+Q: How about a quick example?
+A: Sure! Here's some sample assembler, and a memory dump of the compiled code:
+
+ ; Try some basic stuff
+ SET A, 0x30 ; 7c01 0030
+ SET [0x1000], 0x20 ; 7de1 1000 0020
+ SUB A, [0x1000] ; 7803 1000
+ IFN A, 0x10 ; c00d
+ SET PC, crash ; 7dc1 001a [*]
+
+ ; Do a loopy thing
+ SET I, 10 ; a861
+ SET A, 0x2000 ; 7c01 2000
+ :loop SET [0x2000+I], [A] ; 2161 2000
+ SUB I, 1 ; 8463
+ IFN I, 0 ; 806d
+ SET PC, loop ; 7dc1 000d [*]
+
+ ; Call a subroutine
+ SET X, 0x4 ; 9031
+ JSR testsub ; 7c10 0018 [*]
+ SET PC, crash ; 7dc1 001a [*]
+
+ :testsub SHL X, 4 ; 9037
+ SET PC, POP ; 61c1
+
+ ; Hang forever. X should now be 0x40 if everything went right.
+ :crash SET PC, crash ; 7dc1 001a [*]
+
+ ; [*]: Note that these can be one word shorter and one cycle faster by using the short form (0x00-0x1f) of literals,
+ ; but my assembler doesn't support short form labels yet.
+
+ Full memory dump:
+
+ 0000: 7c01 0030 7de1 1000 0020 7803 1000 c00d
+ 0008: 7dc1 001a a861 7c01 2000 2161 2000 8463
+ 0010: 806d 7dc1 000d 9031 7c10 0018 7dc1 001a
+ 0018: 9037 61c1 7dc1 001a 0000 0000 0000 0000
+ \ No newline at end of file
diff --git a/doc/dcpu16.txt b/doc/dcpu16.txt
new file mode 100644
index 0000000..566dc51
--- /dev/null
+++ b/doc/dcpu16.txt
@@ -0,0 +1,205 @@
+DCPU-16 Specification
+Copyright 1985 Mojang
+Version 1.4
+
+
+
+=== SUMMARY ====================================================================
+
+* 16 bit words
+* 0x10000 words of ram
+* 8 registers (A, B, C, X, Y, Z, I, J)
+* program counter (PC)
+* stack pointer (SP)
+* extra/excess (EX)
+* interrupt address (IA)
+
+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].
+
+For stability and to reduce bugs, it's strongly suggested all multi-word
+operations use little endian in all DCPU-16 programs, wherever possible.
+
+
+
+=== INSTRUCTIONS ===============================================================
+
+Instructions are 1-3 words long and are fully defined by the first word.
+In a basic instruction, the lower five bits of the first word of the instruction
+are the opcode, and the remaining eleven bits are split into a five bit value b
+and a six bit value a.
+b is always handled by the processor after a, and is the lower five bits.
+In bits (in LSB-0 format), a basic instruction has the format: aaaaaabbbbbooooo
+
+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-0x3f | literal value 0xffff-0x1e (-1..30) (literal) (only for a)
+ --+-----------+----------------------------------------------------------------
+
+* "next word" means "[PC++]". Increases the word length of the instruction by 1.
+* 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"
+
+
+
+--- 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)>>16)&0xffff (treats b,
+ | | | a as unsigned)
+ 2 | 0x05 | MLI b, a | like MUL, but treat b, a as signed
+ 3 | 0x06 | DIV b, a | sets b to b/a, sets EX to ((b<<16)/a)&0xffff. if a==0,
+ | | | sets b and EX to 0 instead. (treats b, a as unsigned)
+ 3 | 0x07 | DVI b, a | like DIV, but treat b, a as signed
+ 3 | 0x08 | MOD b, a | sets b to b%a. if a==0, sets b to 0 instead.
+ 1 | 0x09 | AND b, a | sets b to b&a
+ 1 | 0x0a | BOR b, a | sets b to b|a
+ 1 | 0x0b | XOR b, a | sets b to b^a
+ 2 | 0x0c | SHR b, a | sets b to b>>>a, sets EX to ((b<<16)>>a)&0xffff
+ | | | (logical shift)
+ 2 | 0x0d | ASR b, a | sets b to b>>a, sets EX to ((b<<16)>>>a)&0xffff
+ | | | (arithmetic shift) (treats b as signed)
+ 2 | 0x0e | SHL b, a | sets b to b<<a, sets EX to ((b<<a)>>16)&0xffff
+ 2 | 0x0f | STI b, a | sets b to a, then increases I and J by 1
+ 2+| 0x10 | IFB b, a | performs next instruction only if (b&a)!=0
+ 2+| 0x11 | IFC b, a | performs next instruction only if (b&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>a
+ 2+| 0x15 | IFA b, a | performs next instruction only if b>a (signed)
+ 2+| 0x16 | IFL b, a | performs next instruction only if b<a
+ 2+| 0x17 | IFU b, a | performs next instruction only if b<a (signed)
+ - | 0x18 | - |
+ - | 0x19 | - |
+ 3 | 0x1a | ADX b, a | sets b to b+a+EX, sets EX to 0x0001 if there is an over-
+ | | | flow, 0x0 otherwise
+ 3 | 0x1b | SBX b, a | sets b to b-a+EX, sets EX to 0xFFFF if there is an under-
+ | | | flow, 0x0 otherwise
+ - | 0x1c | - |
+ - | 0x1d | - |
+ - | 0x1e | - |
+ - | 0x1f | - |
+---+------+----------+----------------------------------------------------------
+
+* The branching opcodes take one cycle longer to perform if the test fails
+ When they skip an if instruction, they will skip an additional instruction
+ at the cost of one extra cycle. This lets you easily chain conditionals.
+* Signed numbers are represented using two's complement.
+
+
+Special opcodes always have their lower five bits unset, have one value and a
+five bit opcode. In binary, they have the format: aaaaaaooooo00000
+The value (a) is in the same six 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 | - |
+ 9 | 0x07 | HCF a | use sparingly
+ 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
+ - | 0x0b | - |
+ - | 0x0c | - |
+ - | 0x0d | - |
+ - | 0x0e | - |
+ - | 0x0f | - |
+ 2 | 0x10 | HWN a | sets a to number of connected hardware devices
+ 4 | 0x11 | HWQ a | sets A, B, C, X, Y registers to information about hardware a
+ | | | A+(B<<16) is a 32 bit word identifying the hardware id
+ | | | C is the hardware version
+ | | | X+(Y<<16) is a 32 bit word identifying the manufacturer
+ 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-16 will perform at most one interrupt between each instruction.
+
+When IA is set to something other than 0, interrupts triggered on the DCPU-16
+will push PC to the stack, followed by pushing A to the stack, then set the PC
+to IA, and A to the interrupt message. A well formed interrupt handler must pop
+A from the stack before returning (popping PC from the stack)
+
+If IA is set to 0, a triggered interrupt does nothing. Software interrupts still
+take up two clock cycles, but immediately return, hardware interrupts are
+ignored, with the hardware being notified of this. Some hardware may choose to
+attempt to trigger the interrupt again at a later point.
+
+The DCPU-16 has no way of knowing when an interrupt handler has finished, so if
+an interrupt is triggered while an interrupt is being handled, the handler will
+get called twice. Calling IAS 0 immediately at the start of the handler will
+reliably prevent multiple concurrent interrupts.
+
+
+
+=== HARDWARE ===================================================================
+
+The DCPU-16 supports up to 65535 connected hardware devices. These devices can
+be anything from additional storage, sensors, monitors or speakers.
+How to control the hardware is specified per hardware device, but the DCPU-16
+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-16. This
+behavior changes per hardware device and is described in the hardware's
+documentation.
+
+Hardware must NOT start modifying registers or ram on the DCPU-16 before at
+least one HWI call has been made to the hardware.
+
+The DPCU-16 does not support hot swapping hardware. The behavior of connecting
+or disconnecting hardware while the DCPU-16 is running is undefined. \ No newline at end of file
diff --git a/doc/dcpu16_1_3.txt b/doc/dcpu16_1_3.txt
new file mode 100644
index 0000000..c1fe5cd
--- /dev/null
+++ b/doc/dcpu16_1_3.txt
@@ -0,0 +1,204 @@
+DCPU-16 Specification
+Copyright 1985 Mojang
+Version 1.3
+
+
+
+=== SUMMARY ====================================================================
+
+* 16 bit words
+* 0x10000 words of ram
+* 8 registers (A, B, C, X, Y, Z, I, J)
+* program counter (PC)
+* stack pointer (SP)
+* extra/excess (EX)
+* interrupt address (IA)
+
+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].
+
+For stability and to reduce bugs, it's strongly suggested all multi-word
+operations use little endian in all DCPU-16 programs, wherever possible.
+
+
+
+=== INSTRUCTIONS ===============================================================
+
+Instructions are 1-3 words long and are fully defined by the first word.
+In a basic instruction, the lower five bits of the first word of the instruction
+are the opcode, and the remaining eleven bits are split into a five bit value b
+and a six bit value a.
+b is always handled by the processor after a, and is the lower five bits.
+In bits (in LSB-0 format), a basic instruction has the format: aaaaaabbbbbooooo
+
+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-0x3f | literal value 0xffff-0x1e (-1..30) (literal) (only for a)
+ --+-----------+----------------------------------------------------------------
+
+* "next word" means "[PC++]". Increases the word length of the instruction by 1.
+* 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"
+
+
+
+--- 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)>>16)&0xffff (treats b,
+ | | | a as unsigned)
+ 2 | 0x05 | MLI b, a | like MUL, but treat b, a as signed
+ 3 | 0x06 | DIV b, a | sets b to b/a, sets EX to ((b<<16)/a)&0xffff. if a==0,
+ | | | sets b and EX to 0 instead. (treats b, a as unsigned)
+ 3 | 0x07 | DVI b, a | like DIV, but treat b, a as signed
+ 3 | 0x08 | MOD b, a | sets b to b%a. if a==0, sets b to 0 instead.
+ 1 | 0x09 | AND b, a | sets b to b&a
+ 1 | 0x0a | BOR b, a | sets b to b|a
+ 1 | 0x0b | XOR b, a | sets b to b^a
+ 2 | 0x0c | SHR b, a | sets b to b>>>a, sets EX to ((b<<16)>>a)&0xffff
+ | | | (logical shift)
+ 2 | 0x0d | ASR b, a | sets b to b>>a, sets EX to ((b<<16)>>>a)&0xffff
+ | | | (arithmetic shift) (treats b as signed)
+ 2 | 0x0e | SHL b, a | sets b to b<<a, sets EX to ((b<<a)>>16)&0xffff
+ 2 | 0x0f | MVI b, a | sets b to a, then increases I and J by 1
+ 2+| 0x10 | IFB b, a | performs next instruction only if (b&a)!=0
+ 2+| 0x11 | IFC b, a | performs next instruction only if (b&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>a
+ 2+| 0x15 | IFA b, a | performs next instruction only if b>a (signed)
+ 2+| 0x16 | IFL b, a | performs next instruction only if b<a
+ 2+| 0x17 | IFU b, a | performs next instruction only if b<a (signed)
+ - | 0x18 | - |
+ - | 0x19 | - |
+ 3 | 0x1a | ADX b, a | sets b to b+a+EX, sets EX to 0x0001 if there is an over-
+ | | | flow, 0x0 otherwise
+ 3 | 0x1b | SUX b, a | sets b to b-a+EX, sets EX to 0xFFFF if there is an under-
+ | | | flow, 0x0 otherwise
+ - | 0x1c | - |
+ - | 0x1d | - |
+ - | 0x1e | - |
+ - | 0x1f | - |
+---+------+----------+----------------------------------------------------------
+
+* The branching opcodes take one cycle longer to perform if the test fails
+* Signed numbers are represented using two's complement.
+
+
+
+Special opcodes always have their lower five bits unset, have one value and a
+five bit opcode. In binary, they have the format: aaaaaaooooo00000
+The value (a) is in the same six bit format as defined earlier.
+
+--- Special opcodes: (6 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
+ - | 0x0b | - |
+ - | 0x0c | - |
+ - | 0x0d | - |
+ - | 0x0e | - |
+ - | 0x0f | - |
+ 2 | 0x10 | HWN a | sets a to number of connected hardware devices
+ 4 | 0x11 | HWQ a | sets A, B, C, X, Y registers to information about hardware a
+ | | | a+b is a 32 bit word identifying the hardware type
+ | | | c is the hardware revision
+ | | | x+y is a 32 bit word identifying the manufacturer
+ 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-16 will perform at most one interrupt between each instruction.
+
+When IA is set to something other than 0, interrupts triggered on the DCPU-16
+will push PC to the stack, followed by pushing A to the stack, then set the PC
+to IA, and A to the interrupt message. A well formed interrupt handler must pop
+A from the stack before returning (popping PC from the stack)
+
+If IA is set to 0, a triggered interrupt does nothing. Software interrupts still
+take up two clock cycles, but immediately return, hardware interrupts are
+ignored, with the hardware being notified of this. Some hardware may choose to
+attempt to trigger the interrupt again at a later point.
+
+The DCPU-16 has no way of knowing when an interrupt handler has finished, so if
+an interrupt is triggered while an interrupt is being handled, the handler will
+get called twice. Calling IAS 0 immediately at the start of the handler will
+reliably prevent multiple concurrent interrupts.
+
+
+
+=== HARDWARE ===================================================================
+
+The DCPU-16 supports up to 65536 connected hardware devices. These devices can
+be anything from additional storage, sensors, monitors or speakers.
+How to control the hardware is specified per hardware device, but the DCPU-16
+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-16. This
+behavior changes per hardware device and is described in the hardware's
+documentation.
+
+Hardware must NOT start modifying registers or ram on the DCPU-16 before at
+least one HWI call has been made to the hardware.
+
+The DPCU-16 does not support hot swapping hardware. The behavior of connecting
+or disconnecting hardware while the DCPU-16 is running is undefined. \ No newline at end of file
diff --git a/doc/keyboard.txt b/doc/keyboard.txt
new file mode 100644
index 0000000..afa4482
--- /dev/null
+++ b/doc/keyboard.txt
@@ -0,0 +1,31 @@
+Name: Generic Keyboard (compatible)
+ID: 0x30cf7406
+Version: 1
+
+Interrupts do different things depending on contents of the A register:
+
+ A | BEHAVIOR
+---+----------------------------------------------------------------------------
+ 0 | Clear keyboard buffer
+ 1 | Store next key typed in C register, or 0 if the buffer is empty
+ 2 | Set C register to 1 if the key specified by the B register is pressed, or
+ | 0 if it's not pressed
+ 3 | If register B is non-zero, turn on interrupts with message B. If B is zero,
+ | disable interrupts
+---+----------------------------------------------------------------------------
+
+When interrupts are enabled, the keyboard will trigger an interrupt when one or
+more keys have been pressed, released, or typed.
+
+Key numbers are:
+ 0x10: Backspace
+ 0x11: Return
+ 0x12: Insert
+ 0x13: Delete
+ 0x20-0x7f: ASCII characters
+ 0x80: Arrow up
+ 0x81: Arrow down
+ 0x82: Arrow left
+ 0x83: Arrow right
+ 0x90: Shift
+ 0x91: Control
diff --git a/doc/lem1802.txt b/doc/lem1802.txt
new file mode 100644
index 0000000..4db2f42
--- /dev/null
+++ b/doc/lem1802.txt
@@ -0,0 +1,106 @@
+NE_LEM1802 v1.0
+
+ \ | ___
+ |\ \| ___
+ | \
+
+ NYA ELEKTRISKA
+ innovation information
+
+
+
+
+DCPU-16 Hardware Info:
+ Name: LEM1802 - Low Energy Monitor
+ ID: 0x7349f615, version: 0x1802
+ Manufacturer: 0x1c6c8b36 (NYA_ELEKTRISKA)
+
+
+Description:
+ The LEM1802 is a 128x96 pixel color display compatible with the DCPU-16.
+ The display is made up of 32x12 16 bit cells. Each cell displays one
+ monochrome 4x8 pixel character out of 128 available. Each cell has its own
+ foreground and background color out of a palette of 16 colors.
+
+ The LEM1802 is fully backwards compatible with LEM1801 (0x7349f615/0x1801),
+ and adds support for custom palettes and fixes the double buffer color
+ bleed bug.
+
+
+Interrupt behavior:
+ When a HWI is received by the LEM1802, it reads the A register and does one
+ of the following actions:
+
+ 0: MEM_MAP_SCREEN
+ Reads the B register, and maps the video ram to DCPU-16 ram starting
+ at address B. See below for a description of video ram.
+ If B is 0, the screen is disconnected.
+ When the screen goes from 0 to any other value, the the LEM1802 takes
+ about one second to start up. Other interrupts sent during this time
+ are still processed.
+ 1: MEM_MAP_FONT
+ Reads the B register, and maps the font ram to DCPU-16 ram starting
+ at address B. See below for a description of font ram.
+ If B is 0, the default font is used instead.
+ 2: MEM_MAP_PALETTE
+ Reads the B register, and maps the palette ram to DCPU-16 ram starting
+ at address B. See below for a description of palette ram.
+ If B is 0, the default palette is used instead.
+ 3: SET_BORDER_COLOR
+ Reads the B register, and sets the border color to palette index B&0xF
+ 4: MEM_DUMP_FONT
+ Reads the B register, and writes the default font data to DCPU-16 ram
+ starting at address B.
+ Halts the DCPU-16 for 256 cycles
+ 5: MEM_DUMP_PALETTE
+ Reads the B register, and writes the default palette data to DCPU-16
+ ram starting at address B.
+ Halts the DCPU-16 for 16 cycles
+
+
+Video ram:
+ The LEM1802 has no internal video ram, but rather relies on being assigned
+ an area of the DCPU-16 ram. The size of this area is 386 words, and is
+ made up of 32x12 cells of the following bit format (in LSB-0):
+ ffffbbbbBccccccc
+ The lowest 7 bits (ccccccc) select define character to display.
+ ffff and bbbb select which foreground and background color to use.
+ If B (bit 7) is set the character color will blink slowly.
+
+
+Font ram:
+ The LEM1802 has a default built in font. If the user chooses, they may
+ supply their own font by mapping a 256 word memory region with two words
+ per character in the 128 character font.
+ By setting bits in these words, different characters and graphics can be
+ achieved. For example, the character F looks like this:
+ word0 = 1111111100001001
+ word1 = 0000100100000000
+ Or, split into octets:
+ word0 = 11111111 /
+ 00001001
+ word1 = 00001001 /
+ 00000000
+
+
+Palette ram:
+ The LEM1802 has a default built in palette. If the user chooses, they may
+ supply their own palette by mapping a 16 word memory region with one word
+ per palette entry in the 16 color palette.
+ Each color entry has the following bit format (in LSB-0):
+ 0000rrrrggggbbbb
+ Where r, g, b are the red, green and blue channels. A higher value means a
+ lighter color.
+
+
+A message from Ola:
+ Hello!
+
+ It is fun to see that so many people use our products. When I was a small
+ boy, my dad used to tell me "Ola, take care of those who understand less
+ than you. Lack of knowledge is dangerous, but too much is worse".
+ Here at Nya Elektriska have we always tried to improve mankind by showing
+ them the tools required to improve and reach their true potential.
+ Together, you will wake up in time.
+
+ - Ola Kristian Carlsson \ No newline at end of file
diff --git a/doc/notes.txt b/doc/notes.txt
new file mode 100644
index 0000000..ce4fad6
--- /dev/null
+++ b/doc/notes.txt
@@ -0,0 +1 @@
+http://dcpu.com/highnerd/rc_1/clock.txt