Skip to content
This repository
Browse code

Merge https://github.com/0x10cStandardsCommittee/0x10c-Standards

Conflicts:
	ASM/Draft_Assembly_Relocation_Table.txt
  • Loading branch information...
commit c94771afea60ff85ff00428227880301bc0610fd 2 parents da559a4 + 61348f2
James Rhodes authored April 25, 2012
5  .gitignore
... ...
@@ -0,0 +1,5 @@
  1
+*.aux
  2
+*.log
  3
+*.out
  4
+*.tex
  5
+*~
165  ABI/ABI draft 2.txt
... ...
@@ -0,0 +1,165 @@
  1
+RFC X1000 (Standard-ABI)                                   A. Bleck, Ed.
  2
+                                                              April 2012
  3
+
  4
+
  5
+                               ABI draft
  6
+
  7
+Abstract
  8
+
  9
+   This draft specifies an application binary interface for
  10
+   interoperability between subroutines written by different authors or
  11
+   compiled by different compilers.
  12
+
  13
+
  14
+Table of Contents
  15
+
  16
+   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 2
  17
+     1.1.  Requirements Language . . . . . . . . . . . . . . . . . . . 2
  18
+   2.  Rules common to both calling conventions  . . . . . . . . . . . 2
  19
+   3.  Stackcall . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
  20
+   4.  Registercall  . . . . . . . . . . . . . . . . . . . . . . . . . 2
  21
+   5.  Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
  22
+   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 3
  23
+
  24
+
  25
+
  26
+
  27
+
  28
+
  29
+
  30
+
  31
+
  32
+
  33
+
  34
+
  35
+
  36
+
  37
+
  38
+
  39
+
  40
+
  41
+
  42
+
  43
+
  44
+
  45
+
  46
+
  47
+
  48
+
  49
+
  50
+
  51
+
  52
+Bleck                                                           [Page 1]
  53
+
  54
+                                ABI draft                     April 2012
  55
+
  56
+
  57
+1.  Introduction
  58
+
  59
+   Currently there is no standard defined for the behavior of functions
  60
+   that, if conformed to, will allow functions from multiple sources to
  61
+   be compatible.  This RFC specifies two 'calling conventions',
  62
+   hereafter called stackcall and registercall.  Any compiler
  63
+   implementing these calling conventions would be able to call code
  64
+   generated from a different compiler that also implements these
  65
+   conventions safely.
  66
+
  67
+1.1.  Requirements Language
  68
+
  69
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  70
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  71
+   document are to be interpreted as described in RFC 2119.  The key
  72
+   word "CALLER" is the function or code that is making the call, the
  73
+   key word "CALLEE" is the function being called
  74
+
  75
+
  76
+2.  Rules common to both calling conventions
  77
+
  78
+   The CALLER is REQUIRED to assume that the contents of registers A, B
  79
+   and C are not preserved.  The CALLEE is REQUIRED to preserve the
  80
+   contents of registers X, Y, Z, I and J. The CALLER is REQUIRED to
  81
+   assume that the contents of the special purpose register O is not
  82
+   preserved, and contains no valuable information.  The CALLEE MUST
  83
+   return it's result, if any, in register A. The CALLEE MUST remove
  84
+   anything and everything it adds to the stack.  The CALLER is
  85
+   responsible for cleaning any function arguments passed on the stack
  86
+   from the stack.
  87
+
  88
+
  89
+3.  Stackcall
  90
+
  91
+   The CALLER MUST push all arguments to the stack in right to left
  92
+   order, followed by the return pointer, such that the first argument
  93
+   is located on the stack at SP+1, the second is at SP+2, etc.  (The
  94
+   CALLER is RECOMMENDED to use the JSR instruction to perform the jump)
  95
+
  96
+
  97
+4.  Registercall
  98
+
  99
+   The CALLER MUST place the first three function arguments in registers
  100
+   A, B and C, in that order.  Further arguments, if any, MUST be pushed
  101
+   to the stack in right to left order.  The return pointer MUST be
  102
+   pushed last, such that argument four is located on the stack at SP+1,
  103
+   argument five is located at SP+2, etc.  (The CALLER is RECOMMENDED to
  104
+   use the JSR instruction to perform the jump)
  105
+
  106
+
  107
+
  108
+Bleck                                                           [Page 2]
  109
+
  110
+                                ABI draft                     April 2012
  111
+
  112
+
  113
+5.  Scope
  114
+
  115
+   This specification applies only to the interface functions present to
  116
+   each other.  Internal implementation details are intentially
  117
+   excluded.
  118
+
  119
+
  120
+Author's Address
  121
+
  122
+   Blecki (editor)
  123
+
  124
+   Email: jm@omnisu.com
  125
+   URI:   http://jemgine.omnisu.com
  126
