basics: Improve documentation

Add more comments to `sprite.s` and `persist.s` so they can be read by a
newcomer, and also introduce a README for this directory.

Signed-off-by: Miquel Sabaté Solà <msabate@suse.com>

3 files changed, 23 insertions, 9 deletions

diff --git a/basics/README.md b/basics/README.md
new file mode 100644
index 0000000..7571509
--- /dev/null
+++ b/basics/README.md
@@ -0,0 +1,15 @@
+## Basics
+
+Here we have simple programs which try to explain a particular topic of NES
+programming. They are single files which already contain all you need in order
+to have a working program. This means that there is quite a lot of boilerplate
+you might not be aware. For this reason I encourage you to start with the
+`sprite.s` file, which has a step by step explanation on how the NES is
+initialized and what do all these magic "HEADER" and other jargon actually mean.
+Anyhow, these programs are as follows:
+
+- `sprite.s`: detailed explanation on how to initialize the NES in order to have
+  some background and a sprite shown on screen. Follow along the code in order
+  to get a detailed explanation on each section.
+- `input.s`: how to read the input from one controller.
+- `persist.s`: using the MMC1 chip in order to persist data.
diff --git a/basics/persist.s b/basics/persist.s
index 1dcfa29..392797f 100644
--- a/basics/persist.s
+++ b/basics/persist.s
@@ -103,10 +103,10 @@ reset_mmc1:
     ;;               That's why it did not really matter what we had at the iNES
     ;;               header: mirroring is programmatically set, not
     ;;               hardware-bound.
-    ;;   - bit 2: we have two regions: $8000-$BFFF and $C000-$FFFF. This bit
-    ;;            configures which one of them is fixed and which can be
-    ;;            swapped. We set this bit to one, meaning that $8000-$BFFF is
-    ;;            swappable while the other is fixed to the last bank of PRG.
+    ;;   - bit 2: we have two regions (see bit 3): $8000-$BFFF and $C000-$FFFF.
+    ;;            This bit configures which one of them is fixed and which can
+    ;;            be swapped. We set this bit to one, meaning that $8000-$BFFF
+    ;;            is swappable while the other is fixed to the last bank of PRG.
     ;;   - bit 3: swappable PRG size. If set to 0, then 32KB of memory is
     ;;            assumed, and thus bit 2 is ignored (i.e. the whole thing is to
     ;;            be swapped at once). Otherwise, if set to 1, then 16KB is
diff --git a/basics/sprite.s b/basics/sprite.s
index ac68d7f..09dd8e5 100644
--- a/basics/sprite.s
+++ b/basics/sprite.s
@@ -49,9 +49,8 @@
 
     ;; The previous are the mandatory bytes in order to get a "cartridge" going.
     ;; After this there are some other bytes you can put into the header, like
-    ;; if the "cartridge" counts on a battery-backed RAM-mapped section to save
-    ;; states (e.g. The Legend of Zelda) or rare flags like specifying the
-    ;; region (NTSC vs PAL), but for now this falls out of my radar :-)
+    ;; specifying the region (NTSC vs PAL), but for now this falls out of my
+    ;; radar :-)
 
 ;;;
 ;; This is the segment where we tell the processor where to find the code for
@@ -422,8 +421,8 @@ palettes:
     ;; offset for the first element was $00C8, which added to the base address
     ;; of $2000 (start of the first nametable), gives us the address $20C8.
     ;; Therefore, if I want this background element to be rendered in the
-    ;; position I envisioned on this tool, I need to write $20C8 into PPUADDR
-    ;; (NOTE: these are a total of two bytes to be loaded, for operations that
+    ;; position I envisioned on this tool, I need to write $20C8 into PPUADDR.
+    ;; NOTE: these are a total of two bytes to be loaded, for operations that
     ;; only support one byte at a time. Hence, we have to load byte by byte (in
     ;; little-endian format) and store them. As for the PPUDATA address, I need
     ;; to pass #$02 because that's the index inside of the CHR file of the star