Skip to content
This repository
Browse code

Merge branch 'upstream'

  • Loading branch information...
commit 24692bba6264a901285a91d0402c5c25fb97ae42 2 parents 7b166a8 + 125a535
Harry Jeffery authored April 23, 2012
165  ABI/ABI draft 2.txt
... ...
@@ -0,0 +1,165 @@
  1
+RFC X1000 (Standard-ABI)                                   A. Bleck, Ed.
  2
+                                                              April 2012
  3
+
  4
+
  5
+                               ABI draft
  6
+
  7
+Abstract
  8
+
  9
+   This draft specifies an application binary interface for
  10
+   interoperability between subroutines written by different authors or
  11
+   compiled by different compilers.
  12
+
  13
+
  14
+Table of Contents
  15
+
  16
+   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 2
  17
+     1.1.  Requirements Language . . . . . . . . . . . . . . . . . . . 2
  18
+   2.  Rules common to both calling conventions  . . . . . . . . . . . 2
  19
+   3.  Stackcall . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
  20
+   4.  Registercall  . . . . . . . . . . . . . . . . . . . . . . . . . 2
  21
+   5.  Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
  22
+   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 3
  23
+
  24
+
  25
+
  26
+
  27
+
  28
+
  29
+
  30
+
  31
+
  32
+
  33
+
  34
+
  35
+
  36
+
  37
+
  38
+
  39
+
  40
+
  41
+
  42
+
  43
+
  44
+
  45
+
  46
+
  47
+
  48
+
  49
+
  50
+
  51
+
  52
+Bleck                                                           [Page 1]
  53
+
  54
+                                ABI draft                     April 2012
  55
+
  56
+
  57
+1.  Introduction
  58
+
  59
+   Currently there is no standard defined for the behavior of functions
  60
+   that, if conformed to, will allow functions from multiple sources to
  61
+   be compatible.  This RFC specifies two 'calling conventions',
  62
+   hereafter called stackcall and registercall.  Any compiler
  63
+   implementing these calling conventions would be able to call code
  64
+   generated from a different compiler that also implements these
  65
+   conventions safely.
  66
+
  67
+1.1.  Requirements Language
  68
+
  69
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  70
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  71
+   document are to be interpreted as described in RFC 2119.  The key
  72
+   word "CALLER" is the function or code that is making the call, the
  73
+   key word "CALLEE" is the function being called
  74
+
  75
+
  76
+2.  Rules common to both calling conventions
  77
+
  78
+   The CALLER is REQUIRED to assume that the contents of registers A, B
  79
+   and C are not preserved.  The CALLEE is REQUIRED to preserve the
  80
+   contents of registers X, Y, Z, I and J. The CALLER is REQUIRED to
  81
+   assume that the contents of the special purpose register O is not
  82
+   preserved, and contains no valuable information.  The CALLEE MUST
  83
+   return it's result, if any, in register A. The CALLEE MUST remove
  84
+   anything and everything it adds to the stack.  The CALLER is
  85
+   responsible for cleaning any function arguments passed on the stack
  86
+   from the stack.
  87
+
  88
+
  89
+3.  Stackcall
  90
+
  91
+   The CALLER MUST push all arguments to the stack in right to left
  92
+   order, followed by the return pointer, such that the first argument
  93
+   is located on the stack at SP+1, the second is at SP+2, etc.  (The
  94
+   CALLER is RECOMMENDED to use the JSR instruction to perform the jump)
  95
+
  96
+
  97
+4.  Registercall
  98
+
  99
+   The CALLER MUST place the first three function arguments in registers
  100
+   A, B and C, in that order.  Further arguments, if any, MUST be pushed
  101
+   to the stack in right to left order.  The return pointer MUST be
  102
+   pushed last, such that argument four is located on the stack at SP+1,
  103
+   argument five is located at SP+2, etc.  (The CALLER is RECOMMENDED to
  104
+   use the JSR instruction to perform the jump)
  105
+
  106
+
  107
+
  108
+Bleck                                                           [Page 2]
  109
+
  110
+                                ABI draft                     April 2012
  111
+
  112
+
  113
+5.  Scope
  114
+
  115
+   This specification applies only to the interface functions present to
  116
+   each other.  Internal implementation details are intentially
  117
+   excluded.
  118
+
  119
+
  120
+Author's Address
  121
+
  122
+   Blecki (editor)
  123
+
  124
+   Email: jm@omnisu.com
  125
+   URI:   http://jemgine.omnisu.com
  126
+
  127
+
  128
+
  129
+
  130
+
  131
+
  132
+
  133
+
  134
+
  135
+
  136
+
  137
+
  138
+
  139
+
  140
+
  141
+
  142
+
  143
+
  144
+
  145
+
  146
+
  147
+
  148
+
  149
+
  150
+
  151
+
  152
+
  153
+
  154
+
  155
+
  156
+
  157
+
  158
+
  159
+
  160
+
  161
+
  162
+
  163
+
  164
+Bleck                                                           [Page 3]
  165
+
102  ABI/ABI draft 2.xml
... ...
@@ -0,0 +1,102 @@
  1
+<?xml version="1.0" encoding="US-ASCII"?>
  2
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
  3
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
  4
+<?rfc strict="yes" ?>
  5
+<?rfc toc="yes"?>
  6
+<?rfc tocdepth="4"?>
  7
+<?rfc symrefs="yes"?>
  8
+<?rfc sortrefs="yes" ?>
  9
+<?rfc compact="yes" ?>
  10
+<?rfc subcompact="no" ?>
  11
+<?rfc private="RFC X1000 (Standard-ABI)" ?>
  12
+<rfc ipr="none" number="1000" category="info" docName="abi-draft">
  13
+  <front>
  14
+	<title abbrev="ABI draft">ABI draft</title>
  15
+
  16
+    <author fullname="Blecki" initials="A.C." role="editor"
  17
+            surname="Bleck">
  18
+      <organization></organization>
  19
+
  20
+      <address>
  21
+        <email>jm@omnisu.com</email>
  22
