From 405f185d4f5e35c9f7892c8bf216eeda8c422f47 Mon Sep 17 00:00:00 2001
From: Murad <muradkarammaev@gmail.com>
Date: Fri, 4 Feb 2022 17:59:00 +0200
Subject: [PATCH] add basic assembler design document

---
 ASM-SYNTAX.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 ASM-SYNTAX.md

diff --git a/ASM-SYNTAX.md b/ASM-SYNTAX.md
new file mode 100644
index 0000000..5c8ff80
--- /dev/null
+++ b/ASM-SYNTAX.md
@@ -0,0 +1,101 @@
+# ASM SYNTAX
+
+Grammar is described via
+[McKeeman Form](https://www.crockford.com/mckeeman.html).
+
+Instruction operands order resembles Intel syntax.
+
+`digit(min, max)` is a representation of binary, octal,
+decimal or hexadecimal integer in range `[min, max]`.
+I don't want to describe grammar for integers because
+it does not seem like a trivial task. Sue me.
+
+```
+asm
+	instructions
+
+instructions
+	instruction
+	instruction '\n' instructions
+
+instruction
+	mov
+	jmp
+	'EQ'
+	'GT'
+	'LE'
+	'NOT'
+	shift
+	'INC'
+	'DEC'
+	'ADD'
+	'SUB'
+	'AND'
+	'OR'
+	'XOR'
+	'XNOR'
+	'COMPL' register
+	'SETC' digit(0, 1)
+	'NOP'
+	'HALT'
+	'CLOAD' register
+	'ZERO' register
+	'DIV'
+	'MUL'
+	'SWAP'
+	'PRTRD'
+	'RDPRT'
+	'WRPRT'
+
+mov
+	'MOV' register ',' memory
+	'MOV' memory ',' register
+	'MOV' register-half ',' digit(0, 15)
+	'MOV' register ',' register
+
+jmp
+	'JMP' digit(-4, 8)
+	'JE' digit(-4, 8)
+	'JNE' digit(-4, 8)
+	'AJMP' digit(0, 255)
+	'AJE' digit(0, 255)
+	'AJNE' digit(0, 255)
+
+shift
+	'SHR'
+	'SHL'
+	'ROTR'
+	'ROTL'
+	'SHR' register ',' digit(0, 7)
+	'SHL' register ',' digit(0, 7)
+	'ROTR' register ',' digit(0, 7)
+	'ROTL' register ',' digit(0, 7)
+
+register
+	'R0'
+	'R1'
+
+memory
+	'[' digit(0, 15) ']'
+
+register-half
+	register '.l'
+	register '.h'
+```
+
+## Missing stuff
+
+There are no labels.
+We will probably implement them in future.
+Or we will probably not.
+
+## Sample program
+
+```asm
+MOV R0.l, 0xF
+MOV R1.l, 0x3
+ADD
+MOV [0], R0
+ZERO R0
+HALT
+```