Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge branch 'upstream'

  • Loading branch information...
commit 24692bba6264a901285a91d0402c5c25fb97ae42 2 parents 7b166a8 + 125a535
@eXeC64 eXeC64 authored
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
560 ASM/Spec_0xSCA.txt
@@ -0,0 +1,560 @@
+
+
+
+RFC X____ J. Kuijpers, Ed.
+ Jarvix
+ M. Beermann, Ed.
+ April 20, 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. Filename . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 2.2. Lines . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 2.3. Indentation and whitepacing . . . . . . . . . . . . . . . 3
+ 3. Preprocessor Markup . . . . . . . . . . . . . . . . . . . . . 3
+ 3.1. Comments . . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 3.2. Prefix . . . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 3.3. Case insensitivity . . . . . . . . . . . . . . . . . . . . 4
+ 3.4. Directives . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 3.4.1. Inclusion . . . . . . . . . . . . . . . . . . . . . . 4
+ 3.4.1.1. Code . . . . . . . . . . . . . . . . . . . . . . . 4
+ 3.4.1.2. Binary . . . . . . . . . . . . . . . . . . . . . . 5
+ 3.4.2. Definitions . . . . . . . . . . . . . . . . . . . . . 5
+ 3.4.3. Data insertion . . . . . . . . . . . . . . . . . . . . 5
+ 3.4.4. Origin relocation . . . . . . . . . . . . . . . . . . 6
+ 3.4.5. Macros: macro block and macro insertion . . . . . . . 6
+ 3.4.6. Repeat block . . . . . . . . . . . . . . . . . . . . . 6
+ 3.4.7. Conditionals . . . . . . . . . . . . . . . . . . . . . 7
+ 3.4.8. Error reporting . . . . . . . . . . . . . . . . . . . 7
+ 3.4.9. Alignment . . . . . . . . . . . . . . . . . . . . . . 7
+ 3.5. Preprocessor inline arithmetic . . . . . . . . . . . . . . 8
+ 4. Tokenizer Markup . . . . . . . . . . . . . . . . . . . . . . . 8
+ 4.1. Labels . . . . . . . . . . . . . . . . . . . . . . . . . . 8
+ 4.2. Case sensitivity . . . . . . . . . . . . . . . . . . . . . 8
+ 4.3. Inline character literals . . . . . . . . . . . . . . . . 8
+ 4.4. Inline arithmetic . . . . . . . . . . . . . . . . . . . . 9
+ 5. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 9
+ 5.1. Recognition of conformance . . . . . . . . . . . . . . . . 9
+ 6. Design Rationale . . . . . . . . . . . . . . . . . . . . . . . 9
+ 6.1. Labels . . . . . . . . . . . . . . . . . . . . . . . . . . 9
+ 6.2. Preprocessor . . . . . . . . . . . . . . . . . . . . . . . 9
+ 7. Security Considerations . . . . . . . . . . . . . . . . . . . 10
+ 8. Normative References . . . . . . . . . . . . . . . . . . . . . 10
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kuijpers & Beermann [Page 2]
+
+ Assembly Syntactics April 2012
+
+
+1. Introduction
+
+ This documents descrives 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. Filename
+
+ Assembly files on the DCPU-16 platform SHOULD end in '.dasm' or
+ '.dasm16'. This is first used by GitHub [GHBP] to identify DCPU-16
+ assembly files.
+
+2.2. Lines
+
+ An empty line MUST be omitted by the assembler. A line MUST NOT
+ contain more than one instruction. A line MAY both define a label
+ and contain an instruction, in this order.
+
+2.3. Indentation and whitepacing
+
+ 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. Preprocessor Markup
+
+
+
+
+
+
+Kuijpers & Beermann [Page 3]
+
+ Assembly Syntactics April 2012
+
+
+3.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
+ resides within the representation of a string. In that case, the
+ semicolon MUST NOT be treated as a comment.
+
+3.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). Documents SHOULD NOT have mixedusage of these,
+ assemblers SHOULD NOT accept mixing these in a single document.
+
+ Using a dot is RECOMMENDED to distinguish between C preprocessor
+ syntax.
+
+3.3. Case insensitivity
+
+ Assemblers MUST accept directives, definitions and constants without
+ regard to case.
+
+3.4. Directives
+
+ All directives in this section MUST be handled in order and in
+ recognition of their position. For unambigiousity a dot (.) is used
+ here to describe preprocessor directives.
+
+3.4.1. Inclusion
+
+3.4.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. If the given filename does
+ not exist compilation MUST be aborted.
+
+
+
+Kuijpers & Beermann [Page 4]
+
+ Assembly Syntactics April 2012
+
+
+ The latter includes the file from an implementation defined location,
+ which may not even exist but trigger certain behaviour, i.e.
+ inclusion of intrinsics.
+
+3.4.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.
+
+ The latter form of incbin MUST include the file from an
+ implementation defined location.
+
+3.4.2. Definitions
+
+ .def name [value]
+ .undef name
+
+ def 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.
+
+3.4.3. Data insertion
+
+ .word value [,value...]
+ .byte value [,value...]
+ .ascii "string"
+
+ word MUST store the values literally and unpacked at the location of
+ the directive.
+
+ byte MUST pack (i.e. two bytes per word, first byte is LSB) the
+ values at the location of the directive.
+
+ ascii MUST store the string unpacked (i.e. character is LSB, one word
+ per character) at the location of the directive.
+
+
+
+
+
+
+Kuijpers & Beermann [Page 5]
+
+ Assembly Syntactics April 2012
+
+
+3.4.4. Origin relocation
+
+ .org address
+
+ 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.
+
+3.4.5. Macros: macro block and macro insertion
+
+ .macro name([param [,param...]])
+ code
+ .end
+ .ins 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 (,).
+
+ The ins directive MUST insert a formerly defined macros 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.
+
+3.4.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
+
+
+3.4.7. Conditionals
+
+ .if expression
+ codeTrue
+ .elif expression
+ codeElseTrue
+ .else
+ codeElse
+ .end
+ .ifdef definitions
+ isdef(definition)
+
+ For the definition of valid expressions, see Section 3.5.
+
+ The if clause is REQUIRED. The else clause is OPTIONAL. The elif
+ 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(). It is used often and therefor a short
+ syntax is provided.
+
+ Nesting of if directives MUST be supported.
+
+3.4.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.
+
+3.4.9. Alignment
+
+ .align boundary
+
+ Aligns code or data on doubleword or other boundary.
+
+ The assembler MUST add NOPs (0x0000) to the generated machinecode
+ until the alignment is correct. The number of words inserted can be
+
+
+
+Kuijpers & Beermann [Page 7]
+
+ Assembly Syntactics April 2012
+
+
+ calculated using the formula: 'boundary - (currentPosition %
+ boundary)' (% indiciates modulus).
+
+3.5. Preprocessor 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) and %
+ (modulus), parentheses may be used to group expressions. The
+ evaluation order MUST be as follows: multiplication, division,
+ modulus, addition, substraction.
+
+ The following logical and bitwise operators MUST also be supported: =
+ (equal, also ==), != (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.
+
+
+4. Tokenizer Markup
+
+4.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. A label
+ MUST end with a colon (: U+003A). When the label is used, the
+ tokenizer MUST translate the label into the address it represents.
+
+ Local labels MUST start with a dot (. 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.
+
+4.2. Case sensitivity
+
+ Assemblers MUST accept registers and opcodes without regard to case.
+ Assemblers MUST accept labels respecting case.
+
+4.3. Inline character literals
+
+ A character surrounded by apostrophes (' U+0029) MUST be interpreted
+ as its corresponding 7-bit ASCII value in a word (LSB). An assembler
+
+
+
+Kuijpers & Beermann [Page 8]
+
+ Assembly Syntactics April 2012
+
+
+ MUST support at least the ascii values ranging from 32 to 126
+ (printable characters).
+
+4.4. 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) and %
+ (modulus), parentheses may be used to group expressions. The
+ evaluation order MUST be as follows: multiplication, division,
+ modulus, addition, substraction.
+
+ The following bitwise operators MUST also be supported: & (bit-wise
+ AND) ^ (bit-wise XOR), | (bit-wise OR).
+
+
+5. Conformance
+
+5.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.
+
+
+6. Design Rationale
+
+6.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.
+
+6.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.
+
+
+
+
+Kuijpers & Beermann [Page 9]
+
+ Assembly Syntactics April 2012
+
+
+ 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
+ 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.
+
+
+7. Security Considerations
+
+ This memo has no applicable security considerations.
+
+
+8. Normative References
+
+ [GHBP] MartA, 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
373 ASM/Spec_0xSCA.xml
@@ -0,0 +1,373 @@
+<?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 descrives 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="Filename">
+ <t>Assembly files on the DCPU-16 platform SHOULD end in '.dasm'
+ or '.dasm16'. This is first used by
+ <xref target="GHBP">GitHub</xref> to identify DCPU-16 assembly
+ files.</t>
+ </section>
+ <section title="Lines">
+ <t>An empty line MUST be omitted by the assembler. A line MUST
+ NOT contain more than one instruction. A line MAY both define a
+ label and contain an instruction, in this order.</t>
+ </section>
+ <section title="Indentation and whitepacing">
+ <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="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). Documents SHOULD NOT have mixedusage of
+ these, assemblers SHOULD NOT accept mixing these in a single
+ document.</t>
+ <t>Using a dot is RECOMMENDED to distinguish between C preprocessor
+ syntax.</t>
+ </section>
+ <section title="Case insensitivity">
+ <t>Assemblers MUST accept directives, definitions and constants
+ without regard to case.</t>
+ </section>
+ <section title="Directives">
+ <t>All directives in this section MUST be handled in order and
+ in recognition of their position. For unambigiousity a dot (.)
+ is used here 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. If
+ the given filename does not exist compilation MUST be
+ aborted.</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]
+.undef name]]></artwork></figure>
+ <t>def 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[
+.word value [,value...]
+.byte value [,value...]
+.ascii "string"]]></artwork></figure>
+ <t>word MUST store the values literally and unpacked at
+ the location of the directive.</t>
+ <t>byte MUST pack (i.e. two bytes per word, first byte is LSB)
+ the values at the location of the directive.</t>
+ <t>ascii MUST store the string unpacked (i.e. character is LSB,
+ one word per character) at the location of the directive.</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
+.ins 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>The ins directive MUST insert a formerly defined macros 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
+.else
+ codeElse
+.end
+.ifdef definitions
+isdef(definition)]]></artwork></figure>
+ <t>For the definition of valid expressions, see
+ <xref target="pp_ia" />.</t>
+ <t>The if clause is REQUIRED. The else clause is OPTIONAL.
+ The elif 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(). It is used often and
+ therefor a short syntax is provided.</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 NOPs (0x0000) to the generated
+ machinecode until the alignment is correct. The number of
+ words inserted can be calculated using the formula:
+ 'boundary - (currentPosition % boundary)' (% indiciates
+ modulus).</t>
+ </section>
+ </section>
+ <section title="Preprocessor inline arithmetic" anchor="pp_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) and % (modulus), parentheses may be used
+ to group expressions. The evaluation order MUST be as follows:
+ multiplication, division, modulus, addition, substraction.</t>
+ <t>The following logical and bitwise operators MUST also be
+ supported: = (equal, also ==), != (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>
+
+ <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. A label MUST end with a colon (: U+003A). When the label
+ is used, the tokenizer MUST translate the label into the address
+ it represents.</t>
+ <t>Local labels MUST start with a dot (. 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="Case sensitivity">
+ <t>Assemblers MUST accept registers and opcodes without regard
+ to case. Assemblers MUST accept labels respecting case.</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). An assembler MUST support at least the ascii values
+ ranging from 32 to 126 (printable characters).</t>
+ </section>
+ <section title="Inline arithmetic">
+ <t>Source code can include inline arithmetics anywhere a
+ constant value is permitted. Inline arithmetic may only
+ consist of + (addition), - (subtraction), * (multiplication), /
+ (integer division) and % (modulus), parentheses may be used
+ to group expressions. The evaluation order MUST be as follows:
+ multiplication, division, modulus, addition, substraction.</t>
+ <t>The following bitwise operators MUST also be supported: &amp;
+ (bit-wise AND) ^ (bit-wise XOR), | (bit-wise OR).
+ </t>
+ </section>
+ </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 Martí" initials="V" surname="Martí" />
+ <date month="April" year="2012" />
+ </front>
+ </reference>
+ </references>
+ </back>
+
+</rfc>
View
3  NET/Draft_OSI_Physical_Layer.xml
@@ -5,7 +5,7 @@
<title>A Physical layer application for DCPU-16</title>
<author initials="J." surname="Mansfield" fullname="Jacob Mansfield">
<organization abbrev="0x10C-Std">
- the 0x10c Standards Committee
+ 0x10c Standards Committee
</organization>
<address>
<email>cyberjacob@gmail.com</email>
@@ -13,6 +13,7 @@
</author>
<date month="April" year="2012" />
<area>Networking</area>
+ <workgroup>0x10c Standards Committee</workgroup>
<abstract>
<t>This document provides a theoretical implementation of the physical layer of the OSI model on the DCPU-16 platform.</t>
</abstract>
View
5 README.md
@@ -27,10 +27,11 @@ In this directory goes everything that does not fit in the other directories def
If you have a proposal, idea or comment regarding upcoming or new standards, you can make an issue about it.
-From these issues, a Draft will be created using Pull Requests, with the format Draft\_\<Subject\>.txt.
+From these issues, a Draft named Draft\_\<Subject\>.xml will be created using Pull Requests, with the XML format as defined in RFC 2629.
-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_\<Subject\>.md.
+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_\<Subject\>.xml .
+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.
## Voting ##
Please sign in to comment.
Something went wrong with that request. Please try again.