+        <uri>http://jemgine.omnisu.com</uri>
  23
+      </address>
  24
+    </author>
  25
+
  26
+    <date month="April" year="2012" />
  27
+    <area>ABI</area>
  28
+    <workgroup>0x10c Standards Committee</workgroup>
  29
+    <abstract>
  30
+		<t>This draft specifies an application binary interface for 
  31
+		interoperability between subroutines written by different
  32
+		authors or compiled by different compilers.</t>
  33
+    </abstract>
  34
+  </front>
  35
+
  36
+  <middle>
  37
+    <section title="Introduction">
  38
+      <t>Currently there is no standard defined for the behavior of 
  39
+	  functions that, if conformed to, will allow functions from
  40
+	  multiple sources to be compatible. This RFC specifies two
  41
+	  'calling conventions', hereafter called stackcall and
  42
+	  registercall. Any compiler implementing these calling
  43
+	  conventions would be able to call code generated from a 
  44
+	  different compiler that also implements these conventions
  45
+	  safely.</t>
  46
+	  
  47
+	  <section title="Requirements Language">
  48
+        <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  49
+        "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  50
+        document are to be interpreted as described in RFC 2119.
  51
+		
  52
+		The key word "CALLER" is the function or code that is making
  53
+		the call, the key word "CALLEE" is the function being called</t>
  54
+      </section>
  55
+    </section>
  56
+	
  57
+	<section anchor="common" title="Rules common to both calling conventions">
  58
+		<t>The CALLER is REQUIRED to assume that the contents of registers A, B and C 
  59
+		are not preserved.
  60
+		
  61
+		The CALLEE is REQUIRED to preserve the contents of registers X, Y, Z, I and J.
  62
+		
  63
+		The CALLER is REQUIRED to assume that the contents of the special purpose
  64
+		register O is not preserved, and contains no valuable information.
  65
+		
  66
+		The CALLEE MUST return it's result, if any, in register A.
  67
+		
  68
+		The CALLEE MUST remove anything and everything it adds to the stack.
  69
+		
  70
+		The CALLER is responsible for cleaning any function arguments passed on the 
  71
+		stack from the stack.
  72
+		</t>
  73
+    </section>
  74
+    
  75
+	<section anchor="stackcall" title="Stackcall">
  76
+		<t>The CALLER MUST push all arguments to the stack in right to left order,
  77
+		followed by the return pointer, such that the first argument is located
  78
+		on the stack at SP+1, the second is at SP+2, etc. (The CALLER is RECOMMENDED
  79
+		to use the JSR instruction to perform the jump)
  80
+		</t>
  81
+	</section>
  82
+	
  83
+	<section anchor="registercall" title="Registercall">
  84
+		<t>The CALLER MUST place the first three function arguments in registers A,
  85
+		B and C, in that order. Further arguments, if any, MUST be pushed to the stack
  86
+		in right to left order. The return pointer MUST be pushed last, such that
  87
+		argument four is located on the stack at SP+1, argument five is located at
  88
+		SP+2, etc. (The CALLER is RECOMMENDED to use the JSR instruction to perform
  89
+		the jump)
  90
+		</t>
  91
+	</section>
  92
+	
  93
+	<section anchor="scope" title="Scope">
  94
+		<t>This specification applies only to the interface functions present to 
  95
+		each other. Internal implementation details are intentially excluded.</t>
  96
+	</section>
  97
+  </middle>
  98
+
  99
+
  100
+
  101
+</rfc>
  102
+
560  ASM/Spec_0xSCA.txt
... ...
@@ -0,0 +1,560 @@
  1
+
  2
+
  3
+
  4
+RFC X____                                               J. Kuijpers, Ed.
  5
+                                                                  Jarvix
  6
+                                                        M. Beermann, Ed.
  7
+                                                          April 20, 2012
  8
+
  9
+
  10
+                  0xSCA: Standards Committee Assembly
  11
+
  12
+Abstract
  13
+
  14
+   This document describes an assembly and preprocessor syntax suitable
  15
+   for the DCPU-16 environment.  This syntax is called the 0xSCA, or
  16
+   Standards Committee Assembly.
  17
+
  18
+   This is not a standard.
  19
+
  20
+
  21
+
  22
+
  23
+
  24
+
  25
+
  26
+
  27
+
  28
+
  29
+
  30
+
  31
+
  32
+
  33
+
  34
+
  35
+
  36
+
  37
+
  38
+
  39
+
  40
+
  41
+
  42
+
  43
+
  44
+
  45
+
  46
+
  47
+
  48
+
  49
+
  50
+
  51
+
  52
+
  53
+
  54
+
  55
+Kuijpers & Beermann                                             [Page 1]
  56
+
  57
+                           Assembly Syntactics                April 2012
  58
+
  59
+
  60
+Table of Contents
  61
+
  62
+   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
  63
+     1.1.  Requirements Language  . . . . . . . . . . . . . . . . . .  3
  64
+   2.  Document Markup  . . . . . . . . . . . . . . . . . . . . . . .  3
  65
+     2.1.  Filename . . . . . . . . . . . . . . . . . . . . . . . . .  3
  66
+     2.2.  Lines  . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  67
+     2.3.  Indentation and whitepacing  . . . . . . . . . . . . . . .  3
  68
+   3.  Preprocessor Markup  . . . . . . . . . . . . . . . . . . . . .  3
  69
+     3.1.  Comments . . . . . . . . . . . . . . . . . . . . . . . . .  4
  70
+     3.2.  Prefix . . . . . . . . . . . . . . . . . . . . . . . . . .  4
  71
+     3.3.  Case insensitivity . . . . . . . . . . . . . . . . . . . .  4
  72
+     3.4.  Directives . . . . . . . . . . . . . . . . . . . . . . . .  4
  73
+       3.4.1.  Inclusion  . . . . . . . . . . . . . . . . . . . . . .  4
  74
+         3.4.1.1.  Code . . . . . . . . . . . . . . . . . . . . . . .  4
  75
+         3.4.1.2.  Binary . . . . . . . . . . . . . . . . . . . . . .  5
  76
