From 8630b0a8ed8ba33d3eb466fb2ec32c9917fadb46 Mon Sep 17 00:00:00 2001
From: Virgil Dupras <hsoft@hardcoded.net>
Date: Mon, 5 Oct 2020 18:46:22 -0400
Subject: [PATCH] recipes/rc2014/avr: new recipe

---
 recipes/rc2014/README.md |  1 +
 recipes/rc2014/avr.md    | 83 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 recipes/rc2014/avr.md

diff --git a/recipes/rc2014/README.md b/recipes/rc2014/README.md
index 5769ec9..cc19e5d 100644
--- a/recipes/rc2014/README.md
+++ b/recipes/rc2014/README.md
@@ -28,6 +28,7 @@ are other recipes related to the RC2014:
 * [Self-hosting](selfhost.md)
 * [Interfacing a PS/2 keyboard](ps2.md)
 * [Using Zilog's SIO as a console](sio.md)
+* [Making an ATmega328P blink](avr.md)
 
 ## Recipe
 
diff --git a/recipes/rc2014/avr.md b/recipes/rc2014/avr.md
new file mode 100644
index 0000000..d4d5945
--- /dev/null
+++ b/recipes/rc2014/avr.md
@@ -0,0 +1,83 @@
+# Making an ATmega328P blink
+
+Collapse OS has an AVR assembler and an AVR programmer. If you
+have a SPI relay as described in the SD card recipe, then you
+almost have all it takes to make an ATmega328P blink.
+
+First, read `doc/avr.txt`. You'll see that it tells you how to
+build an AVR programmer that works with your SPI relay. You
+might already have such device. For example, I use the same
+device as the one I connect to my Sparkfun AVR Pocket
+Programmer, but I've added an on/off switch to it. I then use
+a 6-pin ribbon cable to connect it to my SPI relay.
+
+If you have a SD card connected to the same SPI relay, you'll
+face a timing challenge: SD specs specifies that the minimum
+SPI clock is 100kHz, but depending on your setup, you might end
+up with an effective `SCK` below that. My own clock setup looks
+like this:
+
+I have a RC2014 Dual clock which allows me to have easy access
+to many clock speeds, but the slowest option is 300kHz, not
+slow enough. My SPI relay has a pin for input clock override,
+and I built a pluggable 4040 with a switch that selects a
+divisor. I plug that module in my SPI relay, then I plug that
+into my RC2014 Dual clock. When doing SD card stuff, I select
+the "no division" position, and when I communicate with the
+AVR chip, I move the switch to increase the divisor.
+
+Once you've done this, you can test that you can communicate
+with your AVR chip by doing `160 162 LOADR` (turn off your
+programmer or alse it might mess up the SPI bus and prevent you
+from using your SD card) and then running:
+
+    1 asp$ aspfl@ .x 0 (spie)
+
+(Replace `1` by your SPI device ID) If everything works fine,
+you'll get the value of the low fuse of the chip.
+
+## Building the blink binary
+
+A blink program for the ATmega328P in Collapse OS would look
+like this:
+
+    50 LOAD ( avra ) 65 66 LOADR ( atmega328p ) H@ ORG !
+    DDRB 5 SBI, PORTB 5 CBI,
+    R16 TCCR0B IN, R16 0x05 ORI, TCCR0B R16 OUT,
+    R1 CLR,
+    L1 LBL! ( loop )
+        R16 TIFR0 IN,
+        R16 0 ( TOV0 ) SBRS,
+            L1 ( loop ) ' RJMP LBL, ( no overflow )
+        R16 0x01 LDI, TIFR0 R16 OUT,
+        R1 INC,
+        PORTB 5 CBI,
+        R1 7 SBRS,
+            PORTB 5 SBI,
+        L1 ( loop ) ' RJMP LBL,
+
+See `doc/asm.txt` for details. For now, you'll paste this into
+an arbitrary unused block. Let's use `999`.
+
+    $ cd recipes/rc2014
+    $ xsel > blk/999
+    $ rm blkfs
+    $ make
+    $ dd if=blkfs of=/dev/<your-sdcard> bs=1024
+
+Now, with your updated SD card in your RC2014, let's assemble
+this binary:
+
+    999 LOAD
+    H@ CREATE end ,
+    CREATE wordcnt end ORG @ - 2 / ,
+    : write 1 asp$ asperase wordcnt 0 DO
+    ORG @ I 2 * + @ I aspfb! LOOP
+    0 aspfp! 0 (spie) ;
+    write
+
+The first line assembles a 16 words binary beginning at `ORG @`,
+then the rest of the lines are about writing these 16 words to
+the AVR chip (see `doc/avr.txt` for details). After you've run
+this, if everything went well, that chip if it has a LED
+attached to PB5, will make that LED blink slowly.