Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

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

Conflicts:
	ASM/Draft_Assembly_Relocation_Table.txt
  • Loading branch information...
commit c94771afea60ff85ff00428227880301bc0610fd 2 parents da559a4 + 61348f2
@hach-que hach-que authored
View
5 .gitignore
@@ -0,0 +1,5 @@
+*.aux
+*.log
+*.out
+*.tex
+*~
View
165 ABI/ABI draft 2.txt
@@ -0,0 +1,165 @@
+RFC X1000 (Standard-ABI) A. Bleck, Ed.
+ April 2012
+
+
+ ABI draft
+
+Abstract
+
+ This draft specifies an application binary interface for
+ interoperability between subroutines written by different authors or
+ compiled by different compilers.
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 1.1. Requirements Language . . . . . . . . . . . . . . . . . . . 2
+ 2. Rules common to both calling conventions . . . . . . . . . . . 2
+ 3. Stackcall . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 4. Registercall . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 5. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 3
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bleck [Page 1]
+
+ ABI draft April 2012
+
+
+1. Introduction
+
+ Currently there is no standard defined for the behavior of functions
+ that, if conformed to, will allow functions from multiple sources to
+ be compatible. This RFC specifies two 'calling conventions',
+ hereafter called stackcall and registercall. Any compiler
+ implementing these calling conventions would be able to call code
+ generated from a different compiler that also implements these
+ conventions safely.
+
+1.1. Requirements Language
+
+ 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. The key
+ word "CALLER" is the function or code that is making the call, the
+ key word "CALLEE" is the function being called
+
+
+2. Rules common to both calling conventions
+
+ The CALLER is REQUIRED to assume that the contents of registers A, B
+ and C are not preserved. The CALLEE is REQUIRED to preserve the
+ contents of registers X, Y, Z, I and J. The CALLER is REQUIRED to
+ assume that the contents of the special purpose register O is not
+ preserved, and contains no valuable information. The CALLEE MUST
+ return it's result, if any, in register A. The CALLEE MUST remove
+ anything and everything it adds to the stack. The CALLER is
+ responsible for cleaning any function arguments passed on the stack
+ from the stack.
+
+
+3. Stackcall
+
+ The CALLER MUST push all arguments to the stack in right to left
+ order, followed by the return pointer, such that the first argument
+ is located on the stack at SP+1, the second is at SP+2, etc. (The
+ CALLER is RECOMMENDED to use the JSR instruction to perform the jump)
+
+
+4. Registercall
+
+ The CALLER MUST place the first three function arguments in registers
+ A, B and C, in that order. Further arguments, if any, MUST be pushed
+ to the stack in right to left order. The return pointer MUST be
+ pushed last, such that argument four is located on the stack at SP+1,
+ argument five is located at SP+2, etc. (The CALLER is RECOMMENDED to
+ use the JSR instruction to perform the jump)
+
+
+
+Bleck [Page 2]
+
+ ABI draft April 2012
+
+
+5. Scope
+
+ This specification applies only to the interface functions present to
+ each other. Internal implementation details are intentially
+ excluded.
+
+
+Author's Address
+
+ Blecki (editor)
+
+ Email: jm@omnisu.com
+ URI: http://jemgine.omnisu.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bleck [Page 3]
+
View
102 ABI/ABI draft 2.xml
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
+<?rfc strict="yes" ?>
+<?rfc toc="yes"?>
+<?rfc tocdepth="4"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes" ?>
+<?rfc compact="yes" ?>
+<?rfc subcompact="no" ?>
+<?rfc private="RFC X1000 (Standard-ABI)" ?>
+<rfc ipr="none" number="1000" category="info" docName="abi-draft">
+ <front>
+ <title abbrev="ABI draft">ABI draft</title>
+
+ <author fullname="Blecki" initials="A.C." role="editor"
+ surname="Bleck">
+ <organization></organization>
+
+ <address>
+ <email>jm@omnisu.com</email>
+ <uri>http://jemgine.omnisu.com</uri>
+ </address>
+ </author>
+
+ <date month="April" year="2012" />
+ <area>ABI</area>
+ <workgroup>0x10c Standards Committee</workgroup>
+ <abstract>
+ <t>This draft specifies an application binary interface for
+ interoperability between subroutines written by different
+ authors or compiled by different compilers.</t>
+ </abstract>
+ </front>
+
+ <middle>
+ <section title="Introduction">
+ <t>Currently there is no standard defined for the behavior of
+ functions that, if conformed to, will allow functions from
+ multiple sources to be compatible. This RFC specifies two
+ 'calling conventions', hereafter called stackcall and
+ registercall. Any compiler implementing these calling
+ conventions would be able to call code generated from a
+ different compiler that also implements these conventions
+ safely.</t>
+
+ <section title="Requirements Language">
+ <t>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.
+
+ The key word "CALLER" is the function or code that is making
+ the call, the key word "CALLEE" is the function being called</t>
+ </section>
+ </section>
+
+ <section anchor="common" title="Rules common to both calling conventions">
+ <t>The CALLER is REQUIRED to assume that the contents of registers A, B and C
+ are not preserved.
+
+ The CALLEE is REQUIRED to preserve the contents of registers X, Y, Z, I and J.
+
+ The CALLER is REQUIRED to assume that the contents of the special purpose
+ register O is not preserved, and contains no valuable information.
+
+ The CALLEE MUST return it's result, if any, in register A.
+
+ The CALLEE MUST remove anything and everything it adds to the stack.
+
+ The CALLER is responsible for cleaning any function arguments passed on the
+ stack from the stack.
+ </t>
+ </section>
+
+ <section anchor="stackcall" title="Stackcall">
+ <t>The CALLER MUST push all arguments to the stack in right to left order,
+ followed by the return pointer, such that the first argument is located
+ on the stack at SP+1, the second is at SP+2, etc. (The CALLER is RECOMMENDED
+ to use the JSR instruction to perform the jump)
+ </t>
+ </section>
+
+ <section anchor="registercall" title="Registercall">
+ <t>The CALLER MUST place the first three function arguments in registers A,
+ B and C, in that order. Further arguments, if any, MUST be pushed to the stack
+ in right to left order. The return pointer MUST be pushed last, such that
+ argument four is located on the stack at SP+1, argument five is located at
+ SP+2, etc. (The CALLER is RECOMMENDED to use the JSR instruction to perform
+ the jump)
+ </t>
+ </section>
+
+ <section anchor="scope" title="Scope">
+ <t>This specification applies only to the interface functions present to
+ each other. Internal implementation details are intentially excluded.</t>
+ </section>
+ </middle>
+
+
+
+</rfc>
+
View
71 ABI/Draft_ABI_1.txt
@@ -6,9 +6,6 @@ On April 5 2012, #0x10c-dev agreed to the following standard ABI:
- Return in A
-- J is used for base stack pointer (preserving the value of SP before allocating
- data for locals)
-
- Function local variables are kept on the stack
- Caller cleans stack
@@ -16,11 +13,23 @@ On April 5 2012, #0x10c-dev agreed to the following standard ABI:
- First three arguments to A, B, C, remaining arguments pushed right-to-left onto
the stack
-- Varargs: follow normal rules, except the entire "..." must go on the stack
- even if it's one of the first three arguments
+- Varargs: follow normal rules; the vararg callee should push C,B,A in its
+prolog to have a nice walkable array, and then clear off these three registers
+from the stack in its epilog.
+
- No stupid tricks with the overflow flag
+Note: A compiler is free to optimize away pointless preservations of registers.
+
+The storage location of preserved copies of registers must be re-entrant safe.
+(For all practical purposes, on the stack.)
+
+Non-required suggestions for convention:
+
+- J is used for base stack pointer (preserving the value of SP before allocating
+ data for locals)
+
--------------------------------------------------------------------------------
EXAMPLE FUNCTION CALL:
@@ -59,3 +68,55 @@ SET PC, POP # return
Last updated for DCPU16v11
example by masterm
+
+---------------------------------------------------------------------
+
+The calling convention I am currently using in DCPUC. I'm not necessarily
+ proposing a complete alternative, just a working implementation to compare with. ~~Blecki
+
+DCPUC Calling Convention
+
+First three arguments are passed in registers A, B and C.
+Remaining arguments are pushed onto the stack left-to-right (Such that the last argument has the lowest address)
+Push the return address last (Using the JSR instruction is preferred)
+Return value is placed in A.
+
+Callee is free to clobber all registers.
+Caller must preserve the registers it cares about (Which includes A, B and C, which may be it's own parameters).
+The Caller removes any arguments on the stack itself.
+
+A sample program and the generated assembly, illustrating a function call.
+
+function foo(a,b,c,d) {
+return foo(1,2,3,4);
+}
+
+foo(1,2,3,4);
+
+SET A, 0x0001 ;Literal
+SET B, 0x0002 ;Literal
+SET C, 0x0003 ;Literal
+SET PUSH, 0x0004 ;Literal
+JSR LABEL1_foo ;Calling function
+ADD SP, 0x0001 ;Remove parameters
+BRK ;Non-standard
+:LABEL1_foo
+SET PUSH, A ;Saving register
+SET A, 0x0001 ;Literal
+SET PUSH, B ;Saving register
+SET B, 0x0002 ;Literal
+SET PUSH, C ;Saving register
+SET C, 0x0003 ;Literal
+SET PUSH, X ;Saving register
+SET PUSH, 0x0004 ;Literal
+JSR LABEL1_foo ;Calling function
+ADD SP, 0x0001 ;Remove parameters
+SET J, A ;Save return value from being overwritten by stored register
+SET X, POP ;Restoring register
+SET C, POP ;Restoring register
+SET B, POP ;Restoring register
+SET A, POP ;Restoring register
+SET X, J
+SET A, X
+SET PC, POP ;Return
+SET PC, POP ;Return
View
57 ASM/Draft_Assembly_Relocation_Table.txt
@@ -19,8 +19,8 @@ Table of Contents
3. Relocation Table Format . . . . . . . . . . . . . . . . . . . . 2
4. Relocation Table Positioning . . . . . . . . . . . . . . . . . 3
5. Security Considerations . . . . . . . . . . . . . . . . . . . . 3
- 6. Normative References . . . . . . . . . . . . . . . . . . . . . 3
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 6. Normative References . . . . . . . . . . . . . . . . . . . . . 4
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 4
@@ -50,7 +50,7 @@ Table of Contents
Rhodes [Page 1]
-
+
Assembly Relocation Table April 2012
@@ -88,8 +88,8 @@ Rhodes [Page 1]
+-------------------------+
| Contents of single Word |
+-------------------------+
- | Magic number (0x1234) |
- | Version number (0x0001) |
+ | Magic number |
+ | Version number |
| Size of table |
| Entry 1 |
| ... |
@@ -106,10 +106,25 @@ Rhodes [Page 1]
Rhodes [Page 2]
-
+
Assembly Relocation Table April 2012
+ Magic number The magic number consists of the string "RT" (stands
+ for "Relocation Table") as a packed 7-bit ASCII literal, thus
+ resulting in the value 0x5254.
+
+ Version number The current version number is 0x0001.
+
+ Size of table This field must be set to the total size of the table,
+ in words. This includes the magic number, the version number and
+ this field, too.
+
+ Entries Each entry is a absolute address pointing to a single word
+ in the file the relocation table is contained in, which should be
+ relocated relatively to the position the code is loaded to.
+
+
4. Relocation Table Positioning
The assembly relocation table must be positioned inside the generated
@@ -145,25 +160,16 @@ Rhodes [Page 2]
original value.
-6. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
-
-
-
-
-
-
-
-
+Rhodes [Page 3]
+
+ Assembly Relocation Table April 2012
-Rhodes [Page 3]
+6. Normative References
- Assembly Relocation Table April 2012
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
Author's Address
@@ -211,10 +217,5 @@ Author's Address
-
-
-
-
-
-
-Rhodes [Page 4]
+Rhodes [Page 4]
+
View
19 ASM/Draft_Assembly_Relocation_Table.xml
@@ -61,13 +61,28 @@
<t>The format of the relocation table is as follows:</t>
<texttable anchor="relocation-table" title="Relocation Table">
<ttcol align="center">Contents of single Word</ttcol>
- <c>Magic number (0x1234)</c>
- <c>Version number (0x0001)</c>
+ <c>Magic number</c>
+ <c>Version number</c>
<c>Size of table</c>
<c>Entry 1</c>
<c>...</c>
<c>Entry N</c>
</texttable>
+ <t>
+ <list style="hanging">
+ <t hangText="Magic number">The magic number consists of the string "RT"
+ (stands for "Relocation Table") as a packed 7-bit ASCII literal, thus
+ resulting in the value 0x5254.</t>
+ <t hangText="Version number">The current version number is 0x0001.</t>
+ <t hangText="Size of table">This field must be set to the total size of
+ the table, in words. This includes the magic number, the version
+ number and this field, too.</t>
+ <t hangText="Entries">Each entry is a absolute address pointing to a
+ single word in the file the relocation table is contained in, which
+ should be relocated relatively to the position the code is loaded to.
+ </t>
+ </list>
+ </t>
</section>
<section anchor="relocation-table-position" title="Relocation Table Positioning">
View
92 ASM/Draft_DCPU-16_Disk_Controller_KK1000.txt
@@ -0,0 +1,92 @@
+DCPU-16 Disk Controller KK1000 (Draft v. 0.9)
+Copyright 2012, Robert "King Korihor" Horning
+
+Licensing for reuse under the terms of the Creative Commons Attribution 3.0 United States license
+http://creativecommons.org/licenses/by/3.0/us/
+
+For commentary and discussion about this standard, please visit:
+
+http://www.0x10cforum.com/forum/m/4932880/viewthread/2727631-dcpu16-disc-controller
+
+*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.
+
+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).
+
+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:
+
++-----+------------------+
+| 0 | Register Select |
++-----+------------------+
+| 1 | Register Value |
++-----+------------------+
+
+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:
+
++---+-----+----------------------------+
+| 0 | WSB | Write Sector Buffer |
++---+-----+----------------------------+
+| 1 | RSB | Read Sector Buffer |
++---+-----+----------------------------+
+| 2 | DSR | Disk Status Register |
++---+-----+----------------------------+
+| 3 | CC | Controller Command |
++---+-----+----------------------------+
+| 4 | SCR | Side Control Register |
++---+-----+----------------------------+
+| 5 | TCR | Track Control Register |
++---+-----+----------------------------+
+| 6 | SAR | Sector Access Register |
++---+-----+----------------------------+
+
+Subsequent registers will be treated as reserved values.
+
+
+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
+
+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.
+
+C - Disk Status Register - Bit flags and other general status information relevant to operating system developers.
+
++---+------------------------------------+
+| 4 | Missing Disk Error |
++---+------------------------------------+
+| 3 | Data Read Error |
++---+------------------------------------+
+| 2 | Drive Connect Error |
++---+------------------------------------+
+| 1 | Write Protect |
++---+------------------------------------+
+| 0 | Busy Indicator |
++---+------------------------------------+
+
+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.
+
++---+-------------------------+
+| 0 | Read Sector |
++---+-------------------------+
+| 1 | Write Sector |
++---+-------------------------+
+| 2 | Format Sector |
++---+-------------------------+
+| 3 | Reset Controller |
++---+-------------------------+
+| 4 | Query Controller Status |
++---+-------------------------+
+
+ 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.
+ 2 - Write Sector - Similar to the Read Sector command, but writes data to the disk instead.
+ 3 - Format Sector - Resets the data at the sector indicated by the sector locator registers to become all zeros
+ 4 - Reset Controller - Resets the state of all registers in the controller to zero
+ 5 - Query Controller Status - Used primarily to update the status flags of the Disk Status Register.
+
+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.
+
+E - Side Control Register - Indicates which "side" of the disk is currently being written
+
+F - Track Control Register - Indicates which "track" is currently being read or written
+
+G - Sector Access Register - Indicates which sector on a given track is currently being accessed
+
+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.
+
+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.
View
195 ASM/Draft_DCPU-16_Specification_v2.txt
@@ -0,0 +1,195 @@
+DCPU-16 Specification
+Copyright 1985 Mojang
+Version 1.1
+
+
+
+=== SUMMARY ====================================================================
+
+* 16 bit words
+* 0x10000 words of ram
+* 8 registers (A, B, C, X, Y, Z, I, J)
+* program counter (PC)
+* stack pointer (SP)
+* extra/excess (EX)
+* interrupt address (IA)
+
+In this document, anything within [brackets] is shorthand for "the value of the
+RAM at the location of the value inside the brackets". For example, SP means
+stack pointer, but [SP] means the value of the RAM at the location the stack
+pointer is pointing at.
+
+Whenever the CPU needs to read a word, it reads [PC], then increases PC by one.
+Shorthand for this is [PC++]. In some cases, the CPU will modify a value before
+reading it, in this case the shorthand is [++PC].
+
+For stability and to reduce bugs, it's strongly suggested all multi-byte
+operations use little endian in all DCPU-16 programs, wherever possible.
+
+
+
+=== INSTRUCTIONS ===============================================================
+
+Instructions are 1-3 words long and are fully defined by the first word.
+In a basic instruction, the lower five bits of the first word of the instruction
+are the opcode, and the remaining eleven bits are split into a five bit value b
+and a six bit value a.
+b is always handled by the processor after a, and is the lower five bits.
+In bits (in LSB-0 format), a basic instruction has the format: aaaaaabbbbbooooo
+
+In the tables below, C is the time required in cycles to look up the value, or
+perform the opcode, VALUE is the numerical value, NAME is the mnemonic, and
+DESCRIPTION is a short text that describes the opcode or value.
+
+
+
+--- Values: (5/6 bits) ---------------------------------------------------------
+ C | VALUE | DESCRIPTION
+---+-----------+----------------------------------------------------------------
+ 0 | 0x00-0x07 | register (A, B, C, X, Y, Z, I or J, in that order)
+ 0 | 0x08-0x0f | [register]
+ 1 | 0x10-0x17 | [register + next word]
+ 0 | 0x18 | (PUSH / [--SP]) if in b, or (POP / [SP++]) if in a
+ 0 | 0x19 | [SP] / PEEK
+ 0 | 0x1a | [SP + next word] / PICK n
@riking
riking added a note

