├── .gitignore ├── TESTS └── high-nerd.dasm16 ├── README.md ├── ABI ├── Draft_ABI_1.txt ├── ABI draft 2.xml └── ABI draft 2.txt ├── MISC ├── X1000_Spec_Formatting_Conventions.xml ├── X1000_Spec_Formatting_Conventions.txt └── Open_Letter_Notch.txt ├── ASM ├── Draft_Assembly_Relocation_Table.xml ├── Draft_DCPU-16_Disk_Controller_KK1000.txt ├── Draft_Assembly_Relocation_Table.txt ├── Draft_Extension_Declaration_Table.xml ├── Draft_Extension_Declaration_Table.txt ├── Spec_0xSCA.txt └── Spec_0xSCA.xml ├── LIB ├── Draft_String_Format.txt └── Draft-String-Format.xml ├── NET ├── Draft_OSI_Physical_Layer.xml └── Draft_OSI_Physical_Layer.txt └── FS ├── Draft_Harrys_Allocation_Table.xml └── Draft_Harrys_Allocation_Table.txt /.gitignore: -------------------------------------------------------------------------------- 1 | *.aux 2 | *.log 3 | *.out 4 | *.tex 5 | *~ -------------------------------------------------------------------------------- /TESTS/high-nerd.dasm16: -------------------------------------------------------------------------------- 1 | ; 2 | ; Unit test by James Rhodes 3 | ; 4 | ; This unit test ensures emulator compliance with how high-nerd 5 | ; should work. Corrections and expansions are appreciated. 6 | ; 7 | 8 | ; 9 | ; At the end of the test, the emulator state should be (empty 10 | ; indicates the value is unspecified): 11 | ; 12 | ; A: 0x0000 [A]: 13 | ; B: 0x0000 [B]: 14 | ; C: 0xFB50 [C]: 15 | ; X: 0x0000 [X]: 16 | ; Y: 0x0000 [Y]: 17 | ; Z: 0x0000 [Z]: 18 | ; I: 0x0000 [I]: 19 | ; J: 0x0000 [J]: 20 | ; PC: SP: 0x0000 21 | ; EX: 0x5556 IA: 0x0000 22 | ; 23 | 24 | SET C, 500 ; C = 500 25 | ADD C, 499 ; C = 999 26 | SUB C, 99 ; C = 900 27 | MUL C, 2 ; C = 1800 28 | SET A, 0xFFFF ; C = 1800, A = 0xFFFF 29 | SUB A, C ; C = 1800, A = 0xF8F8 30 | SET C, A ; C = -1800, A = 0xF8F8 31 | SET A, 0 ; C = -1800 32 | MLI C, 2 ; C = -3600 33 | DVI C, 3 ; C = -1200 (0xFB50) 34 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # 0x10c Standards Committee # 2 | 3 | The 0x10c Standards Committee is a fully community driven organization working towards a series of standards for application development for the DCPU-16 within 0x10c. 4 | 5 | ## Directory Hierarchy ## 6 | 7 | ### ABI ### 8 | This directory contains the standards and proposals regarding the Application Binary Interface. 9 | 10 | ### ASM ### 11 | If you want to write DCPU-16 assembly (probably the case), this is where to look. It contains standards about the syntax and has information for assemblers and compilers. 12 | 13 | ### FS ### 14 | This directory contains the standards and proposals regarding the File System(s) used by the DCPU-16. 15 | 16 | ### LIB ### 17 | In here go all specifications and proposals for the layout and implementation of libraries. 18 | 19 | ### NET ### 20 | Anything about networking goes in the net folder. 21 | 22 | ### HW ### 23 | Anything about hardware components and communicating directly with hardware components goes in here. 24 | 25 | ### MISC ### 26 | In this directory goes everything that does not fit in the other directories defined above. 27 | 28 | ### TESTS ### 29 | Tests for software that can be used to ensure standards compliance. 30 | 31 | 32 | ## Procedures and Naming Standards ## 33 | 34 | If you have a proposal, idea or comment regarding upcoming or new standards, you can make an issue about it. 35 | 36 | From these issues, a Draft named Draft\_\.xml will be created using Pull Requests, with the XML format as defined in RFC 2629. 37 | 38 | When the community agrees on the draft being a standard, and the game is expected to not collide with the standard in a later stage, the draft will be renamed Standard_\.xml . 39 | 40 | New versions of a standard must be submitted as a new draft, if this draft becomes a standard it must contain a reference to the superseded standard which is subsequently updated with a reference to the new version. 41 | 42 | ## Voting ## 43 | 44 | Voting times will be based on their importance and impact: 45 | 46 | ### LOW IMPORTANCE ### 47 | LOW IMPORTANCE votes are votes for minor changes such as naming standards and file formats. Expected time: 15-30 minutes. 48 | 49 | ### HIGH IMPORTANCE ### 50 | HIGH IMPORTANCE votes are votes for major changes such as method call conventions. Expected time: At least 24 hours, to give people across the world enough time to vote. 51 | 52 | 53 | ## Community ## 54 | 55 | With pull requests you can propose changes to drafts or create new drafts. 56 | 57 | The issues section should be used to comment on the documents and to suggest changes to make them better. 58 | 59 | Everything that is not directly about the standards should go to 60 | [#0x10c-dev](irc://irc.freenode.net/#0x10c-dev) @ FreeNode.net 61 | 62 | You can discuss the ideas, drafts and standards via IRC: 63 | [#0x10c-std](irc://irc.freenode.net/#0x10c-std) @ FreeNode.net 64 | -------------------------------------------------------------------------------- /ABI/Draft_ABI_1.txt: -------------------------------------------------------------------------------- 1 | On April 5 2012, #0x10c-dev agreed to the following standard ABI: 2 | 3 | - Registers A, B, C are clobberable across calls 4 | 5 | - Registers I, J, X, Y, Z are preserved across calls 6 | 7 | - Return in A 8 | 9 | - Function local variables are kept on the stack 10 | 11 | - Caller cleans stack 12 | 13 | - First three arguments to A, B, C, remaining arguments pushed right-to-left onto 14 | the stack 15 | 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 | 20 | 21 | - No stupid tricks with the overflow flag 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 | 33 | -------------------------------------------------------------------------------- 34 | 35 | EXAMPLE FUNCTION CALL: 36 | 37 | # func(1, 2, 3, 4, 5); 38 | 39 | # first 3 arguments are passed via registers 40 | SET A, 1 41 | SET B, 2 42 | SET C, 3 43 | # 4 and 5 are pushed to stack in reverse order 44 | SET PUSH, 5 45 | SET PUSH, 4 46 | JSR func 47 | ADD SP, 2 # callers cleans up the stack (two passed words) 48 | 49 | EXAMPLE FUNCTION PROLOGUE/EPILOGUE: 50 | 51 | # Prologue: 52 | SET PUSH, J 53 | SET J, SP 54 | SUB SP, 5 # Reserve 5 words for function locals 55 | 56 | # Function body: 57 | SET A, [J-1] # Access first local variable 58 | SET B, [J+2] # Access 4th function argument 59 | SET C, [J+3] # Access 5th function argument 60 | 61 | # etc ... 62 | 63 | # Epilogue: 64 | SET A, return_value 65 | SET SP, J 66 | SET J, POP 67 | SET PC, POP # return 68 | 69 | Last updated for DCPU16v11 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 123 | -------------------------------------------------------------------------------- /ABI/ABI draft 2.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | ABI draft 15 | 16 | 18 | 19 | 20 |
21 | jm@omnisu.com 22 | http://jemgine.omnisu.com 23 |
24 | 25 | 26 | 27 | ABI 28 | 0x10c Standards Committee 29 | 30 | This draft specifies an application binary interface for 31 | interoperability between subroutines written by different 32 | authors or compiled by different compilers. 33 | 34 | 35 | 36 | 37 |
38 | 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. 46 | 47 |
48 | 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 54 |
55 |
56 | 57 |
58 | 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 | 73 |
74 | 75 |
76 | 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 | 81 |
82 | 83 |
84 | 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 | 91 |
92 | 93 |
94 | This specification applies only to the interface functions present to 95 | each other. Internal implementation details are intentially excluded. 96 |
97 | 98 | 99 | 100 | 101 | 102 | 103 | -------------------------------------------------------------------------------- /ABI/ABI draft 2.txt: -------------------------------------------------------------------------------- 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 | -------------------------------------------------------------------------------- /MISC/X1000_Spec_Formatting_Conventions.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | Specification Formatting Conventions 15 | 16 | 18 | Redpoint Software 19 | 20 |
21 | jrhodes@redpointsoftware.com.au 22 | http://www.redpointsoftware.com.au/ 23 |
24 | 25 | 26 | 27 | Misc 28 | 0x10c Standards Committee 29 | 30 | This draft provides guidelines on formatting draft specifications 31 | for submission to the 0x10c standards committee. It is designed 32 | to loosely correlate with the formatting of RFCs. 33 | 34 | 35 | 36 | 37 |
38 | Currently there are no standards defined for the formatting 39 | of standards to the committee. This RFC proposes using the 40 | standards already in place in RFCs globally. 41 | 42 |
43 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 44 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 45 | document are to be interpreted as described in RFC 2119. 47 |
48 |
49 | 50 |
51 | The numbering prefix of RFCs submitted to the 0x10c 52 | standards committee begins at X1000, as these 53 | RFCs are independent of the globally recognised list of RFCs. 54 | Hence this document forms RFC X1000. 55 | RFCs do not have a number assigned to them when they are 56 | initially submitted as drafts. Only once an RFC is voted to 57 | be standard by the committee is it assigned the number, whichever 58 | the next freely available number is in the numbering sequence. 59 |
60 | 61 |
62 | This is an example of how you would change the DOCTYPE if 63 | you wanted to reference RFC X1000 in your own XRFC. 64 | 68 | ]> 69 | ]]> 70 | Then in the references section, do: 71 | &rfcx1000; 72 |
73 | 74 |
75 | Authors of RFCs for submission to the 0x10c standards 76 | committee are RECOMMENDED to use xml2ref as specified in RFC 2629 for initially drafting 78 | specifications they wish to submit. 79 | When authors want to submit their RFC they MUST include 80 | both the original source file if applicable (such as the 81 | .xml file if using xml2rfc) and a resulting plain text 82 | document that MUST formatted according to RFC conventions. 83 | The website 84 | http://xml.resource.org/ is noted 85 | to have an online formatter than can perform this conversion 86 | for authors. 87 |
88 | 89 |
90 | Authors of RFCs MUST include their email address as part 91 | of their author status in an RFC. 92 | Authors of RFCs MAY include an URI that is unique to them. 93 | Inclusion of other information is OPTIONAL. 94 |
95 | 96 |
97 | Authors of RFCs MUST provide a section for security 98 | considerations as specified in RFC 99 | 3552. 100 |
101 | 102 |
103 | It is RECOMMENDED to authors of RFCs to look at the source 104 | file of this RFCs to gain a guideline on how RFCs are 105 | constructed with xml2rfc. 106 |
107 | 108 |
109 | This memo has no applicable security considerations. 110 |
111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | -------------------------------------------------------------------------------- /ASM/Draft_Assembly_Relocation_Table.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | Assembly Relocation Table 15 | 16 | 18 | Redpoint Software 19 | 20 |
21 | jrhodes@redpointsoftware.com.au 22 | http://www.redpointsoftware.com.au/ 23 |
24 | 25 | 26 | 27 | Asm 28 | 0x10c Standards Committee 29 | 30 | This draft provides a formal structure for providing an assembly 31 | relocation table from within DCPU-16 programs. 32 | 33 | 34 | 35 | 36 |
37 | As it stands, code generated by assemblers is either not relocatable, 38 | or the relocation format is not standardized. Thus this document 39 | suggests a standard mechanism for providing a table of addresses that 40 | need relocating. 41 | 42 |
43 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 44 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 45 | document are to be interpreted as described in RFC 2119. 47 |
48 |
49 | 50 |
51 | For the purposes of this draft, the role of assemblers is to generate 52 | code from a defined syntax to DCPU-16 bytecode. 53 | In this case, assemblers SHOULD provide an option to generate 54 | relocatable code, but MUST NOT generate relocatable code unless the 55 | user indicates that they wish to do so. 56 |
57 | 58 |
59 | For purposes of future versioning, this document specifies version 1 60 | of the relocation table format. 61 | The format of the relocation table is as follows: 62 | 63 | Contents of single Word 64 | Magic number 65 | Version number 66 | Size of table 67 | Entry 1 68 | ... 69 | Entry N 70 | 71 | 72 | 73 | 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. 76 | The current version number is 0x0001. 77 | 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. 80 | 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 | 84 | 85 | 86 |
87 | 88 |
89 | The assembly relocation table must be positioned inside the generated 90 | code, but have no effect on the program execution. 91 | When an assembler generates relocatable code, the first instruction 92 | MUST be a jump to the start of the actual program code. This results 93 | in the first two words being: 94 | 95 | Contents of single Word 96 | SET PC, <next word literally> 97 | Location of first program instruction 98 | 99 | It is important to note that assemblers will have to offset all label 100 | addresses by the size of the relocation table, plus the two words at 101 | the start. 102 |
103 | 104 |
105 | It is potentially possible for a malicious user to generate code 106 | which determines the offset of the resulting relocatable program when 107 | it is loaded into memory and executed. 108 | This is possible by creating a label with a predetermined address if 109 | the program was running at 0x0, and calculating the difference 110 | between the actual address that the program would jump to and the 111 | original value. 112 |
113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | -------------------------------------------------------------------------------- /MISC/X1000_Spec_Formatting_Conventions.txt: -------------------------------------------------------------------------------- 1 | RFC X1000 (Standard-Misc) J. Rhodes, Ed. 2 | Redpoint Software 3 | April 2012 4 | 5 | 6 | Specification Formatting Conventions 7 | 8 | Abstract 9 | 10 | This draft provides guidelines on formatting draft specifications for 11 | submission to the 0x10c standards committee. It is designed to 12 | loosely correlate with the formatting of RFCs. 13 | 14 | 15 | Table of Contents 16 | 17 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 18 | 1.1. Requirements Language . . . . . . . . . . . . . . . . . . . 2 19 | 2. Numbering RFCs . . . . . . . . . . . . . . . . . . . . . . . . 2 20 | 3. Referencing RFCs . . . . . . . . . . . . . . . . . . . . . . . 2 21 | 4. Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . 2 22 | 5. Author Notation . . . . . . . . . . . . . . . . . . . . . . . . 3 23 | 6. Required Sections . . . . . . . . . . . . . . . . . . . . . . . 3 24 | 7. Additional Notes . . . . . . . . . . . . . . . . . . . . . . . 3 25 | 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 3 26 | 9. Normative References . . . . . . . . . . . . . . . . . . . . . 3 27 | Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 4 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 | Rhodes [Page 1] 53 | 54 | Specification Conventions April 2012 55 | 56 | 57 | 1. Introduction 58 | 59 | Currently there are no standards defined for the formatting of 60 | standards to the committee. This RFC proposes using the standards 61 | already in place in RFCs globally. 62 | 63 | 1.1. Requirements Language 64 | 65 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 66 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 67 | document are to be interpreted as described in RFC 2119 [RFC2119]. 68 | 69 | 70 | 2. Numbering RFCs 71 | 72 | The numbering prefix of RFCs submitted to the 0x10c standards 73 | committee begins at X1000, as these RFCs are independent of the 74 | globally recognised list of RFCs. Hence this document forms RFC 75 | X1000. 76 | 77 | RFCs do not have a number assigned to them when they are initially 78 | submitted as drafts. Only once an RFC is voted to be standard by the 79 | committee is it assigned the number, whichever the next freely 80 | available number is in the numbering sequence. 81 | 82 | 83 | 3. Referencing RFCs 84 | 85 | This is an example of how you would change the DOCTYPE if you wanted 86 | to reference RFC X1000 in your own XRFC. 87 | 88 | ]> 91 | 92 | Then in the references section, do: 93 | 94 | &rfcx1000; 95 | 96 | 97 | 4. Formatting 98 | 99 | Authors of RFCs for submission to the 0x10c standards committee are 100 | RECOMMENDED to use xml2ref as specified in RFC 2629 [RFC2629] for 101 | initially drafting specifications they wish to submit. 102 | 103 | When authors want to submit their RFC they MUST include both the 104 | original source file if applicable (such as the .xml file if using 105 | 106 | 107 | 108 | Rhodes [Page 2] 109 | 110 | Specification Conventions April 2012 111 | 112 | 113 | xml2rfc) and a resulting plain text document that MUST formatted 114 | according to RFC conventions. 115 | 116 | The website http://xml.resource.org/ is noted to have an online 117 | formatter than can perform this conversion for authors. 118 | 119 | 120 | 5. Author Notation 121 | 122 | Authors of RFCs MUST include their email address as part of their 123 | author status in an RFC. 124 | 125 | Authors of RFCs MAY include an URI that is unique to them. 126 | 127 | Inclusion of other information is OPTIONAL. 128 | 129 | 130 | 6. Required Sections 131 | 132 | Authors of RFCs MUST provide a section for security considerations as 133 | specified in RFC 3552 [RFC3552]. 134 | 135 | 136 | 7. Additional Notes 137 | 138 | It is RECOMMENDED to authors of RFCs to look at the source file of 139 | this RFCs to gain a guideline on how RFCs are constructed with 140 | xml2rfc. 141 | 142 | 143 | 8. Security Considerations 144 | 145 | This memo has no applicable security considerations. 146 | 147 | 148 | 9. 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 | [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 154 | June 1999. 155 | 156 | [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 157 | Text on Security Considerations", BCP 72, RFC 3552, 158 | July 2003. 159 | 160 | 161 | 162 | 163 | 164 | Rhodes [Page 3] 165 | 166 | Specification Conventions April 2012 167 | 168 | 169 | Author's Address 170 | 171 | James Rhodes (editor) 172 | Redpoint Software 173 | 174 | Email: jrhodes@redpointsoftware.com.au 175 | URI: http://www.redpointsoftware.com.au/ 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | Rhodes [Page 4] -------------------------------------------------------------------------------- /ASM/Draft_DCPU-16_Disk_Controller_KK1000.txt: -------------------------------------------------------------------------------- 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. -------------------------------------------------------------------------------- /ASM/Draft_Assembly_Relocation_Table.txt: -------------------------------------------------------------------------------- 1 | RFC X____ (Draft-Asm) J. Rhodes, Ed. 2 | Redpoint Software 3 | April 2012 4 | 5 | 6 | Assembly Relocation Table 7 | 8 | Abstract 9 | 10 | This draft provides a formal structure for providing an assembly 11 | relocation table from within DCPU-16 programs. 12 | 13 | 14 | Table of Contents 15 | 16 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 17 | 1.1. Requirements Language . . . . . . . . . . . . . . . . . . . 2 18 | 2. Role of Assemblers . . . . . . . . . . . . . . . . . . . . . . 2 19 | 3. Relocation Table Format . . . . . . . . . . . . . . . . . . . . 2 20 | 4. Relocation Table Positioning . . . . . . . . . . . . . . . . . 3 21 | 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 3 22 | 6. Normative References . . . . . . . . . . . . . . . . . . . . . 4 23 | Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 4 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 | Rhodes [Page 1] 53 | 54 | Assembly Relocation Table April 2012 55 | 56 | 57 | 1. Introduction 58 | 59 | As it stands, code generated by assemblers is either not relocatable, 60 | or the relocation format is not standardized. Thus this document 61 | suggests a standard mechanism for providing a table of addresses that 62 | need relocating. 63 | 64 | 1.1. Requirements Language 65 | 66 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 67 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 68 | document are to be interpreted as described in RFC 2119 [RFC2119]. 69 | 70 | 71 | 2. Role of Assemblers 72 | 73 | For the purposes of this draft, the role of assemblers is to generate 74 | code from a defined syntax to DCPU-16 bytecode. 75 | 76 | In this case, assemblers SHOULD provide an option to generate 77 | relocatable code, but MUST NOT generate relocatable code unless the 78 | user indicates that they wish to do so. 79 | 80 | 81 | 3. Relocation Table Format 82 | 83 | For purposes of future versioning, this document specifies version 1 84 | of the relocation table format. 85 | 86 | The format of the relocation table is as follows: 87 | 88 | +-------------------------+ 89 | | Contents of single Word | 90 | +-------------------------+ 91 | | Magic number | 92 | | Version number | 93 | | Size of table | 94 | | Entry 1 | 95 | | ... | 96 | | Entry N | 97 | +-------------------------+ 98 | 99 | Table 1: Relocation Table 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | Rhodes [Page 2] 109 | 110 | Assembly Relocation Table April 2012 111 | 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 | 128 | 4. Relocation Table Positioning 129 | 130 | The assembly relocation table must be positioned inside the generated 131 | code, but have no effect on the program execution. 132 | 133 | When an assembler generates relocatable code, the first instruction 134 | MUST be a jump to the start of the actual program code. This results 135 | in the first two words being: 136 | 137 | +---------------------------------------+ 138 | | Contents of single Word | 139 | +---------------------------------------+ 140 | | SET PC, | 141 | | Location of first program instruction | 142 | +---------------------------------------+ 143 | 144 | Table 2: Relocation Setup Table 145 | 146 | It is important to note that assemblers will have to offset all label 147 | addresses by the size of the relocation table, plus the two words at 148 | the start. 149 | 150 | 151 | 5. Security Considerations 152 | 153 | It is potentially possible for a malicious user to generate code 154 | which determines the offset of the resulting relocatable program when 155 | it is loaded into memory and executed. 156 | 157 | This is possible by creating a label with a predetermined address if 158 | the program was running at 0x0, and calculating the difference 159 | between the actual address that the program would jump to and the 160 | original value. 161 | 162 | 163 | 164 | Rhodes [Page 3] 165 | 166 | Assembly Relocation Table April 2012 167 | 168 | 169 | 6. Normative References 170 | 171 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 172 | Requirement Levels", BCP 14, RFC 2119, March 1997. 173 | 174 | 175 | Author's Address 176 | 177 | James Rhodes (editor) 178 | Redpoint Software 179 | 180 | Email: jrhodes@redpointsoftware.com.au 181 | URI: http://www.redpointsoftware.com.au/ 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | Rhodes [Page 4] 221 | -------------------------------------------------------------------------------- /LIB/Draft_String_Format.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | RFC (Draft-Lib) M. Schuetze 5 | April 11, 2012 6 | 7 | 8 | String Format 9 | 10 | Abstract 11 | 12 | This document presents a general format for strings in libraries 13 | intended to be shared across programs and with other users. 14 | 15 | 16 | Table of Contents 17 | 18 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 19 | 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 2 20 | 1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 2 21 | 2. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 22 | 3. Rationale . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 23 | 3.1. Benefits . . . . . . . . . . . . . . . . . . . . . . . . . 3 24 | 3.2. Disadvantages . . . . . . . . . . . . . . . . . . . . . . . 3 25 | 4. Other Notes . . . . . . . . . . . . . . . . . . . . . . . . . . 4 26 | 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 4 27 | 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 4 28 | Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 4 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 | Schuetze [Page 1] 56 | 57 | String Format April 2012 58 | 59 | 60 | 1. Introduction 61 | 62 | Shared Libraries depend on certain formats being given. Strings, 63 | being a common argument type for cross-library calls, should 64 | therefore be standardized. Length-prefixed strings are to be used 65 | for security and efficiency reasons. 66 | 67 | 1.1. Terminology 68 | 69 | word 70 | 16 bits. This is the smallest unit addressable by the DCPU. 71 | 72 | character 73 | A group of bits representing a glyph or control sequence. A 74 | control sequence is a non-printing character that influences the 75 | text. 76 | 77 | string 78 | A sequence of characters. The length of the sequence can vary at 79 | runtime. 80 | 81 | P-string 82 | A string whose length in words is indicated by prefixing a word 83 | containing that length to the character string. The prefix word 84 | itself MUST NOT be included when determining the length. 85 | 86 | C-string 87 | A string whose length is indicated by suffixing a NUL character to 88 | the character string. The first occurrence of such NUL character 89 | terminates the string. The NUL character is the character whose 90 | bits are all zero. 91 | 92 | library 93 | A group of functions used by different programs. 94 | 95 | program 96 | A sequence of machine instructions for the DCPU. 97 | 98 | user 99 | Any person using or creating a program. 100 | 101 | 1.2. Notational Conventions 102 | 103 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 104 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 105 | document are to be interpreted as described in RFC 2119 [RFC2119]. 106 | 107 | 108 | 109 | 110 | 111 | Schuetze [Page 2] 112 | 113 | String Format April 2012 114 | 115 | 116 | 2. Format 117 | 118 | A P-string is composed of a 16-bit length prefix and a sequence of n 119 | words where n is the value of the prefix. 120 | 121 | The prefix word MUST be present and MUST represent the exact number 122 | of following words. 123 | 124 | Note that the empty P-string consists entirely of a length word 125 | containing 0x0000. 126 | 127 | P-STRING = LENGTH BODY 128 | LENGTH = n 129 | BODY = nWORD 130 | WORD = %x0000-ffff 131 | ; any 16-bit value 132 | 133 | 134 | 3. Rationale 135 | 136 | This section is not normative. 137 | 138 | The rationale for using P-strings is a simple matter of weighing 139 | benefits against disadvantages. 140 | 141 | 3.1. Benefits 142 | 143 | o Accessing the length of the string is O(1) fast. 144 | 145 | o Buffer overflows are prevented by being able to allocate enough 146 | space ahead of time. 147 | 148 | * This also increases the security of programs by preventing 149 | arbitrary shell code from being executed. 150 | 151 | o The null-character can be used in strings, while using it in a 152 | C-string would terminate the string. 153 | 154 | o The same format can be used for other data structures such as 155 | length-prefixed arrays. This means that functions such as concat 156 | must only be implemented once. 157 | 158 | 3.2. Disadvantages 159 | 160 | o Indexing begins at 1 instead of 0. 161 | 162 | o Fixed-length strings still require a prefixed length word. The 163 | same would be true of fixed-length C-strings. Both formats can be 164 | 165 | 166 | 167 | Schuetze [Page 3] 168 | 169 | String Format April 2012 170 | 171 | 172 | abbreviated by omitting the known prefix/terminator at the cost of 173 | ceasing to be a P- or C-string per the definitions given here. 174 | 175 | 176 | 4. Other Notes 177 | 178 | o Since the smallest addressable size in the DCPU is a word (16 179 | bits), this effectively allows a maximum string length of 65536 180 | characters without any loss in efficiency. 181 | 182 | o Cutting off the beginning of a string is more expensive for 183 | P-strings, but cutting off the end is more expensive for 184 | C-strings. (Other solutions are possible, but introduce memory 185 | leaks.) Therefore, the two arguments negate each other. 186 | 187 | o The names P-string and C-string come from Pascal and C, which use 188 | the respective format. 189 | 190 | o The current implementation of characters in the DCPU effectively 191 | leaves the high 8 bits empty. It is therefore possible to store 192 | two characters in one word. Such packed strings are outside the 193 | scope of this RFC. 194 | 195 | 196 | 5. Security Considerations 197 | 198 | Using P-strings reduces the risk of arbitrary shell code being 199 | executed by overflowing the input buffer. However, hidden 200 | instructions in the string may be executed later when the sections 201 | are not cleared and the stack or instruction pointer is moved there. 202 | Measures should be taken by the user to ensure this does not happen. 203 | 204 | 205 | 6. References 206 | 207 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 208 | Requirement Levels", BCP 14, RFC 2119, March 1997. 209 | 210 | 211 | Author's Address 212 | 213 | Malte Schuetze 214 | 215 | Email: malte.schuetze@fgms.de 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | Schuetze [Page 4] 224 | 225 | -------------------------------------------------------------------------------- /LIB/Draft-String-Format.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | String Format 15 | 16 | 17 |
18 | malte.schuetze@fgms.de 19 |
20 | 21 | 22 | 23 | Lib 24 | 0x10c Standards Committee 25 | String 26 | String Format 27 | Library Specifications 28 | 29 | This document presents a general format for strings in 30 | libraries intended to be shared across programs and with 31 | other users. 32 | 33 | 34 | 35 | 36 |
37 | Shared Libraries depend on certain formats being given. 38 | Strings, being a common argument type for cross-library 39 | calls, should therefore be standardized. Length-prefixed 40 | strings are to be used for security and efficiency reasons. 41 | 42 |
43 | 44 | 45 | 46 | 47 | 16 bits. 48 | This is the smallest unit addressable by the DCPU. 49 | 50 | 51 | 52 | A group of bits representing a glyph or control sequence. A 53 | control sequence is a non-printing character that 54 | influences the text. 55 | 56 | 57 | 58 | A sequence of characters. 59 | The length of the sequence can vary at runtime. 60 | 61 | 62 | 63 | A string whose length in words is indicated by prefixing 64 | a word containing that length to the character string. 65 | The prefix word itself MUST NOT be included when 66 | determining the length. 67 | 68 | 69 | 70 | A string whose length is indicated by suffixing a NUL 71 | character to the character string. The first occurrence of 72 | such NUL character terminates the string. The NUL character 73 | is the character whose bits are all zero. 74 | 75 | 76 | 77 | A group of functions used by different programs. 78 | 79 | 80 | 81 | A sequence of machine instructions for the DCPU. 82 | 83 | 84 | 85 | Any person using or creating a program. 86 | 87 | 88 | 89 |
90 |
91 | The key words "MUST", "MUST NOT", "REQUIRED", 92 | "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", 93 | "RECOMMENDED", "MAY", and "OPTIONAL" in this document 94 | are to be interpreted as described in RFC 2119. 96 |
97 |
98 |
99 | A P-string is composed of a 16-bit length prefix and a 100 | sequence of n words where n is the value of the prefix. 101 | 102 | The prefix word MUST be present and MUST represent the exact 103 | number of following words. 104 | Note that the empty P-string consists entirely of a length word 105 | containing 0x0000. 106 |
107 | 114 |
115 |
116 |
117 | This section is not normative. 118 | The rationale for using P-strings is a simple matter of 119 | weighing benefits against disadvantages. 120 |
121 | 122 | 123 | Accessing the length of the string is O(1) fast. 124 | Buffer overflows are prevented by being able to 125 | allocate enough space ahead of time. 126 | 127 | This also increases the security of programs 128 | by preventing arbitrary shell code from being 129 | executed. 130 | 131 | 132 | The null-character can be used in strings, while 133 | using it in a C-string would terminate the string. 134 | The same format can be used for other data structures 135 | such as length-prefixed arrays. This means that 136 | functions such as concat must only be implemented once. 137 | 138 | 139 |
140 |
141 | 142 | 143 | Indexing begins at 1 instead of 0. 144 | Fixed-length strings still require a prefixed length word. 145 | The same would be true of fixed-length C-strings. Both formats 146 | can be abbreviated by omitting the known prefix/terminator 147 | at the cost of ceasing to be a P- or C-string per the 148 | definitions given here. 149 | 150 | 151 |
152 |
153 |
154 | 155 | 156 | Since the smallest addressable size in the DCPU is a 157 | word (16 bits), this effectively allows a maximum string 158 | length of 65536 characters without any loss in 159 | efficiency. 160 | Cutting off the beginning of a string is more 161 | expensive for P-strings, but cutting off the end is 162 | more expensive for C-strings. (Other solutions are 163 | possible, but introduce memory leaks.) Therefore, the 164 | two arguments negate each other. 165 | The names P-string and C-string come from Pascal and 166 | C, which use the respective format. 167 | The current implementation of characters in the DCPU 168 | effectively leaves the high 8 bits empty. It is therefore 169 | possible to store two characters in one word. Such packed 170 | strings are outside the scope of this RFC. 171 | 172 | 173 |
174 |
175 | Using P-strings reduces the risk of arbitrary shell 176 | code being executed by overflowing the input buffer. 177 | However, hidden instructions in the string may be executed 178 | later when the sections are not cleared and the stack or 179 | instruction pointer is moved there. Measures should be 180 | taken by the user to ensure this does not happen. 181 |
182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | -------------------------------------------------------------------------------- /NET/Draft_OSI_Physical_Layer.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | A Physical layer application for DCPU-16 6 | 7 | 8 | 0x10c Standards Committee 9 | 10 |
11 | cyberjacob@gmail.com 12 |
13 | 14 | 15 | Networking 16 | 0x10c Standards Committee 17 | 18 | This document provides a theoretical implementation of the physical layer of the OSI model on the DCPU-16 platform. 19 | 20 | 21 | 22 |
23 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. 24 | This implementation has been written in such a way that more than one CPU can communicate on the same physical bus. it does not cover routing and addressing of data, as this is not part of the physical/link level. 25 |
26 | 27 | ATU: arbitrary time unit. A period of time or delay that MAY vary due to circumstances outside the control of the player. E.G. CPU response time, link latency, etc. 28 | sender: the CPU initiating the data transfer, from which the transfer originates, that contains the data to be transferred before the transfer is started. 29 | recipient: the CPU accepting data from the sender, which does not have any of the data used in the transfer at the start of the transfer 30 | 31 |
32 |
33 |
34 |
35 | It SHOULD be noted that as the 0x10c game is still in development, the full specifications of the DCPU-16 processor are subject to change at any time in the future. 36 |
37 |
38 | The current specifications at the time of the last update of this document (Wednesday 11th April 2012) are: 39 | 40 | 16 bit unsigned words 41 | 0x10000 words of ram 42 | 8 registers (A, B, C, X, Y, Z, I, J) 43 | program counter (PC) 44 | stack pointer (SP) 45 | overflow (O) 46 | Instructions are 1-3 words long and are fully defined by the first word. 47 | 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 48 | If any instruction tries to assign a literal value, the assignment fails silently. Other than that, the instruction behaves as normal. 49 | All values that read a word (0x10-0x17, 0x1e, and 0x1f) take 1 cycle to look up. The rest take 0 cycles. 50 | 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" 51 | 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. 52 | JSR takes 2 cycles, plus the cost of a. 53 | 54 | For clarity, the opcodes and FAQ have not been included in this summary. 55 |
56 |
57 | There have been no official press releases from Mojang on the following information, however this document was written with the following assumptions: 58 | 59 | The DCPU-16 processor has no support for interrupts 60 | The DCPU-16 processor has support for basic electrical input/output operations 61 | The 0x10c game realistically simulates electrical physics 62 | 63 |
64 |
65 |
66 | The lack of interrupts can mainly be solved by a vigorous clocking of all the data. 67 | This would be achieved by the use of three physical signalling lines between the CPUs wishing to communicate. These lines would be titled PTS, PTS-ACK and DATA. 68 |
69 | The data line would be used for the actual data being transferred between two CPUs. 70 | Each bit of data would be present on the Data line for 4 ATUs, without a need to clear the line between bits. 71 | The data line SHOULD be kept low at all times when a data transfer is not taking place. 72 | If a sending CPU needs to abort a data transfer, it MUST remove it's PTS before the data. 73 |
74 |
75 | The PTS (Permission To Send) line is used by the sending CPU to request the recipient CPU's attention. 76 | The PTS line is pulled high by the sending CPU for two ATUs in each data transfer bit, to indicate that the next bit of data has been placed onto the data line. 77 |
78 | The PTS line SHOULD be pulled high by the sending CPU when no transfer is taking place, to indicate that the CPU wishes to start a transfer. 79 | The transfer-start PTS is RECOMMENDED, and is used to ensure that two sending CPUs do not start a transfer at the same time. 80 | A sending CPU MUST NOT ack a PTS transfer-start request when is is sending, or wishes to start sending. 81 | A sending CPU that does not receive an ack for it's transfer-start PTS MUST NOT begin transferring data. It MUST withdraw the PTS after a reasonable amount of time, and try again later 82 | A sending CPU SHOULD NOT attempt to start a transfer while an existing transfer is taking place, however the transfer-start PTS exists as a failsafe for this not being observed. 83 | If the sending CPU detects the PTS line has been brought high by another CPU during it's data transfer, the sending CPU SHOULD abort it's data transfer immediately. 84 |
85 |
86 |
87 | The PTS-ACK line is used by the recipient CPU(s) to indicate they have PTS from the sending CPU, and have acted accordingly. 88 | If the PTS indicates that the sending CPU wants to initiate a transfer, the PTS-ACK would indicate that the recipient CPU is ready to start the transfer. 89 | If the PTS indicates that the next bit of data has been stored on the CPU, and that it can safely be removed from the data line. 90 | The PTS-ACK line is inverse to it's meaning, to enable multiple CPUs to communicate on the same physical bus. This ensures that all CPUs on the bus have ack'd the PTS before the sending CPU will recognise the PTS-ACK signal. 91 | Because of this, a quick link latency will result in the PTS-ACK line mirroring the PTS line, with approximately 1 CPU cycle delay. 92 | A sending CPU MAY choose to withdraw it's transmission attempt if a recipient CPU does not ack the PTS within a reasonable amount of time. If doing this, the sending CPU MUST remove the PTS before the data 93 | If a recipient CPU needs to abort a data transfer, it MAY be done by not responding to a PTS. This SHOULD activate the sending CPU's timeout, and cause it to abort the transfer. 94 |
95 |
96 | An example transfer of the binary data "10110101010101" would go as follows: 97 | 98 | Dir Line Data 99 | O Data: _____****____********____****____*********____****____****____****____ 100 | O PTS: __**__**__**__**__**__**__**__**__*******__**__**__**__**__**__**_____ 101 | I PTS-ACK:***_**_*_*__**__**__**__**__**__*******__**__**__**__**__**__**__***** 102 | ATU Frame: 0000000001111111111222222222233333333334444444444555555555566666666677 103 | 1234567890123456789012345678901234567890123456780123456789012345678901 104 | 105 | 106 | Notes: 107 | 108 | Direction is relative to the sender. 109 | Each character represents one ATU frame, which is one ATU in length. 110 | A "*" is equivalent to binary 1. 111 | An "_" is equivalent to binary 0. 112 | The demonstration shows an example of a CPU taking a long time to respond between frames 35 and 39 113 | 114 | 115 |
116 |
117 |
118 | This memo raises no security issues; however, according to RFC2223, your document should contain a section near the end that discusses the security considerations of the protocol or procedures that are the main topic of your document. 119 |
120 | 121 | 122 | 123 | 124 | -------------------------------------------------------------------------------- /NET/Draft_OSI_Physical_Layer.txt: -------------------------------------------------------------------------------- 1 | Network Working Group J. Mansfield 2 | Internet-Draft 0x10C-Std 3 | Expires: October 14, 2012 April 12, 2012 4 | 5 | 6 | A Physical layer application for DCPU-16 7 | Draft_OSI_Physical_Layer 8 | 9 | Abstract 10 | 11 | This document provides a theoretical implementation of the physical 12 | layer of the OSI model on the DCPU-16 platform. 13 | 14 | Status of this Memo 15 | 16 | This document is a Draft and is in full conformance with 17 | all provisions of Section 10 of RFC 2026. 18 | 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 | Mansfield Expires October 14, 2012 [Page 1] 55 | 56 | Internet-Draft A Physical layer application for DCPU-16 April 2012 57 | 58 | 59 | 1. Preamble 60 | 61 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 62 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 63 | document are to be interpreted as described in RFC 2119. 64 | 65 | This implementation has been written in such a way that more than one 66 | CPU can communicate on the same physical bus. it does not cover 67 | routing and addressing of data, as this is not part of the physical/ 68 | link level. 69 | 70 | 1.1. Definitions 71 | 72 | ATU: arbitrary time unit. A period of time or delay that MAY vary 73 | due to circumstances outside the control of the player. E.G. CPU 74 | response time, link latency, etc. 75 | 76 | sender: the CPU initiating the data transfer, from which the 77 | transfer originates, that contains the data to be transferred 78 | before the transfer is started. 79 | 80 | recipient: the CPU accepting data from the sender, which does not 81 | have any of the data used in the transfer at the start of the 82 | transfer 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | Mansfield Expires October 14, 2012 [Page 2] 111 | 112 | Internet-Draft A Physical layer application for DCPU-16 April 2012 113 | 114 | 115 | 2. Hardware Limitations 116 | 117 | 2.1. Full details unknown 118 | 119 | It SHOULD be noted that as the 0x10c game is still in development, 120 | the full specifications of the DCPU-16 processor are subject to 121 | change at any time in the future. 122 | 123 | At the last revision of this RFC, version 1.1 of the DCPU-16 124 | specifications have been released. 125 | 126 | 2.2. Assumed Information 127 | 128 | There have been no official press releases from Mojang on the 129 | following information, however this document was written with the 130 | following assumptions: 131 | 132 | The DCPU-16 processor has no support for interrupts 133 | 134 | The DCPU-16 processor has support for basic electrical input/ 135 | output operations 136 | 137 | The 0x10c game realistically simulates electrical physics 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 | 165 | 166 | Mansfield Expires October 14, 2012 [Page 3] 167 | 168 | Internet-Draft A Physical layer application for DCPU-16 April 2012 169 | 170 | 171 | 3. Implementation 172 | 173 | The lack of interrupts can mainly be solved by a vigorous clocking of 174 | all the data. 175 | 176 | This would be achieved by the use of three physical signalling lines 177 | between the CPUs wishing to communicate. These lines would be titled 178 | PTS, PTS-ACK and DATA. 179 | 180 | 3.1. Data 181 | 182 | The data line would be used for the actual data being transferred 183 | between two CPUs. 184 | 185 | Each bit of data would be present on the Data line for 4 ATUs, 186 | without a need to clear the line between bits. 187 | 188 | The data line SHOULD be kept low at all times when a data transfer is 189 | not taking place. 190 | 191 | If a sending CPU needs to abort a data transfer, it MUST remove it's 192 | PTS before the data. 193 | 194 | 3.2. PTS 195 | 196 | The PTS (Permission To Send) line is used by the sending CPU to 197 | request the recipient CPU's attention. 198 | 199 | The PTS line is pulled high by the sending CPU for two ATUs in each 200 | data transfer bit, to indicate that the next bit of data has been 201 | placed onto the data line. 202 | 203 | 3.2.1. transfer-start requests 204 | 205 | The PTS line SHOULD be pulled high by the sending CPU when no 206 | transfer is taking place, to indicate that the CPU wishes to start a 207 | transfer. 208 | 209 | The transfer-start PTS is RECOMMENDED, and is used to ensure that two 210 | sending CPUs do not start a transfer at the same time. 211 | 212 | A sending CPU MUST NOT ack a PTS transfer-start request when is is 213 | sending, or wishes to start sending. 214 | 215 | A sending CPU that does not receive an ack for it's transfer-start 216 | PTS MUST NOT begin transferring data. It MUST withdraw the PTS after 217 | a reasonable amount of time, and try again later 218 | 219 | 220 | 221 | 222 | Mansfield Expires October 14, 2012 [Page 4] 223 | 224 | Internet-Draft A Physical layer application for DCPU-16 April 2012 225 | 226 | 227 | A sending CPU SHOULD NOT attempt to start a transfer while an 228 | existing transfer is taking place, however the transfer-start PTS 229 | exists as a failsafe for this not being observed. 230 | 231 | If the sending CPU detects the PTS line has been brought high by 232 | another CPU during it's data transfer, the sending CPU SHOULD abort 233 | it's data transfer immediately. 234 | 235 | 3.3. PTS-ACK 236 | 237 | The PTS-ACK line is used by the recipient CPU(s) to indicate they 238 | have PTS from the sending CPU, and have acted accordingly. 239 | 240 | If the PTS indicates that the sending CPU wants to initiate a 241 | transfer, the PTS-ACK would indicate that the recipient CPU is ready 242 | to start the transfer. 243 | 244 | If the PTS indicates that the next bit of data has been stored on the 245 | CPU, and that it can safely be removed from the data line. 246 | 247 | The PTS-ACK line is inverse to it's meaning, to enable multiple CPUs 248 | to communicate on the same physical bus. This ensures that all CPUs 249 | on the bus have ack'd the PTS before the sending CPU will recognise 250 | the PTS-ACK signal. 251 | 252 | Because of this, a quick link latency will result in the PTS-ACK line 253 | mirroring the PTS line, with approximately 1 CPU cycle delay. 254 | 255 | A sending CPU MAY choose to withdraw it's transmission attempt if a 256 | recipient CPU does not ack the PTS within a reasonable amount of 257 | time. If doing this, the sending CPU MUST remove the PTS before the 258 | data 259 | 260 | If a recipient CPU needs to abort a data transfer, it MAY be done by 261 | not responding to a PTS. This SHOULD activate the sending CPU's 262 | timeout, and cause it to abort the transfer. 263 | 264 | 265 | 266 | 267 | 268 | 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 | 277 | 278 | Internet-Draft A Physical layer application for DCPU-16 April 2012 279 | 280 | Mansfield Expires October 14, 2012 [Page 5] 281 | 282 | 283 | 284 | An example transfer of the binary data "10110101010101" would go as 285 | follows: 286 | 287 | Dir Line Data 288 | O Data: _____****____********____****____*********____****____****____****____ 289 | O PTS: __**__**__**__**__**__**__**__**__*******__**__**__**__**__**__**_____ 290 | I PTS-ACK:***_**_*_*__**__**__**__**__**__*******__**__**__**__**__**__**__***** 291 | ATU Frame: 0000000001111111111222222222233333333334444444444555555555566666666677 292 | 1234567890123456789012345678901234567890123456780123456789012345678901 293 | 294 | Notes: 295 | 296 | Direction is relative to the sender. 297 | 298 | Each character represents one ATU frame, which is one ATU in 299 | length. 300 | 301 | A "*" is equivalent to binary 1. 302 | 303 | An "_" is equivalent to binary 0. 304 | 305 | The demonstration shows an example of a CPU taking a long time to 306 | respond between frames 35 and 39 307 | 308 | Figure 1 309 | 310 | 311 | 312 | 313 | 314 | 4. Security Considerations 315 | 316 | This memo raises no security issues; however, according to RFC2223, 317 | your document should contain a section near the end that discusses 318 | the security considerations of the protocol or procedures that are 319 | the main topic of your document. 320 | 321 | 322 | 323 | 324 | 325 | Author's Address 326 | 327 | Jacob Mansfield 328 | the 0x10c Standards Committee 329 | 330 | Email: cyberjacob@gmail.com 331 | 332 | 333 | 334 | Mansfield Expires October 14, 2012 [Page 8] 335 | 336 | 337 | 338 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 346 | 347 | 348 | 349 | 350 | 351 | 352 | 353 | 354 | 355 | 356 | 357 | 358 | 359 | 360 | 361 | 362 | 363 | 364 | 365 | 366 | 367 | 368 | 369 | 370 | 371 | 372 | 373 | 374 | 375 | Mansfield Expires October 14, 2012 [Page 10] 376 | 377 | -------------------------------------------------------------------------------- /ASM/Draft_Extension_Declaration_Table.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | Extension Declaration Table 15 | 16 | 18 | Redpoint Software 19 | 20 |
21 | jrhodes@redpointsoftware.com.au 22 | http://www.redpointsoftware.com.au/ 23 |
24 | 25 | 26 | 27 | Asm 28 | 0x10c Standards Committee 29 | 30 | This draft provides a formal structure for assemblers to notify 31 | emulators what non-standard extensions a specific set of binary 32 | code is relying on (such as input or hardware interfaces). 33 | 34 | 35 | 36 | 37 |
38 | There are currently a wide variety of implementations for hardware 39 | components such as screens and keyboard input. Each implementation 40 | of this hardware varies between emulator causing unintended discrepancies 41 | when running assembly code in a different emulator. 42 | This RFC strives 43 | to ensure that emulators provide only standard functionality unless 44 | experimental features are explicitly requested when assembling the code 45 | originally. 46 | 47 |
48 | 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. 52 |
53 |
54 | 55 |
56 | An extension is herein defined as a request for additional functionality 57 | to be provided by the emulator or assembler which is not yet an approved 58 | standard. 59 | This includes functionality which is widely used in the 60 | community (screens and keyboard input at the time of writing) that has 61 | not yet been confirmed by Notch. 62 |
63 | 64 |
65 | For the purposes of this draft, the role of assemblers is to generate 66 | code from a defined syntax to DCPU-16 bytecode. 67 | In this case, assemblers MUST generate an extension table, unless 68 | the total number of extensions requested is 0, in which case the 69 | assembler MUST NOT generate an extension table. 70 | Assemblers SHOULD support a directive format that allows users to 71 | specify which extensions they wish to use, although the exact syntax 72 | of the format is not specified. If an assembler provides syntax to 73 | the user to enable a given extension, they MUST use the extension 74 | names specified in this document. If an assembler does not provide 75 | a syntax to enable specific extensions, it MUST NOT emit an extension 76 | table under any circumstances. From herein, the syntax through which 77 | an assembler allows extensions to be enabled will be referred to as 78 | the 'extension directive'. 79 | When functionality that was previously provided via an extension 80 | becomes standardized, assemblers that have support for recognising the specific 81 | extension SHOULD continue to recognise it in the extension directive 82 | for a reasonable period, after which they MAY drop recognising it 83 | (for example, at a next major release). 84 | If an assembler did not previously recognise a specific 85 | extension name, and the extension becomes standardized, then the 86 | assembler SHOULD NOT recognise the extension name in the extension 87 | directive, unless it is still widely used. 88 |
89 | 90 |
91 | For the purposes of this draft, the role of emulators is to execute 92 | DCPU-16 bytecode produced by an assembler according to standards laid 93 | out officially by Notch and the committee. 94 | If an emulator is executing bytecode which does not have an extension 95 | table in the specified format, it MUST NOT provide any additional features 96 | other than those defined in standards. 97 | Emulators MUST NOT provide non-standard functionality unless it is 98 | specifically requested by the code. This includes current non-standard 99 | extensions such as screens and keyboard input; emulators MUST stop providing 100 | this functionality to code that does not request it. [The author of this 101 | draft is aware that this will prevent existing compiled code from working 102 | in standardized emulators; this is intended to ensure code standardization] 103 | Emulators MAY drop support or add support for extensions at any time, 104 | without any prerequisites on doing so. 105 | Unlike assemblers, when functionality that was previously provided 106 | via an extension becomes standardized, emulators MUST continue to support 107 | the extension in the extension table. 108 | In addition, when functionality that was previously provided via 109 | an extension that the emulator did not support becomes standardized, 110 | emulators MUST support the new standard and MUST recognise the previously 111 | used extension name (although it will not affect emulator functionality 112 | as the extension functionality is now standard). 113 |
114 | 115 |
116 | For purposes of future versioning, this document specifies version 1 117 | of the extension table format. 118 | The format of the extension table is as follows: 119 | 120 | Field 121 | Size 122 | Magic number (0xF100) 123 | Single word 124 | Version number (0x0001) 125 | Single word 126 | Number of entries in table 127 | Single word 128 | Entry 1 129 | String length + 1 130 | ... 131 | ... 132 | Entry N 133 | String length + 1 134 | 135 | Each string is a unique entry, and one either defined in the 136 | table below, or may be a non-standard name (providing it is 137 | unique and meaningful) that is defined by either an assembler 138 | or emulator. 139 | Strings are formatted with each ASCII character taking up a 140 | single word, plus a NULL terminator (which also takes up a single 141 | word). Thus the size of a string is the number of characters, 142 | plus one for the terminator (as shown in the table above). 143 | Note that the "Number of entries" is strictly this; the table 144 | does not expose it's total size in words. 145 |
146 | 147 |
148 | The assembly extension table must be positioned inside the generated 149 | code, but have no effect on the program execution. 150 | When an assembler generates an extension table, the first instruction 151 | MUST be a jump to the start of the actual program code. This results 152 | in the first two words being: 153 | 154 | Contents of single Word 155 | SET PC, <next word literally> 156 | Location of first program instruction 157 | 158 | It is important to note that assemblers will have to offset all label 159 | addresses by the total size (not number of entries) of the extension 160 | table, plus the two words at the start. 161 |
162 | 163 |
164 | The following is a list of extension names currently applicable. 165 | Assemblers and emulators SHOULD support these directives until such 166 | time as the specific functionality is standardized. 167 | 168 | Name 169 | experimental-output-screen-32x12-0x8000 170 | experimental-output-screen-32x16-0x8000 171 | experimental-input-keyboard-single-0x9000 172 | 173 | Individual assemblers and emulators may support names outside 174 | these values. If an emulator encounters an extension name that 175 | it can not handle, it MUST NOT execute the byte code. 176 | Likewise, if an assembler encounters an extension name that it does not 177 | recognise, it MUST NOT assemble the byte code and MUST inform 178 | the user that it does not support the extension name. 179 | 180 |
181 | Indiciates that the code wishes for a memory-mapped screen to 182 | be positioned at 0x8000 in RAM, with a size of 32x12. 183 |
184 | 185 |
186 | Indiciates that the code wishes for a memory-mapped screen to 187 | be positioned at 0x8000 in RAM, with a size of 32x16. 188 |
189 | 190 |
191 | Indiciates that the code wishes for the ASCII code of the last 192 | key pressed to be placed at 0x9000. The emulator only exposes the single, 193 | last key pressed and MUST NOT clear the position when the key 194 | is released. The emulator MUST continue to set the value of 195 | 0x9000 whileever a key is held down. 196 |
197 |
198 | 199 |
200 | The extension table is read once at the start by an emulator and hence 201 | even if the program overwrites it's own extension table, it has no effect 202 | on on-going execution. 203 | Emulators MUST NOT enable features if the extension table changes 204 | at run-time. 205 |
206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | -------------------------------------------------------------------------------- /MISC/Open_Letter_Notch.txt: -------------------------------------------------------------------------------- 1 | Dear Notch, 2 | 3 | I'm writing to you on behalf of #0x10c-std community at Freenode IRC. We have been discussing various ideas for DCPU-16 4 | for a couple of days now and in the process devised much improved DCPU-16 specification. Our rationale for changes is to 5 | keep emulation complexity minimal, yet enable DCPU to be as flexible as possible for people to be able to do really cool 6 | stuff with it. 7 | 8 | As you see we also propose very simple interrupts mechanisim. We believe that it is vital for DCPU to become really 9 | general-purpose processor since interrupts allow among many things: flexible timers or preemptive task-switching to 10 | happen. However we kept the complexity minimal so DCPU is capable of only one interrupt handler and no interrupt 11 | queues or priorities. We believe the gains to DCPU capabilites are worth increased emulation cost. 12 | 13 | Please reconsider implementing this simple interrupt system. :) 14 | 15 | As closing words I'd like you to know that we think you're doing great job with 0x10c! 16 | We never had this much fun with game that isn't even released yet. Keep up the good work! 17 | 18 | - The #0x10c-std community. 19 | 20 | *** DCPU16 SPECIFICATION FOLLOWS *** 21 | 22 | DCPU-16 Specification 23 | Copyright 2012 Mojang 24 | Version 1.2 25 | Edited by: 0x10c Standards Committee (rmmh, Jarvix, tpw_rules, et al) 26 | 27 | * 16 bit words 28 | * 0x10000 words of ram 29 | * 8 registers (A, B, C, X, Y, Z, I, J) 30 | * program counter (PC) 31 | * stack pointer (SP) 32 | * extra/excess (EX) 33 | * control register (CR) internal 34 | 35 | In this document, anything within [brackets] is shorthand for "the value of the RAM at the location of the value inside the brackets". 36 | For example, SP means stack pointer, but [SP] means the value of the RAM at the location the stack pointer is pointing at. 37 | 38 | Whenever the CPU needs to read a word, it reads [PC], then increases PC by one. Shorthand for this is [PC++]. 39 | In some cases, the CPU will modify a value before reading it, in this case the shorthand is [++PC]. 40 | 41 | Instructions are 1-3 words long and are fully defined by the first word. 42 | In a basic instruction, the lower five bits of the first word of the instruction are the opcode, 43 | and the remaining eleven bits are split into a five bit value a and a six bit value b. 44 | a is always handled by the processor after b, and is the lower five bits. 45 | In bits (with the least significant being last), a basic instruction has the format: bbbbbbaaaaaooooo 46 | 47 | 48 | 49 | Values: (5/6 bits) 50 | 0x00-0x07: register (A, B, C, X, Y, Z, I or J, in that order) 51 | 0x08-0x0f: [register] 52 | 0x10-0x17: [register + next word] 53 | 0x18: (PUSH / [--SP]) if in a, or (POP / [SP++]) if in b 54 | 0x19: [SP] / PEEK 55 | 0x1a: [SP + next word] / PICK n 56 | 0x1b: SP 57 | 0x1c: PC 58 | 0x1d: EX 59 | 0x1e: [next word] 60 | 0x1f: next word (literal) 61 | 0x20-0x3f: literal value 0xffff-0x1e (-1..30) (literal) (only for b) 62 | 63 | * "next word" really means "[PC++]". These increase the word length of the instruction by 1. 64 | * All values that read a word (0x10-0x17, 0x1e, and 0x1f) take 1 cycle to look up. The rest take 0 cycles. 65 | * 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" 66 | 67 | 68 | 69 | Basic opcodes: (5 bits) 70 | 0x0: special instruction - see below 71 | 0x1: SET a, b - sets a to b 72 | 0x2: ADD a, b - sets a to a+b, sets EX to 0x0001 if there's an overflow, 0x0 otherwise 73 | 0x3: SUB a, b - sets a to a-b, sets EX to 0xffff if there's an underflow, 0x0 otherwise 74 | 0x4: MUL a, b - sets a to a*b, sets EX to ((a*b)>>16)&0xffff (treats a, b as unsigned) 75 | 0x5: MLI a, b - like MUL, but treat a, b as signed 76 | 0x6: DIV a, b - sets a to a/b, sets EX to ((a<<16)/b)&0xffff. if b==0, sets a and EX to 0 instead. (treats a, b as unsigned) 77 | 0x7: DVI a, b - like DIV, but treat a, b as signed 78 | 0x8: MOD a, b - sets a to a%b. if b==0, sets a to 0 instead. 79 | 0x9: AND a, b - sets a to a&b 80 | 0xa: BOR a, b - sets a to a|b 81 | 0xb: XOR a, b - sets a to a^b 82 | 0xc: SHR a, b - sets a to a>>>b, sets EX to ((a<<16)>>b)&0xffff (logical shift) 83 | 0xd: ASR a, b - sets a to a>>b, sets EX to ((a<<16)>>>b)&0xffff (arithmetic shift) (treats a as signed) 84 | 0xe: SHL a, b - sets a to a<>16)&0xffff 85 | 0x10: special instruction - see below 86 | 0x11: IFB a, b - performs next instruction only if (a&b)!=0 (Bit set) 87 | 0x12: IFE a, b - performs next instruction only if a==b (Equal) 88 | 0x13: IFN a, b - performs next instruction only if a!=b (Not equal) 89 | 0x14: IFG a, b - performs next instruction only if a>b (signed) (Greater) 90 | 0x15: IFA a, b - performs next instruction only if a>b (unsigned) (Above) 91 | 0x16: IFL a, b - performs next instruction only if a" is a one-instruction JMP. 125 | For small relative jumps in a single word, you can even do "ADD PC, " or "SUB PC, ". 126 | For RET, simply do "SET PC, POP" 127 | 128 | Q: How does the extra register (EX) work? 129 | A: EX is set by certain instructions (see above), but never automatically read. You can use its value in instructions, however. 130 | For example, to do a 32 bit add of 0x12345678 and 0xaabbccdd, do this: 131 | SET [0x1000], 0x5678 ; low word 132 | SET [0x1001], 0x1234 ; high word 133 | ADD [0x1000], 0xccdd ; add low words, sets EX to either 0 or 1 (in this case 1) 134 | ADD [0x1001], EX ; add EX to the high word 135 | ADD [0x1001], 0xaabb ; add high words, sets EX again (to 0, as 0xaabb+0x1235 is lower than 0x10000) 136 | 137 | Q: How do I do 32 or 64 bit division using EX? 138 | A: This is left as an exercise for the reader. 139 | 140 | Q: How about a quick example? 141 | A: Sure! Here's some sample assembler, and a memory dump of the compiled code: 142 | 143 | ; Try some basic stuff 144 | SET A, 0x30 ; 7c01 0030 145 | SET [0x1000], 0x20 ; 7de1 1000 0020 146 | SUB A, [0x1000] ; 7803 1000 147 | IFN A, 0x10 ; c00d 148 | SET PC, crash ; 7dc1 001a [*] 149 | 150 | ; Do a loopy thing 151 | SET I, 10 ; a861 152 | SET A, 0x2000 ; 7c01 2000 153 | :loop SET [0x2000+I], [A] ; 2161 2000 154 | SUB I, 1 ; 8463 155 | IFN I, 0 ; 806d 156 | SET PC, loop ; 7dc1 000d [*] 157 | 158 | ; Call a subroutine 159 | SET X, 0x4 ; 9031 160 | JSR testsub ; 7c10 0018 [*] 161 | SET PC, crash ; 7dc1 001a [*] 162 | 163 | :testsub SHL X, 4 ; 9037 164 | SET PC, POP ; 61c1 165 | 166 | ; Hang forever. X should now be 0x40 if everything went right. 167 | :crash SET PC, crash ; 7dc1 001a [*] 168 | 169 | ; [*]: Note that these can be one word shorter and one cycle faster by using the short form (0x00-0x1f) of literals, 170 | ; but my assembler doesn't support short form labels yet. 171 | 172 | Full memory dump: 173 | 174 | 0000: 7c01 0030 7de1 1000 0020 7803 1000 c00d 175 | 0008: 7dc1 001a a861 7c01 2000 2161 2000 8463 176 | 0010: 806d 7dc1 000d 9031 7c10 0018 7dc1 001a 177 | 0018: 9037 61c1 7dc1 001a 0000 0000 0000 0000 178 | 179 | ====== Interrupts ====== 180 | 181 | == Enabling interrupts 182 | To enable interrupts, the address of your handler and the interrupt flag have to be set. 183 | The address of the handler should be put into a -to-be-defined-location-. 184 | 185 | The program will do something along the lines: 186 | 187 | SET [0xFFFE], myHandler ; set the address of the handler into the predefined location (0xFFFE is an example) 188 | XOR CR, 1 ; enable the interrupt flag 189 | 190 | == An interrupt occurs 191 | The virtual machine received an interrupt (or creates one). 192 | The VM will do the following: 193 | 194 | 1. Verify the Interrupt Flag is 1 by AND-ing CR with 1 and comparing. 195 | If it is 0, skip interrupt handling 196 | If it is 1, set it to 0 and continue interrupt handling 197 | 2. It reads the handler address from the predefined location in memory 198 | 3. If the address equals 0xFFFF, handling the interrupts is skipped 199 | 5. Pushes the PC onto the stack 200 | 6. Pushes the argument onto the stack 201 | 7. Pushes the interrupt number onto the stack 202 | 8. It calls the handler with SET PC,handler 203 | The handler performs the action and returns directly to the interrupted code 204 | 205 | The INT opcode does the same as a hardware interrupt. argument 2 is 0, argument 1 is the interrupt code. 206 | 207 | === Example that would be possible with this system 208 | ; Code by Jarvix 209 | 210 | ;There was an interrupt by the timer! 211 | 212 | ;;;VM 213 | 214 | ; check the IF and clear it 215 | 216 | ; This is how the stack looks 217 | SET PUSH, PC ; is current PC 218 | SET PUSH, 0 ; timer has no argument 219 | SET PUSH, 1 ; timer is interrupt 1 220 | 221 | ; vm does the lookup job 222 | ; jumps to the handler 223 | 224 | ;;;HANDLER 225 | :interruptHandler 226 | ; arg is in [SP] 227 | ; arg2 is in [SP+1] 228 | ; PC is in [SP+2] 229 | 230 | ; Save all registers 231 | SET PUSH, EX 232 | SET PUSH, A 233 | SET PUSH, B 234 | SET PUSH, C 235 | SET PUSH, X 236 | SET PUSH, Y 237 | SET PUSH, I 238 | SET PUSH, J 239 | 240 | ; Get new stack address somehow 241 | ; Each program has its own stack. 242 | ; Switching the stack pointer continues running 243 | ; the next program 244 | 245 | ; Set new stack address 246 | SET SP, newStack 247 | 248 | ; We now are on the new stack of another task, 249 | ; that also pushed their registers 250 | SET J, POP 251 | SET I, POP 252 | SET Y, POP 253 | SET X, POP 254 | SET C, POP 255 | SET B, POP 256 | SET A, POP 257 | SET EX, POP 258 | 259 | ; We restore the program 260 | 261 | ; Remove the interrupt info without clobbering 262 | SUB SP,2 263 | 264 | ; Turn on interrupts 265 | STI 266 | 267 | ; in notch-code this is SET PC,POP 268 | SET PC, POP 269 | 270 | ; We now run not in the VM but the actual code again, skipping thus the VM. -------------------------------------------------------------------------------- /ASM/Draft_Extension_Declaration_Table.txt: -------------------------------------------------------------------------------- 1 | RFC X____ (Draft-Asm) J. Rhodes, Ed. 2 | Redpoint Software 3 | April 2012 4 | 5 | 6 | Extension Declaration Table 7 | 8 | Abstract 9 | 10 | This draft provides a formal structure for assemblers to notify 11 | emulators what non-standard extensions a specific set of binary code 12 | is relying on (such as input or hardware interfaces). 13 | 14 | 15 | Table of Contents 16 | 17 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 18 | 1.1. Requirements Language . . . . . . . . . . . . . . . . . . . 2 19 | 2. Extension Definition . . . . . . . . . . . . . . . . . . . . . 2 20 | 3. Role of Assemblers . . . . . . . . . . . . . . . . . . . . . . 2 21 | 4. Role of Emulators . . . . . . . . . . . . . . . . . . . . . . . 3 22 | 5. Extension Table Format . . . . . . . . . . . . . . . . . . . . 3 23 | 6. Extension Table Positioning . . . . . . . . . . . . . . . . . . 4 24 | 7. Extension Names . . . . . . . . . . . . . . . . . . . . . . . . 5 25 | 7.1. experimental-output-screen-32x12-0x8000 . . . . . . . . . . 5 26 | 7.2. experimental-output-screen-32x16-0x8000 . . . . . . . . . . 5 27 | 7.3. experimental-input-keyboard-single-0x9000 . . . . . . . . . 5 28 | 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 29 | 9. Normative References . . . . . . . . . . . . . . . . . . . . . 6 30 | Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 6 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | Rhodes [Page 1] 53 | 54 | Extension Declaration Table April 2012 55 | 56 | 57 | 1. Introduction 58 | 59 | There are currently a wide variety of implementations for hardware 60 | components such as screens and keyboard input. Each implementation 61 | of this hardware varies between emulator causing unintended 62 | discrepancies when running assembly code in a different emulator. 63 | 64 | This RFC strives to ensure that emulators provide only standard 65 | functionality unless experimental features are explicitly requested 66 | when assembling the code originally. 67 | 68 | 1.1. Requirements Language 69 | 70 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 71 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 72 | document are to be interpreted as described in RFC 2119 [RFC2119]. 73 | 74 | 75 | 2. Extension Definition 76 | 77 | An extension is herein defined as a request for additional 78 | functionality to be provided by the emulator or assembler which is 79 | not yet an approved standard. 80 | 81 | This includes functionality which is widely used in the community 82 | (screens and keyboard input at the time of writing) that has not yet 83 | been confirmed by Notch. 84 | 85 | 86 | 3. Role of Assemblers 87 | 88 | For the purposes of this draft, the role of assemblers is to generate 89 | code from a defined syntax to DCPU-16 bytecode. 90 | 91 | In this case, assemblers MUST generate an extension table, unless the 92 | total number of extensions requested is 0, in which case the 93 | assembler MUST NOT generate an extension table. 94 | 95 | Assemblers SHOULD support a directive format that allows users to 96 | specify which extensions they wish to use, although the exact syntax 97 | of the format is not specified. If an assembler provides syntax to 98 | the user to enable a given extension, they MUST use the extension 99 | names specified in this document. If an assembler does not provide a 100 | syntax to enable specific extensions, it MUST NOT emit an extension 101 | table under any circumstances. From herein, the syntax through which 102 | an assembler allows extensions to be enabled will be referred to as 103 | the 'extension directive'. 104 | 105 | 106 | 107 | 108 | Rhodes [Page 2] 109 | 110 | Extension Declaration Table April 2012 111 | 112 | 113 | When functionality that was previously provided via an extension 114 | becomes standardized, assemblers that have support for recognising 115 | the specific extension SHOULD continue to recognise it in the 116 | extension directive for a reasonable period, after which they MAY 117 | drop recognising it (for example, at a next major release). 118 | 119 | If an assembler did not previously recognise a specific extension 120 | name, and the extension becomes standardized, then the assembler 121 | SHOULD NOT recognise the extension name in the extension directive, 122 | unless it is still widely used. 123 | 124 | 125 | 4. Role of Emulators 126 | 127 | For the purposes of this draft, the role of emulators is to execute 128 | DCPU-16 bytecode produced by an assembler according to standards laid 129 | out officially by Notch and the committee. 130 | 131 | If an emulator is executing bytecode which does not have an extension 132 | table in the specified format, it MUST NOT provide any additional 133 | features other than those defined in standards. 134 | 135 | Emulators MUST NOT provide non-standard functionality unless it is 136 | specifically requested by the code. This includes current non- 137 | standard extensions such as screens and keyboard input; emulators 138 | MUST stop providing this functionality to code that does not request 139 | it. [The author of this draft is aware that this will prevent 140 | existing compiled code from working in standardized emulators; this 141 | is intended to ensure code standardization] 142 | 143 | Emulators MAY drop support or add support for extensions at any time, 144 | without any prerequisites on doing so. 145 | 146 | Unlike assemblers, when functionality that was previously provided 147 | via an extension becomes standardized, emulators MUST continue to 148 | support the extension in the extension table. 149 | 150 | In addition, when functionality that was previously provided via an 151 | extension that the emulator did not support becomes standardized, 152 | emulators MUST support the new standard and MUST recognise the 153 | previously used extension name (although it will not affect emulator 154 | functionality as the extension functionality is now standard). 155 | 156 | 157 | 5. Extension Table Format 158 | 159 | For purposes of future versioning, this document specifies version 1 160 | of the extension table format. 161 | 162 | 163 | 164 | Rhodes [Page 3] 165 | 166 | Extension Declaration Table April 2012 167 | 168 | 169 | The format of the extension table is as follows: 170 | 171 | +----------------------------+-------------------+ 172 | | Field | Size | 173 | +----------------------------+-------------------+ 174 | | Magic number (0xF100) | Single word | 175 | | Version number (0x0001) | Single word | 176 | | Number of entries in table | Single word | 177 | | Entry 1 | String length + 1 | 178 | | ... | ... | 179 | | Entry N | String length + 1 | 180 | +----------------------------+-------------------+ 181 | 182 | Table 1: Extension Table 183 | 184 | Each string is a unique entry, and one either defined in the table 185 | below, or may be a non-standard name (providing it is unique and 186 | meaningful) that is defined by either an assembler or emulator. 187 | 188 | Strings are formatted with each ASCII character taking up a single 189 | word, plus a NULL terminator (which also takes up a single word). 190 | Thus the size of a string is the number of characters, plus one for 191 | the terminator (as shown in the table above). 192 | 193 | Note that the "Number of entries" is strictly this; the table does 194 | not expose it's total size in words. 195 | 196 | 197 | 6. Extension Table Positioning 198 | 199 | The assembly extension table must be positioned inside the generated 200 | code, but have no effect on the program execution. 201 | 202 | When an assembler generates an extension table, the first instruction 203 | MUST be a jump to the start of the actual program code. This results 204 | in the first two words being: 205 | 206 | +---------------------------------------+ 207 | | Contents of single Word | 208 | +---------------------------------------+ 209 | | SET PC, | 210 | | Location of first program instruction | 211 | +---------------------------------------+ 212 | 213 | Table 2: Extension Setup Table 214 | 215 | It is important to note that assemblers will have to offset all label 216 | addresses by the total size (not number of entries) of the extension 217 | 218 | 219 | 220 | Rhodes [Page 4] 221 | 222 | Extension Declaration Table April 2012 223 | 224 | 225 | table, plus the two words at the start. 226 | 227 | 228 | 7. Extension Names 229 | 230 | The following is a list of extension names currently applicable. 231 | Assemblers and emulators SHOULD support these directives until such 232 | time as the specific functionality is standardized. 233 | 234 | +-------------------------------------------+ 235 | | Name | 236 | +-------------------------------------------+ 237 | | experimental-output-screen-32x12-0x8000 | 238 | | experimental-output-screen-32x16-0x8000 | 239 | | experimental-input-keyboard-single-0x9000 | 240 | +-------------------------------------------+ 241 | 242 | Table 3: Extension Names 243 | 244 | Individual assemblers and emulators may support names outside these 245 | values. If an emulator encounters an extension name that it can not 246 | handle, it MUST NOT execute the byte code. 247 | 248 | Likewise, if an assembler encounters an extension name that it does 249 | not recognise, it MUST NOT assemble the byte code and MUST inform the 250 | user that it does not support the extension name. 251 | 252 | 7.1. experimental-output-screen-32x12-0x8000 253 | 254 | Indiciates that the code wishes for a memory-mapped screen to be 255 | positioned at 0x8000 in RAM, with a size of 32x12. 256 | 257 | 7.2. experimental-output-screen-32x16-0x8000 258 | 259 | Indiciates that the code wishes for a memory-mapped screen to be 260 | positioned at 0x8000 in RAM, with a size of 32x16. 261 | 262 | 7.3. experimental-input-keyboard-single-0x9000 263 | 264 | Indiciates that the code wishes for the ASCII code of the last key 265 | pressed to be placed at 0x9000. The emulator only exposes the 266 | single, last key pressed and MUST NOT clear the position when the key 267 | is released. The emulator MUST continue to set the value of 0x9000 268 | whileever a key is held down. 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 | Rhodes [Page 5] 277 | 278 | Extension Declaration Table April 2012 279 | 280 | 281 | 8. Security Considerations 282 | 283 | The extension table is read once at the start by an emulator and 284 | hence even if the program overwrites it's own extension table, it has 285 | no effect on on-going execution. 286 | 287 | Emulators MUST NOT enable features if the extension table changes at 288 | run-time. 289 | 290 | 291 | 9. Normative References 292 | 293 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 294 | Requirement Levels", BCP 14, RFC 2119, March 1997. 295 | 296 | 297 | Author's Address 298 | 299 | James Rhodes (editor) 300 | Redpoint Software 301 | 302 | Email: jrhodes@redpointsoftware.com.au 303 | URI: http://www.redpointsoftware.com.au/ 304 | 305 | 306 | 307 | 308 | 309 | 310 | 311 | 312 | 313 | 314 | 315 | 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 | 330 | 331 | 332 | Rhodes [Page 6] -------------------------------------------------------------------------------- /FS/Draft_Harrys_Allocation_Table.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | Harry's Allocation Table 15 | 16 | 18 |
19 | harry@exec64.co.uk 20 | http://www.exec64.co.uk/ 21 |
22 | 23 | 24 | Misc 25 | 0x10c Standards Committee 26 | 27 | This draft provides the specification for the HAT(Harry's Allocation 28 | Table) filesystem. It is intended to provide a clear reference for 29 | anyone wishing to implement this filesystem. 30 | 31 | 32 | 33 | 34 |
35 | This RFC provides a filesystem designed specifically for use on 36 | DCPU-16 systems. 37 | HAT is designed to be simple and easy to implement while still 38 | providing all the features required of a filesystem. 39 |
40 | 41 |
42 | HAT has a two layered design. The lower layer consists only of sectors. 43 | The lower layer is abstracted from the higher layer using "strips". The 44 | higher layer consists of inodes, links and raw file data. 45 | The lower layer deals with the management of sectors and provides 46 | access to virtual strips of disk space. 47 | The higher layer stores inodes, links and file data in these strips. 48 | Each strip (constructed in the lower layer using one or more sectors) 49 | contains an inode followed by either links or file data. 50 | Each inode represents either a file or a directory. If the inode 51 | represents a file the strip contains the inode followed immediately 52 | by all the file data. If the inode represents a directory the strip 53 | contains the inode followed by a list of links. 54 | Each link binds a file name to a file/directory. Each directory 55 | may contain several links to more directories or files, resulting 56 | in a tree growing from the root directory. 57 |
58 | 59 |
60 | This section defines the data structures that comprise the HAT 61 | filesystem. 62 | All sizes are given in words, which are considered to be 16 bits 63 | long. 64 | 65 |
66 | 67 | Section 68 | header 69 | sector map 70 | sector joins 71 | sector 0 72 | sector 1 73 | sector 2 74 | ... 75 | 76 | 77 |
78 | This structure contains the header information for HAT. 79 | 80 | 81 | Size 82 | Name 83 | 1version 84 | 1num_sectors 85 | 2sector_map_start 86 | 2sector_joins_start 87 | 2sectors_start 88 | 1sector_size 89 | 1sectors_used 90 | 91 | 92 |
93 | The version field is a magic number that identifies both that the 94 | filesystem in use is HAT and the version of HAT. 95 | The value of this field must be 0x4001. This magic number 96 | identifies the filesystem as version one of HAT. 97 |
98 | 99 |
100 | This field contains the total number of sectors in the 101 | filesystem. 102 |
103 | 104 |
105 | This field contains the address of the start of the sector map. 106 | 107 |
108 | 109 |
110 | This field contains the address of the start of the array of 111 | sector joins. 112 |
113 | 114 |
115 | This field contains the address of the first sector on disk. 116 | This is required because the first sector may not be positioned 117 | immediately after the header. The first sector may be positioned 118 | to provide alignment with the underlying disk's blocks. 119 |
120 | 121 |
122 | This field contains the size of each sector in the filesystem. 123 | 124 | This must be a power of 2, such as 128, 256 or 512. 125 |
126 | 127 |
128 | This field contains the number of sectors that are currently in 129 | use. 130 |
131 | 132 |
133 | 134 |
135 | This section is a bitmap representing which sectors are in use. 136 | It can be used to quickly locate free sectors for new files. 137 | 138 | 139 | Size 140 | Name 141 | ceil(num_sectors/16)bitmap 142 | 143 | 144 |
145 | This field is a bitmap that represents all the sectors in the 146 | filesystem. Each bit of the bitmap represents whether a sector 147 | is in use. When a sector is in use the corresponding bit is set 148 | to 1. When a sector is free, the corresponding bit is set to 0. 149 | The MSB is considered to be the first bit and the LSB is 150 | considered to be the last bit. 151 | Any spare bits at the end of the bitmap must be set to 1. 152 |
153 |
154 | 155 |
156 | This section is an array of words, each word is used to join 157 | one sector to another. 158 | 159 | 160 | Size 161 | Name 162 | 1sector0_next 163 | 1sector1_next 164 | 1sector2_next 165 | 1sector3_next 166 | 1... 167 | 168 | Each entry joins the end of one sector to the start of another, 169 | if there is no next sector the entry is set to 0. 170 | For example, if there is a strip starting in sector 0, then 171 | continuing in sector 2, then sector 1, then finishing in sector 3, 172 | then the value of sector0_next will be 2, sector1_next will be 3, 173 | sector2_next will be 1, sector3_next will be 0. 174 | The total length of this section in words is the total number 175 | of sectors in the filesystem. 176 |
177 | 178 |
179 | The sector structure is used to store blocks of raw data. 180 | Sectors themselves are just raw blocks of data with no formatting 181 | or wrapping. 182 | Each sector has the size equal to the sector_size, as defined by 183 | the header of the filesystem. 184 |
185 | 186 |
187 | 188 |
189 | 190 |
191 | The inode structure is used to store metadata about files. 192 | 193 | 194 | Size 195 | Name 196 | 1type 197 | 1num_links 198 | 2content_size 199 | 200 | 201 |
202 | 203 | 204 | value 205 | meaning 206 | 0inode is unused 207 | 1inode is a directory 208 | 2inode is a file 209 | 210 | 211 | This field indicates what type of inode it is. If this field is 212 | set to 0 then the inode is not in use and represents nothing. If 213 | this field is set to 1 then the inode represents a directory. If 214 | this field is set to 2 then the inode represents a file. 215 |
216 | 217 |
218 | This field contains the number of links there are that 219 | point to the strip containing this inode. 220 |
221 | 222 |
223 | This field contains the amount of data stored with this 224 | inode in words. 225 |
226 | 227 |
228 | 229 |
230 | 231 | Size 232 | Name 233 | 1strip_start_sector 234 | 15file_name 235 | 236 | 237 |
238 | This field contains the index of the start sector of the strip 239 | the inode being linked to is stored in. 240 |
241 | 242 |
243 | This field contains the file name to be associated with the 244 | inode that is being linked. Only alphanumeric characters, 245 | periods(.) and underscores(_) are allowed in the filename. The 246 | maximum length of the filename is 15 characters, any unused 247 | characters at the end of the filename must be set to 0x0000. 248 |
249 |
250 | 251 |
252 | 253 |
254 | 255 |
256 | This section contains information and examples on the operation 257 | and usage of the HAT filesystem. It is meant only as a rough guide 258 | for someone who is wishing to implement HAT. 259 | 260 |
261 | The HAT filesystem is very simple to construct. The creation 262 | of the filesystem can be split into a few simple steps. 263 | 264 | Calculate size and number of sectors from disk space. 265 | Write the header to disk, the sector map and initialise all 266 | the sectors as unused. 267 | Create the root directory's inode using a strip starting at 268 | sector 0. 269 | 270 | Once the structure of the filesystem has been initialised it is 271 | ready for use. 272 | 273 | For 16 sectors on a disk the amount of disk space required is 274 | (sector_size * 16) + 1. So, to calculate the amount of sectors 275 | you can fit on a disk simply minus the size of the header from the 276 | disk and then divide it by (sector_size * 16) + 1. Round the resulting 277 | number down to have the maximum number of sectors that can go onto the 278 | disk. 279 | 280 | It is highly recommended to set the sector size less than or equal 281 | to the size of blocks on the disk that the filesystem is being 282 | created on. It is also highly advised to align the first sector to 283 | a block to maximise io performance. 284 | 285 |
286 | 287 |
288 | To open a file is very simple. HAT is simply passed an absolute 289 | path to the file. The path is then broken up into a list of of 290 | directories. The list is traversed, starting at the root inode until 291 | the file's inode is found. 292 |
293 | 294 |
295 | Unused sectors can be found very quickly using the sector map. 296 | By performing NOT(word AND 0xFFFF) against each word of the bitmap 297 | a free sector can be found. 298 |
299 |
300 | 301 |
302 | As there is no way to stop a program reading from or writing straight 303 | to the disk HAT makes no attempt at providing any security. Any file 304 | security should be done in userspace using encryption. 305 |
306 | 307 | 308 | 309 | 310 | 311 | 312 | 313 | 314 | -------------------------------------------------------------------------------- /FS/Draft_Harrys_Allocation_Table.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | RFC (Draft-Fs) H. Jeffery, Ed. 5 | April 22, 2012 6 | 7 | 8 | Harry's Allocation Table 9 | 10 | Abstract 11 | 12 | This draft provides the specification for the HAT(Harry's Allocation 13 | Table) filesystem. It is intended to provide a clear reference for 14 | anyone wishing to implement this filesystem. 15 | 16 | 17 | Table of Contents 18 | 19 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 20 | 2. Design Summary . . . . . . . . . . . . . . . . . . . . . . . . 2 21 | 3. Data Structures . . . . . . . . . . . . . . . . . . . . . . . . 2 22 | 3.1. Lower Layer . . . . . . . . . . . . . . . . . . . . . . . . 3 23 | 3.1.1. header . . . . . . . . . . . . . . . . . . . . . . . . 3 24 | 3.1.1.1. version . . . . . . . . . . . . . . . . . . . . . . 3 25 | 3.1.1.2. num_sectors . . . . . . . . . . . . . . . . . . . . 3 26 | 3.1.1.3. sector_map_start . . . . . . . . . . . . . . . . . 4 27 | 3.1.1.4. sector_joins_start . . . . . . . . . . . . . . . . 4 28 | 3.1.1.5. sectors_start . . . . . . . . . . . . . . . . . . . 4 29 | 3.1.1.6. sector_size . . . . . . . . . . . . . . . . . . . . 4 30 | 3.1.1.7. sectors_used . . . . . . . . . . . . . . . . . . . 4 31 | 3.1.2. sector map . . . . . . . . . . . . . . . . . . . . . . 4 32 | 3.1.2.1. bitmap . . . . . . . . . . . . . . . . . . . . . . 4 33 | 3.1.3. sector joins . . . . . . . . . . . . . . . . . . . . . 5 34 | 3.1.4. sector . . . . . . . . . . . . . . . . . . . . . . . . 5 35 | 3.2. Higher Layer . . . . . . . . . . . . . . . . . . . . . . . 5 36 | 3.2.1. inode . . . . . . . . . . . . . . . . . . . . . . . . . 5 37 | 3.2.1.1. type . . . . . . . . . . . . . . . . . . . . . . . 6 38 | 3.2.1.2. num_links . . . . . . . . . . . . . . . . . . . . . 6 39 | 3.2.1.3. content_size . . . . . . . . . . . . . . . . . . . 6 40 | 3.2.2. link . . . . . . . . . . . . . . . . . . . . . . . . . 6 41 | 3.2.2.1. strip_start_sector . . . . . . . . . . . . . . . . 7 42 | 3.2.2.2. file_name . . . . . . . . . . . . . . . . . . . . . 7 43 | 4. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 44 | 4.1. Constructing a HAT filesystem . . . . . . . . . . . . . . . 7 45 | 4.2. Finding a file's inode . . . . . . . . . . . . . . . . . . 8 46 | 4.3. Allocating sectors . . . . . . . . . . . . . . . . . . . . 8 47 | 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 48 | Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 49 | 50 | 51 | 52 | 53 | 54 | 55 | Jeffery [Page 1] 56 | 57 | HAT April 2012 58 | 59 | 60 | 1. Introduction 61 | 62 | This RFC provides a filesystem designed specifically for use on 63 | DCPU-16 systems. 64 | 65 | HAT is designed to be simple and easy to implement while still 66 | providing all the features required of a filesystem. 67 | 68 | 69 | 2. Design Summary 70 | 71 | HAT has a two layered design. The lower layer consists only of 72 | sectors. The lower layer is abstracted from the higher layer using 73 | "strips". The higher layer consists of inodes, links and raw file 74 | data. 75 | 76 | The lower layer deals with the management of sectors and provides 77 | access to virtual strips of disk space. 78 | 79 | The higher layer stores inodes, links and file data in these strips. 80 | Each strip (constructed in the lower layer using one or more sectors) 81 | contains an inode followed by either links or file data. 82 | 83 | Each inode represents either a file or a directory. If the inode 84 | represents a file the strip contains the inode followed immediately 85 | by all the file data. If the inode represents a directory the strip 86 | contains the inode followed by a list of links. 87 | 88 | Each link binds a file name to a file/directory. Each directory may 89 | contain several links to more directories or files, resulting in a 90 | tree growing from the root directory. 91 | 92 | 93 | 3. Data Structures 94 | 95 | This section defines the data structures that comprise the HAT 96 | filesystem. 97 | 98 | All sizes are given in words, which are considered to be 16 bits 99 | long. 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | Jeffery [Page 2] 112 | 113 | HAT April 2012 114 | 115 | 116 | 3.1. Lower Layer 117 | 118 | +--------------+ 119 | | Section | 120 | +--------------+ 121 | | header | 122 | | sector map | 123 | | sector joins | 124 | | sector 0 | 125 | | sector 1 | 126 | | sector 2 | 127 | | ... | 128 | +--------------+ 129 | 130 | Table 1: Filesystem Structure 131 | 132 | 3.1.1. header 133 | 134 | This structure contains the header information for HAT. 135 | 136 | +------+--------------------+ 137 | | Size | Name | 138 | +------+--------------------+ 139 | | 1 | version | 140 | | 1 | num_sectors | 141 | | 2 | sector_map_start | 142 | | 2 | sector_joins_start | 143 | | 2 | sectors_start | 144 | | 1 | sector_size | 145 | | 1 | sectors_used | 146 | +------+--------------------+ 147 | 148 | Table 2: Header Structure 149 | 150 | 3.1.1.1. version 151 | 152 | The version field is a magic number that identifies both that the 153 | filesystem in use is HAT and the version of HAT. 154 | 155 | The value of this field must be 0x4001. This magic number identifies 156 | the filesystem as version one of HAT. 157 | 158 | 3.1.1.2. num_sectors 159 | 160 | This field contains the total number of sectors in the filesystem. 161 | 162 | 163 | 164 | 165 | 166 | 167 | Jeffery [Page 3] 168 | 169 | HAT April 2012 170 | 171 | 172 | 3.1.1.3. sector_map_start 173 | 174 | This field contains the address of the start of the sector map. 175 | 176 | 3.1.1.4. sector_joins_start 177 | 178 | This field contains the address of the start of the array of sector 179 | joins. 180 | 181 | 3.1.1.5. sectors_start 182 | 183 | This field contains the address of the first sector on disk. 184 | 185 | This is required because the first sector may not be positioned 186 | immediately after the header. The first sector may be positioned to 187 | provide alignment with the underlying disk's blocks. 188 | 189 | 3.1.1.6. sector_size 190 | 191 | This field contains the size of each sector in the filesystem. 192 | 193 | This must be a power of 2, such as 128, 256 or 512. 194 | 195 | 3.1.1.7. sectors_used 196 | 197 | This field contains the number of sectors that are currently in use. 198 | 199 | 3.1.2. sector map 200 | 201 | This section is a bitmap representing which sectors are in use. It 202 | can be used to quickly locate free sectors for new files. 203 | 204 | +----------------------+--------+ 205 | | Size | Name | 206 | +----------------------+--------+ 207 | | ceil(num_sectors/16) | bitmap | 208 | +----------------------+--------+ 209 | 210 | Table 3: sector map structure 211 | 212 | 3.1.2.1. bitmap 213 | 214 | This field is a bitmap that represents all the sectors in the 215 | filesystem. Each bit of the bitmap represents whether a sector is in 216 | use. When a sector is in use the corresponding bit is set to 1. 217 | When a sector is free, the corresponding bit is set to 0. 218 | 219 | The MSB is considered to be the first bit and the LSB is considered 220 | 221 | 222 | 223 | Jeffery [Page 4] 224 | 225 | HAT April 2012 226 | 227 | 228 | to be the last bit. 229 | 230 | Any spare bits at the end of the bitmap must be set to 1. 231 | 232 | 3.1.3. sector joins 233 | 234 | This section is an array of words, each word is used to join one 235 | sector to another. 236 | 237 | +------+--------------+ 238 | | Size | Name | 239 | +------+--------------+ 240 | | 1 | sector0_next | 241 | | 1 | sector1_next | 242 | | 1 | sector2_next | 243 | | 1 | sector3_next | 244 | | 1 | ... | 245 | +------+--------------+ 246 | 247 | Table 4: sector links structure 248 | 249 | Each entry joins the end of one sector to the start of another, if 250 | there is no next sector the entry is set to 0. 251 | 252 | For example, if there is a strip starting in sector 0, then 253 | continuing in sector 2, then sector 1, then finishing in sector 3, 254 | then the value of sector0_next will be 2, sector1_next will be 3, 255 | sector2_next will be 1, sector3_next will be 0. 256 | 257 | The total length of this section in words is the total number of 258 | sectors in the filesystem. 259 | 260 | 3.1.4. sector 261 | 262 | The sector structure is used to store blocks of raw data. Sectors 263 | themselves are just raw blocks of data with no formatting or 264 | wrapping. 265 | 266 | Each sector has the size equal to the sector_size, as defined by the 267 | header of the filesystem. 268 | 269 | 3.2. Higher Layer 270 | 271 | 3.2.1. inode 272 | 273 | The inode structure is used to store metadata about files. 274 | 275 | 276 | 277 | 278 | 279 | Jeffery [Page 5] 280 | 281 | HAT April 2012 282 | 283 | 284 | +------+--------------+ 285 | | Size | Name | 286 | +------+--------------+ 287 | | 1 | type | 288 | | 1 | num_links | 289 | | 2 | content_size | 290 | +------+--------------+ 291 | 292 | Table 5: inode structure 293 | 294 | 3.2.1.1. type 295 | 296 | +-------+----------------------+ 297 | | value | meaning | 298 | +-------+----------------------+ 299 | | 0 | inode is unused | 300 | | 1 | inode is a directory | 301 | | 2 | inode is a file | 302 | +-------+----------------------+ 303 | 304 | Table 6: type values 305 | 306 | This field indicates what type of inode it is. If this field is set 307 | to 0 then the inode is not in use and represents nothing. If this 308 | field is set to 1 then the inode represents a directory. If this 309 | field is set to 2 then the inode represents a file. 310 | 311 | 3.2.1.2. num_links 312 | 313 | This field contains the number of links there are that point to the 314 | strip containing this inode. 315 | 316 | 3.2.1.3. content_size 317 | 318 | This field contains the amount of data stored with this inode in 319 | words. 320 | 321 | 3.2.2. link 322 | 323 | +------+--------------------+ 324 | | Size | Name | 325 | +------+--------------------+ 326 | | 1 | strip_start_sector | 327 | | 15 | file_name | 328 | +------+--------------------+ 329 | 330 | Table 7: link structure 331 | 332 | 333 | 334 | 335 | Jeffery [Page 6] 336 | 337 | HAT April 2012 338 | 339 | 340 | 3.2.2.1. strip_start_sector 341 | 342 | This field contains the index of the start sector of the strip the 343 | inode being linked to is stored in. 344 | 345 | 3.2.2.2. file_name 346 | 347 | This field contains the file name to be associated with the inode 348 | that is being linked. Only alphanumeric characters, periods(.) and 349 | underscores(_) are allowed in the filename. The maximum length of 350 | the filename is 15 characters, any unused characters at the end of 351 | the filename must be set to 0x0000. 352 | 353 | 354 | 4. Usage 355 | 356 | This section contains information and examples on the operation and 357 | usage of the HAT filesystem. It is meant only as a rough guide for 358 | someone who is wishing to implement HAT. 359 | 360 | 4.1. Constructing a HAT filesystem 361 | 362 | The HAT filesystem is very simple to construct. The creation of the 363 | filesystem can be split into a few simple steps. 364 | 365 | 1. Calculate size and number of sectors from disk space. 366 | 367 | 2. Write the header to disk, the sector map and initialise all the 368 | sectors as unused. 369 | 370 | 3. Create the root directory's inode using a strip starting at 371 | sector 0. 372 | 373 | Once the structure of the filesystem has been initialised it is ready 374 | for use. 375 | 376 | For 16 sectors on a disk the amount of disk space required is 377 | (sector_size * 16) + 1. So, to calculate the amount of sectors you 378 | can fit on a disk simply minus the size of the header from the disk 379 | and then divide it by (sector_size * 16) + 1. Round the resulting 380 | number down to have the maximum number of sectors that can go onto 381 | the disk. 382 | 383 | It is highly recommended to set the sector size less than or equal to 384 | the size of blocks on the disk that the filesystem is being created 385 | on. It is also highly advised to align the first sector to a block 386 | to maximise io performance. 387 | 388 | 389 | 390 | 391 | Jeffery [Page 7] 392 | 393 | HAT April 2012 394 | 395 | 396 | 4.2. Finding a file's inode 397 | 398 | To open a file is very simple. HAT is simply passed an absolute path 399 | to the file. The path is then broken up into a list of of 400 | directories. The list is traversed, starting at the root inode until 401 | the file's inode is found. 402 | 403 | 4.3. Allocating sectors 404 | 405 | Unused sectors can be found very quickly using the sector map. By 406 | performing NOT(word AND 0xFFFF) against each word of the bitmap a 407 | free sector can be found. 408 | 409 | 410 | 5. Security Considerations 411 | 412 | As there is no way to stop a program reading from or writing straight 413 | to the disk HAT makes no attempt at providing any security. Any file 414 | security should be done in userspace using encryption. 415 | 416 | 417 | Author's Address 418 | 419 | Harry Jeffery (editor) 420 | 421 | Email: harry@exec64.co.uk 422 | URI: http://www.exec64.co.uk/ 423 | 424 | 425 | 426 | 427 | 428 | 429 | 430 | 431 | 432 | 433 | 434 | 435 | 436 | 437 | 438 | 439 | 440 | 441 | 442 | 443 | 444 | 445 | 446 | 447 | Jeffery [Page 8] 448 | 449 | -------------------------------------------------------------------------------- /ASM/Spec_0xSCA.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | RFC X____ J. Kuijpers, Ed. 5 | Jarvix 6 | M. Beermann, Ed. 7 | April 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 whitespace . . . . . . . . . . . . . . . . 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.3.1. Ascii Literal Flags . . . . . . . . . . . . . . . 6 77 | 4.3.4. Origin relocation . . . . . . . . . . . . . . . . . . 6 78 | 4.3.5. Macros: macro block and macro insertion . . . . . . . 7 79 | 4.3.6. Repeat block . . . . . . . . . . . . . . . . . . . . . 7 80 | 4.3.7. Conditionals . . . . . . . . . . . . . . . . . . . . . 7 81 | 4.3.8. Error reporting . . . . . . . . . . . . . . . . . . . 8 82 | 4.3.9. Alignment . . . . . . . . . . . . . . . . . . . . . . 8 83 | 4.3.10. Echo general output . . . . . . . . . . . . . . . . . 8 84 | 5. Tokenizer Markup . . . . . . . . . . . . . . . . . . . . . . . 9 85 | 5.1. Labels . . . . . . . . . . . . . . . . . . . . . . . . . . 9 86 | 5.2. Inline character literals . . . . . . . . . . . . . . . . 9 87 | 6. Inline arithmetic . . . . . . . . . . . . . . . . . . . . . . 9 88 | 7. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 9 89 | 7.1. Recognition of conformance . . . . . . . . . . . . . . . . 10 90 | 8. Design Rationale . . . . . . . . . . . . . . . . . . . . . . . 10 91 | 8.1. Labels . . . . . . . . . . . . . . . . . . . . . . . . . . 10 92 | 8.2. Preprocessor . . . . . . . . . . . . . . . . . . . . . . . 10 93 | 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 94 | 10. Normative References . . . . . . . . . . . . . . . . . . . . . 11 95 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 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 whitespace 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 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 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 occurrences 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 | .dp value [,value...] 252 | .fill count[,value] 253 | .ascii [flags][]"string" 254 | 255 | dw (data word) MUST store the values literally and unpacked at the 256 | location of the directive. 257 | 258 | dp (data pack) MUST pack pairs of values into a single word. The 259 | first value is placed into the high octet, and the second is placed 260 | into the low octet of the word. Should there be an odd number of 261 | values after a dp declaration, the remaining octet MUST be filled 262 | with the value 0. 263 | 264 | fill (fill words) MUST insert a count of words, initialized to the 265 | specified value. If the value is not provided, the assembler MUST 266 | assume 0. 267 | 268 | ascii (ascii string) MUST pack the ascii values of the string as 269 | described by the flags that precede it. An explanation of the flags 270 | is provided in the section on ascii flags.Section 4.3.3.1 271 | 272 | The optional value parameter in between less than (< U+003C) and 273 | greater than (> U+003E) will be bitwise ORed with each character in 274 | the string. The upper octet for unpacked strings will default to all 275 | 0's before the bitwise OR. 276 | 277 | 278 | 279 | Kuijpers & Beermann [Page 5] 280 | 281 | Assembly Syntactics April 2012 282 | 283 | 284 | 4.3.3.1. Ascii Literal Flags 285 | 286 | k: The ascii values are "packed." Each character is mapped to an 287 | octet of data. These are written in order. Certain other flags may 288 | place octets that precede the first character's octet. 289 | 290 | s: The ascii values are "packed" and "swapped." Like k, each 291 | character uses one octet, however the order of the octets is reversed 292 | within each word. Flags k and s are incompatible with each other. 293 | Certain other flags may place octets before the first character 294 | octet. 295 | 296 | z: Zero terminate the string, inheriting character width. A null 297 | character will be appended to the string. If the string is one of 298 | the packed formats only one octet will be added, where unpacked 299 | strings will have a full word of zero. For the purpose of 300 | determining string length, this zero counts as one character. 301 | 302 | x: Word Zero terminate the string. This will zero terminate the 303 | string, forcing a zero word onto the end of the string. If the 304 | string is packed and of an odd length, a zero octet will be placed at 305 | the end of the content, before the zero word. For the purpose of 306 | determining string length, this zero will add quantity of zero octets 307 | added divided by the octet width of each character. 308 | 309 | For example, an unpacked string will always have 1 added to the 310 | string length by the Z flag. A packed string of odd length will have 311 | 3 added to the string length, where an even length packed string will 312 | have 2 added to the length; 313 | 314 | Flags w and x are incompatible. 315 | 316 | a: Octet Pascal Length. This will prepend the length of the string 317 | as an octet to the string content. This is only compatible with a 318 | packed mode, either k or s. (For swapped mode, this will end up 319 | being the lower (second) octet of the first word.) 320 | 321 | p: Word Pascal Length. This will prepend the length of the string as 322 | a full word to the string content. This is compatible with either 323 | packed or unpacked modes. Flags a and p are incompatible. 324 | 325 | 4.3.4. Origin relocation 326 | 327 | .org address 328 | 329 | The org preprocessor directive MUST take an address as the only 330 | argument. Assemblers SHOULD verify the address is 16-bit sized. 331 | Assembler MUST add this address to the address of all labels, 332 | 333 | 334 | 335 | Kuijpers & Beermann [Page 6] 336 | 337 | Assembly Syntactics April 2012 338 | 339 | 340 | creating a relocation of the program. 341 | 342 | 4.3.5. Macros: macro block and macro insertion 343 | 344 | .macro name([param [,param...]]) 345 | code 346 | .end 347 | name([param [,param...]]) 348 | 349 | The macro directive defines a macro, a parameterized block of code 350 | that can be inserted any time later. Parameters, if any, are written 351 | in parentheses separated by commas (,). 352 | 353 | Using the name with parentheses MUST insert a formerly defined macro 354 | and expands the parameters of the macro with the comma-separated 355 | parameters following the name of the macro to insert. 356 | 357 | Parameter substitutions can only be constant values and memory 358 | references. Preprocessor directives inside the macro MUST be handled 359 | upon insertion, not definition. 360 | 361 | 4.3.6. Repeat block 362 | 363 | .rep times 364 | code 365 | .end 366 | 367 | The code in the repeat-block MUST be repeated the number of times 368 | specified. 'times' MUST be a positive integer. Preprocessor 369 | directives inside the repeat-block MUST be handled when the 370 | repetition is complete, to make allow conditional repetitions. 371 | 372 | 4.3.7. Conditionals 373 | 374 | .if expression 375 | codeTrue 376 | .elif expression 377 | codeElseTrue 378 | .elseif expression 379 | codeElseTrue 380 | .else 381 | codeElse 382 | .end 383 | .ifdef definition 384 | .ifndef definition 385 | isdef(definition) 386 | 387 | For the definition of valid expressions, see Section 6. 388 | 389 | 390 | 391 | Kuijpers & Beermann [Page 7] 392 | 393 | Assembly Syntactics April 2012 394 | 395 | 396 | The if clause is REQUIRED. The else clause is OPTIONAL. The elif/ 397 | elseif clause is OPTIONAL and can occur multiple times. 398 | 399 | If expression consists of a single constant value, then expression = 400 | 1 MUST be assumed. If expression evaluates to 1, the codeTrue-block 401 | MUST be assembled. When the evaluation fails, the next elif block 402 | must be evaluated. In any other case codeElse, if an else clause is 403 | specified, MUST be assembled. 404 | 405 | isdef(symbol) can be used in place of expression. isdef MUST evaluate 406 | to 1 if the given symbol is currently defined, else it MUST evaluate 407 | to 0. 408 | 409 | ifdef is short for if isdef(). ifndef is short for if !isdef() 410 | 411 | Nesting of if directives MUST be supported. 412 | 413 | 4.3.8. Error reporting 414 | 415 | .error message 416 | 417 | Triggers an assembler error with the message, stopping execution of 418 | the assembler. The message SHOULD be shown in combination with the 419 | filename and line number. 420 | 421 | 4.3.9. Alignment 422 | 423 | .align boundary 424 | 425 | Aligns code or data on doubleword or other boundary. 426 | 427 | The assembler MUST add zeroed words (0x0000) to the generated 428 | machinecode until the alignment is correct. The number of words 429 | inserted can be calculated using the formula: 'boundary - 430 | (currentPosition modulo boundary)'. 431 | 432 | 4.3.10. Echo general output 433 | 434 | .echo message 435 | 436 | The echo directive can be used to inform the user about (possible) 437 | issues, progress, etc. 438 | 439 | The assembler SHOULD report the message to the user. 440 | 441 | 442 | 443 | 444 | 445 | 446 | 447 | Kuijpers & Beermann [Page 8] 448 | 449 | Assembly Syntactics April 2012 450 | 451 | 452 | 5. Tokenizer Markup 453 | 454 | 5.1. Labels 455 | 456 | Labels MUST be single-worded identifiers containing only alphabetical 457 | characters (/[A-Za-z]/), numbers (/[0-9]/), underscores (_ U+005F), 458 | and periods(. U+002E). The label MUST represent the address of 459 | following instruction or data. A label MUST NOT start with a number, 460 | an underscore or a period. A label SHOULD end with a colon (: 461 | U+003A), but starting with a colon MAY be supported. A label MUST 462 | NOT end with a period. 463 | 464 | Local labels MUST start with an underscore (_ U+002E) and end with a 465 | colon (: U+003A). Local labels MUST be scoped between the 466 | surrounding global labels. Local labels in different scopes MUST be 467 | able to have the same name. 468 | 469 | 5.2. Inline character literals 470 | 471 | A character surrounded by apostrophes (' U+0029) MUST be interpreted 472 | as its corresponding 7-bit ASCII value in a word (LSB). 473 | 474 | 475 | 6. Inline arithmetic 476 | 477 | Source code can include inline arithmetics anywhere a constant value 478 | is permitted. Inline arithmetic may only consist of + (addition), - 479 | (subtraction), * (multiplication), / (integer division), % (modulus) 480 | and ! (negation), parentheses may be used to group expressions. 481 | 482 | The following bitwise operators MUST also be supported: & (bit-wise 483 | AND) ^ (bit-wise XOR), | (bit-wise OR), ~ (bit-wise NOT), << and >> 484 | (bit-wise shifts). 485 | 486 | The following logical and bitwise operators MUST also be supported: 487 | == (equal), != (not equal, also <>), < (smaller than), > (greater 488 | than), <= (smaller or equal), >= (greater or equal), & (bit-wise AND) 489 | ^ (bit-wise XOR), | (bit-wise OR), && (logical AND), || (logical OR), 490 | ^^ (logical XOR) which MUST be evaluated with respect to this order. 491 | 492 | Inline arithmetic MUST be evaluated as soon as possible, the result 493 | MUST be used as a literal value in place of the expression. 494 | 495 | 496 | 7. Conformance 497 | 498 | 499 | 500 | 501 | 502 | 503 | Kuijpers & Beermann [Page 9] 504 | 505 | Assembly Syntactics April 2012 506 | 507 | 508 | 7.1. Recognition of conformance 509 | 510 | An assembler, formatter and any other assembly related program that 511 | is fully compliant to 0xSCA MAY label itself "0xSCA compatible". 512 | When using this label, the subject SHOULD include a note of the 513 | version of the RFC it is written against. 514 | 515 | 516 | 8. Design Rationale 517 | 518 | 8.1. Labels 519 | 520 | Although Notch used the syntax :label in his first examples, it is 521 | not common in any popular assembler. Thus we decided for label: as 522 | the recommended form, still silently allowing the deprecated form. 523 | 524 | To simplify writing reusable code we also introduced local labels, 525 | which are only visible from within the global label they are defined 526 | within. Implementing this is easy to do and introduces little 527 | overhead, as nesting is neither specified nor recommended. 528 | 529 | 8.2. Preprocessor 530 | 531 | 0xSCA allows many operators and even parentheses in expressions for 532 | if-clauses, which complicates the implementation of these. We do 533 | recognize that, but the actual implementation difficulty is not too 534 | high, as there are many examples how to achieve this and we think 535 | that the additional power and reduced code complexity, resulting in 536 | better maintainable code, is worth the effort. 537 | 538 | The ability to define custom constants inline is easy to implement 539 | and yields more easily maintainable code, while introducing a minimum 540 | of additional syntax. 541 | 542 | Both kinds of file inclusion support two different forms, one 543 | including the file relative to the current file, and the other 544 | including it from an implementation defined location. The former is 545 | ideal for splitting a program in multiple parts, while the latter is 546 | intended for implementation-provided resources such as source level 547 | libraries. 548 | 549 | A preprocessor must accept every directive with a dot (.) or a number 550 | sign (#) prefix. While Notch seems to prefer the latter, the former 551 | is much more common among todays assemblers. Thus we decided to 552 | support both, especially as the implementation-side overhead is very 553 | low. 554 | 555 | 556 | 557 | 558 | 559 | Kuijpers & Beermann [Page 10] 560 | 561 | Assembly Syntactics April 2012 562 | 563 | 564 | 9. Security Considerations 565 | 566 | This memo has no applicable security considerations. 567 | 568 | 569 | 10. Normative References 570 | 571 | [GHBP] Marti, V., "Take Over The Galaxy with GitHub", April 2012, 572 | . 574 | 575 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 576 | Requirement Levels", BCP 14, RFC 2119, March 1997. 577 | 578 | 579 | Authors' Addresses 580 | 581 | Jos Kuijpers (editor) 582 | Jarvix 583 | 584 | Email: jos@kuijpersvof.nl (contact for any inquiries) 585 | URI: http://www.jarvix.org/ 586 | 587 | 588 | Marian Beermann (editor) 589 | 590 | Email: public@enkore.de 591 | URI: http://www.enkore.de/ 592 | 593 | 594 | 595 | 596 | 597 | 598 | 599 | 600 | 601 | 602 | 603 | 604 | 605 | 606 | 607 | 608 | 609 | 610 | 611 | 612 | 613 | 614 | 615 | Kuijpers & Beermann [Page 11] 616 | -------------------------------------------------------------------------------- /ASM/Spec_0xSCA.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 0xSCA: Standards Committee Assembly 15 | 16 | 18 | Jarvix 19 | 20 |
21 | jos@kuijpersvof.nl (contact for any inquiries) 22 | http://www.jarvix.org/ 23 |
24 | 25 | 27 |
28 | public@enkore.de 29 | http://www.enkore.de/ 30 |
31 | 32 | 33 | ASM 34 | 0x10c Standards Committee 35 | 36 | This document describes an assembly and preprocessor syntax 37 | suitable for the DCPU-16 environment. This syntax is called the 38 | 0xSCA, or Standards Committee Assembly. 39 | This is not a standard. 40 | 41 | 42 | 43 | 44 |
45 | This documents describes 0xSCA, Standards Committee Assembly. It 46 | is a definition of a syntax to be used for writing assembly for the 47 | DCPU-16 processor. Use of this syntax is voluntarily. With 0xSCA, 48 | there is a defined syntax, and could decrease code incompatibility 49 | among compilers. 50 | Again, to be clear: 0xSCA is a syntax definition, not a standard. 51 | 0xSCA is to DCPU-16, what AT&T or the NASM syntax is to IA-32. 52 | 53 |
54 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 55 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 56 | document are to be interpreted as described in RFC 2119. 58 |
59 |
60 | 61 |
62 |
63 | Whitespace MUST be allowed between all 64 | elements of a line, including but not limited to opcodes, values, 65 | syntactic characters and preprocessor directives. Both a space 66 | (' ' U+0020) and a tab (U+0009) are considered whitespace 67 | characters. 68 | Indenting instructions is RECOMMENDED. NOT indenting 69 | labels and preprocessor directives RECOMMENDED. The assembler 70 | MUST NOT mandate indentation to assemble successfully. 71 |
72 |
73 | 74 |
75 | Assemblers MUST accept everything without regard to case EXCEPT 76 | string and character literals. 77 |
78 | 79 |
80 |
81 | Comments are used to add information to the code, making it 82 | more readable and understandable. Comments can consist any 83 | character in any combination. This document specifies one-line 84 | comments only. 85 | Any characters following and in the same line of a semicolon 86 | (; U+003B) are comments and MUST be ignored, except when the 87 | semicolon resides within the representation of a string. In 88 | that case, the semicolon MUST NOT be treated as a comment. 89 |
90 |
91 | Every preprocessor directive starts with an identifier. This 92 | identifier is used to distinguish preprocessor directives from 93 | other code. 94 | For historical reasons, directives can either start with a dot 95 | (. U+002E) or a number sign (# U+0023). 96 | Preprocessor directives MUST start with a dot (. U+002E) or a 97 | number sign (# U+0023). 98 | Using a dot is RECOMMENDED to distinguish between C preprocessor 99 | syntax. 100 |
101 |
102 | All directives in this section MUST be handled in order and 103 | in recognition of their position. For the purpose of this document, 104 | a dot (.) is used to describe preprocessor directives. 105 |
106 |
107 |
]]>
110 | The former directive MUST include the file into the 111 | current file. The path is relative to the current file. 112 | The assembler SHOULD report to the user if the given 113 | filename does not exist and continue assembly. 114 | The latter includes the file from an implementation 115 | defined location, which may not even exist but trigger 116 | certain behaviour, i.e. inclusion of intrinsics. 117 |
118 |
119 |
]]>
122 | incbin MUST include the specified binary as raw, 123 | unprocessed data, the path to the file is relative 124 | from the current file. All labels behind this directive 125 | MUST be offset by the size of the file. 126 | The latter form of incbin MUST include the file from 127 | an implementation defined location. 128 |
129 |
130 |
131 |
136 | def/define/equ MUST assign the constant value to name. If the value 137 | is omitted, the literal 1 (one) MUST be assumed. 138 | undef MUST remove the given symbol from the namespace. 139 | If the given symbol does not exist compilation SHOULD 140 | continue and a warning MAY be emitted. 141 | Any occurrences of the definition during its existence, 142 | MUST be replaced with the given value to the definition. 143 |
144 |
145 |
]"string"]]>
150 | dw (data word) MUST store the values literally and unpacked at the 151 | location of the directive. 152 | dp (data pack) MUST pack pairs of values into a single word. The 153 | first value is placed into the high octet, and the second is placed 154 | into the low octet of the word. Should there be an odd number of 155 | values after a dp declaration, the remaining octet MUST be filled 156 | with the value 0. 157 | fill (fill words) MUST insert a count of words, initialized to the 158 | specified value. If the value is not provided, the assembler MUST 159 | assume 0. 160 | ascii (ascii string) MUST pack the ascii values of the string as 161 | described by the flags that precede it. An explanation of the flags 162 | is provided in the section on ascii flags. 163 | The optional value parameter in between less than (< U+003C) 164 | and greater than (> U+003E) will be bitwise ORed with each character 165 | in the string. The upper octet for unpacked strings will default to 166 | all 0's before the bitwise OR. 167 |
168 | k: The ascii values are "packed." Each character is mapped to an 169 | octet of data. These are written in order. Certain other flags 170 | may place octets that precede the first character's octet. 171 | s: The ascii values are "packed" and "swapped." Like k, each 172 | character uses one octet, however the order of the octets is 173 | reversed within each word. Flags k and s are incompatible with 174 | each other. Certain other flags may place octets before the first 175 | character octet. 176 | z: Zero terminate the string, inheriting character width. A null 177 | character will be appended to the string. If the string is one of 178 | the packed formats only one octet will be added, where unpacked 179 | strings will have a full word of zero. For the purpose of 180 | determining string length, this zero counts as one character. 181 | x: Word Zero terminate the string. This will zero terminate the 182 | string, forcing a zero word onto the end of the string. If the 183 | string is packed and of an odd length, a zero octet will be 184 | placed at the end of the content, before the zero word. For the 185 | purpose of determining string length, this zero will add quantity 186 | of zero octets added divided by the octet width of each character. 187 | For example, an unpacked string will always have 1 added to the 188 | string length by the Z flag. A packed string of odd length will 189 | have 3 added to the string length, where an even length packed 190 | string will have 2 added to the length; 191 | Flags w and x are incompatible. 192 | a: Octet Pascal Length. This will prepend the length of the string 193 | as an octet to the string content. This is only compatible with 194 | a packed mode, either k or s. (For swapped mode, this will end 195 | up being the lower (second) octet of the first word.) 196 | p: Word Pascal Length. This will prepend the length of the string 197 | as a full word to the string content. This is compatible with 198 | either packed or unpacked modes. Flags a and p are incompatible. 199 |
200 | 201 |
202 |
203 |
205 | The org preprocessor directive MUST take an address 206 | as the only argument. Assemblers SHOULD verify the 207 | address is 16-bit sized. Assembler MUST add this 208 | address to the address of all labels, creating a 209 | relocation of the program. 210 |
211 |
212 |
217 | The macro directive defines a macro, a parameterized block 218 | of code that can be inserted any time later. Parameters, 219 | if any, are written in parentheses separated by commas (,). 220 | Using the name with parentheses MUST insert a formerly defined 221 | macro and expands the parameters of the macro with the 222 | comma-separated parameters following the name of the macro to 223 | insert. 224 | Parameter substitutions can only be constant values and 225 | memory references. Preprocessor directives inside the macro 226 | MUST be handled upon insertion, not definition. 227 |
228 |
229 |
233 | The code in the repeat-block MUST be repeated the number 234 | of times specified. 'times' MUST be a positive integer. 235 | Preprocessor directives inside the repeat-block MUST be 236 | handled when the repetition is complete, to make allow 237 | conditional repetitions. 238 |
239 |
240 |
253 | For the definition of valid expressions, see 254 | . 255 | The if clause is REQUIRED. The else clause is OPTIONAL. 256 | The elif/elseif clause is OPTIONAL and can occur multiple times. 257 | If expression consists of a single constant value, 258 | then expression = 1 MUST be assumed. If expression evaluates 259 | to 1, the codeTrue-block MUST be assembled. When the 260 | evaluation fails, the next elif block must be evaluated. In 261 | any other case codeElse, if an else clause is specified, 262 | MUST be assembled. 263 | isdef(symbol) can be used in place of expression. 264 | isdef MUST evaluate to 1 if the given symbol is currently 265 | defined, else it MUST evaluate to 0. 266 | ifdef is short for if isdef(). ifndef is short for if !isdef() 267 | Nesting of if directives MUST be supported. 268 |
269 |
270 |
272 | Triggers an assembler error with the message, stopping 273 | execution of the assembler. The message SHOULD be shown in 274 | combination with the filename and line number. 275 |
276 |
277 |
279 | Aligns code or data on doubleword or other boundary. 280 | The assembler MUST add zeroed words (0x0000) to the generated 281 | machinecode until the alignment is correct. The number of 282 | words inserted can be calculated using the formula: 283 | 'boundary - (currentPosition modulo boundary)'. 284 |
285 |
286 |
288 | The echo directive can be used to inform the user about 289 | (possible) issues, progress, etc. 290 | The assembler SHOULD report the message to the user. 291 |
292 |
293 |
294 | 295 |
296 |
297 | Labels MUST be single-worded identifiers containing only 298 | alphabetical characters (/[A-Za-z]/), numbers (/[0-9]/), 299 | underscores (_ U+005F), and periods(. U+002E). The label MUST represent 300 | the address of following instruction or data. A label MUST NOT start with a 301 | number, an underscore or a period. A label SHOULD end with a colon (: U+003A), but 302 | starting with a colon MAY be supported. A label MUST NOT end with a period. 303 | Local labels MUST start with an underscore (_ U+002E) and end 304 | with a colon (: U+003A). Local labels MUST be scoped between the 305 | surrounding global labels. Local labels in different scopes 306 | MUST be able to have the same name. 307 |
308 |
309 | A character surrounded by apostrophes (' U+0029) MUST be 310 | interpreted as its corresponding 7-bit ASCII value in a word 311 | (LSB). 312 |
313 |
314 | 315 |
316 | Source code can include inline arithmetics anywhere a 317 | constant value is permitted. Inline arithmetic may only 318 | consist of + (addition), - (subtraction), * (multiplication), / 319 | (integer division), % (modulus) and ! (negation), parentheses may be used 320 | to group expressions. 321 | The following bitwise operators MUST also be supported: & 322 | (bit-wise AND) ^ (bit-wise XOR), | (bit-wise OR), ~ (bit-wise NOT), << 323 | and >> (bit-wise shifts). 324 | 325 | The following logical and bitwise operators MUST also be 326 | supported: == (equal), != (not equal, also <>), 327 | < (smaller than), > (greater than), <= (smaller or 328 | equal), >= (greater or equal), & (bit-wise AND) ^ 329 | (bit-wise XOR), | (bit-wise OR), && (logical AND), || 330 | (logical OR), ^^ (logical XOR) which MUST be evaluated with 331 | respect to this order. 332 | Inline arithmetic MUST be evaluated as soon as possible, 333 | the result MUST be used as a literal value in place of the expression. 334 |
335 | 336 |
337 |
338 | An assembler, formatter and any other assembly related 339 | program that is fully compliant to 0xSCA MAY label itself 340 | "0xSCA compatible". When using this label, the subject SHOULD 341 | include a note of the version of the RFC it is written against. 342 | 343 |
344 |
345 | 346 |
347 |
348 | Although Notch used the syntax :label in his first 349 | examples, it is not common in any popular assembler. 350 | Thus we decided for label: as the recommended form, 351 | still silently allowing the deprecated form. 352 | To simplify writing reusable code we also introduced 353 | local labels, which are only visible from within the 354 | global label they are defined within. Implementing this 355 | is easy to do and introduces little overhead, as nesting 356 | is neither specified nor recommended. 357 |
358 | 359 |
360 | 0xSCA allows many operators and even parentheses in 361 | expressions for if-clauses, which complicates the 362 | implementation of these. We do recognize that, but 363 | the actual implementation difficulty is not too high, 364 | as there are many examples how to achieve this and 365 | we think that the additional power and reduced 366 | code complexity, resulting in better maintainable 367 | code, is worth the effort. 368 | The ability to define custom constants inline is 369 | easy to implement and yields more easily maintainable 370 | code, while introducing a minimum of additional syntax. 371 | Both kinds of file inclusion support two different 372 | forms, one including the file relative to the current file, 373 | and the other including it from an implementation defined 374 | location. The former is ideal for splitting a program 375 | in multiple parts, while the latter is intended for 376 | implementation-provided resources such as source level 377 | libraries. 378 | A preprocessor must accept every directive with 379 | a dot (.) or a number sign (#) prefix. While Notch seems 380 | to prefer the latter, the former is much more common 381 | among todays assemblers. Thus we decided to support 382 | both, especially as the implementation-side overhead is 383 | very low. 384 |
385 |
386 | 387 |
388 | This memo has no applicable security considerations. 389 |
390 | 391 | 392 | 393 | 394 | 395 | 396 | 397 | Take Over The Galaxy with GitHub 398 | 399 | 400 | 401 | 402 | 403 | 404 | --------------------------------------------------------------------------------