+
  127
+
  128
+
  129
+
  130
+
  131
+
  132
+
  133
+
  134
+
  135
+
  136
+
  137
+
  138
+
  139
+
  140
+
  141
+
  142
+
  143
+
  144
+
  145
+
  146
+
  147
+
  148
+
  149
+
  150
+
  151
+
  152
+
  153
+
  154
+
  155
+
  156
+
  157
+
  158
+
  159
+
  160
+
  161
+
  162
+
  163
+
  164
+Bleck                                                           [Page 3]
  165
+
102  ABI/ABI draft 2.xml
... ...
@@ -0,0 +1,102 @@
  1
+<?xml version="1.0" encoding="US-ASCII"?>
  2
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
  3
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
  4
+<?rfc strict="yes" ?>
  5
+<?rfc toc="yes"?>
  6
+<?rfc tocdepth="4"?>
  7
+<?rfc symrefs="yes"?>
  8
+<?rfc sortrefs="yes" ?>
  9
+<?rfc compact="yes" ?>
  10
+<?rfc subcompact="no" ?>
  11
+<?rfc private="RFC X1000 (Standard-ABI)" ?>
  12
+<rfc ipr="none" number="1000" category="info" docName="abi-draft">
  13
+  <front>
  14
+	<title abbrev="ABI draft">ABI draft</title>
  15
+
  16
+    <author fullname="Blecki" initials="A.C." role="editor"
  17
+            surname="Bleck">
  18
+      <organization></organization>
  19
+
  20
+      <address>
  21
+        <email>jm@omnisu.com</email>
  22
+        <uri>http://jemgine.omnisu.com</uri>
  23
+      </address>
  24
+    </author>
  25
+
  26
+    <date month="April" year="2012" />
  27
+    <area>ABI</area>
  28
+    <workgroup>0x10c Standards Committee</workgroup>
  29
+    <abstract>
  30
+		<t>This draft specifies an application binary interface for 
  31
+		interoperability between subroutines written by different
  32
+		authors or compiled by different compilers.</t>
  33
+    </abstract>
  34
+  </front>
  35
+
  36
+  <middle>
  37
+    <section title="Introduction">
  38
+      <t>Currently there is no standard defined for the behavior of 
  39
+	  functions that, if conformed to, will allow functions from
  40
+	  multiple sources to be compatible. This RFC specifies two
  41
+	  'calling conventions', hereafter called stackcall and
  42
+	  registercall. Any compiler implementing these calling
  43
+	  conventions would be able to call code generated from a 
  44
+	  different compiler that also implements these conventions
  45
+	  safely.</t>
  46
+	  
  47
+	  <section title="Requirements Language">
  48
+        <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  49
+        "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  50
+        document are to be interpreted as described in RFC 2119.
  51
+		
  52
+		The key word "CALLER" is the function or code that is making
  53
+		the call, the key word "CALLEE" is the function being called</t>
  54
+      </section>
  55
+    </section>
  56
+	
  57
+	<section anchor="common" title="Rules common to both calling conventions">
  58
+		<t>The CALLER is REQUIRED to assume that the contents of registers A, B and C 
  59
+		are not preserved.
  60
+		
  61
+		The CALLEE is REQUIRED to preserve the contents of registers X, Y, Z, I and J.
  62
+		
  63
+		The CALLER is REQUIRED to assume that the contents of the special purpose
  64
+		register O is not preserved, and contains no valuable information.
  65
+		
  66
+		The CALLEE MUST return it's result, if any, in register A.
  67
+		
  68
+		The CALLEE MUST remove anything and everything it adds to the stack.
  69
+		
  70
+		The CALLER is responsible for cleaning any function arguments passed on the 
  71
+		stack from the stack.
  72
+		</t>
  73
+    </section>
  74
+    
  75
+	<section anchor="stackcall" title="Stackcall">
  76
+		<t>The CALLER MUST push all arguments to the stack in right to left order,
  77
+		followed by the return pointer, such that the first argument is located
  78
+		on the stack at SP+1, the second is at SP+2, etc. (The CALLER is RECOMMENDED
  79
+		to use the JSR instruction to perform the jump)
  80
+		</t>
  81
+	</section>
  82
+	
  83
+	<section anchor="registercall" title="Registercall">
  84
+		<t>The CALLER MUST place the first three function arguments in registers A,
  85
+		B and C, in that order. Further arguments, if any, MUST be pushed to the stack
  86
+		in right to left order. The return pointer MUST be pushed last, such that
  87
+		argument four is located on the stack at SP+1, argument five is located at
  88
+		SP+2, etc. (The CALLER is RECOMMENDED to use the JSR instruction to perform
  89
+		the jump)
  90
+		</t>
  91
+	</section>
  92
+	
  93