This value should add a cycle as it involves the next word.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ 0 | 0x1b | SP
+ 0 | 0x1c | PC
+ 0 | 0x1d | EX
+ 1 | 0x1e | [next word]
+ 1 | 0x1f | next word (literal)
+ 0 | 0x20-0x3f | literal value 0xffff-0x1e (-1..30) (literal) (only for a)
+ --+-----------+----------------------------------------------------------------
+
+* "next word" means "[PC++]". Increases the word length of the instruction by 1.
+* By using 0x18, 0x19, 0x1a as PEEK, POP/PUSH, and PICK there's a reverse stack
+ starting at memory location 0xffff. Example: "SET PUSH, 10", "SET X, POP"
+
+
+
+--- Basic opcodes (5 bits) ----------------------------------------------------
+ C | VAL | NAME | DESCRIPTION
+---+------+----------+--------------------------------------------------------
+ - | 0x00 | n/a | special instruction - see below
+ 1 | 0x01 | SET b, a | sets b to a
+ 2 | 0x02 | ADD b, a | sets b to b+a, sets EX to 0x0001 if there's an overflow,
+ | | | 0x0 otherwise
+ 2 | 0x03 | SUB b, a | sets b to b-a, sets EX to 0xffff if there's an underflow,
+ | | | 0x0 otherwise
+ 2 | 0x04 | MUL b, a | sets b to b*a, sets EX to ((b*a)>>16)&0xffff (treats b,
+ | | | a as unsigned)
+ 2 | 0x05 | MLI b, a | like MUL, but treat b, a as signed
+ 3 | 0x06 | DIV b, a | sets b to b/a, sets EX to ((b<<16)/a)&0xffff. if a==0,
+ | | | sets b and EX to 0 instead. (treats b, a as unsigned)
+ 3 | 0x07 | DVI b, a | like DIV, but treat b, a as signed
+ 3 | 0x08 | MOD b, a | sets b to b%a. if a==0, sets b to 0 instead.
+ 1 | 0x09 | AND b, a | sets b to b&a
+ 1 | 0x0a | BOR b, a | sets b to b|a
+ 1 | 0x0b | XOR b, a | sets b to b^a
+ 2 | 0x0c | SHR b, a | sets b to b>>>a, sets EX to ((b<<16)>>a)&0xffff
+ | | | (logical shift)
+ 2 | 0x0d | ASR b, a | sets b to b>>a, sets EX to ((b<<16)>>>a)&0xffff
+ | | | (arithmetic shift) (treats b as signed)
+ 2 | 0x0e | SHL b, a | sets b to b<<a, sets EX to ((b<<a)>>16)&0xffff
+ - | 0x0f | - |
+ 2+| 0x10 | IFB b, a | performs next instruction only if (b&a)!=0
+ 2+| 0x11 | IFC b, a | performs next instruction only if (b&a)==0
+ 2+| 0x12 | IFE b, a | performs next instruction only if b==a
+ 2+| 0x13 | IFN b, a | performs next instruction only if b!=a
+ 2+| 0x14 | IFG b, a | performs next instruction only if b>a
+ 2+| 0x15 | IFA b, a | performs next instruction only if b>a (signed)
+ 2+| 0x16 | IFL b, a | performs next instruction only if b<a
+ 2+| 0x17 | IFU b, a | performs next instruction only if b<a (signed)
+ - | 0x18 | - |
+ - | 0x19 | - |
+ - | 0x1a | - |
+ - | 0x1b | - |
+ - | 0x1c | - |
+ - | 0x1d | - |
+ - | 0x1e | - |
+ - | 0x1f | - |
+---+------+----------+----------------------------------------------------------
+
+* The branching opcodes take one cycle longer to perform if the test fails
+* Signed numbers are represented using two's complement.
+
+
+
+Special opcodes always have their lower five bits unset, have one value and a
+five bit opcode. In binary, they have the format: aaaaaaooooo00000
+The value (a) is in the same six bit format as defined earlier.
+
+--- Special opcodes: (6 bits) --------------------------------------------------
+ C | VAL | NAME | DESCRIPTION
+---+------+-------+-------------------------------------------------------------
+ - | 0x00 | n/a | reserved for future expansion
+ 3 | 0x01 | JSR a | pushes the address of the next instruction to the stack,
+ | | | then sets PC to a
+ - | 0x02 | - |
+ - | 0x03 | - |
+ - | 0x04 | - |
+ - | 0x05 | - |
+ - | 0x06 | - |
+ - | 0x07 | - |
+ 4 | 0x08 | INT a | triggers a software interrupt with message a
+ 1 | 0x09 | ING a | sets a to IN
+ 1 | 0x0a | INS a | sets IN to a
@riking
riking added a note

