From cf9c8405d09c4749ccbafddb721b3e4a2352c9f4 Mon Sep 17 00:00:00 2001
From: Zack Buhman <zack@buhman.org>
Date: Thu, 24 Aug 2023 04:03:43 +0000
Subject: [PATCH] README: improve

---
 README.rst    | 104 +++++++++++++++++++++++++++++++++++++++++++++-----
 test/Makefile |   4 +-
 2 files changed, 98 insertions(+), 10 deletions(-)

diff --git a/README.rst b/README.rst
index e47bc07..0a88356 100644
--- a/README.rst
+++ b/README.rst
@@ -1,17 +1,103 @@
-===========
+###########
 scu-dsp-asm
-===========
+###########
 
-Differences that affect source code:
+scu-dsp-asm is an assembler for SCU DSP mnemonics, using SEGA syntax.
 
-MC0-MC2 in DMA SRC/DST arguments.
+Usage:
 
-expressions that end with ':'
+.. code::
+   
+   scu-dsp-asm input-file.asm output-file.bin
 
-Differences that affect code generation:
+If no arguments are given, scu-dsp-asm starts a basic REPL.
 
-DMA vs DMA2
+Wherever possible, scu-dsp-asm attempts to preserve compatibility with
+the same source code used with the SEGA-authored ``dspasm.exe``,
+**except** in the cases where ``dspasm.exe`` behavior is considered a
+bug.
 
-invalid x-bus
+Differences that affect source code
+===================================
 
-motorola s record is not supported
+MC0-MC3 must not appear in in DMA source/destination arguments
+--------------------------------------------------------------
+
+For example, the following are not legal:
+
+.. code::
+   
+   DMA D0,MC0,#$02
+   DMA MC1,D0,#$02
+
+Instead, they should be written as:
+
+.. code::
+   
+   DMA D0,M0,#$02
+   DMA M1,D0,#$02
+   
+``dspasm.exe`` generates the same code given either the former or
+latter example as input. scu-dsp-asm, however, rejects the former
+example as invalid: it misleads what the result of the operation is.
+
+This change is consistent with what is written in the SCU manual
+(ST-97-R5-072694), but is inconsistent with SEGA's SCU DSP examples.
+
+Differences that affect code generation
+=======================================
+
+DMA default "add mode"
+----------------------
+
+``dspasm.exe`` has a bug where, despite the SCU manual
+(ST-97-R5-072694) claiming that the default DMA "add mode" is ``1``,
+the generated code is add mode ``2``.
+
+This bug is documented in "Sega Developers Conference Conference
+Proceedings March 5 7, 1996" on pdf page 48, printed page 3-14,
+slide 25. However, Sega of America did not fully understand the nature
+of the bug: patching ``dspasm.exe`` output is not necessary, because
+``dspasm.exe`` does in fact generate the correct code for the ``DMA1``
+mnemonic.
+
+In short:
+
+- ``dspasm.exe`` assembles ``DMA`` as the equivalent of the ``DMA2``
+  mnemonic
+
+- scu-dsp-asm assembles ``DMA`` as the equivalent of the ``DMA1``
+  mnemonic, which is the correct behavior as originally intended by
+  SEGA.
+
+Spurious invalid X-bus opcodes generation
+-----------------------------------------
+
+Under seemly-random circumstances, ``dspasm.exe`` emits the undefined
+X-bus opcode ``001``. Given:
+
+.. code::
+   
+   MOV M3,A  MOV 1,PL
+
+The ``dspasm.exe``-generated code is:
+
+.. code::
+   
+   00000000100001101101010100000001
+           ^ 
+However, the correct code should be:
+
+.. code::
+   
+   00000000000001101101010100000001
+           ^
+
+This is particularly interesting because the example mnemonics did not
+contain any X-bus operation to start with.
+	   
+Motorola S-record output is not supported
+-----------------------------------------
+
+Instead, scu-dsp-asm currently emits a raw binary file that contains
+fully assembled SCU DSP code.
diff --git a/test/Makefile b/test/Makefile
index f1e94e8..5c2ab98 100644
--- a/test/Makefile
+++ b/test/Makefile
@@ -7,6 +7,8 @@ ACTUAL = $(patsubst %.asm,actual/%.bin,$(SRC))
 ALL = $(EXPECT) $(ACTUAL)
 ALL_TXT = $(patsubst %.bin,%.txt,$(ALL))
 
+all-expect: $(EXPECT)
+all-actual: $(ACTUAL)
 all: $(ALL)
 all-txt: $(ALL_TXT)
 
@@ -35,7 +37,7 @@ expect/%.bin: %.s
 
 actual/%.bin: %.asm
 	@mkdir -p $(dir $@)
-	../main $< $@
+	../scu-dsp-asm $< $@
 
 clean:
 	rm -f expect/*.{bin,txt} actual/*.{bin,txt} *.s