+	<section anchor="scope" title="Scope">
  94
+		<t>This specification applies only to the interface functions present to 
  95
+		each other. Internal implementation details are intentially excluded.</t>
  96
+	</section>
  97
+  </middle>
  98
+
  99
+
  100
+
  101
+</rfc>
  102
+
71  ABI/Draft_ABI_1.txt
@@ -6,9 +6,6 @@ On April 5 2012, #0x10c-dev agreed to the following standard ABI:
6 6
 
7 7
 - Return in A
8 8
 
9  
-- J is used for base stack pointer (preserving the value of SP before allocating
10  
-  data for locals)
11  
-
12 9
 - Function local variables are kept on the stack
13 10
 
14 11
 - Caller cleans stack
@@ -16,11 +13,23 @@ On April 5 2012, #0x10c-dev agreed to the following standard ABI:
16 13
 - First three arguments to A, B, C, remaining arguments pushed right-to-left onto
17 14
   the stack
18 15
 
19  
-- Varargs: follow normal rules, except the entire "..." must go on the stack 
20  
-  even if it's one of the first three arguments
  16
+- Varargs: follow normal rules; the vararg callee should push C,B,A in its
  17
+prolog to have a nice walkable array, and then clear off these three registers
  18
+from the stack in its epilog. 
  19
+
21 20
 
22 21
 - No stupid tricks with the overflow flag
23 22
 
  23
+Note: A compiler is free to optimize away pointless preservations of registers.
  24
+
  25
+The storage location of preserved copies of registers must be re-entrant safe.
  26
+(For all practical purposes, on the stack.)
  27
+
  28
+Non-required suggestions for convention:
  29
+
  30
+- J is used for base stack pointer (preserving the value of SP before allocating
  31
+  data for locals)
  32
+
24 33
 --------------------------------------------------------------------------------
25 34
 
26 35
 EXAMPLE FUNCTION CALL:
@@ -59,3 +68,55 @@ SET PC, POP # return
59 68
 
60 69
 Last updated for DCPU16v11
61 70
 example by masterm
  71
+
  72
+---------------------------------------------------------------------
  73
+
  74
+The calling convention I am currently using in DCPUC. I'm not necessarily
  75
+  proposing a complete alternative, just a working implementation to compare with. ~~Blecki
  76
+
  77
+DCPUC Calling Convention
  78
+
  79
+First three arguments are passed in registers A, B and C.
  80
+Remaining arguments are pushed onto the stack left-to-right (Such that the last argument has the lowest address)
  81
+Push the return address last (Using the JSR instruction is preferred)
  82
+Return value is placed in A.
  83
+
  84
+Callee is free to clobber all registers.
  85
