# HG changeset patch
# User Robert McIntyre <rlm@mit.edu>
# Date 1334385142 18000
# Node ID 55a45f67e4a4fe466c3c11b77565a0eba6701a30
# Parent  7116b3f51ba85c3a2b317745533a37edb8d37d55
brought documentation up to date.

diff -r 7116b3f51ba8 -r 55a45f67e4a4 clojure/com/aurellem/gb/rlm_assembly.clj
--- a/clojure/com/aurellem/gb/rlm_assembly.clj	Fri Apr 13 11:33:56 2012 -0500
+++ b/clojure/com/aurellem/gb/rlm_assembly.clj	Sat Apr 14 01:32:22 2012 -0500
@@ -6,11 +6,6 @@
   (:import [com.aurellem.gb.gb_driver SaveState]))
 
 
-;; MODE-SELECT
-;; SET-LENGTH
-;; SET-TARGET
-;; WRITE
-;; JUMP
 
 ;; Specs for Main Bootstrap Program
 
@@ -20,51 +15,86 @@
 ;;   [:d :u :l :r :start :select :b :a]  -->  11111111
 ;;   [      :l    :start            :a]  -->  00101001
 
+;;; MODES
+;; There are five modes in total:
+;;   MODE-SELECT
+;;   SET-H
+;;   SET-L
+;;   WRITE
+;;   JUMP
+
 ;;; MODE-SELECT
 ;;   The bootstrap program starts in MODE-SELECT mode.
 ;;   MODE-SELECT transitions to one of three modes depending
 ;;   on which buttons are pressed:
-;;       0   (no-buttons)  :  MODE-SELECT
-;;       8   [:start]      :  WRITE-BYTES
-;;    0xFF   (all-buttons) :  JUMP
+;;       0   :  MODE-SELECT
+;;    0x67   :  SET-H
+;;    0x6F   :  SET-L
+;;    0x47   :  WRITE
+;;    0xE9   :  JUMP
+
+;;; SET-H
+;;   SET-H sets the high 8 bits of the target address to which
+;;   data will be written / the program will jump.  It expects
+;;   the following:
+;;
+;;    Byte 0 : New Value of H
+;;    Byte 1 : 0x00
+
+;;; SET-L
+;;   This mode sets the low 8 bits of the target address and has
+;;   the same semantics as SET-H.
 
 ;;; WRITE-BYTES
-
 ;;   WRITE-BYTES mode writes sequences of arbitray values to
 ;;   arbitray memory locations. It expects you to enter a
-;;   header of three bytes describing what to write:
+;;   header of one byte describing how many bytes to write.
 
 ;;    Byte 0  : Number of Bytes to Write
-;;    Byte 1  : Start Address High Byte
-;;    Byte 1  : Start Address Low  Byte
 
 ;;   Then, you enter the number of bytes specified in Byte 0
-;;   they are written to the start address in
-;;   sequence. After the last byte is written control
-;;   returns to MODE-SELECT mode.
+;;   and they are written to the start address in sequence.
+;;   After the last byte is written control returns to
+;;   MODE-SELECT mode. The Target address will be incremented by
+;;   Number of Bytes to Write once you are done writing.
 
 ;;   Example: to write the sequence [1 2 3 4] starting at
-;;   address 0xC01F enter
+;;   the target address enter:
 ;;    Byte 0  : 4 (will write four bytes)
-;;    Byte 1  : 0xC0  (high byte of 0xC01F)
-;;    Byte 2  : 0x1F  (low  byte of 0xC01F)
 ;;    Byte 3  : 1 (write 1 to 0xC01F)
 ;;    Byte 4  : 2 (write 2 to 0xC020)
 ;;    Byte 5  : 3 (write 3 to 0xC021)
 ;;    Byte 6  : 4 (write 4 to 0xC022)
 
 ;;; JUMP 
-;;   JUMP mode jumps program control to any arbitray
-;;   location. It expects you to enter two bytes which
-;;   correspond to the high and low bytes of the memory
-;;   address to which you want to jump.
-;;    Byte 0  : Jump Address High Byte
-;;    Byte 1  : Jump Address Low  Byte
+;;   JUMP mode jumps program control to the target address.
 
-;;   Example: to jump to address 0x1234 enter
-;;    Byte 0  : 0x12 (high byte of 0x1234)
-;;    Byte 1  : 0x34 (low  byte of 0x1234)
+;;; EXAMPLE
+;;   To write the infinite loop program [0x18 0xFE] to address
+;;   0xC00F and then jump to said program, enter the following
+;;   starting from MODE-SELECT mode.
 
+;;    Byte 0  : 0x67 [:a :b :l :u :select]        ;; SET-H mode
+;;    Byte 1  : 0xC0 [:d :u]                      ;; 0xC0 -> H
+;;    Byte 2  : 0x00 []                           ;; trailer
+
+;;    Byte 3  : 0x6F [:a :start :b :l :u :select] ;; SET-L mode
+;;    Byte 4  : 0x0F [:a :start :b :select]       ;; 0x0F -> L
+;;    Byte 5  : 0x00 []                           ;; trailer
+
+;;    Byte 6  : 0x47 [:a :b :u :select]           ;; WRITE-MODE
+;;    Byte 7  : 0x02 [:b]                         ;; write 2 bytes
+;;    Byte 8  : 0x18 [:r :start]                  ;; assembly
+;;    Byte 9  : 0xFE [:r :start :b :d :l :u :select] ;; assembly
+
+;;    target address is now 0xC011 since we wrote 2 bytes.
+;;    set it back to 0xC00F.
+
+;;    Byte 10 : 0x6F [:a :start :b :l :u :select] ;; SET-L mode
+;;    Byte 12 : 0x0F [:a :start :b :select]       ;; 0x0F -> L
+;;    Byte 13 : 0x00 []                           ;; trailer
+
+;;    Byte 14 : 0xE9                              ;; JUMP-MODE
 
 (defn ->signed-8-bit [n]
   (if (< n 0)
@@ -365,10 +395,7 @@
             (step (buttons (nth assembly 0)))
             (step (buttons (nth assembly 1)))
             (step (buttons (nth assembly 2)))
-            (step (buttons (nth assembly 3)))
-            (step [])
-            (step [])
-            (step []))]
+            (step (buttons (nth assembly 3))))]
     ;;(println "before :" (get-mem-region before))
     ;;(println "after  :" (get-mem-region after))
     ;;(assert (= assembly (take 4 (get-mem-region after))))