+       3.4.2.  Definitions  . . . . . . . . . . . . . . . . . . . . .  5
  77
+       3.4.3.  Data insertion . . . . . . . . . . . . . . . . . . . .  5
  78
+       3.4.4.  Origin relocation  . . . . . . . . . . . . . . . . . .  6
  79
+       3.4.5.  Macros: macro block and macro insertion  . . . . . . .  6
  80
+       3.4.6.  Repeat block . . . . . . . . . . . . . . . . . . . . .  6
  81
+       3.4.7.  Conditionals . . . . . . . . . . . . . . . . . . . . .  7
  82
+       3.4.8.  Error reporting  . . . . . . . . . . . . . . . . . . .  7
  83
+       3.4.9.  Alignment  . . . . . . . . . . . . . . . . . . . . . .  7
  84
+     3.5.  Preprocessor inline arithmetic . . . . . . . . . . . . . .  8
  85
+   4.  Tokenizer Markup . . . . . . . . . . . . . . . . . . . . . . .  8
  86
+     4.1.  Labels . . . . . . . . . . . . . . . . . . . . . . . . . .  8
  87
+     4.2.  Case sensitivity . . . . . . . . . . . . . . . . . . . . .  8
  88
+     4.3.  Inline character literals  . . . . . . . . . . . . . . . .  8
  89
+     4.4.  Inline arithmetic  . . . . . . . . . . . . . . . . . . . .  9
  90
+   5.  Conformance  . . . . . . . . . . . . . . . . . . . . . . . . .  9
  91
+     5.1.  Recognition of conformance . . . . . . . . . . . . . . . .  9
  92
+   6.  Design Rationale . . . . . . . . . . . . . . . . . . . . . . .  9
  93
+     6.1.  Labels . . . . . . . . . . . . . . . . . . . . . . . . . .  9
  94
+     6.2.  Preprocessor . . . . . . . . . . . . . . . . . . . . . . .  9
  95
+   7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 10
  96
+   8.  Normative References . . . . . . . . . . . . . . . . . . . . . 10
  97
+   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10
  98
+
  99
+
  100
+
  101
+
  102
+
  103
+
  104
+
  105
+
  106
+
  107
+
  108
+
  109
+
  110
+
  111
+Kuijpers & Beermann                                             [Page 2]
  112
+
  113
+                           Assembly Syntactics                April 2012
  114
+
  115
+
  116
+1.  Introduction
  117
+
  118
+   This documents descrives 0xSCA, Standards Committee Assembly.  It is
  119
+   a definition of a syntax to be used for writing assembly for the
  120
+   DCPU-16 processor.  Use of this syntax is voluntarily.  With 0xSCA,
  121
+   there is a defined syntax, and could decrease code incompatibility
  122
+   among compilers.
  123
+
  124
+   Again, to be clear: 0xSCA is a syntax definition, not a standard.
  125
+   0xSCA is to DCPU-16, what AT&T or the NASM syntax is to IA-32.
  126
+
  127
+1.1.  Requirements Language
  128
+
  129
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  130
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  131
+   document are to be interpreted as described in RFC 2119 [RFC2119].
  132
+
  133
+
  134
+2.  Document Markup
  135
+
  136
+2.1.  Filename
  137
+
  138
+   Assembly files on the DCPU-16 platform SHOULD end in '.dasm' or
  139
+   '.dasm16'.  This is first used by GitHub [GHBP] to identify DCPU-16
  140
+   assembly files.
  141
+
  142
+2.2.  Lines
  143
+
  144
+   An empty line MUST be omitted by the assembler.  A line MUST NOT
  145
+   contain more than one instruction.  A line MAY both define a label
  146
+   and contain an instruction, in this order.
  147
+
  148
+2.3.  Indentation and whitepacing
  149
+
  150
+   Whitespace MUST be allowed between all elements of a line, including
  151
+   but not limited to opcodes, values, syntactic characters and
  152
+   preprocessor directives.  Both a space (' ' U+0020) and a tab
  153
+   (U+0009) are considered whitespace characters.
  154
+
  155
+   Indenting instructions is RECOMMENDED.  NOT indenting labels and
  156
+   preprocessor directives RECOMMENDED.  The assembler MUST NOT mandate
  157
+   indentation to assemble successfully.
  158
+
  159
+
  160
+3.  Preprocessor Markup
  161
+
  162
+
  163
+
  164
+
  165
+
  166
+
  167
+Kuijpers & Beermann                                             [Page 3]
  168
+
  169
+                           Assembly Syntactics                April 2012
  170
+
  171
+
  172
+3.1.  Comments
  173
+
  174
+   Comments are used to add information to the code, making it more
  175
+   readable and understandable.  Comments can consist any character in
  176
+   any combination.  This document specifies one-line comments only.
  177
+
  178
+   Any characters following and in the same line of a semicolon (;
  179
+   U+003B) are comments and MUST be ignored, except when the semicolon
  180
+   resides within the representation of a string.  In that case, the
  181
+   semicolon MUST NOT be treated as a comment.
  182
+
  183
+3.2.  Prefix
  184
+
  185
+   Every preprocessor directive starts with an identifier.  This
  186
+   identifier is used to distinguish preprocessor directives from other
  187
+   code.
  188
+
  189
