Complete TODO comments and documentation

1 files changed, 38 insertions, 125 deletions

diff --git a/README.md b/README.md
index 60fdfbd..0e4b280 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,15 @@
 <!--
   README.md - Description of sbc-harness
 
-  Copyright (C) 2024  Luke T. Shumaker <lukeshu@lukeshu.com>
+  Copyright (C) 2024-2025  Luke T. Shumaker <lukeshu@lukeshu.com>
   SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
 # Building
 
-Building requires cmake, make, an "arm-none-eabi" toolchain (including
-newlib), and picotool (including the .cmake files;
-eg. /usr/lib/cmake/picotool/*.cmake).
+Building requires CMake, GNU Make, an "arm-none-eabi" toolchain
+(including newlib), and picotool (including the `.cmake` files;
+e.g. `/usr/lib/cmake/picotool/*.cmake`).
 
 At the time of this writing, on Parabola GNU/Linux-libre that means:
 
@@ -20,122 +20,35 @@ At the time of this writing, on Parabola GNU/Linux-libre that means:
  - arm-none-eabi-newlib 4.4.0.20231231-1
  - picotool 2.0.0-2
 
-```bash
-mkdir build
-cd build
-cmake -DCMAKE_BUILD_TYPE=Debug ..
-make
-```
-# Debugging
-
-UART:
-- pin1: gpio0: TX (so connect it to your FTDI's RX)
-- pin2: gpio1: RX (so connect it to your FTDI's TX)
-- pin3: gnd (so connect it to your FTDI's GND)
-- `picocom --baud=115200 /dev/ttyUSB0`
-- `picocom --baud=115200 /dev/ttyACM0`
-
-- `openocd -f interface/cmsis-dap.cfg -c 'set USE_CORE 0' -f target/rp2040.cfg -c "adapter speed 5000"`
-  (Explanation of `USE_CORE`: https://github.com/raspberrypi/debugprobe/issues/45)
-- `arm-none-eabi-gdb ./build/rp2040-Debug/cmd/sbc_harness/sbc_harness.elf`
-  ```
-  target extended-remote localhost:3333
-  monitor reset init
-  continue
-  ```
-  https://openocd.org/doc/html/General-Commands.html
-
-SWD:
-- https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html
-- https://github.com/raspberrypi/debugprobe
-- https://developer.arm.com/documentation/101451/0100/About-CMSIS-DAP
-
-## Raspberry Pi 3-pin Debug Connector
-- https://datasheets.raspberrypi.com/debug/debug-connector-specification.pdf
-
-| Pin # | UART                 | ARM SW-DP                          | cJTAG (IEEE 1149.7)              |
-|-------|----------------------|------------------------------------|----------------------------------|
-| 1     | RX (target←debugger) | SC/SWCLK (serial clock)            | TMSC - Test Clock Control        |
-| 2     | GND                  | GND                                | GND                              |
-| 3     | TX (target→debugger) | SD/SWDIO (bidi serial data)        | TCKC - Test Master/Slave Control |
-|       |                      | SWO (optional: serial wire output) |                                  |
-
-## UART (Universal asynchronous receiver/transmitter)
-
-## ARM SWD (Serial Wire Debug)
-- https://developer.arm.com/documentation/101761/1-0/Debug-and-trace-interface/Serial-Wire-Debug-signals
-- https://developer.arm.com/documentation/ihi0031/a/The-Serial-Wire-Debug-Port--SW-DP-/Introduction-to-the-ARM-Serial-Wire-Debug--SWD--protocol
-- https://arm-software.github.io/CMSIS-DAP/latest/index.html
-- ADIv5: https://developer.arm.com/documentation/ihi0031/g/
-- ADIv6: https://developer.arm.com/documentation/ihi0074/e/
-
-Alternative to Raspberry Pi Debug Probe:
-https://oshwlab.com/wagiminator/samd11c-swd-programmer which uses
-https://github.com/ataradov/free-dap instead of ARM's reference CMSIS
-implementation
-
-Note that the RP2040 chip has a pure SW-DP (just speaks SWD), not a
-JTAG-DP (just speaks JTAG) or a SWJ-DP (can speak either SWD or JTAG).
-
-```
-+-[Host PC]-------------------------+
-|                                   |
-|              +-----+              |
-|              | GDB |              |
-|              +-----+              |
-|                 ^                 |
-|                 | GDB Remote Serial Protocol
-|                 | on localhost:3333
-|                 V                 |
-|            +---------+            |
-|            | OpenOCD |            |
-|            +---------+            |
-|                 ^                 |
-|                 |                 |
-+-----------------|-----------------+
-                USB-A
-                  |
-                  | ARM CMSIS-DAP protocol
-                  | (a USB-based protocol)
-                  |
-            (micro)USB-B
-       +-[Debug Probe]-------+
-       |          |          |
-       |          V          |
-       |  +----------------+ |
-       |  |     ARM's      | |
-       |  |   reference    | |
-       |  |   CMSIS-DAP    | |
-       |  | implementation | |
-       |  +----------------+ |
-       |          ^          |
-       |          |          |
-       +----------|----------+
-         SW-DP (3-pin JST-SH)
-                  |
-                  | ADIv5 SWD protocol
-                  |
-        SW-DP (3 .1" headers)
-+-[SBC-Harness]---|-----------------+
-|                 |                 |
-| ,---------------'                 |
-| |                                 |
-| |  +----------------------------+ |
-| |  | Cortex-M0+                 | |
-| |  | +------------------------+ | |
-| +--->| CoreSight ADIv5 module | | |
-| |  | +------------------------+ | |
-| |  +----------------------------+ |
-| |                                 |
-| |  +----------------------------+ |
-| |  | Cortex-M0+                 | |
-| |  | +------------------------+ | |
-| `--->| CoreSight ADIv5 module | | |
-|    | +------------------------+ | |
-|    +----------------------------+ |
-|                                   |
-+-----------------------------------+
-```
+Then, simply run `make`.  This will create
+`build/rp2040-*/cmd/sbc_harness/sbc_harness.{bin,uf2,elf}` files.  The
+`.bin` file is the raw firmware image; the `.uf2` file is that wrapped
+into a [USB Flashing Format (UF2)](https://github.com/microsoft/uf2)
+container that can be used with the bootrom flasher (yes, the
+`.uf2` is expected to be about twice the size of the `.bin`); the
+`.elf` is the firmware image plus debugger symbols.
+
+There are several ways of putting this firmware file onto the harness:
+
+ 1. bootrom flasher: Hold the "BOOTSEL" button when powering on.  The
+    harness will appear to a host PC as a USB storage device.  Simply
+    mount the device and copy the `.uf2` file to the device.  It will
+    automatically reboot into the new firmware image.
+ 2. debug port: Using OpenOCD (see `HACKING.md`), run the OpenOCD command
+    `program /path/to/sbc_harness.elf reset`.
+
+    If OpenOCD is not already running:
+    ```
+    openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "program $PWD/build/rp2040-Debug/cmd/sbc_harness/sbc_harness.elf reset exit"`
+    ```
+
+    If OpenOCD is already running:
+    ```
+    socat STDIO TCP:localhost:4444 <<<"program $PWD/build/rp2040-Debug/cmd/sbc_harness/sbc_harness.elf reset"
+    ```
+ 3. Use `flashprog` or `flashrom` and a SOIC-8 clip to directly
+    program the flash chip.  I'm not sure why you would do this
+    instead of one of the above.
 
 # Usage
 
@@ -164,7 +77,7 @@ There are lots of 9P clients that you can use.  9P is a filesystem
 protocol; and you can mount it directly with the the Linux kernel's
 v9fs filesystem driver, with plan9port's `9pfuse`; or interact with it
 without mounting it using the shell commands `9p` (from plan9port),
-`wmiir`, `ixpc`; or interact with it without mounting it by using a
+`wmiir`, or `ixpc`; or interact with it without mounting it by using a
 library for your programming language of choice.
 
 Some notes on choosing a client:
@@ -174,18 +87,18 @@ Some notes on choosing a client:
  - I generally like mounting it as a real filesystem, but this means
    that you only get errno errors, and the more-helpful error strings
    are discarded.
- - The sbc-harness only supports 8 concurrent connections to the 9P
+ - The sbc-harness only supports 7 concurrent connections to the 9P
    server, so while shell commands are handy for poking around, for
    real use where you're doing things in parallel you'll likely want
    to mount it or use a library that can reuse existing connections.
 
 # Bugs/Limitations
 
- - Only supports 8 concurrent TCP connectsions to the 9P server (due
+ - Only supports 7 concurrent TCP connectsions to the 9P server (due
    to limitations in the W5500 TCP-offload chip; TODO: investigate
    using a software TCP/IP stack with the W5500 in MAC-raw mode)
- - Only supports 16 concurrent 9P requests (I wanted a static limit,
-   and "connections*2" seemed reasonable)
+ - Only supports 2 concurrent 9P requests per connection (I wanted a
+   static limit, and 2 seemed reasonable)
  - Only supports IPv4, not IPv6 (due to limitations in the W5500
    TCP-offload chip; TODO: investigate upgrading to the W6100 or using
    a software TCP/IP stack with the W5500 in MAC-raw mode)