is "IN" supposed to be IA, or is it supposed to be "input" (don't think so)?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ - | 0x0b | - |
+ - | 0x0c | - |
+ - | 0x0d | - |
+ - | 0x0e | - |
+ - | 0x0f | - |
+ 2 | 0x10 | HWN a | sets a to number of connected hardware devices
+ 4 | 0x11 | HWQ a | sets A, B, C, X, Y registers to information about hardware a
+ | | | a+b is a 32 bit word identifying the hardware type
+ | | | c is the hardware revision
+ | | | x+y is a 32 bit word identifying the manufacturer
+ 4+| 0x12 | HWI a | sends an interrupt to hardware a
+ - | 0x13 | - |
+ - | 0x14 | - |
+ - | 0x15 | - |
+ - | 0x16 | - |
+ - | 0x17 | - |
+ - | 0x18 | - |
+ - | 0x19 | - |
+ - | 0x1a | - |
+ - | 0x1b | - |
+ - | 0x1c | - |
+ - | 0x1d | - |
+ - | 0x1e | - |
+ - | 0x1f | - |
+---+------+-------+-------------------------------------------------------------
+
+
+
+=== INTERRUPTS =================================================================
+
+When IA is set to something other than 0, interrupts triggered on the DCPU-16
+will push PC to the stack, followed by pushing A to the stack, then set the PC
+to IA, and A to the interrupt message. A well formed interrupt handler must pop
+A from the stack before returning (popping PC from the stack)
+
+If IA is set to 0, a triggered interrupt does nothing.
+
+The DCPU-16 will attempt to perform one clock interrupt 60 times per second,
+with the A message being 0.
+
+
+
+=== HARDWARE ===================================================================
+
+The DCPU-16 supports up to 65536 connected hardware devices. These devices can
+be anything from additional storage, sensors, monitors or speakers.
+How to control the hardware is specified per hardware device, but the DCPU-16
+supports a standard enumeration method for detecting connected hardware via
+the HWN, HWQ and HWI instructions.
+
+Interrupts sent to hardware can't contain messages, can take additional cycles,
+and can read or modify any registers or memory adresses on the DCPU-16. This
+behavior changes per hardware device and is documented in the hardware
+documentation.
+
+Hardware must NOT start modifying registers or ram on the DCPU-16 before at
+least one HWI call has been made to the hardware.
+
+The DPCU-16 does not support hot swapping hardware. The behavior of connecting
+or disconnecting hardware while the DCPU-16 is undefined.
@riking
riking added a note

"while the DCPU-16 is running is undefined"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
View
560 ASM/Spec_0xSCA.txt
@@ -0,0 +1,560 @@
+
+
+
+RFC X____ J. Kuijpers, Ed.
+ Jarvix
+ M. Beermann, Ed.
+ April 24, 2012
+
+
+ 0xSCA: Standards Committee Assembly
+
+Abstract
+
+ This document describes an assembly and preprocessor syntax suitable
+ for the DCPU-16 environment. This syntax is called the 0xSCA, or
+ Standards Committee Assembly.
+
+ This is not a standard.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kuijpers & Beermann [Page 1]
+
+ Assembly Syntactics April 2012
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3
+ 2. Document Markup . . . . . . . . . . . . . . . . . . . . . . . 3
+ 2.1. Indentation and whitepace . . . . . . . . . . . . . . . . 3
+ 3. Case sensitivity . . . . . . . . . . . . . . . . . . . . . . . 3
+ 4. Preprocessor Markup . . . . . . . . . . . . . . . . . . . . . 3
+ 4.1. Comments . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 4.2. Prefix . . . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 4.3. Directives . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 4.3.1. Inclusion . . . . . . . . . . . . . . . . . . . . . . 4
+ 4.3.1.1. Code . . . . . . . . . . . . . . . . . . . . . . . 4
+ 4.3.1.2. Binary . . . . . . . . . . . . . . . . . . . . . . 4
+ 4.3.2. Definitions . . . . . . . . . . . . . . . . . . . . . 5
+ 4.3.3. Data insertion . . . . . . . . . . . . . . . . . . . . 5
+ 4.3.4. Origin relocation . . . . . . . . . . . . . . . . . . 5
+ 4.3.5. Macros: macro block and macro insertion . . . . . . . 6
+ 4.3.6. Repeat block . . . . . . . . . . . . . . . . . . . . . 6
+ 4.3.7. Conditionals . . . . . . . . . . . . . . . . . . . . . 7
+ 4.3.8. Error reporting . . . . . . . . . . . . . . . . . . . 7
+ 4.3.9. Alignment . . . . . . . . . . . . . . . . . . . . . . 7
+ 4.3.10. Echo general output . . . . . . . . . . . . . . . . . 8
+ 5. Tokenizer Markup . . . . . . . . . . . . . . . . . . . . . . . 8
+ 5.1. Labels . . . . . . . . . . . . . . . . . . . . . . . . . . 8
+ 5.2. Inline character literals . . . . . . . . . . . . . . . . 8
+ 6. Inline arithmetic . . . . . . . . . . . . . . . . . . . . . . 8
+ 7. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 9
+ 7.1. Recognition of conformance . . . . . . . . . . . . . . . . 9
+ 8. Design Rationale . . . . . . . . . . . . . . . . . . . . . . . 9
+ 8.1. Labels . . . . . . . . . . . . . . . . . . . . . . . . . . 9
+ 8.2. Preprocessor . . . . . . . . . . . . . . . . . . . . . . . 9
+ 9. Security Considerations . . . . . . . . . . . . . . . . . . . 10
+ 10. Normative References . . . . . . . . . . . . . . . . . . . . . 10
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kuijpers & Beermann [Page 2]
+
+ Assembly Syntactics April 2012
+
+
+1. Introduction
+
+ This documents describes 0xSCA, Standards Committee Assembly. It is
+ a definition of a syntax to be used for writing assembly for the
+ DCPU-16 processor. Use of this syntax is voluntarily. With 0xSCA,
+ there is a defined syntax, and could decrease code incompatibility
+ among compilers.
+
+ Again, to be clear: 0xSCA is a syntax definition, not a standard.
+ 0xSCA is to DCPU-16, what AT&T or the NASM syntax is to IA-32.
+
+1.1. Requirements Language
+
+ 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 [RFC2119].
+
+
+2. Document Markup
+
+2.1. Indentation and whitepace
+
+ Whitespace MUST be allowed between all elements of a line, including
+ but not limited to opcodes, values, syntactic characters and
+ preprocessor directives. Both a space (' ' U+0020) and a tab
+ (U+0009) are considered whitespace characters.
+
+ Indenting instructions is RECOMMENDED. NOT indenting labels and
+ preprocessor directives RECOMMENDED. The assembler MUST NOT mandate
+ indentation to assemble successfully.
+
+
+3. Case sensitivity
+
+ Assemblers MUST accept everything without regard to case EXCEPT
+ string and character literals.
+
+
+4. Preprocessor Markup
+
+4.1. Comments
+
+ Comments are used to add information to the code, making it more
+ readable and understandable. Comments can consist any character in
+ any combination. This document specifies one-line comments only.
+
+ Any characters following and in the same line of a semicolon (;
+ U+003B) are comments and MUST be ignored, except when the semicolon
+
+
+
+Kuijpers & Beermann [Page 3]
+
+ Assembly Syntactics April 2012
+
+
+ resides within the representation of a string. In that case, the
+ semicolon MUST NOT be treated as a comment.
+
+4.2. Prefix
+
+ Every preprocessor directive starts with an identifier. This
+ identifier is used to distinguish preprocessor directives from other
+ code.
+
+ For historical reasons, directives can either start with a dot (.
+ U+002E) or a number sign (# U+0023).
+
+ Preprocessor directives MUST start with a dot (. U+002E) or a number
+ sign (# U+0023).
+
+ Using a dot is RECOMMENDED to distinguish between C preprocessor
+ syntax.
+
+4.3. Directives
+
+ All directives in this section MUST be handled in order and in
+ recognition of their position. For the purpose of this document, a
+ dot (.) is used to describe preprocessor directives.
+
+4.3.1. Inclusion
+
+4.3.1.1. Code
+
+ .include "file"
+ .include <file>
+
+ The former directive MUST include the file into the current file.
+ The path is relative to the current file. The assembler SHOULD
+ report to the user if the given filename does not exist and continue
+ assembly.
+
+ The latter includes the file from an implementation defined location,
+ which may not even exist but trigger certain behaviour, i.e.
+ inclusion of intrinsics.
+
+4.3.1.2. Binary
+
+ .incbin "file"
+ .incbin <file>
+
+ incbin MUST include the specified binary as raw, unprocessed data,
+ the path to the file is relative from the current file. All labels
+ behind this directive MUST be offset by the size of the file.
+
+
+
+Kuijpers & Beermann [Page 4]
+
+ Assembly Syntactics April 2012
+
+
+ The latter form of incbin MUST include the file from an
+ implementation defined location.
+
+4.3.2. Definitions
+
+ .def name [value]
+ .define name [value]
+ .equ name value
+ .undef name
+
+ def/define/equ MUST assign the constant value to name. If the value
+ is omitted, the literal 1 (one) MUST be assumed.
+
+ undef MUST remove the given symbol from the namespace. If the given
+ symbol does not exist compilation SHOULD continue and a warning MAY
+ be emitted.
+
+ Any occurances of the definition during its existence, MUST be
+ replaced with the given value to the definition.
+
+4.3.3. Data insertion
+
+ .dw value [,value...]
+ .db value [,value...]
+ .ascii "string"
+
+ dw (data word) MUST store the values literally and unpacked at the
+ location of the directive.
+
+ db (data byte) MUST pack (i.e. two bytes per word, first byte is LSB)
+ the values at the location of the directive. Words are filled with
+ empty bytes when the data does not evenly fit into 16-bit words.
+
+ ascii MUST store the string unpacked (i.e. character is LSB, one word
+ per character) at the location of the directive.
+
+ asciip (a pascal string) MUST store the string unpacked (i.e.
+ character is LSB, one word per character) at the location of the
+ directive, prepending the string with its length.
+
+ asciic (a C string) MUST store the string unpacked (i.e. character is
+ LSB, one word per character) at the location of the directive,
+ appending 0x0000 (\0).
+
+4.3.4. Origin relocation
+
+ .org address
+
+
+
+
+Kuijpers & Beermann [Page 5]
+
+ Assembly Syntactics April 2012
+
+
+ The org preprocessor directive MUST take an address as the only
+ argument. Assemblers SHOULD verify the address is 16-bit sized.
+ Assembler MUST add this address to the address of all labels,
+ creating a relocation of the program.
+
+4.3.5. Macros: macro block and macro insertion
+
+ .macro name([param [,param...]])
+ code
+ .end
+ name([param [,param...]])
+
+ The macro directive defines a macro, a parametrized block of code
+ that can be inserted any time later. Parameters, if any, are written
+ in parentheses seperated by commas (,).
+
+ Using the name with parenthis MUST insert a formerly defined macro
+ and expands the parameters of the macro with the comma-seperated
+ parameters following the name of the macro to insert.
+
+ Parameter substitutions can only be constant values and memory
+ references. Preprocessor directives inside the macro MUST be handled
+ upon insertion, not definition.
+
+4.3.6. Repeat block
+
+ .rep times
+ code
+ .end
+
+ The code in the repeat-block MUST be repeated the number of times
+ specified. 'times' MUST be a positive integer. Preprocessor
+ directives inside the repeat-block MUST be handled when the
+ repetition is complete, to make allow conditional repetitions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kuijpers & Beermann [Page 6]
+
+ Assembly Syntactics April 2012
+
+
+4.3.7. Conditionals
+
+ .if expression
+ codeTrue
+ .elif expression
+ codeElseTrue
+ .elseif expression
+ codeElseTrue
+ .else
+ codeElse
+ .end
+ .ifdef definition
+ .ifndef definition
+ isdef(definition)
+
+ For the definition of valid expressions, see Section 6.
+
+ The if clause is REQUIRED. The else clause is OPTIONAL. The elif/
+ elseif clause is OPTIONAL and can occur multiple times.
+
+ If expression consists of a single constant value, then expression =
+ 1 MUST be assumed. If expression evaluates to 1, the codeTrue-block
+ MUST be assembled. When the evaluation fails, the next elif block
+ must be evaluated. In any other case codeElse, if an else clause is
+ specified, MUST be assembled.
+
+ isdef(symbol) can be used in place of expression. isdef MUST evaluate
+ to 1 if the given symbol is currently defined, else it MUST evaluate
+ to 0.
+
+ ifdef is short for if isdef(). ifndef is short for if !isdef()
+
+ Nesting of if directives MUST be supported.
+
+4.3.8. Error reporting
+
+ .error message
+
+ Triggers an assembler error with the message, stopping execution of
+ the assembler. The message SHOULD be shown in combination with the
+ filename and line number.
+
+4.3.9. Alignment
+
+ .align boundary
+
+ Aligns code or data on doubleword or other boundary.
+
+
+
+
+Kuijpers & Beermann [Page 7]
+
+ Assembly Syntactics April 2012
+
+
+ The assembler MUST add zeroed words (0x0000) to the generated
+ machinecode until the alignment is correct. The number of words
+ inserted can be calculated using the formula: 'boundary -
+ (currentPosition modulo boundary)'.
+
+4.3.10. Echo general output
+
+ .echo message
+
+ The echo directive can be used to inform the user about (possible)
+ issues, progress, etc.
+
+ The assembler SHOULD report the message to the user.
+
+
+5. Tokenizer Markup
+
+5.1. Labels
+
+ Labels MUST be single-worded identifiers containing only alphabetical
+ characters (/[A-Za-z]/), numbers (/[0-9]/) and underscores (_
+ U+005F). The label MUST represent the address of following
+ instruction or data. A label MUST NOT start with a number or an
+ underscore. A label SHOULD end with a colon (: U+003A), but starting
+ with a colon MAY be supported.
+
+ Local labels MUST start with an underscore (_ U+002E) and end with a
+ colon (: U+003A). Local labels MUST be scoped between the
+ surrounding global labels. Local labels in different scopes MUST be
+ able to have the same name.
+
+5.2. Inline character literals
+
+ A character surrounded by apostrophes (' U+0029) MUST be interpreted
+ as its corresponding 7-bit ASCII value in a word (LSB).
+
+
+6. Inline arithmetic
+
+ Source code can include inline arithmetics anywhere a constant value
+ is permitted. Inline arithmetic may only consist of + (addition), -
+ (subtraction), * (multiplication), / (integer division), % (modulus)
+ and ! (negation), parentheses may be used to group expressions.
+
+ The following bitwise operators MUST also be supported: & (bit-wise
+ AND) ^ (bit-wise XOR), | (bit-wise OR), ~ (bit-wise NOT), << and >>
+ (bit-wise shifts).
+
+
+
+
+Kuijpers & Beermann [Page 8]
+
+ Assembly Syntactics April 2012
+
+
+ The following logical and bitwise operators MUST also be supported:
+ == (equal), != (not equal, also <>), < (smaller than), > (greater
+ than), <= (smaller or equal), >= (greater or equal), & (bit-wise AND)
+ ^ (bit-wise XOR), | (bit-wise OR), && (logical AND), || (logical OR),
+ ^^ (logical XOR) which MUST be evaluated with respect to this order.
+
+ Inline arithmetic MUST be evaluated as soon as possible, the result
+ MUST be used as a literal value in place of the expression.
+
+
+7. Conformance
+
+7.1. Recognition of conformance
+
+ An assembler, formatter and any other assembly related program that
+ is fully compliant to 0xSCA MAY label itself "0xSCA compatible".
+ When using this label, the subject SHOULD include a note of the
+ version of the RFC it is written against.
+
+
+8. Design Rationale
+
+8.1. Labels
+
+ Although Notch used the syntax :label in his first examples, it is
+ not common in any popular assembler. Thus we decided for label: as
+ the recommended form, still silently allowing the deprecated form.
+
+ To simplify writing reusable code we also introduced local labels,
+ which are only visible from within the global label they are defined
+ within. Implementing this is easy to do and introduces little
+ overhead, as nesting is neither specified nor recommended.
+
+8.2. Preprocessor
+
+ 0xSCA allows many operators and even parentheses in expressions for
+ if-clauses, which complicates the implementation of these. We do
+ recognize that, but the actual implementation difficulty is not too
+ high, as there are many examples how to achieve this and we think
+ that the additional power and reduced code complexity, resulting in
+ better maintainable code, is worth the effort.
+
+ The ability to define custom constants inline is easy to implement
+ and yields more easily maintainable code, while introducing a minimum
+ of additional syntax.
+
+ Both kinds of file inclusion support two different forms, one
+ including the file relative to the current file, and the other
+
+
+
+Kuijpers & Beermann [Page 9]
+
+ Assembly Syntactics April 2012
+
+
+ including it from an implementation defined location. The former is
+ ideal for splitting a program in multiple parts, while the latter is
+ intended for implementation-provided resources such as source level
+ libraries.
+
+ A preprocessor must accept every directive with a dot (.) or a number
+ sign (#) prefix. While Notch seems to prefer the latter, the former
+ is much more common among todays assemblers. Thus we decided to
+ support both, especiall as the implementation-side overhead is very
+ low.
+
+
+9. Security Considerations
+
+ This memo has no applicable security considerations.
+
+
+10. Normative References
+
+ [GHBP] Marti, V., "Take Over The Galaxy with GitHub", April 2012,
+ <https://github.com/blog/
+ 1098-take-over-the-galaxy-with-github>.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+
+Authors' Addresses
+
+ Jos Kuijpers (editor)
+ Jarvix
+
+ Email: jos@kuijpersvof.nl (contact for any inquiries)
+ URI: http://www.jarvix.org/
+
+
+ Marian Beermann (editor)
+
+ Email: public@enkore.de
+ URI: http://www.enkore.de/
+
+
+
+
+
+
+
+
+
+
+
+Kuijpers & Beermann [Page 10]
+
View
365 ASM/Spec_0xSCA.xml
@@ -0,0 +1,365 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
+<?rfc strict="yes" ?>
+<?rfc toc="yes"?>
+<?rfc tocdepth="4"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes" ?>
+<?rfc compact="yes" ?>
+<?rfc subcompact="no" ?>
+<?rfc private="RFC X____" ?>
+<rfc ipr="none" category="bcp" docName="recommendation-for-assembly-syntactics">
+ <front>
+ <title abbrev="Assembly Syntactics">0xSCA: Standards Committee Assembly</title>
+
+ <author fullname="Jos Kuijpers" initials="J.C." role="editor"
+ surname="Kuijpers">
+ <organization>Jarvix</organization>
+
+ <address>
+ <email>jos@kuijpersvof.nl (contact for any inquiries)</email>
+ <uri>http://www.jarvix.org/</uri>
+ </address>
+ </author>
+ <author fullname="Marian Beermann" initials="M.B." role="editor"
+ surname="Beermann">
+ <address>
+ <email>public@enkore.de</email>
+ <uri>http://www.enkore.de/</uri>
+ </address>
+ </author>
+ <date month="April" year="2012" />
+ <area>ASM</area>
+ <workgroup>0x10c Standards Committee</workgroup>
+ <abstract>
+ <t>This document describes an assembly and preprocessor syntax
+ suitable for the DCPU-16 environment. This syntax is called the
+ 0xSCA, or Standards Committee Assembly.</t>
+ <t>This is not a standard.</t>
+ </abstract>
+ </front>
+
+ <middle>
+ <section title="Introduction">
+ <t>This documents describes 0xSCA, Standards Committee Assembly. It
+ is a definition of a syntax to be used for writing assembly for the
+ DCPU-16 processor. Use of this syntax is voluntarily. With 0xSCA,
+ there is a defined syntax, and could decrease code incompatibility
+ among compilers.</t>
+ <t>Again, to be clear: 0xSCA is a syntax definition, not a standard.
+ 0xSCA is to DCPU-16, what AT&amp;T or the NASM syntax is to IA-32.</t>
+
+ <section title="Requirements Language">
+ <t>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 <xref
+ target="RFC2119">RFC 2119</xref>.</t>
+ </section>
+ </section>
+
+ <section title="Document Markup">
+ <section title="Indentation and whitepace">
+ <t>Whitespace MUST be allowed between all
+ elements of a line, including but not limited to opcodes, values,
+ syntactic characters and preprocessor directives. Both a space
+ (' ' U+0020) and a tab (U+0009) are considered whitespace
+ characters.</t>
+ <t>Indenting instructions is RECOMMENDED. NOT indenting
+ labels and preprocessor directives RECOMMENDED. The assembler
+ MUST NOT mandate indentation to assemble successfully.</t>
+ </section>
+ </section>
+
+ <section title="Case sensitivity">
+ <t>Assemblers MUST accept everything without regard to case EXCEPT
+ string and character literals.</t>
+ </section>
+
+ <section title="Preprocessor Markup">
+ <section title="Comments">
+ <t>Comments are used to add information to the code, making it
+ more readable and understandable. Comments can consist any
+ character in any combination. This document specifies one-line
+ comments only.</t>
+ <t>Any characters following and in the same line of a semicolon
+ (; U+003B) are comments and MUST be ignored, except when the
+ semicolon resides within the representation of a string. In
+ that case, the semicolon MUST NOT be treated as a comment.</t>
+ </section>
+ <section title="Prefix">
+ <t>Every preprocessor directive starts with an identifier. This
+ identifier is used to distinguish preprocessor directives from
+ other code.</t>
+ <t>For historical reasons, directives can either start with a dot
+ (. U+002E) or a number sign (# U+0023).</t>
+ <t>Preprocessor directives MUST start with a dot (. U+002E) or a
+ number sign (# U+0023).</t>
+ <t>Using a dot is RECOMMENDED to distinguish between C preprocessor
+ syntax.</t>
+ </section>
+ <section title="Directives">
+ <t>All directives in this section MUST be handled in order and
+ in recognition of their position. For the purpose of this document,
+ a dot (.) is used to describe preprocessor directives.</t>
+ <section title="Inclusion">
+ <section title="Code">
+ <figure><artwork><![CDATA[
+.include "file"
+.include <file>]]></artwork></figure>
+ <t>The former directive MUST include the file into the
+ current file. The path is relative to the current file.
+ The assembler SHOULD report to the user if the given
+ filename does not exist and continue assembly.</t>
+ <t>The latter includes the file from an implementation
+ defined location, which may not even exist but trigger
+ certain behaviour, i.e. inclusion of intrinsics.</t>
+ </section>
+ <section title="Binary">
+ <figure><artwork><![CDATA[
+.incbin "file"
+.incbin <file>]]></artwork></figure>
+ <t>incbin MUST include the specified binary as raw,
+ unprocessed data, the path to the file is relative
+ from the current file. All labels behind this directive
+ MUST be offset by the size of the file.</t>
+ <t>The latter form of incbin MUST include the file from
+ an implementation defined location.</t>
+ </section>
+ </section>
+ <section title="Definitions">
+ <figure><artwork><![CDATA[
+.def name [value]
+.define name [value]
+.equ name value
+.undef name]]></artwork></figure>
+ <t>def/define/equ MUST assign the constant value to name. If the value
+ is omitted, the literal 1 (one) MUST be assumed.</t>
+ <t>undef MUST remove the given symbol from the namespace.
+ If the given symbol does not exist compilation SHOULD
+ continue and a warning MAY be emitted.</t>
+ <t>Any occurances of the definition during its existence,
+ MUST be replaced with the given value to the definition.</t>
+ </section>
+ <section title="Data insertion">
+ <figure><artwork><![CDATA[
+.dw value [,value...]
+.db value [,value...]
+.ascii "string"]]></artwork></figure>
+ <t>dw (data word) MUST store the values literally and unpacked at
+ the location of the directive.</t>
+ <t>db (data byte) MUST pack (i.e. two bytes per word, first byte is LSB)
+ the values at the location of the directive. Words are filled with empty
+ bytes when the data does not evenly fit into 16-bit words.</t>
+ <t>ascii MUST store the string unpacked (i.e. character is LSB,
+ one word per character) at the location of the directive.</t>
+ <t>asciip (a pascal string) MUST store the string unpacked (i.e.
+ character is LSB, one word per character) at the location of the
+ directive, prepending the string with its length.</t>
+ <t>asciic (a C string) MUST store the string unpacked (i.e.
+ character is LSB, one word per character) at the location of the
+ directive, appending 0x0000 (\0).</t>
+ </section>
+ <section title="Origin relocation">
+ <figure><artwork><![CDATA[
+.org address]]></artwork></figure>
+ <t>The org preprocessor directive MUST take an address
+ as the only argument. Assemblers SHOULD verify the
+ address is 16-bit sized. Assembler MUST add this
+ address to the address of all labels, creating a
+ relocation of the program.</t>
+ </section>
+ <section title="Macros: macro block and macro insertion">
+ <figure><artwork><![CDATA[
+.macro name([param [,param...]])
+ code
+.end
+name([param [,param...]])]]></artwork></figure>
+ <t>The macro directive defines a macro, a parametrized block
+ of code that can be inserted any time later. Parameters,
+ if any, are written in parentheses seperated by commas (,).</t>
+ <t>Using the name with parenthis MUST insert a formerly defined
+ macro and expands the parameters of the macro with the
+ comma-seperated parameters following the name of the macro to
+ insert.</t>
+ <t>Parameter substitutions can only be constant values and
+ memory references. Preprocessor directives inside the macro
+ MUST be handled upon insertion, not definition.</t>
+ </section>
+ <section title="Repeat block">
+ <figure><artwork><![CDATA[
+.rep times
+ code
+.end]]></artwork></figure>
+ <t>The code in the repeat-block MUST be repeated the number
+ of times specified. 'times' MUST be a positive integer.
+ Preprocessor directives inside the repeat-block MUST be
+ handled when the repetition is complete, to make allow
+ conditional repetitions.</t>
+ </section>
+ <section title="Conditionals">
+ <figure><artwork><![CDATA[
+.if expression
+ codeTrue
+.elif expression
+ codeElseTrue
+.elseif expression
+ codeElseTrue
+.else
+ codeElse
+.end
+.ifdef definition
+.ifndef definition
+isdef(definition)]]></artwork></figure>
+ <t>For the definition of valid expressions, see
+ <xref target="ia" />.</t>
+ <t>The if clause is REQUIRED. The else clause is OPTIONAL.
+ The elif/elseif clause is OPTIONAL and can occur multiple times.</t>
+ <t>If expression consists of a single constant value,
+ then expression = 1 MUST be assumed. If expression evaluates
+ to 1, the codeTrue-block MUST be assembled. When the
+ evaluation fails, the next elif block must be evaluated. In
+ any other case codeElse, if an else clause is specified,
+ MUST be assembled.</t>
+ <t>isdef(symbol) can be used in place of expression.
+ isdef MUST evaluate to 1 if the given symbol is currently
+ defined, else it MUST evaluate to 0.</t>
+ <t>ifdef is short for if isdef(). ifndef is short for if !isdef()</t>
+ <t>Nesting of if directives MUST be supported.</t>
+ </section>
+ <section title="Error reporting">
+ <figure><artwork><![CDATA[
+.error message]]></artwork></figure>
+ <t>Triggers an assembler error with the message, stopping
+ execution of the assembler. The message SHOULD be shown in
+ combination with the filename and line number.</t>
+ </section>
+ <section title="Alignment">
+ <figure><artwork><![CDATA[
+.align boundary]]></artwork></figure>
+ <t>Aligns code or data on doubleword or other boundary.</t>
+ <t>The assembler MUST add zeroed words (0x0000) to the generated
+ machinecode until the alignment is correct. The number of
+ words inserted can be calculated using the formula:
+ 'boundary - (currentPosition modulo boundary)'.</t>
+ </section>
+ <section title="Echo general output">
+ <figure><artwork><![CDATA[
+.echo message]]></artwork></figure>
+ <t>The echo directive can be used to inform the user about
+ (possible) issues, progress, etc.</t>
+ <t>The assembler SHOULD report the message to the user.</t>
+ </section>
+ </section>
+ </section>
+
+ <section title="Tokenizer Markup">
+ <section title="Labels">
+ <t>Labels MUST be single-worded identifiers containing only
+ alphabetical characters (/[A-Za-z]/), numbers (/[0-9]/) and
+ underscores (_ U+005F). The label MUST represent the address of
+ following instruction or data. A label MUST NOT start with a
+ number or an underscore. A label SHOULD end with a colon (: U+003A), but
+ starting with a colon MAY be supported.</t>
+ <t>Local labels MUST start with an underscore (_ U+002E) and end
+ with a colon (: U+003A). Local labels MUST be scoped between the
+ surrounding global labels. Local labels in different scopes
+ MUST be able to have the same name.</t>
+ </section>
+ <section title="Inline character literals">
+ <t>A character surrounded by apostrophes (' U+0029) MUST be
+ interpreted as its corresponding 7-bit ASCII value in a word
+ (LSB).</t>
+ </section>
+ </section>
+
+ <section title="Inline arithmetic" anchor="ia">
+ <t>Source code can include inline arithmetics anywhere a
+ constant value is permitted. Inline arithmetic may only
+ consist of + (addition), - (subtraction), * (multiplication), /
+ (integer division), % (modulus) and ! (negation), parentheses may be used
+ to group expressions.</t>
+ <t>The following bitwise operators MUST also be supported: &amp;
+ (bit-wise AND) ^ (bit-wise XOR), | (bit-wise OR), ~ (bit-wise NOT), &lt;&lt;
+ and &gt;&gt; (bit-wise shifts).
+ </t>
+ <t>The following logical and bitwise operators MUST also be
+ supported: == (equal), != (not equal, also &lt;&gt;),
+ &lt; (smaller than), &gt; (greater than), &lt;= (smaller or
+ equal), &gt;= (greater or equal), &amp; (bit-wise AND) ^
+ (bit-wise XOR), | (bit-wise OR), &amp;&amp; (logical AND), ||
+ (logical OR), ^^ (logical XOR) which MUST be evaluated with
+ respect to this order.</t>
+ <t>Inline arithmetic MUST be evaluated as soon as possible,
+ the result MUST be used as a literal value in place of the expression.</t>
+ </section>
+
+ <section title="Conformance">
+ <section title="Recognition of conformance">
+ <t>An assembler, formatter and any other assembly related
+ program that is fully compliant to 0xSCA MAY label itself
+ "0xSCA compatible". When using this label, the subject SHOULD
+ include a note of the version of the RFC it is written against.
+ </t>
+ </section>
+ </section>
+
+ <section title="Design Rationale">
+ <section title="Labels">
+ <t>Although Notch used the syntax :label in his first
+ examples, it is not common in any popular assembler.
+ Thus we decided for label: as the recommended form,
+ still silently allowing the deprecated form.</t>
+ <t>To simplify writing reusable code we also introduced
+ local labels, which are only visible from within the
+ global label they are defined within. Implementing this
+ is easy to do and introduces little overhead, as nesting
+ is neither specified nor recommended.</t>
+ </section>
+
+ <section title="Preprocessor">
+ <t>0xSCA allows many operators and even parentheses in
+ expressions for if-clauses, which complicates the
+ implementation of these. We do recognize that, but
+ the actual implementation difficulty is not too high,
+ as there are many examples how to achieve this and
+ we think that the additional power and reduced
+ code complexity, resulting in better maintainable
+ code, is worth the effort.</t>
+ <t>The ability to define custom constants inline is
+ easy to implement and yields more easily maintainable
+ code, while introducing a minimum of additional syntax.</t>
+ <t>Both kinds of file inclusion support two different
+ forms, one including the file relative to the current file,
+ and the other including it from an implementation defined
+ location. The former is ideal for splitting a program
+ in multiple parts, while the latter is intended for
+ implementation-provided resources such as source level
+ libraries.</t>
+ <t>A preprocessor must accept every directive with
+ a dot (.) or a number sign (#) prefix. While Notch seems
+ to prefer the latter, the former is much more common
+ among todays assemblers. Thus we decided to support
+ both, especiall as the implementation-side overhead is
+ very low.</t>
+ </section>
+ </section>
+
+ <section anchor="Security" title="Security Considerations">
+ <t>This memo has no applicable security considerations.</t>
+ </section>
+ </middle>
+
+ <back>
+ <references title="Normative References">
+ <?rfc include="reference.RFC.2119.xml"?>
+ <reference anchor="GHBP" target="https://github.com/blog/1098-take-over-the-galaxy-with-github">
+ <front>
+ <title>Take Over The Galaxy with GitHub</title>
+ <author fullname="Vincent Marti" initials="V" surname="Marti" />
+ <date month="April" year="2012" />
+ </front>
+ </reference>
+ </references>
+ </back>
+</rfc>
View
448 FS/Draft_Harrys_Allocation_Table.txt
@@ -0,0 +1,448 @@
+
+
+
+RFC (Draft-Fs) H. Jeffery, Ed.
+ April 22, 2012
+
+
+ Harry's Allocation Table
+
+Abstract
+
+ This draft provides the specification for the HAT(Harry's Allocation
+ Table) filesystem. It is intended to provide a clear reference for
+ anyone wishing to implement this filesystem.
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 2. Design Summary . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 3. Data Structures . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 3.1. Lower Layer . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 3.1.1. header . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 3.1.1.1. version . . . . . . . . . . . . . . . . . . . . . . 3
+ 3.1.1.2. num_sectors . . . . . . . . . . . . . . . . . . . . 3
+ 3.1.1.3. sector_map_start . . . . . . . . . . . . . . . . . 4
+ 3.1.1.4. sector_joins_start . . . . . . . . . . . . . . . . 4
+ 3.1.1.5. sectors_start . . . . . . . . . . . . . . . . . . . 4
+ 3.1.1.6. sector_size . . . . . . . . . . . . . . . . . . . . 4
+ 3.1.1.7. sectors_used . . . . . . . . . . . . . . . . . . . 4
+ 3.1.2. sector map . . . . . . . . . . . . . . . . . . . . . . 4
+ 3.1.2.1. bitmap . . . . . . . . . . . . . . . . . . . . . . 4
+ 3.1.3. sector joins . . . . . . . . . . . . . . . . . . . . . 5
+ 3.1.4. sector . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 3.2. Higher Layer . . . . . . . . . . . . . . . . . . . . . . . 5
+ 3.2.1. inode . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 3.2.1.1. type . . . . . . . . . . . . . . . . . . . . . . . 6
+ 3.2.1.2. num_links . . . . . . . . . . . . . . . . . . . . . 6
+ 3.2.1.3. content_size . . . . . . . . . . . . . . . . . . . 6
+ 3.2.2. link . . . . . . . . . . . . . . . . . . . . . . . . . 6
+ 3.2.2.1. strip_start_sector . . . . . . . . . . . . . . . . 7
+ 3.2.2.2. file_name . . . . . . . . . . . . . . . . . . . . . 7
+ 4. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
+ 4.1. Constructing a HAT filesystem . . . . . . . . . . . . . . . 7
+ 4.2. Finding a file's inode . . . . . . . . . . . . . . . . . . 8
+ 4.3. Allocating sectors . . . . . . . . . . . . . . . . . . . . 8
+ 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 8
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8
+
+
+
+
+
+
+Jeffery [Page 1]
+
+ HAT April 2012
+
+
+1. Introduction
+
+ This RFC provides a filesystem designed specifically for use on
+ DCPU-16 systems.
+
+ HAT is designed to be simple and easy to implement while still
+ providing all the features required of a filesystem.
+
+
+2. Design Summary
+
+ HAT has a two layered design. The lower layer consists only of
+ sectors. The lower layer is abstracted from the higher layer using
+ "strips". The higher layer consists of inodes, links and raw file
+ data.
+
+ The lower layer deals with the management of sectors and provides
+ access to virtual strips of disk space.
+
+ The higher layer stores inodes, links and file data in these strips.
+ Each strip (constructed in the lower layer using one or more sectors)
+ contains an inode followed by either links or file data.
+
+ Each inode represents either a file or a directory. If the inode
+ represents a file the strip contains the inode followed immediately
+ by all the file data. If the inode represents a directory the strip
+ contains the inode followed by a list of links.
+
+ Each link binds a file name to a file/directory. Each directory may
+ contain several links to more directories or files, resulting in a
+ tree growing from the root directory.
+
+
+3. Data Structures
+
+ This section defines the data structures that comprise the HAT
+ filesystem.
+
+ All sizes are given in words, which are considered to be 16 bits
+ long.
+
+
+
+
+
+
+
+
+
+
+
+Jeffery [Page 2]
+
+ HAT April 2012
+
+
+3.1. Lower Layer
+
+ +--------------+
+ | Section |
+ +--------------+
+ | header |
+ | sector map |
+ | sector joins |
+ | sector 0 |
+ | sector 1 |
+ | sector 2 |
+ | ... |
+ +--------------+
+
+ Table 1: Filesystem Structure
+
+3.1.1. header
+
+ This structure contains the header information for HAT.
+
+ +------+--------------------+
+ | Size | Name |
+ +------+--------------------+
+ | 1 | version |
+ | 1 | num_sectors |
+ | 2 | sector_map_start |
+ | 2 | sector_joins_start |
+ | 2 | sectors_start |
+ | 1 | sector_size |
+ | 1 | sectors_used |
+ +------+--------------------+
+
+ Table 2: Header Structure
+
+3.1.1.1. version
+
+ The version field is a magic number that identifies both that the
+ filesystem in use is HAT and the version of HAT.
+
+ The value of this field must be 0x4001. This magic number identifies
+ the filesystem as version one of HAT.
+
+3.1.1.2. num_sectors
+
+ This field contains the total number of sectors in the filesystem.
+
+
+
+
+
+
+Jeffery [Page 3]
+
+ HAT April 2012
+
+
+3.1.1.3. sector_map_start
+
+ This field contains the address of the start of the sector map.
+
+3.1.1.4. sector_joins_start
+
+ This field contains the address of the start of the array of sector
+ joins.
+
+3.1.1.5. sectors_start
+
+ This field contains the address of the first sector on disk.
+
+ This is required because the first sector may not be positioned
+ immediately after the header. The first sector may be positioned to
+ provide alignment with the underlying disk's blocks.
+
+3.1.1.6. sector_size
+
+ This field contains the size of each sector in the filesystem.
+
+ This must be a power of 2, such as 128, 256 or 512.
+
+3.1.1.7. sectors_used
+
+ This field contains the number of sectors that are currently in use.
+
+3.1.2. sector map
+
+ This section is a bitmap representing which sectors are in use. It
+ can be used to quickly locate free sectors for new files.
+
+ +----------------------+--------+
+ | Size | Name |
+ +----------------------+--------+
+ | ceil(num_sectors/16) | bitmap |
+ +----------------------+--------+
+
+ Table 3: sector map structure
+
+3.1.2.1. bitmap
+
+ This field is a bitmap that represents all the sectors in the
+ filesystem. Each bit of the bitmap represents whether a sector is in
+ use. When a sector is in use the corresponding bit is set to 1.
+ When a sector is free, the corresponding bit is set to 0.
+
+ The MSB is considered to be the first bit and the LSB is considered
+
+
+
+Jeffery [Page 4]
+
+ HAT April 2012
+
+
+ to be the last bit.
+
+ Any spare bits at the end of the bitmap must be set to 1.
+
+3.1.3. sector joins
+
+ This section is an array of words, each word is used to join one
+ sector to another.
+
+ +------+--------------+
+ | Size | Name |
+ +------+--------------+
+ | 1 | sector0_next |
+ | 1 | sector1_next |
+ | 1 | sector2_next |
+ | 1 | sector3_next |
+ | 1 | ... |
+ +------+--------------+
+
+ Table 4: sector links structure
+
+ Each entry joins the end of one sector to the start of another, if
+ there is no next sector the entry is set to 0.
+
+ For example, if there is a strip starting in sector 0, then
+ continuing in sector 2, then sector 1, then finishing in sector 3,
+ then the value of sector0_next will be 2, sector1_next will be 3,
+ sector2_next will be 1, sector3_next will be 0.
+
+ The total length of this section in words is the total number of
+ sectors in the filesystem.
+
+3.1.4. sector
+
+ The sector structure is used to store blocks of raw data. Sectors
+ themselves are just raw blocks of data with no formatting or
+ wrapping.
+
+ Each sector has the size equal to the sector_size, as defined by the
+ header of the filesystem.
+
+3.2. Higher Layer
+
+3.2.1. inode
+
+ The inode structure is used to store metadata about files.
+
+
+
+
+
+Jeffery [Page 5]
+
+ HAT April 2012
+
+
+ +------+--------------+
+ | Size | Name |
+ +------+--------------+
+ | 1 | type |
+ | 1 | num_links |
+ | 2 | content_size |
+ +------+--------------+
+
+ Table 5: inode structure
+
+3.2.1.1. type
+
+ +-------+----------------------+
+ | value | meaning |
+ +-------+----------------------+
+ | 0 | inode is unused |
+ | 1 | inode is a directory |
+ | 2 | inode is a file |
+ +-------+----------------------+
+
+ Table 6: type values
+
+ This field indicates what type of inode it is. If this field is set
+ to 0 then the inode is not in use and represents nothing. If this
+ field is set to 1 then the inode represents a directory. If this
+ field is set to 2 then the inode represents a file.
+
+3.2.1.2. num_links
+
+ This field contains the number of links there are that point to the
+ strip containing this inode.
+
+3.2.1.3. content_size
+
+ This field contains the amount of data stored with this inode in
+ words.
+
+3.2.2. link
+
+ +------+--------------------+
+ | Size | Name |
+ +------+--------------------+
+ | 1 | strip_start_sector |
+ | 15 | file_name |
+ +------+--------------------+
+
+ Table 7: link structure
+
+
+
+
+Jeffery [Page 6]
+
+ HAT April 2012
+
+
+3.2.2.1. strip_start_sector
+
+ This field contains the index of the start sector of the strip the
+ inode being linked to is stored in.
+
+3.2.2.2. file_name
+
+ This field contains the file name to be associated with the inode
+ that is being linked. Only alphanumeric characters, periods(.) and
+ underscores(_) are allowed in the filename. The maximum length of
+ the filename is 15 characters, any unused characters at the end of
+ the filename must be set to 0x0000.
+
+
+4. Usage
+
+ This section contains information and examples on the operation and
+ usage of the HAT filesystem. It is meant only as a rough guide for
+ someone who is wishing to implement HAT.
+
+4.1. Constructing a HAT filesystem
+
+ The HAT filesystem is very simple to construct. The creation of the
+ filesystem can be split into a few simple steps.
+
+ 1. Calculate size and number of sectors from disk space.
+
+ 2. Write the header to disk, the sector map and initialise all the
+ sectors as unused.
+
+ 3. Create the root directory's inode using a strip starting at
+ sector 0.
+
+ Once the structure of the filesystem has been initialised it is ready
+ for use.
+
+ For 16 sectors on a disk the amount of disk space required is
+ (sector_size * 16) + 1. So, to calculate the amount of sectors you
+ can fit on a disk simply minus the size of the header from the disk
+ and then divide it by (sector_size * 16) + 1. Round the resulting
+ number down to have the maximum number of sectors that can go onto
+ the disk.
+
+ It is highly recommended to set the sector size less than or equal to
+ the size of blocks on the disk that the filesystem is being created
+ on. It is also highly advised to align the first sector to a block
+ to maximise io performance.
+
+
+
+
+Jeffery [Page 7]
+
+ HAT April 2012
+
+
+4.2. Finding a file's inode
+
+ To open a file is very simple. HAT is simply passed an absolute path
+ to the file. The path is then broken up into a list of of
+ directories. The list is traversed, starting at the root inode until
+ the file's inode is found.
+
+4.3. Allocating sectors
+
+ Unused sectors can be found very quickly using the sector map. By
+ performing NOT(word AND 0xFFFF) against each word of the bitmap a
+ free sector can be found.
+
+
+5. Security Considerations
+
+ As there is no way to stop a program reading from or writing straight
+ to the disk HAT makes no attempt at providing any security. Any file
+ security should be done in userspace using encryption.
+
+
+Author's Address
+
+ Harry Jeffery (editor)
+
+ Email: harry@exec64.co.uk
+ URI: http://www.exec64.co.uk/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Jeffery [Page 8]
+
View
313 FS/Draft_Harrys_Allocation_Table.xml
@@ -0,0 +1,313 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
+<?rfc strict="yes" ?>
+<?rfc toc="yes"?>
+<?rfc tocdepth="4"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes" ?>
+<?rfc compact="yes" ?>
+<?rfc subcompact="no" ?>
+<?rfc private="RFC (Draft-Fs)" ?>
+<rfc ipr="none" category="info" docName="draft-harrys-allocation-table">
+ <front>
+ <title abbrev="HAT">Harry's Allocation Table</title>
+
+ <author fullname="Harry Jeffery" initials="H.J." role="editor"
+ surname="Jeffery">
+ <address>
+ <email>harry@exec64.co.uk</email>
+ <uri>http://www.exec64.co.uk/</uri>
+ </address>
+ </author>
+ <date month="April" year="2012" />
+ <area>Misc</area>
+ <workgroup>0x10c Standards Committee</workgroup>
+ <abstract>
+ <t>This draft provides the specification for the HAT(Harry's Allocation
+ Table) filesystem. It is intended to provide a clear reference for
+ anyone wishing to implement this filesystem.</t>
+ </abstract>
+ </front>
+
+ <middle>
+ <section anchor="Introduction" title="Introduction">
+ <t>This RFC provides a filesystem designed specifically for use on
+ DCPU-16 systems.</t>
+ <t>HAT is designed to be simple and easy to implement while still
+ providing all the features required of a filesystem.</t>
+ </section>
+
+ <section anchor="Summary" title="Design Summary">
+ <t>HAT has a two layered design. The lower layer consists only of sectors.
+ The lower layer is abstracted from the higher layer using "strips". The
+ higher layer consists of inodes, links and raw file data.</t>
+ <t>The lower layer deals with the management of sectors and provides
+ access to virtual strips of disk space.</t>
+ <t>The higher layer stores inodes, links and file data in these strips.
+ Each strip (constructed in the lower layer using one or more sectors)
+ contains an inode followed by either links or file data.</t>
+ <t>Each inode represents either a file or a directory. If the inode
+ represents a file the strip contains the inode followed immediately
+ by all the file data. If the inode represents a directory the strip
+ contains the inode followed by a list of links.</t>
+ <t>Each link binds a file name to a file/directory. Each directory
+ may contain several links to more directories or files, resulting
+ in a tree growing from the root directory.</t>
+ </section>
+
+ <section anchor="Structures" title="Data Structures" >
+ <t>This section defines the data structures that comprise the HAT
+ filesystem.</t>
+ <t>All sizes are given in words, which are considered to be 16 bits
+ long.</t>
+
+ <section anchor="LowerLayerStructures" title="Lower Layer">
+ <texttable anchor="StructureTable" title="Filesystem Structure">
+ <ttcol align="center">Section</ttcol>
+ <c>header</c>
+ <c>sector map</c>
+ <c>sector joins</c>
+ <c>sector 0</c>
+ <c>sector 1</c>
+ <c>sector 2</c>
+ <c>...</c>
+ </texttable>
+
+ <section anchor="Header" title="header">
+ <t>This structure contains the header information for HAT.</t>
+
+ <texttable anchor="HeaderTable" title="Header Structure">
+ <ttcol align="center">Size</ttcol>
+ <ttcol align="center">Name</ttcol>
+ <c>1</c><c>version</c>
+ <c>1</c><c>num_sectors</c>
+ <c>2</c><c>sector_map_start</c>
+ <c>2</c><c>sector_joins_start</c>
+ <c>2</c><c>sectors_start</c>
+ <c>1</c><c>sector_size</c>
+ <c>1</c><c>sectors_used</c>
+ </texttable>
+
+ <section anchor="HeaderVersion" title="version">
+ <t>The version field is a magic number that identifies both that the
+ filesystem in use is HAT and the version of HAT.</t>
+ <t>The value of this field must be 0x4001. This magic number
+ identifies the filesystem as version one of HAT.</t>
+ </section>
+
+ <section anchor="HeaderNumSectors" title="num_sectors">
+ <t>This field contains the total number of sectors in the
+ filesystem.</t>
+ </section>
+
+ <section anchor="HeaderSectorMapStart" title="sector_map_start">
+ <t>This field contains the address of the start of the sector map.
+ </t>
+ </section>
+
+ <section anchor="HeaderSectorLinksStart" title="sector_joins_start">
+ <t>This field contains the address of the start of the array of
+ sector joins.</t>
+ </section>
+
+ <section anchor="HeaderSectorsStart" title="sectors_start">
+ <t>This field contains the address of the first sector on disk.</t>
+ <t>This is required because the first sector may not be positioned
+ immediately after the header. The first sector may be positioned
+ to provide alignment with the underlying disk's blocks.</t>
+ </section>
+
+ <section anchor="HeaderSectorSize" title="sector_size">
+ <t>This field contains the size of each sector in the filesystem.
+ </t>
+ <t>This must be a power of 2, such as 128, 256 or 512.</t>
+ </section>
+
+ <section anchor="HeaderSectorsUsed" title="sectors_used">
+ <t>This field contains the number of sectors that are currently in
+ use.</t>
+ </section>
+
+ </section>
+
+ <section anchor="SectorMap" title="sector map">
+ <t>This section is a bitmap representing which sectors are in use.
+ It can be used to quickly locate free sectors for new files.</t>
+
+ <texttable anchor="SectorMapTable" title="sector map structure">
+ <ttcol align="center">Size</ttcol>
+ <ttcol align="center">Name</ttcol>
+ <c>ceil(num_sectors/16)</c><c>bitmap</c>
+ </texttable>
+
+ <section anchor="SectorMapBitmap" title="bitmap">
+ <t>This field is a bitmap that represents all the sectors in the
+ filesystem. Each bit of the bitmap represents whether a sector
+ is in use. When a sector is in use the corresponding bit is set
+ to 1. When a sector is free, the corresponding bit is set to 0.</t>
+ <t>The MSB is considered to be the first bit and the LSB is
+ considered to be the last bit.</t>
+ <t>Any spare bits at the end of the bitmap must be set to 1.</t>
+ </section>
+ </section>
+
+ <section anchor="SectorJoins" title="sector joins">
+ <t>This section is an array of words, each word is used to join
+ one sector to another.</t>
+
+ <texttable anchor="SectorLinksTable" title="sector links structure">
+ <ttcol align="center">Size</ttcol>
+ <ttcol align="center">Name</ttcol>
+ <c>1</c><c>sector0_next</c>
+ <c>1</c><c>sector1_next</c>
+ <c>1</c><c>sector2_next</c>
+ <c>1</c><c>sector3_next</c>
+ <c>1</c><c>...</c>
+ </texttable>
+ <t>Each entry joins the end of one sector to the start of another,
+ if there is no next sector the entry is set to 0.</t>
+ <t>For example, if there is a strip starting in sector 0, then
+ continuing in sector 2, then sector 1, then finishing in sector 3,
+ then the value of sector0_next will be 2, sector1_next will be 3,
+ sector2_next will be 1, sector3_next will be 0.</t>
+ <t>The total length of this section in words is the total number
+ of sectors in the filesystem.</t>
+ </section>
+
+ <section anchor="Sector" title="sector">
+ <t>The sector structure is used to store blocks of raw data.
+ Sectors themselves are just raw blocks of data with no formatting
+ or wrapping.</t>
+ <t>Each sector has the size equal to the sector_size, as defined by
+ the header of the filesystem.</t>
+ </section>
+
+ </section>
+
+ <section anchor="HigherLayerStructures" title="Higher Layer">
+
+ <section anchor="Inode" title="inode">
+ <t>The inode structure is used to store metadata about files.</t>
+
+ <texttable anchor="InodeTable" title="inode structure">
+ <ttcol align="center">Size</ttcol>
+ <ttcol align="center">Name</ttcol>
+ <c>1</c><c>type</c>
+ <c>1</c><c>num_links</c>
+ <c>2</c><c>content_size</c>
+ </texttable>
+
+ <section anchor="InodeType" title="type">
+
+ <texttable anchor="InodeTypeTable" title="type values">
+ <ttcol align="center">value</ttcol>
+ <ttcol align="center">meaning</ttcol>
+ <c>0</c><c>inode is unused</c>
+ <c>1</c><c>inode is a directory</c>
+ <c>2</c><c>inode is a file</c>
+ </texttable>
+
+ <t>This field indicates what type of inode it is. If this field is
+ set to 0 then the inode is not in use and represents nothing. If
+ this field is set to 1 then the inode represents a directory. If
+ this field is set to 2 then the inode represents a file.</t>
+ </section>
+
+ <section anchor="InodeNumLinks" title="num_links">
+ <t>This field contains the number of links there are that
+ point to the strip containing this inode.</t>
+ </section>
+
+ <section anchor="InodeContentSize" title="content_size">
+ <t>This field contains the amount of data stored with this
+ inode in words.</t>
+ </section>
+
+ </section>
+
+ <section anchor="Link" title="link">
+ <texttable anchor="LinkTable" title="link structure">
+ <ttcol align="center">Size</ttcol>
+ <ttcol align="center">Name</ttcol>
+ <c>1</c><c>strip_start_sector</c>
+ <c>15</c><c>file_name</c>
+ </texttable>
+
+ <section anchor="LinkStripStartSector" title="strip_start_sector">
+ <t>This field contains the index of the start sector of the strip
+ the inode being linked to is stored in.</t>
+ </section>
+
+ <section anchor="LinkFileName" title="file_name">
+ <t>This field contains the file name to be associated with the
+ inode that is being linked. Only alphanumeric characters,
+ periods(.) and underscores(_) are allowed in the filename. The
+ maximum length of the filename is 15 characters, any unused
+ characters at the end of the filename must be set to 0x0000.</t>
+ </section>
+ </section>
+
+ </section>
+
+ </section>
+
+ <section anchor="Usage" title="Usage">
+ <t>This section contains information and examples on the operation
+ and usage of the HAT filesystem. It is meant only as a rough guide
+ for someone who is wishing to implement HAT.</t>
+
+ <section anchor="UsageCreation" title="Constructing a HAT filesystem">
+ <t>The HAT filesystem is very simple to construct. The creation
+ of the filesystem can be split into a few simple steps.</t>
+ <t><list style="format %d.">
+ <t>Calculate size and number of sectors from disk space.</t>
+ <t>Write the header to disk, the sector map and initialise all
+ the sectors as unused.</t>
+ <t>Create the root directory's inode using a strip starting at
+ sector 0.</t>
+ </list></t>
+ <t>Once the structure of the filesystem has been initialised it is
+ ready for use.</t>
+
+ <t>For 16 sectors on a disk the amount of disk space required is
+ (sector_size * 16) + 1. So, to calculate the amount of sectors
+ you can fit on a disk simply minus the size of the header from the
+ disk and then divide it by (sector_size * 16) + 1. Round the resulting
+ number down to have the maximum number of sectors that can go onto the
+ disk.</t>
+
+ <t>It is highly recommended to set the sector size less than or equal
+ to the size of blocks on the disk that the filesystem is being
+ created on. It is also highly advised to align the first sector to
+ a block to maximise io performance.</t>
+
+ </section>
+
+ <section anchor="UsageFinding" title="Finding a file's inode">
+ <t>To open a file is very simple. HAT is simply passed an absolute
+ path to the file. The path is then broken up into a list of of
+ directories. The list is traversed, starting at the root inode until
+ the file's inode is found.</t>
+ </section>
+
+ <section anchor="UsageAllocatingSectors" title="Allocating sectors">
+ <t>Unused sectors can be found very quickly using the sector map.
+ By performing NOT(word AND 0xFFFF) against each word of the bitmap
+ a free sector can be found.</t>
+ </section>
+ </section>
+
+ <section anchor="Security" title="Security Considerations">
+ <t>As there is no way to stop a program reading from or writing straight
+ to the disk HAT makes no attempt at providing any security. Any file
+ security should be done in userspace using encryption.</t>
+ </section>
+
+ </middle>
+
+ <back>
+ </back>
+
+</rfc>
+
View
189 LIB/Draft-String-Format.xml
@@ -0,0 +1,189 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
+<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
+<?rfc strict="yes"?>
+<?rfc toc="yes"?>
+<?rfc tocdepth="4"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes"?>
+<?rfc compact="yes"?>
+<?rfc subcompact="no"?>
+<?rfc private="RFC (Draft-Lib)"?>
+<rfc ipr="none" category="std" docName="draft-string-format">
+ <front>
+ <title abbrev="String Format">String Format</title>
+
+ <author initials="M.S." surname="Schuetze" fullname="Malte Schuetze">
+ <address>
+ <email>malte.schuetze@fgms.de</email>
+ </address>
+ </author>
+
+ <date month="April" year="2012"/>
+ <area>Lib</area>