+   For historical reasons, directives can either start with a dot (.
  190
+   U+002E) or a number sign (# U+0023).
  191
+
  192
+   Preprocessor directives MUST start with a dot (.  U+002E) or a number
  193
+   sign (# U+0023).  Documents SHOULD NOT have mixedusage of these,
  194
+   assemblers SHOULD NOT accept mixing these in a single document.
  195
+
  196
+   Using a dot is RECOMMENDED to distinguish between C preprocessor
  197
+   syntax.
  198
+
  199
+3.3.  Case insensitivity
  200
+
  201
+   Assemblers MUST accept directives, definitions and constants without
  202
+   regard to case.
  203
+
  204
+3.4.  Directives
  205
+
  206
+   All directives in this section MUST be handled in order and in
  207
+   recognition of their position.  For unambigiousity a dot (.) is used
  208
+   here to describe preprocessor directives.
  209
+
  210
+3.4.1.  Inclusion
  211
+
  212
+3.4.1.1.  Code
  213
+
  214
+   .include "file"
  215
+   .include <file>
  216
+
  217
+   The former directive MUST include the file into the current file.
  218
+   The path is relative to the current file.  If the given filename does
  219
+   not exist compilation MUST be aborted.
  220
+
  221
+
  222
+
  223
+Kuijpers & Beermann                                             [Page 4]
  224
+
  225
+                           Assembly Syntactics                April 2012
  226
+
  227
+
  228
+   The latter includes the file from an implementation defined location,
  229
+   which may not even exist but trigger certain behaviour, i.e.
  230
+   inclusion of intrinsics.
  231
+
  232
+3.4.1.2.  Binary
  233
+
  234
+   .incbin "file"
  235
+   .incbin <file>
  236
+
  237
+   incbin MUST include the specified binary as raw, unprocessed data,
  238
+   the path to the file is relative from the current file.  All labels
  239
+   behind this directive MUST be offset by the size of the file.
  240
+
  241
+   The latter form of incbin MUST include the file from an
  242
+   implementation defined location.
  243
+
  244
+3.4.2.  Definitions
  245
+
  246
+   .def name [value]
  247
+   .undef name
  248
+
  249
+   def MUST assign the constant value to name.  If the value is omitted,
  250
+   the literal 1 (one) MUST be assumed.
  251
+
  252
+   undef MUST remove the given symbol from the namespace.  If the given
  253
+   symbol does not exist compilation SHOULD continue and a warning MAY
  254
+   be emitted.
  255
+
  256
+   Any occurances of the definition during its existence, MUST be
  257
+   replaced with the given value to the definition.
  258
+
  259
+3.4.3.  Data insertion
  260
+
  261
+   .word value [,value...]
  262
+   .byte value [,value...]
  263
+   .ascii "string"
  264
+
  265
+   word MUST store the values literally and unpacked at the location of
  266
+   the directive.
  267
+
  268
+   byte MUST pack (i.e. two bytes per word, first byte is LSB) the
  269
+   values at the location of the directive.
  270
+
  271
+   ascii MUST store the string unpacked (i.e. character is LSB, one word
  272
+   per character) at the location of the directive.
  273
+
  274
+
  275
+
  276
+
  277
+
  278
+
  279
+Kuijpers & Beermann                                             [Page 5]
  280
+
  281
+                           Assembly Syntactics                April 2012
  282
+
  283
+
  284
+3.4.4.  Origin relocation
  285
+
  286
+   .org address
  287
+
  288
+   The org preprocessor directive MUST take an address as the only
  289
+   argument.  Assemblers SHOULD verify the address is 16-bit sized.
  290
+   Assembler MUST add this address to the address of all labels,
  291
+   creating a relocation of the program.
  292
+
  293
+3.4.5.  Macros: macro block and macro insertion
  294
+
  295
+   .macro name([param [,param...]])
  296
+       code
  297
+   .end
  298
+   .ins name([param [,param...]])
  299
+
  300
+   The macro directive defines a macro, a parametrized block of code
  301
+   that can be inserted any time later.  Parameters, if any, are written
  302
+   in parentheses seperated by commas (,).
  303
+
  304
+   The ins directive MUST insert a formerly defined macros and expands
  305
+   the parameters of the macro with the comma-seperated parameters
  306
+   following the name of the macro to insert.
  307
+
  308
+   Parameter substitutions can only be constant values and memory
  309
+   references.  Preprocessor directives inside the macro MUST be handled
  310
+   upon insertion, not definition.
  311
+
  312
+3.4.6.  Repeat block
  313
+
  314
+   .rep times
  315
+       code
  316
+   .end
  317
+
  318
+   The code in the repeat-block MUST be repeated the number of times
  319
+   specified. 'times' MUST be a positive integer.  Preprocessor
  320
+   directives inside the repeat-block MUST be handled when the
  321
+   repetition is complete, to make allow conditional repetitions.
  322
+
  323
+
  324
+
  325
+
  326
+
  327
+
  328
+
  329
+
  330
+
  331
+
  332
+
  333
+
  334
+
  335
+Kuijpers & Beermann                                             [Page 6]
  336
+
  337
+                           Assembly Syntactics                April 2012
  338
+
  339
+
  340
+3.4.7.  Conditionals
  341
+
  342
+   .if expression
  343
+       codeTrue
  344
+   .elif expression
  345
+       codeElseTrue
  346
+   .else
  347
+       codeElse
  348
+   .end
  349
+   .ifdef definitions
  350
+   isdef(definition)
  351
+
  352
+   For the definition of valid expressions, see Section 3.5.
  353
+
  354
+   The if clause is REQUIRED.  The else clause is OPTIONAL.  The elif
  355
+   clause is OPTIONAL and can occur multiple times.
  356
+
  357
+   If expression consists of a single constant value, then expression =
  358
+   1 MUST be assumed.  If expression evaluates to 1, the codeTrue-block
  359
+   MUST be assembled.  When the evaluation fails, the next elif block
  360
+   must be evaluated.  In any other case codeElse, if an else clause is
  361
+   specified, MUST be assembled.
  362
+
  363
+   isdef(symbol) can be used in place of expression. isdef MUST evaluate
  364
+   to 1 if the given symbol is currently defined, else it MUST evaluate
  365
+   to 0.
  366
+
  367
+   ifdef is short for if isdef().  It is used often and therefor a short
  368
+   syntax is provided.
  369
+
  370
+   Nesting of if directives MUST be supported.
  371
+
  372
+3.4.8.  Error reporting
  373
+
  374
+   .error message
  375
+
  376
+   Triggers an assembler error with the message, stopping execution of
  377
+   the assembler.  The message SHOULD be shown in combination with the
  378
+   filename and line number.
  379
+
  380
+3.4.9.  Alignment
  381
+
  382
+   .align boundary
  383
+
  384
+   Aligns code or data on doubleword or other boundary.
  385
+
  386
+   The assembler MUST add NOPs (0x0000) to the generated machinecode
  387
+   until the alignment is correct.  The number of words inserted can be
  388
+
  389
+
  390
+
  391
+Kuijpers & Beermann                                             [Page 7]
  392
+
  393
+                           Assembly Syntactics                April 2012
  394
+
  395
+
  396
+   calculated using the formula: 'boundary - (currentPosition %
  397
+   boundary)' (% indiciates modulus).
  398
+
  399
+3.5.  Preprocessor inline arithmetic
  400
+
  401
+   Source code can include inline arithmetics anywhere a constant value
  402
+   is permitted.  Inline arithmetic may only consist of + (addition), -
  403
+   (subtraction), * (multiplication), / (integer division) and %
  404
+   (modulus), parentheses may be used to group expressions.  The
  405
+   evaluation order MUST be as follows: multiplication, division,
  406
+   modulus, addition, substraction.
  407
+
  408
+   The following logical and bitwise operators MUST also be supported: =
  409
+   (equal, also ==), != (not equal, also <>), < (smaller than), >
  410
+   (greater than), <= (smaller or equal), >= (greater or equal), & (bit-
  411
+   wise AND) ^ (bit-wise XOR), | (bit-wise OR), && (logical AND), ||
  412
+   (logical OR), ^^ (logical XOR) which MUST be evaluated with respect
  413
+   to this order.
  414
+
  415
+   Inline arithmetic MUST be evaluated as soon as possible, the result
  416
+   MUST be used as a literal value in place of the expression.
  417
+
  418
+
  419
+4.  Tokenizer Markup
  420
+
  421
+4.1.  Labels
  422
+
  423
+   Labels MUST be single-worded identifiers containing only alphabetical
  424
+   characters (/[A-Za-z]/), numbers (/[0-9]/) and underscores (_
  425
+   U+005F).  The label MUST represent the address of following
  426
+   instruction or data.  A label MUST NOT start with a number.  A label
  427
+   MUST end with a colon (: U+003A).  When the label is used, the
  428
+   tokenizer MUST translate the label into the address it represents.
  429
+
  430
+   Local labels MUST start with a dot (.  U+002E) and end with a colon
  431
+   (: U+003A).  Local labels MUST be scoped between the surrounding
  432
+   global labels.  Local labels in different scopes MUST be able to have
  433
+   the same name.
  434
+
  435
+4.2.  Case sensitivity
  436
+
  437
+   Assemblers MUST accept registers and opcodes without regard to case.
  438
+   Assemblers MUST accept labels respecting case.
  439
+
  440
+4.3.  Inline character literals
  441
+
  442
+   A character surrounded by apostrophes (' U+0029) MUST be interpreted
  443
+   as its corresponding 7-bit ASCII value in a word (LSB).  An assembler
  444
+
  445
+
  446
+
  447
+Kuijpers & Beermann                                             [Page 8]
  448
+
  449
+                           Assembly Syntactics                April 2012
  450
+
  451
+
  452
+   MUST support at least the ascii values ranging from 32 to 126
  453
+   (printable characters).
  454
+
  455
+4.4.  Inline arithmetic
  456
+
  457
+   Source code can include inline arithmetics anywhere a constant value
  458
+   is permitted.  Inline arithmetic may only consist of + (addition), -
  459
+   (subtraction), * (multiplication), / (integer division) and %
  460
+   (modulus), parentheses may be used to group expressions.  The
  461
+   evaluation order MUST be as follows: multiplication, division,
  462
+   modulus, addition, substraction.
  463
+
  464
+   The following bitwise operators MUST also be supported: & (bit-wise
  465
+   AND) ^ (bit-wise XOR), | (bit-wise OR).
  466
+
  467
+
  468
+5.  Conformance
  469
+
  470
+5.1.  Recognition of conformance
  471
+
  472
+   An assembler, formatter and any other assembly related program that
  473
+   is fully compliant to 0xSCA MAY label itself "0xSCA compatible".
  474
+   When using this label, the subject SHOULD include a note of the
  475
+   version of the RFC it is written against.
  476
+
  477
+
  478
+6.  Design Rationale
  479
+
  480
+6.1.  Labels
  481
+
  482
+   Although Notch used the syntax :label in his first examples, it is
  483
+   not common in any popular assembler.  Thus we decided for label: as
  484
+   the recommended form, still silently allowing the deprecated form.
  485
+
  486
+   To simplify writing reusable code we also introduced local labels,
  487
+   which are only visible from within the global label they are defined
  488
+   within.  Implementing this is easy to do and introduces little
  489
+   overhead, as nesting is neither specified nor recommended.
  490
+
  491
+6.2.  Preprocessor
  492
+
  493
+   0xSCA allows many operators and even parentheses in expressions for
  494
+   if-clauses, which complicates the implementation of these.  We do
  495
+   recognize that, but the actual implementation difficulty is not too
  496
+   high, as there are many examples how to achieve this and we think
  497
+   that the additional power and reduced code complexity, resulting in
  498
+   better maintainable code, is worth the effort.
  499
+
  500
+
  501
+
  502
+
  503
+Kuijpers & Beermann                                             [Page 9]
  504
+
  505
+                           Assembly Syntactics                April 2012
  506
+
  507
+
  508
+   The ability to define custom constants inline is easy to implement
  509
+   and yields more easily maintainable code, while introducing a minimum
  510
+   of additional syntax.
  511
+
  512
+   Both kinds of file inclusion support two different forms, one
  513
+   including the file relative to the current file, and the other
  514
+   including it from an implementation defined location.  The former is
  515
+   ideal for splitting a program in multiple parts, while the latter is
  516
+   intended for implementation-provided resources such as source level
  517
+   libraries.
  518
+
  519
+   A preprocessor must accept every directive with a dot (.) or a number
  520
+   sign (#) prefix.  While Notch seems to prefer the latter, the former
  521
+   is much more common among todays assemblers.  Thus we decided to
  522
+   support both, especiall as the implementation-side overhead is very
  523
+   low.
  524
+
  525
+
  526
+7.  Security Considerations
  527
+
  528
+   This memo has no applicable security considerations.
  529
+
  530
+
  531
+8.  Normative References
  532
+
  533
+   [GHBP]     MartA, V., "Take Over The Galaxy with GitHub", April 2012,
  534
+              <https://github.com/blog/
  535
+              1098-take-over-the-galaxy-with-github>.
  536
+
  537
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
  538
+              Requirement Levels", BCP 14, RFC 2119, March 1997.
  539
+
  540
+
  541
+Authors' Addresses
  542
+
  543
+   Jos Kuijpers (editor)
  544
+   Jarvix
  545
+
  546
+   Email: jos@kuijpersvof.nl (contact for any inquiries)
  547
+   URI:   http://www.jarvix.org/
  548
+
  549
+
  550
+   Marian Beermann (editor)
  551
+
  552
+   Email: public@enkore.de
  553
+   URI:   http://www.enkore.de/
  554
+
  555
+
  556
+
  557
+
  558
+
  559
+Kuijpers & Beermann                                            [Page 10]
  560
+
373  ASM/Spec_0xSCA.xml
... ...
@@ -0,0 +1,373 @@
  1
+<?xml version="1.0" encoding="US-ASCII"?>
  2
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
  3
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
  4
+<?rfc strict="yes" ?>
  5
+<?rfc toc="yes"?>
  6
+<?rfc tocdepth="4"?>
  7
+<?rfc symrefs="yes"?>
  8
+<?rfc sortrefs="yes" ?>
  9
+<?rfc compact="yes" ?>
  10
+<?rfc subcompact="no" ?>
  11
+<?rfc private="RFC X____" ?>
  12
+<rfc ipr="none" category="bcp" docName="recommendation-for-assembly-syntactics">
  13
+    <front>
  14
+        <title abbrev="Assembly Syntactics">0xSCA: Standards Committee Assembly</title>
  15
+
  16
+        <author fullname="Jos Kuijpers" initials="J.C." role="editor"
  17
+        surname="Kuijpers">
  18
+            <organization>Jarvix</organization>
  19
+
  20
+            <address>
  21
+                <email>jos@kuijpersvof.nl (contact for any inquiries)</email>
  22
+                <uri>http://www.jarvix.org/</uri>
  23
+            </address>
  24
+        </author>
  25
+        <author fullname="Marian Beermann" initials="M.B." role="editor"
  26
+            surname="Beermann">
  27
+            <address>
  28
+                <email>public@enkore.de</email>
  29
+                <uri>http://www.enkore.de/</uri>
  30
+            </address>
  31
+        </author>
  32
+        <date month="April" year="2012" />
  33
+        <area>ASM</area>
  34
+        <workgroup>0x10c Standards Committee</workgroup>
  35
+        <abstract>
  36
+          <t>This document describes an assembly and preprocessor syntax
  37
+          suitable for the DCPU-16 environment. This syntax is called the
  38
+          0xSCA, or Standards Committee Assembly.</t>
  39
+          <t>This is not a standard.</t>
  40
+        </abstract>
  41
+      </front>
  42
+
  43
+    <middle>
  44
+        <section title="Introduction">
  45
+          <t>This documents descrives 0xSCA, Standards Committee Assembly. It
  46
+		  is a definition of a syntax to be used for writing assembly for the
  47
+		  DCPU-16 processor. Use of this syntax is voluntarily. With 0xSCA,
  48
+		  there is a defined syntax, and could decrease code incompatibility
  49
+		  among compilers.</t>
  50
+		  <t>Again, to be clear: 0xSCA is a syntax definition, not a standard.
  51
+		  0xSCA is to DCPU-16, what AT&amp;T or the NASM syntax is to IA-32.</t>
  52
+
  53
+          <section title="Requirements Language">
  54
+            <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  55
+            "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  56
+            document are to be interpreted as described in <xref
  57
+            target="RFC2119">RFC 2119</xref>.</t>
  58
+          </section>
  59
+        </section>
  60
+
  61
+        <section title="Document Markup">
  62
+            <section title="Filename">
  63
+                <t>Assembly files on the DCPU-16 platform SHOULD end in '.dasm'
  64
+				or '.dasm16'. This is first used by
  65
+                <xref target="GHBP">GitHub</xref> to identify DCPU-16 assembly
  66
+				files.</t>
  67
+            </section>
  68
+            <section title="Lines">
  69
+                <t>An empty line MUST be omitted by the assembler. A line MUST
  70
+                NOT contain more than one instruction. A line MAY both define a
  71
+                label and contain an instruction, in this order.</t>
  72
+            </section>
  73
+            <section title="Indentation and whitepacing">
  74
+                <t>Whitespace MUST be allowed between all
  75
+                elements of a line, including but not limited to opcodes, values,
  76
+                syntactic characters and preprocessor directives. Both a space
  77
+                (' ' U+0020) and a tab (U+0009) are considered whitespace
  78
+                characters.</t>
  79
+                <t>Indenting instructions is RECOMMENDED. NOT indenting
  80
+                labels and preprocessor directives RECOMMENDED. The assembler
  81
+                MUST NOT mandate indentation to assemble successfully.</t>
  82
+            </section>
  83
+        </section>
  84
+    
  85
+        <section title="Preprocessor Markup">
  86
+            <section title="Comments">
  87
+                <t>Comments are used to add information to the code, making it
  88
+                more readable and understandable. Comments can consist any
  89
+                character in any combination. This document specifies one-line
  90
+                comments only.</t>
  91
+                <t>Any characters following and in the same line of a semicolon
  92
+                (; U+003B) are    comments and MUST be ignored, except when the
  93
+                semicolon resides within  the representation of a string. In
  94
+                that case, the semicolon MUST NOT be treated as a comment.</t>
  95
+            </section>
  96
+            <section title="Prefix">
  97
+                <t>Every preprocessor directive starts with an identifier. This
  98
+                identifier is used to distinguish preprocessor directives from
  99
+                other code.</t>
  100
+                <t>For historical reasons, directives can either start with a dot
  101
+                (. U+002E) or a number sign (# U+0023).</t>
  102
+                <t>Preprocessor directives MUST start with a dot (. U+002E) or a 
  103
+                number sign (# U+0023). Documents SHOULD NOT have mixedusage of
  104
+				these, assemblers SHOULD NOT accept mixing these in a single
  105
+				document.</t>
  106
+				<t>Using a dot is RECOMMENDED to distinguish between C preprocessor
  107
+                syntax.</t>
  108
+            </section>
  109
+            <section title="Case insensitivity">
  110
+                <t>Assemblers MUST accept directives, definitions and constants
  111
+                without regard to case.</t>
  112
+            </section>
  113
+            <section title="Directives">
  114
+                <t>All directives in this section MUST be handled in order and
  115
+                in recognition of their position. For unambigiousity a dot (.)
  116
+				is used here to describe preprocessor directives.</t>
  117
+                <section title="Inclusion">
  118
+                    <section title="Code">
  119
+                        <figure><artwork><![CDATA[
  120
+.include "file"
  121
+.include <file>]]></artwork></figure>
  122
+                        <t>The former directive MUST include the file into the
  123
+                        current file. The path is relative to the current file. If
  124
+                        the given filename does not exist compilation MUST be
  125
+                        aborted.</t>
  126
+                        <t>The latter includes the file from an implementation
  127
+                        defined location, which may not even exist but trigger
  128
+                        certain behaviour, i.e. inclusion of intrinsics.</t>
  129
+                    </section>
  130
+                    <section title="Binary">
  131
+                        <figure><artwork><![CDATA[
  132
+.incbin "file"
  133
+.incbin <file>]]></artwork></figure>
  134
+                        <t>incbin MUST include the specified binary as raw,
  135
+                        unprocessed data, the path to the file is relative 
  136
+                        from the current file. All labels behind this directive
  137
+                        MUST be offset by the size of the file.</t>
  138
+                        <t>The latter form of incbin MUST include the file from
  139
+                        an implementation defined location.</t>
  140
+                    </section>
  141
+                </section>
  142
+                <section title="Definitions">
  143
+                    <figure><artwork><![CDATA[
  144
+.def name [value]
  145
+.undef name]]></artwork></figure>
  146
+                    <t>def MUST assign the constant value to name. If the value
  147
+                    is omitted, the literal 1 (one) MUST be assumed.</t>
  148
+                    <t>undef MUST remove the given symbol from the namespace.
  149
+                    If the given symbol does not exist compilation SHOULD
  150
+                    continue and a warning MAY be emitted.</t>
  151
+					<t>Any occurances of the definition during its existence,
  152
+					MUST be replaced with the given value to the definition.</t>
  153
+                </section>
  154
+                <section title="Data insertion">
  155
+                    <figure><artwork><![CDATA[
  156
+.word value [,value...]
  157
+.byte value [,value...]
  158
+.ascii "string"]]></artwork></figure>
  159
+                    <t>word MUST store the values literally and unpacked at
  160
+                    the location of the directive.</t>
  161
+                    <t>byte MUST pack (i.e. two bytes per word, first byte is LSB)
  162
+                    the values at the location of the directive.</t>
  163
+                    <t>ascii MUST store the string unpacked (i.e. character is LSB,
  164
+                    one word per character) at the location of the directive.</t>
  165
+                </section>
  166
+                <section title="Origin relocation">
  167
+                    <figure><artwork><![CDATA[
  168
+.org address]]></artwork></figure>
  169
+                    <t>The org preprocessor directive MUST take an address
  170
+                    as the only argument. Assemblers SHOULD verify the
  171
+                    address is 16-bit sized. Assembler MUST add this
  172
+                    address to the address of all labels, creating a
  173
+                    relocation of the program.</t>
  174
+                </section>
  175
+                <section title="Macros: macro block and macro insertion">
  176
+                    <figure><artwork><![CDATA[
  177
+.macro name([param [,param...]])
  178
+    code
  179
+.end
  180
+.ins name([param [,param...]])]]></artwork></figure>
  181
+                    <t>The macro directive defines a macro, a parametrized block
  182
+                    of code that can be inserted any time later. Parameters,
  183
+                    if any, are written in parentheses seperated by commas (,).</t>
  184
+                    <t>The ins directive MUST insert a formerly defined macros and
  185
+                    expands the parameters of the macro with the comma-seperated
  186
+                    parameters following the name of the macro to insert.</t>
  187
+                    <t>Parameter substitutions can only be constant values and
  188
+                    memory references. Preprocessor directives inside the macro
  189
+                    MUST be handled upon insertion, not definition.</t>
  190
+                </section>
  191
+                <section title="Repeat block">
  192
+                    <figure><artwork><![CDATA[
  193
+.rep times
  194
+    code
  195
+.end]]></artwork></figure>
  196
+                    <t>The code in the repeat-block MUST be repeated the number
  197
+                    of times specified. 'times' MUST be a positive integer.
  198
+                    Preprocessor directives inside the repeat-block MUST be
  199
+                    handled when the repetition is complete, to make allow
  200
+                    conditional repetitions.</t>
  201
+                </section>
  202
+                <section title="Conditionals">
  203
+                    <figure><artwork><![CDATA[
  204
+.if expression
  205
+    codeTrue
  206
+.elif expression
  207
+    codeElseTrue
  208
+.else
  209
+    codeElse
  210
+.end
  211
+.ifdef definitions
  212
+isdef(definition)]]></artwork></figure>
  213
+                    <t>For the definition of valid expressions, see
  214
+                    <xref target="pp_ia" />.</t>
  215
+                    <t>The if clause is REQUIRED. The else clause is OPTIONAL.
  216
+					The elif clause is OPTIONAL and can occur multiple times.</t>
  217
+                    <t>If expression consists of a single constant value,
  218
+                    then expression = 1 MUST be assumed. If expression evaluates
  219
+					to 1, the codeTrue-block MUST be assembled. When the
  220
+					evaluation fails, the next elif block must be evaluated. In
  221
+					any other case codeElse, if an else clause is specified,
  222
+					MUST be assembled.</t>
  223
+                    <t>isdef(symbol) can be used in place of expression.
  224
+                    isdef MUST evaluate to 1 if the given symbol is currently
  225
+                    defined, else it MUST evaluate to 0.</t>
  226
+					<t>ifdef is short for if isdef(). It is used often and
  227
+					therefor a short syntax is provided.</t>
  228
+                    <t>Nesting of if directives MUST be supported.</t>
  229
+                </section>
  230
+                <section title="Error reporting">
  231
+                    <figure><artwork><![CDATA[
  232
+.error message]]></artwork></figure>
  233
+                    <t>Triggers an assembler error with the message, stopping
  234
+                    execution of the assembler. The message SHOULD be shown in
  235
+                    combination with the filename and line number.</t>
  236
+                </section>
  237
+                <section title="Alignment">
  238
+                    <figure><artwork><![CDATA[
  239
+.align boundary]]></artwork></figure>
  240
+                    <t>Aligns code or data on doubleword or other boundary.</t>
  241
+                    <t>The assembler MUST add NOPs (0x0000) to the generated
  242
+                    machinecode until the alignment is correct. The number of
  243
+                    words inserted can be calculated using the formula:
  244
+                    'boundary - (currentPosition % boundary)' (% indiciates
  245
+                    modulus).</t>
  246
+                </section>
  247
+            </section>
  248
+            <section title="Preprocessor inline arithmetic" anchor="pp_ia">
  249
+                <t>Source code can include inline arithmetics anywhere a
  250
+                constant value is permitted. Inline arithmetic may only
  251
+                consist of + (addition), - (subtraction), * (multiplication), /
  252
+                (integer division) and % (modulus), parentheses may be used
  253
+                to group expressions. The evaluation order MUST be as follows:
  254
+                multiplication, division, modulus, addition, substraction.</t>
  255
+                <t>The following logical and bitwise operators MUST also be
  256
+                supported: = (equal, also ==), != (not equal, also &lt;&gt;),
  257
+				&lt; (smaller than), &gt; (greater than), &lt;= (smaller or
  258
+				equal), &gt;= (greater or equal), &amp; (bit-wise AND) ^
  259
+				(bit-wise XOR), | (bit-wise OR), &amp;&amp; (logical AND), ||
  260
+				(logical OR), ^^ (logical XOR) which MUST be evaluated with
  261
+				respect to this order.</t>
  262
+                <t>Inline arithmetic MUST be evaluated as soon as possible, 
  263
+                the result MUST be used as a literal value in place of the expression.</t>
  264
+            </section>
  265
+        </section>
  266
+    
  267
+        <section title="Tokenizer Markup">
  268
+            <section title="Labels">
  269
+                <t>Labels MUST be single-worded identifiers containing only
  270
+                alphabetical characters (/[A-Za-z]/), numbers (/[0-9]/) and
  271
+                underscores (_ U+005F). The label MUST represent the address of
  272
+                following instruction or data. A label MUST NOT start with a
  273
+                number. A label MUST end with a colon (: U+003A). When the label
  274
+                is used, the tokenizer MUST translate the label into the address
  275
+                it represents.</t>
  276
+                <t>Local labels MUST start with a dot (. U+002E) and end with
  277
+                a colon (: U+003A). Local labels MUST be scoped between the
  278
+                surrounding global labels. Local labels in different scopes
  279
+                MUST be able to have the same name.</t>
  280
+            </section>
  281
+            <section title="Case sensitivity">
  282
+                <t>Assemblers MUST accept registers and opcodes without regard
  283
+                to case. Assemblers MUST accept labels respecting case.</t>
  284
+            </section>
  285
+            <section title="Inline character literals">
  286
+                <t>A character surrounded by apostrophes (' U+0029) MUST be
  287
+                interpreted as its corresponding 7-bit ASCII value in a word
  288
+                (LSB). An assembler MUST support at least the ascii values
  289
+                ranging from 32 to 126 (printable characters).</t>
  290
+            </section>
  291
+            <section title="Inline arithmetic">
  292
+                <t>Source code can include inline arithmetics anywhere a
  293
+                constant value is permitted. Inline arithmetic may only
  294
+                consist of + (addition), - (subtraction), * (multiplication), /
  295
+                (integer division) and % (modulus), parentheses may be used
  296
+                to group expressions. The evaluation order MUST be as follows:
  297
+                multiplication, division, modulus, addition, substraction.</t>
  298
+				<t>The following bitwise operators MUST also be supported: &amp;
  299
+				(bit-wise AND) ^ (bit-wise XOR), | (bit-wise OR).
  300
+				</t>
  301
+			</section>
  302
+        </section>
  303
+
  304
+        <section title="Conformance">
  305
+            <section title="Recognition of conformance">
  306
+                <t>An assembler, formatter and any other assembly related
  307
+                program that is fully compliant to 0xSCA MAY label itself
  308
+                "0xSCA compatible". When using this label, the subject SHOULD
  309
+                include a note of the version of the RFC it is written against.
  310
+                </t>
  311
+            </section>
  312
+        </section>
  313
+
  314
+	<section title="Design Rationale">
  315
+		<section title="Labels">
  316
+			<t>Although Notch used the syntax :label in his first
  317
+			examples, it is not common in any popular assembler.
  318
+			Thus we decided for label: as the recommended form,
  319
+			still silently allowing the deprecated form.</t>
  320
+			<t>To simplify writing reusable code we also introduced
  321
+			local labels, which are only visible from within the
  322
+			global label they are defined within. Implementing this
  323
+			is easy to do and introduces little overhead, as nesting
  324
+			is neither specified nor recommended.</t>
  325
+		</section>
  326
+
  327
+		<section title="Preprocessor">
  328
+			<t>0xSCA allows many operators and even parentheses in