Skip to content
This repository
Browse code

Moved Notch-specs to 0x10c-Specifications.

  • Loading branch information...
commit 2df56c61730b3a5c8afd9ad487be7f4414e8f35e 1 parent 442e92b
Jos Kuijpers authored April 28, 2012
143  ASM/Draft_DCPU-16_Specification.txt
... ...
@@ -1,143 +0,0 @@
1  
-DCPU-16 Specification
2  
-Copyright 2012 Mojang
3  
-Version 1.1 (Check 0x10c.com for updated versions)
4  
-
5  
-* 16 bit unsigned words
6  
-* 0x10000 words of ram
7  
-* 8 registers (A, B, C, X, Y, Z, I, J)
8  
-* program counter (PC)
9  
-* stack pointer (SP)
10  
-* overflow (O)
11  
-
12  
-In this document, anything within [brackets] is shorthand for "the value of the RAM at the location of the value inside the brackets".
13  
-For example, SP means stack pointer, but [SP] means the value of the RAM at the location the stack pointer is pointing at.
14  
-
15  
-Whenever the CPU needs to read a word, it reads [PC], then increases PC by one. Shorthand for this is [PC++].
16  
-In some cases, the CPU will modify a value before reading it, in this case the shorthand is [++PC].
17  
-
18  
-Instructions are 1-3 words long and are fully defined by the first word.
19  
-In a basic instruction, the lower four bits of the first word of the instruction are the opcode,
20  
-and the remaining twelve bits are split into two six bit values, called a and b.
21  
-a is always handled by the processor before b, and is the lower six bits.
22  
-In bits (with the least significant being last), a basic instruction has the format: bbbbbbaaaaaaoooo
23  
-
24  
-
25  
-
26  
-Values: (6 bits)
27  
-    0x00-0x07: register (A, B, C, X, Y, Z, I or J, in that order)
28  
-    0x08-0x0f: [register]
29  
-    0x10-0x17: [next word + register]
30  
-         0x18: POP / [SP++]
31  
-         0x19: PEEK / [SP]
32  
-         0x1a: PUSH / [--SP]
33  
-         0x1b: SP
34  
-         0x1c: PC
35  
-         0x1d: O
36  
-         0x1e: [next word]
37  
-         0x1f: next word (literal)
38  
-    0x20-0x3f: literal value 0x00-0x1f (literal)
39  
-    
40  
-* "next word" really means "[PC++]". These increase the word length of the instruction by 1. 
41  
-* If any instruction tries to assign a literal value, the assignment fails silently. Other than that, the instruction behaves as normal.
42  
-* All values that read a word (0x10-0x17, 0x1e, and 0x1f) take 1 cycle to look up. The rest take 0 cycles.
43  
-* 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"
44  
-
45  
-
46  
-
47  
-Basic opcodes: (4 bits)
48  
-    0x0: non-basic instruction - see below
49  
-    0x1: SET a, b - sets a to b
50  
-    0x2: ADD a, b - sets a to a+b, sets O to 0x0001 if there's an overflow, 0x0 otherwise
51  
-    0x3: SUB a, b - sets a to a-b, sets O to 0xffff if there's an underflow, 0x0 otherwise
52  
-    0x4: MUL a, b - sets a to a*b, sets O to ((a*b)>>16)&0xffff
53  
-    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.
54  
-    0x6: MOD a, b - sets a to a%b. if b==0, sets a to 0 instead.
55  
-    0x7: SHL a, b - sets a to a<<b, sets O to ((a<<b)>>16)&0xffff
56  
-    0x8: SHR a, b - sets a to a>>b, sets O to ((a<<16)>>b)&0xffff
57  
-    0x9: AND a, b - sets a to a&b
58  
-    0xa: BOR a, b - sets a to a|b
59  
-    0xb: XOR a, b - sets a to a^b
60  
-    0xc: IFE a, b - performs next instruction only if a==b
61  
-    0xd: IFN a, b - performs next instruction only if a!=b
62  
-    0xe: IFG a, b - performs next instruction only if a>b
63  
-    0xf: IFB a, b - performs next instruction only if (a&b)!=0
64  
-    
65  
-* SET, AND, BOR and XOR take 1 cycle, plus the cost of a and b
66  
-* ADD, SUB, MUL, SHR, and SHL take 2 cycles, plus the cost of a and b
67  
-* DIV and MOD take 3 cycles, plus the cost of a and b
68  
-* IFE, IFN, IFG, IFB take 2 cycles, plus the cost of a and b, plus 1 if the test fails
69  
-    
70  
-
71  
-    
72  
-Non-basic opcodes always have their lower four bits unset, have one value and a six bit opcode.
73  
-In binary, they have the format: aaaaaaoooooo0000
74  
-The value (a) is in the same six bit format as defined earlier.
75  
-
76  
-Non-basic opcodes: (6 bits)
77  
-         0x00: reserved for future expansion
78  
-         0x01: JSR a - pushes the address of the next instruction to the stack, then sets PC to a
79  
-    0x02-0x3f: reserved
80  
-    
81  
-* JSR takes 2 cycles, plus the cost of a.
82  
-
83  
-
84  
-
85  
-FAQ:
86  
-
87  
-Q: Why is there no JMP or RET?
88  
-A: They're not needed! "SET PC, <target>" is a one-instruction JMP.
89  
-   For small relative jumps in a single word, you can even do "ADD PC, <dist>" or "SUB PC, <dist>".
90  
-   For RET, simply do "SET PC, POP"
91  
-   
92  
-
93  
-Q: How does the overflow (O) work?
94  
-A: O is set by certain instructions (see above), but never automatically read. You can use its value in instructions, however.
95  
-   For example, to do a 32 bit add of 0x12345678 and 0xaabbccdd, do this:
96  
-      SET [0x1000], 0x5678    ; low word
97  
-      SET [0x1001], 0x1234    ; high word
98  
-      ADD [0x1000], 0xccdd    ; add low words, sets O to either 0 or 1 (in this case 1)
99  
-      ADD [0x1001], O         ; add O to the high word
100  
-      ADD [0x1001], 0xaabb    ; add high words, sets O again (to 0, as 0xaabb+0x1235 is lower than 0x10000)
101  
-
102  
-Q: How do I do 32 or 64 bit division using O?
103  
-A: This is left as an exercise for the reader.
104  
-     
105  
-Q: How about a quick example?
106  
-A: Sure! Here's some sample assembler, and a memory dump of the compiled code:
107  
-
108  
-        ; Try some basic stuff
109  
-                      SET A, 0x30              ; 7c01 0030
110  
-                      SET [0x1000], 0x20       ; 7de1 1000 0020
111  
-                      SUB A, [0x1000]          ; 7803 1000
112  
-                      IFN A, 0x10              ; c00d 
113  
-                         SET PC, crash         ; 7dc1 001a [*]
114  
-                      
115  
-        ; Do a loopy thing
116  
-                      SET I, 10                ; a861
117  
-                      SET A, 0x2000            ; 7c01 2000
118  
-        :loop         SET [0x2000+I], [A]      ; 2161 2000
119  
-                      SUB I, 1                 ; 8463
120  
-                      IFN I, 0                 ; 806d
121  
-                         SET PC, loop          ; 7dc1 000d [*]
122  
-        
123  
-        ; Call a subroutine
124  
-                      SET X, 0x4               ; 9031
125  
-                      JSR testsub              ; 7c10 0018 [*]
126  
-                      SET PC, crash            ; 7dc1 001a [*]
127  
-        
128  
-        :testsub      SHL X, 4                 ; 9037
129  
-                      SET PC, POP              ; 61c1
130  
-                        
131  
-        ; Hang forever. X should now be 0x40 if everything went right.
132  
-        :crash        SET PC, crash            ; 7dc1 001a [*]
133  
-        
134  
-        ; [*]: Note that these can be one word shorter and one cycle faster by using the short form (0x00-0x1f) of literals,
135  
-        ;      but my assembler doesn't support short form labels yet.     
136  
-
137  
-  Full memory dump:
138  
-  
139  
-        0000: 7c01 0030 7de1 1000 0020 7803 1000 c00d
140  
-        0008: 7dc1 001a a861 7c01 2000 2161 2000 8463
141  
-        0010: 806d 7dc1 000d 9031 7c10 0018 7dc1 001a
142  
-        0018: 9037 61c1 7dc1 001a 0000 0000 0000 0000
143  
-        
195  ASM/Draft_DCPU-16_Specification_v2.txt
... ...
@@ -1,195 +0,0 @@
1  
-DCPU-16 Specification
2  
-Copyright 1985 Mojang
3  
-Version 1.1
4  
-
5  
-
6  
-
7  
-=== SUMMARY ====================================================================
8  
-
9  
-* 16 bit words
10  
-* 0x10000 words of ram
11  
-* 8 registers (A, B, C, X, Y, Z, I, J)
12  
-* program counter (PC)
13  
-* stack pointer (SP)
14  
-* extra/excess (EX)
15  
-* interrupt address (IA)
16  
-
17  
-In this document, anything within [brackets] is shorthand for "the value of the
18  
-RAM at the location of the value inside the brackets". For example, SP means
19  
-stack pointer, but [SP] means the value of the RAM at the location the stack
20  
-pointer is pointing at.
21  
-
22  
-Whenever the CPU needs to read a word, it reads [PC], then increases PC by one.
23  
-Shorthand for this is [PC++]. In some cases, the CPU will modify a value before
24  
-reading it, in this case the shorthand is [++PC].
25  
-
26  
-For stability and to reduce bugs, it's strongly suggested all multi-byte
27  
-operations use little endian in all DCPU-16 programs, wherever possible.
28  
-
29  
-
30  
-
31  
-=== INSTRUCTIONS ===============================================================
32  
-
33  
-Instructions are 1-3 words long and are fully defined by the first word.
34  
-In a basic instruction, the lower five bits of the first word of the instruction
35  
-are the opcode, and the remaining eleven bits are split into a five bit value b
36  
-and a six bit value a.
37  
-b is always handled by the processor after a, and is the lower five bits.
38  
-In bits (in LSB-0 format), a basic instruction has the format: aaaaaabbbbbooooo
39  
-
40  
-In the tables below, C is the time required in cycles to look up the value, or
41  
-perform the opcode, VALUE is the numerical value, NAME is the mnemonic, and
42  
-DESCRIPTION is a short text that describes the opcode or value.
43  
-
44  
-
45  
-
46  
---- Values: (5/6 bits) ---------------------------------------------------------
47  
- C | VALUE     | DESCRIPTION
48  
----+-----------+----------------------------------------------------------------
49  
- 0 | 0x00-0x07 | register (A, B, C, X, Y, Z, I or J, in that order)
50  
- 0 | 0x08-0x0f | [register]
51  
- 1 | 0x10-0x17 | [register + next word]
52  
- 0 |      0x18 | (PUSH / [--SP]) if in b, or (POP / [SP++]) if in a
53  
- 0 |      0x19 | [SP] / PEEK
54  
- 0 |      0x1a | [SP + next word] / PICK n
55  
- 0 |      0x1b | SP
56  
- 0 |      0x1c | PC
57  
- 0 |      0x1d | EX
58  
- 1 |      0x1e | [next word]
59  
- 1 |      0x1f | next word (literal)
60  
- 0 | 0x20-0x3f | literal value 0xffff-0x1e (-1..30) (literal) (only for a)
61  
- --+-----------+----------------------------------------------------------------
62  
-  
63  
-* "next word" means "[PC++]". Increases the word length of the instruction by 1.
64  
-* By using 0x18, 0x19, 0x1a as PEEK, POP/PUSH, and PICK there's a reverse stack
65  
-  starting at memory location 0xffff. Example: "SET PUSH, 10", "SET X, POP"
66  
-
67  
-
68  
-
69  
---- Basic opcodes (5 bits) ----------------------------------------------------
70  
- C | VAL  | NAME     | DESCRIPTION
71  
----+------+----------+--------------------------------------------------------
72  
- - | 0x00 | n/a      | special instruction - see below
73  
- 1 | 0x01 | SET b, a | sets b to a
74  
- 2 | 0x02 | ADD b, a | sets b to b+a, sets EX to 0x0001 if there's an overflow, 
75  
-   |      |          | 0x0 otherwise
76  
- 2 | 0x03 | SUB b, a | sets b to b-a, sets EX to 0xffff if there's an underflow,
77  
-   |      |          | 0x0 otherwise
78  
- 2 | 0x04 | MUL b, a | sets b to b*a, sets EX to ((b*a)>>16)&0xffff (treats b,
79  
-   |      |          | a as unsigned)
80  
- 2 | 0x05 | MLI b, a | like MUL, but treat b, a as signed
81  
- 3 | 0x06 | DIV b, a | sets b to b/a, sets EX to ((b<<16)/a)&0xffff. if a==0,
82  
-   |      |          | sets b and EX to 0 instead. (treats b, a as unsigned)
83  
- 3 | 0x07 | DVI b, a | like DIV, but treat b, a as signed
84  
- 3 | 0x08 | MOD b, a | sets b to b%a. if a==0, sets b to 0 instead.
85  
- 1 | 0x09 | AND b, a | sets b to b&a
86  
- 1 | 0x0a | BOR b, a | sets b to b|a
87  
- 1 | 0x0b | XOR b, a | sets b to b^a
88  
- 2 | 0x0c | SHR b, a | sets b to b>>>a, sets EX to ((b<<16)>>a)&0xffff 
89  
-   |      |          | (logical shift)
90  
- 2 | 0x0d | ASR b, a | sets b to b>>a, sets EX to ((b<<16)>>>a)&0xffff 
91  
-   |      |          | (arithmetic shift) (treats b as signed)
92  
- 2 | 0x0e | SHL b, a | sets b to b<<a, sets EX to ((b<<a)>>16)&0xffff
93  
- - | 0x0f | -        |
94  
- 2+| 0x10 | IFB b, a | performs next instruction only if (b&a)!=0
95  
- 2+| 0x11 | IFC b, a | performs next instruction only if (b&a)==0
96  
- 2+| 0x12 | IFE b, a | performs next instruction only if b==a 
97  
- 2+| 0x13 | IFN b, a | performs next instruction only if b!=a 
98  
- 2+| 0x14 | IFG b, a | performs next instruction only if b>a 
99  
- 2+| 0x15 | IFA b, a | performs next instruction only if b>a (signed)
100  
- 2+| 0x16 | IFL b, a | performs next instruction only if b<a 
101  
- 2+| 0x17 | IFU b, a | performs next instruction only if b<a (signed)
102  
- - | 0x18 | -        |
103  
- - | 0x19 | -        |
104  
- - | 0x1a | -        |
105  
- - | 0x1b | -        |
106  
- - | 0x1c | -        |
107  
- - | 0x1d | -        |
108  
- - | 0x1e | -        |
109  
- - | 0x1f | -        |
110  
----+------+----------+----------------------------------------------------------
111  
-
112  
-* The branching opcodes take one cycle longer to perform if the test fails
113  
-* Signed numbers are represented using two's complement.
114  
-
115  
-
116  
-    
117  
-Special opcodes always have their lower five bits unset, have one value and a
118  
-five bit opcode. In binary, they have the format: aaaaaaooooo00000
119  
-The value (a) is in the same six bit format as defined earlier.
120  
-
121  
---- Special opcodes: (6 bits) --------------------------------------------------
122  
- C | VAL  | NAME  | DESCRIPTION
123  
----+------+-------+-------------------------------------------------------------
124  
- - | 0x00 | n/a   | reserved for future expansion
125  
- 3 | 0x01 | JSR a | pushes the address of the next instruction to the stack,
126  
-   |      |       | then sets PC to a
127  
- - | 0x02 | -     |
128  
- - | 0x03 | -     |
129  
- - | 0x04 | -     |
130  
- - | 0x05 | -     |
131  
- - | 0x06 | -     |
132  
- - | 0x07 | -     |
133  
- 4 | 0x08 | INT a | triggers a software interrupt with message a
134  
- 1 | 0x09 | ING a | sets a to IN 
135  
- 1 | 0x0a | INS a | sets IN to a
136  
- - | 0x0b | -     |
137  
- - | 0x0c | -     |
138  
- - | 0x0d | -     |
139  
- - | 0x0e | -     |
140  
- - | 0x0f | -     |
141  
- 2 | 0x10 | HWN a | sets a to number of connected hardware devices
142  
- 4 | 0x11 | HWQ a | sets A, B, C, X, Y registers to information about hardware a
143  
-   |      |       | a+b is a 32 bit word identifying the hardware type
144  
-   |      |       | c is the hardware revision
145  
-   |      |       | x+y is a 32 bit word identifying the manufacturer
146  
- 4+| 0x12 | HWI a | sends an interrupt to hardware a
147  
- - | 0x13 | -     |
148  
- - | 0x14 | -     |
149  
- - | 0x15 | -     |
150  
- - | 0x16 | -     |
151  
- - | 0x17 | -     |
152  
- - | 0x18 | -     |
153  
- - | 0x19 | -     |
154  
- - | 0x1a | -     |
155  
- - | 0x1b | -     |
156  
- - | 0x1c | -     |
157  
- - | 0x1d | -     |
158  
- - | 0x1e | -     |
159  
- - | 0x1f | -     |
160  
----+------+-------+-------------------------------------------------------------
161  
-
162  
-
163  
-
164  
-=== INTERRUPTS =================================================================    
165  
-
166  
-When IA is set to something other than 0, interrupts triggered on the DCPU-16
167  
-will push PC to the stack, followed by pushing A to the stack, then set the PC
168  
-to IA, and A to the interrupt message. A well formed interrupt handler must pop
169  
-A from the stack before returning (popping PC from the stack)
170  
- 
171  
-If IA is set to 0, a triggered interrupt does nothing.
172  
-
173  
-The DCPU-16 will attempt to perform one clock interrupt 60 times per second,
174  
-with the A message being 0.
175  
-
176  
-
177  
-
178  
-=== HARDWARE ===================================================================    
179  
-
180  
-The DCPU-16 supports up to 65536 connected hardware devices. These devices can
181  
-be anything from additional storage, sensors, monitors or speakers.
182  
-How to control the hardware is specified per hardware device, but the DCPU-16
183  
-supports a standard enumeration method for detecting connected hardware via
184  
-the HWN, HWQ and HWI instructions.
185  
-
186  
-Interrupts sent to hardware can't contain messages, can take additional cycles,
187  
-and can read or modify any registers or memory adresses on the DCPU-16. This
188  
-behavior changes per hardware device and is documented in the hardware
189  
-documentation.
190  
-
191  
-Hardware must NOT start modifying registers or ram on the DCPU-16 before at
192  
-least one HWI call has been made to the hardware.
193  
-
194  
-The DPCU-16 does not support hot swapping hardware. The behavior of connecting
195  
-or disconnecting hardware while the DCPU-16 is undefined.

0 notes on commit 2df56c6

Please sign in to comment.
Something went wrong with that request. Please try again.