+Caller must preserve the registers it cares about (Which includes A, B and C, which may be it's own parameters).
  86
+The Caller removes any arguments on the stack itself.
  87
+
  88
+A sample program and the generated assembly, illustrating a function call.
  89
+
  90
+function foo(a,b,c,d) {
  91
+return foo(1,2,3,4);
  92
+}
  93
+
  94
+foo(1,2,3,4);
  95
+
  96
+SET A, 0x0001 ;Literal
  97
+SET B, 0x0002 ;Literal
  98
+SET C, 0x0003 ;Literal
  99
+SET PUSH, 0x0004 ;Literal
  100
+JSR LABEL1_foo ;Calling function
  101
+ADD SP, 0x0001 ;Remove parameters
  102
+BRK ;Non-standard
  103
+:LABEL1_foo
  104
+SET PUSH, A ;Saving register
  105
+SET A, 0x0001 ;Literal
  106
+SET PUSH, B ;Saving register
  107
+SET B, 0x0002 ;Literal
  108
+SET PUSH, C ;Saving register
  109
+SET C, 0x0003 ;Literal
  110
+SET PUSH, X ;Saving register
  111
+SET PUSH, 0x0004 ;Literal
  112
+JSR LABEL1_foo ;Calling function
  113
+ADD SP, 0x0001 ;Remove parameters
  114
+SET J, A ;Save return value from being overwritten by stored register
  115
+SET X, POP ;Restoring register
  116
+SET C, POP ;Restoring register
  117
+SET B, POP ;Restoring register
  118
+SET A, POP ;Restoring register
  119
+SET X, J
  120
+SET A, X
  121
+SET PC, POP ;Return
  122
+SET PC, POP ;Return
57  ASM/Draft_Assembly_Relocation_Table.txt
@@ -19,8 +19,8 @@ Table of Contents
19 19
    3.  Relocation Table Format . . . . . . . . . . . . . . . . . . . . 2
20 20
    4.  Relocation Table Positioning  . . . . . . . . . . . . . . . . . 3
21 21
    5.  Security Considerations . . . . . . . . . . . . . . . . . . . . 3
22  
-   6.  Normative References  . . . . . . . . . . . . . . . . . . . . . 3
23  
-   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 3
  22
+   6.  Normative References  . . . . . . . . . . . . . . . . . . . . . 4
  23
+   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 4
24 24
 
25 25
 
26 26
 
@@ -50,7 +50,7 @@ Table of Contents
50 50
 
51 51
 
52 52
 Rhodes                                                          [Page 1]
53  
-
  53
+
54 54
                         Assembly Relocation Table             April 2012
55 55
 
56 56
 
@@ -88,8 +88,8 @@ Rhodes                                                          [Page 1]
88 88
                         +-------------------------+
89 89
                         | Contents of single Word |
90 90
                         +-------------------------+
91  
-                        |  Magic number (0x1234)  |
92  
-                        | Version number (0x0001) |
  91
+                        |       Magic number      |
  92
+                        |      Version number     |
93 93
                         |      Size of table      |
94 94
                         |         Entry 1         |
95 95
                         |           ...           |
@@ -106,10 +106,25 @@ Rhodes                                                          [Page 1]
106 106
 
107 107
 
108 108
 Rhodes                                                          [Page 2]
109  
-
  109
+
110 110
                         Assembly Relocation Table             April 2012
111 111
 
112 112
 
  113
+   Magic number  The magic number consists of the string "RT" (stands
  114
+      for "Relocation Table") as a packed 7-bit ASCII literal, thus
  115
+      resulting in the value 0x5254.
  116
+
  117
+   Version number  The current version number is 0x0001.
  118
+
  119
+   Size of table  This field must be set to the total size of the table,
  120
+      in words.  This includes the magic number, the version number and
  121
+      this field, too.
  122
+
  123
+   Entries  Each entry is a absolute address pointing to a single word
  124
+      in the file the relocation table is contained in, which should be
  125
+      relocated relatively to the position the code is loaded to.
  126
+
  127
+
113 128
 4.  Relocation Table Positioning
114 129
 
115 130
    The assembly relocation table must be positioned inside the generated
@@ -145,25 +160,16 @@ Rhodes                                                          [Page 2]
145 160
    original value.
146 161
 
147 162
 
148  
-6.  Normative References
149  
-
150  
-   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
151  
-              Requirement Levels", BCP 14, RFC 2119, March 1997.
152  
-
153  
-
154  
-
155  
-
156  
-
157  
-
158  
-
159  
-
160  
-
161 163
 
  164
+Rhodes                                                          [Page 3]
  165
+
  166
+                        Assembly Relocation Table             April 2012
162 167
 
163 168
 
164  
-Rhodes                                                          [Page 3]
  169
+6.  Normative References
165 170
 
166  
-                        Assembly Relocation Table             April 2012
  171
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
  172
+              Requirement Levels", BCP 14, RFC 2119, March 1997.
167 173
 
168 174
 
169 175
 Author's Address
@@ -211,10 +217,5 @@ Author's Address
211 217
 
212 218
 
213 219
 
214  
-
215  
-
216  
-
217  
-
218  
-
219  
-
220  
-Rhodes                                                          [Page 4]
  220
+Rhodes                                                          [Page 4]
  221
+
19  ASM/Draft_Assembly_Relocation_Table.xml
@@ -61,13 +61,28 @@
61 61
       <t>The format of the relocation table is as follows:</t>
62 62
       <texttable anchor="relocation-table" title="Relocation Table">
63 63
         <ttcol align="center">Contents of single Word</ttcol>
64  
-        <c>Magic number (0x1234)</c>
65  
-        <c>Version number (0x0001)</c>
  64
+        <c>Magic number</c>
  65
+        <c>Version number</c>
66 66
         <c>Size of table</c>
67 67
         <c>Entry 1</c>
68 68
         <c>...</c>
69 69
         <c>Entry N</c>
70 70
       </texttable>
  71
+      <t>
  72
+        <list style="hanging">
  73
+          <t hangText="Magic number">The magic number consists of the string "RT"
  74
+            (stands for "Relocation Table") as a packed 7-bit ASCII literal, thus
  75
+            resulting in the value 0x5254.</t>
  76
+          <t hangText="Version number">The current version number is 0x0001.</t>
  77
+          <t hangText="Size of table">This field must be set to the total size of
  78
+            the table, in words. This includes the magic number, the version
  79
+            number and this field, too.</t>
  80
+          <t hangText="Entries">Each entry is a absolute address pointing to a
  81
+            single word in the file the relocation table is contained in, which
  82
+            should be relocated relatively to the position the code is loaded to.
  83
+          </t>
  84
+        </list>
  85
+      </t>
71 86
     </section>
72 87
 
73 88
     <section anchor="relocation-table-position" title="Relocation Table Positioning">
92  ASM/Draft_DCPU-16_Disk_Controller_KK1000.txt
... ...
@@ -0,0 +1,92 @@
  1
+DCPU-16 Disk Controller KK1000 (Draft v. 0.9)
  2
+Copyright 2012, Robert "King Korihor" Horning
  3
+
  4
+Licensing for reuse under the terms of the Creative Commons Attribution 3.0 United States license
  5
+http://creativecommons.org/licenses/by/3.0/us/
  6
+
  7
+For commentary and discussion about this standard, please visit:
  8
+
  9
+http://www.0x10cforum.com/forum/m/4932880/viewthread/2727631-dcpu16-disc-controller
  10
+
  11
+*Note* - This standard has been written using an informal tone.  Future versions of this standard will be updated to conform to a format and style similar to the other DCPU-16 standards that may be found with the DCPU-16 standards committee.
  12
+
  13
+Here is what we know:  The external storage device attached to the DCPU-16 will be one (or more) floppy disc drives each of which will contain 1.44 MiB of data storage (the 3-1/2" discs that originally came with the Macintosh computer and later on PCs and other computers later on).  Sector sizes traditionally have been 512 bytes, or in DCPU-16 terms, 256 words (close enough for our needs).  This is a total of 2,880 sectors on a given floppy disc.  The physical addressing composed of reading in 18 sectors per track, 80 tracks per side and two sides of the disc.  The data transfer rate (if this is simulated) was about 500 kilobits per second (or about 125 sectors per second and with the DCPU-16 about 800 machine cycles to load a sector as the limiting factor from the disc controller itself).
  14
+
  15
+I'm proposing that the access to this controller be done through a two word "register" selector/data access combination for software control of the disc controller:
  16
+
  17
++-----+------------------+
  18
+|  0  |  Register Select |
  19
++-----+------------------+
  20
+|  1  |  Register Value  |
  21
++-----+------------------+
  22
+
  23
+With this access, there will be several configuration "registers" that will control how the DCPU-16 will communicate with the drive controller.  The following are the registers which will be used in this proposal:
  24
+
  25
++---+-----+----------------------------+
  26
+| 0 | WSB | Write Sector Buffer        |
  27
++---+-----+----------------------------+
  28
+| 1 | RSB | Read Sector Buffer         |
  29
++---+-----+----------------------------+
  30
+| 2 | DSR | Disk Status Register       |
  31
++---+-----+----------------------------+
  32
+| 3 | CC  | Controller Command         |
  33
++---+-----+----------------------------+
  34
+| 4 | SCR | Side Control Register      |
  35
++---+-----+----------------------------+
  36
+| 5 | TCR | Track Control Register     |
  37
++---+-----+----------------------------+
  38
+| 6 | SAR | Sector Access Register     |
  39
++---+-----+----------------------------+
  40
+
  41
+Subsequent registers will be treated as reserved values.
  42
+
  43
+
  44
+A - Write Sector Buffer - This is the DCPU-16 address where the sector data is located at which is to be written to the disk drive
  45
+
  46
+B - Read Sector Buffer - The DCPU-16 address where sector data from the floppy disk will be placed after it has been read from the disk drive.
  47
+
  48
+C - Disk Status Register - Bit flags and other general status information relevant to operating system developers.
  49
+
  50
++---+------------------------------------+
  51
+| 4 | Missing Disk Error                 |
  52
++---+------------------------------------+
  53
+| 3 | Data Read Error                    |
  54
++---+------------------------------------+
  55
+| 2 | Drive Connect Error                |
  56
++---+------------------------------------+
  57
+| 1 | Write Protect                      |
  58
++---+------------------------------------+
  59
+| 0 | Busy Indicator                     |
  60
++---+------------------------------------+
  61
+
  62
+D - Controller Command - Any words written to this register give "commands" to the disk controller that will impact the operation of the disk.  Reading this register will always return the value 0.
  63
+
  64
++---+-------------------------+
  65
+| 0 | Read Sector             |
  66
++---+-------------------------+
  67
+| 1 | Write Sector            |
  68
++---+-------------------------+
  69
+| 2 | Format Sector           |
  70
++---+-------------------------+
  71
+| 3 | Reset Controller        |
  72
++---+-------------------------+
  73
+| 4 | Query Controller Status |
  74
++---+-------------------------+
  75
+
  76
+  1 - Read Sector - Initiates the actions that reads data from the controller and places that data in the DCPU address based upon the Read Sector address.
  77
+  2 - Write Sector - Similar to the Read Sector command, but writes data to the disk instead.
  78
+  3 - Format Sector - Resets the data at the sector indicated by the sector locator registers to become all zeros
  79
+  4 - Reset Controller - Resets the state of all registers in the controller to zero 
  80
+  5 - Query Controller Status - Used primarily to update the status flags of the Disk Status Register.
  81
+
  82
+Other command words may be implemented in this specification in the future, so they should be treated as "reserved" and will produce unpredictable results if used.
  83
+
  84
+E - Side Control Register - Indicates which "side" of the disk is currently being written
  85
+
  86
+F - Track Control Register - Indicates which "track" is currently being read or written
  87
+
  88
+G - Sector Access Register - Indicates which sector on a given track is currently being accessed
  89
+
  90
+I envision that the boot process of the computer would reset all of the registers in this controller to zero, which would include a "read command" to take "Side 0, Track 0, Sector 0" and place the first sector data at address 0 in the DCPU-16.  This would effectively be the first software that the DCPU-16 would be executing upon power-up or re-boot, and it would be at that point the responsibility of the OS developer to designate other memory locations and sectors that will be read by this device, if any.
  91
+
  92
+I'm not sure if there ought to be any sort of simulated time elapsed from when a sector read is requested to when the sector data actually appears in the DCPU-16.  If such a simulated elapsed time does happen, partial sectors may be put into the DCPU and the Disk Status Register will indicate when the full sector has been read.  If this was being completely faithful to how disk controllers work IRL, it would take about 800 DCPU-16 clock cycles to read in a sector.  With this schema, the DCPU-16 could perform other tasks during the sector loading process like scanning the keyboard or doing other application and OS related operations.
195  ASM/Draft_DCPU-16_Specification_v2.txt
... ...
@@ -0,0 +1,195 @@
  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.
560  ASM/Spec_0xSCA.txt
... ...
@@ -0,0 +1,560 @@
  1
+
  2
+
  3
+
  4
+RFC X____                                               J. Kuijpers, Ed.
  5
+                                                                  Jarvix
  6
+                                                        M. Beermann, Ed.
  7
+                                                          April 24, 2012
  8
+
  9
+
  10
+                  0xSCA: Standards Committee Assembly
  11
+
  12
+Abstract
  13
+
  14
+   This document describes an assembly and preprocessor syntax suitable
  15
+   for the DCPU-16 environment.  This syntax is called the 0xSCA, or
  16
+   Standards Committee Assembly.
  17
+
  18
+   This is not a standard.
  19
+
  20
+
  21
+
  22
+
  23
+
  24
+
  25
+
  26
+
  27
+
  28
+
  29
+
  30
+
  31
+
  32
+
  33
+
  34
+
  35
+
  36
+
  37
+
  38
+
  39
+
  40
+
  41
+
  42
+
  43
+
  44
+
  45
+
  46
+
  47
+
  48
+
  49
+
  50
+
  51
+
  52
+
  53
+
  54
+
  55
+Kuijpers & Beermann                                             [Page 1]
  56
+
  57
+                           Assembly Syntactics                April 2012
  58
+
  59
+
  60
+Table of Contents
  61
+
  62
+   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
  63
+     1.1.  Requirements Language  . . . . . . . . . . . . . . . . . .  3
  64
+   2.  Document Markup  . . . . . . . . . . . . . . . . . . . . . . .  3
  65
+     2.1.  Indentation and whitepace  . . . . . . . . . . . . . . . .  3
  66
+   3.  Case sensitivity . . . . . . . . . . . . . . . . . . . . . . .  3
  67
+   4.  Preprocessor Markup  . . . . . . . . . . . . . . . . . . . . .  3
  68
+     4.1.  Comments . . . . . . . . . . . . . . . . . . . . . . . . .  3
  69
+     4.2.  Prefix . . . . . . . . . . . . . . . . . . . . . . . . . .  4
  70
+     4.3.  Directives . . . . . . . . . . . . . . . . . . . . . . . .  4
  71
+       4.3.1.  Inclusion  . . . . . . . . . . . . . . . . . . . . . .  4
  72
+         4.3.1.1.  Code . . . . . . . . . . . . . . . . . . . . . . .  4
  73
+         4.3.1.2.  Binary . . . . . . . . . . . . . . . . . . . . . .  4
  74
+       4.3.2.  Definitions  . . . . . . . . . . . . . . . . . . . . .  5
  75
+       4.3.3.  Data insertion . . . . . . . . . . . . . . . . . . . .  5
  76
+       4.3.4.  Origin relocation  . . . . . . . . . . . . . . . . . .  5
  77
+       4.3.5.  Macros: macro block and macro insertion  . . . . . . .  6
  78
+       4.3.6.  Repeat block . . . . . . . . . . . . . . . . . . . . .  6
  79
+       4.3.7.  Conditionals . . . . . . . . . . . . . . . . . . . . .  7
  80
+       4.3.8.  Error reporting  . . . . . . . . . . . . . . . . . . .  7
  81
+       4.3.9.  Alignment  . . . . . . . . . . . . . . . . . . . . . .  7
  82
+       4.3.10. Echo general output  . . . . . . . . . . . . . . . . .  8
  83
+   5.  Tokenizer Markup . . . . . . . . . . . . . . . . . . . . . . .  8
  84
+     5.1.  Labels . . . . . . . . . . . . . . . . . . . . . . . . . .  8
  85
+     5.2.  Inline character literals  . . . . . . . . . . . . . . . .  8
  86
+   6.  Inline arithmetic  . . . . . . . . . . . . . . . . . . . . . .  8
  87
+   7.  Conformance  . . . . . . . . . . . . . . . . . . . . . . . . .  9
  88
+     7.1.  Recognition of conformance . . . . . . . . . . . . . . . .  9
  89
+   8.  Design Rationale . . . . . . . . . . . . . . . . . . . . . . .  9
  90
+     8.1.  Labels . . . . . . . . . . . . . . . . . . . . . . . . . .  9
  91
+     8.2.  Preprocessor . . . . . . . . . . . . . . . . . . . . . . .  9
  92
+   9.  Security Considerations  . . . . . . . . . . . . . . . . . . . 10
  93
+   10. Normative References . . . . . . . . . . . . . . . . . . . . . 10
  94
+   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10
  95
+
  96
+
  97
+
  98
+
  99
+
  100
+
  101
+
  102
+
  103
+
  104
+
  105
+
  106
+
  107
+
  108
+
  109
+
  110
+
  111
+Kuijpers & Beermann                                             [Page 2]
  112
+
  113
+                           Assembly Syntactics                April 2012
  114
+
  115
+
  116
+1.  Introduction
  117
+
  118
+   This documents describes 0xSCA, Standards Committee Assembly.  It is
  119
+   a definition of a syntax to be used for writing assembly for the
  120
+   DCPU-16 processor.  Use of this syntax is voluntarily.  With 0xSCA,
  121
+   there is a defined syntax, and could decrease code incompatibility
  122
+   among compilers.
  123
+
  124
+   Again, to be clear: 0xSCA is a syntax definition, not a standard.
  125
+   0xSCA is to DCPU-16, what AT&T or the NASM syntax is to IA-32.
  126
+
  127
+1.1.  Requirements Language
  128
+
  129
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  130
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  131
+   document are to be interpreted as described in RFC 2119 [RFC2119].
  132
+
  133
+
  134
+2.  Document Markup
  135
+
  136
+2.1.  Indentation and whitepace
  137
+
  138
+   Whitespace MUST be allowed between all elements of a line, including
  139
+   but not limited to opcodes, values, syntactic characters and
  140
+   preprocessor directives.  Both a space (' ' U+0020) and a tab
  141
+   (U+0009) are considered whitespace characters.
  142
+
  143
+   Indenting instructions is RECOMMENDED.  NOT indenting labels and
  144
+   preprocessor directives RECOMMENDED.  The assembler MUST NOT mandate
  145
+   indentation to assemble successfully.
  146
+
  147
+
  148
+3.  Case sensitivity
  149
+
  150
+   Assemblers MUST accept everything without regard to case EXCEPT
  151
+   string and character literals.
  152
+
  153
+
  154
+4.  Preprocessor Markup
  155
+
  156
+4.1.  Comments
  157
+
  158
+   Comments are used to add information to the code, making it more
  159
+   readable and understandable.  Comments can consist any character in
  160
+   any combination.  This document specifies one-line comments only.
  161
+
  162
+   Any characters following and in the same line of a semicolon (;
  163
+   U+003B) are comments and MUST be ignored, except when the semicolon
  164
+
  165
+
  166
+
  167
+Kuijpers & Beermann                                             [Page 3]
  168
+
  169
+                           Assembly Syntactics                April 2012
  170
+
  171
+
  172
+   resides within the representation of a string.  In that case, the
  173
+   semicolon MUST NOT be treated as a comment.
  174
+
  175
+4.2.  Prefix
  176
+
  177
+   Every preprocessor directive starts with an identifier.  This
  178
+   identifier is used to distinguish preprocessor directives from other
  179
+   code.
  180
+
  181
+   For historical reasons, directives can either start with a dot (.
  182
+   U+002E) or a number sign (# U+0023).
  183
+
  184
+   Preprocessor directives MUST start with a dot (.  U+002E) or a number
  185
+   sign (# U+0023).
  186
+
  187
+   Using a dot is RECOMMENDED to distinguish between C preprocessor
  188
+   syntax.
  189
+
  190
+4.3.  Directives
  191
+
  192
+   All directives in this section MUST be handled in order and in
  193
+   recognition of their position.  For the purpose of this document, a
  194
+   dot (.) is used to describe preprocessor directives.
  195
+
  196
+4.3.1.  Inclusion
  197
+
  198
+4.3.1.1.  Code
  199
+
  200
+   .include "file"
  201
+   .include <file>
  202
+
  203
+   The former directive MUST include the file into the current file.
  204
+   The path is relative to the current file.  The assembler SHOULD
  205
+   report to the user if the given filename does not exist and continue
  206
+   assembly.
  207
+
  208
+   The latter includes the file from an implementation defined location,
  209
+   which may not even exist but trigger certain behaviour, i.e.
  210
+   inclusion of intrinsics.
  211
+
  212
+4.3.1.2.  Binary
  213
+
  214
+   .incbin "file"
  215
+   .incbin <file>
  216
+
  217
+   incbin MUST include the specified binary as raw, unprocessed data,
  218
+   the path to the file is relative from the current file.  All labels
  219
+   behind this directive MUST be offset by the size of the file.
  220
+
  221
+
  222
+
  223
+Kuijpers & Beermann                                             [Page 4]
  224
+
  225
+                           Assembly Syntactics                April 2012
  226
+
  227
+
  228
+   The latter form of incbin MUST include the file from an
  229
+   implementation defined location.
  230
+
  231
+4.3.2.  Definitions
  232
+
  233
+   .def name [value]
  234
+   .define name [value]
  235
+   .equ name value
  236
+   .undef name
  237
+
  238
+   def/define/equ MUST assign the constant value to name.  If the value
  239
+   is omitted, the literal 1 (one) MUST be assumed.
  240
+
  241
+   undef MUST remove the given symbol from the namespace.  If the given
  242
+   symbol does not exist compilation SHOULD continue and a warning MAY
  243
+   be emitted.
  244
+
  245
+   Any occurances of the definition during its existence, MUST be
  246
+   replaced with the given value to the definition.
  247
+
  248
+4.3.3.  Data insertion
  249
+
  250
+   .dw value [,value...]
  251
+   .db value [,value...]
  252
+   .ascii "string"
  253
+
  254
+   dw (data word) MUST store the values literally and unpacked at the
  255
+   location of the directive.
  256
+
  257
+   db (data byte) MUST pack (i.e. two bytes per word, first byte is LSB)
  258
+   the values at the location of the directive.  Words are filled with
  259
+   empty bytes when the data does not evenly fit into 16-bit words.
  260
+
  261
+   ascii MUST store the string unpacked (i.e. character is LSB, one word
  262
+   per character) at the location of the directive.
  263
+
  264
+   asciip (a pascal string) MUST store the string unpacked (i.e.
  265
+   character is LSB, one word per character) at the location of the
  266
+   directive, prepending the string with its length.
  267
+
  268
+   asciic (a C string) MUST store the string unpacked (i.e. character is
  269
+   LSB, one word per character) at the location of the directive,
  270
+   appending 0x0000 (\0).
  271
+
  272
+4.3.4.  Origin relocation
  273
+
  274
+   .org address
  275
+
  276
+
  277
+
  278
+
  279
+Kuijpers & Beermann                                             [Page 5]
  280
+
  281
+                           Assembly Syntactics                April 2012
  282
+
  283
+
  284
+   The org preprocessor directive MUST take an address as the only
  285
+   argument.  Assemblers SHOULD verify the address is 16-bit sized.
  286
+   Assembler MUST add this address to the address of all labels,
  287
+   creating a relocation of the program.
  288
+
  289
+4.3.5.  Macros: macro block and macro insertion
  290
+
  291
+   .macro name([param [,param...]])
  292
+       code
  293
+   .end
  294
+   name([param [,param...]])
  295
+
  296
+   The macro directive defines a macro, a parametrized block of code
  297
+   that can be inserted any time later.  Parameters, if any, are written
  298
+   in parentheses seperated by commas (,).
  299
+
  300
+   Using the name with parenthis MUST insert a formerly defined macro
  301
+   and expands the parameters of the macro with the comma-seperated
  302
+   parameters following the name of the macro to insert.
  303
+
  304
+   Parameter substitutions can only be constant values and memory
  305
+   references.  Preprocessor directives inside the macro MUST be handled
  306
+   upon insertion, not definition.
  307
+
  308
+4.3.6.  Repeat block
  309
+
  310
+   .rep times
  311
+       code
  312
+   .end
  313
+
  314
+   The code in the repeat-block MUST be repeated the number of times
  315
+   specified. 'times' MUST be a positive integer.  Preprocessor
  316
+   directives inside the repeat-block MUST be handled when the
  317
+   repetition is complete, to make allow conditional repetitions.
  318
+
  319
+
  320
+
  321
+
  322
+
  323
+
  324
+
  325
+
  326