cmd/sbc_harness: Add documentation for rom.bin and flash.bin

7 files changed, 104 insertions, 6 deletions

diff --git a/.editorconfig b/.editorconfig
index 4bf1ae1..af47cbe 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -30,10 +30,10 @@ _mode = markdown
 [*.9p{,.wip}]
 _mode = 9p
 
-[{lib9p/tests/test_server/static.h.gen,build-aux/embed-sources.h.gen,build-aux/lint-{generic,unknown},build-aux/get-dscname}]
+[{lib9p/tests/test_server/static.h.gen,build-aux/embed-sources.h.gen,build-aux/lint-{generic,unknown}}]
 _mode = sh
 
-[{build-aux/lint-h,build-aux/lint-bin,build-aux/linux-errno.txt.gen,libusb/include/libusb/tusb_helpers.h.gen,lib9p/tests/runtest}]
+[{build-aux/lint-h,build-aux/lint-bin,build-aux/get-dscname,build-aux/linux-errno.txt.gen,libusb/include/libusb/tusb_helpers.h.gen,lib9p/tests/runtest}]
 _mode = bash
 
 [{lib9p/idl.gen,lib9p/include/lib9p/linux-errno.h.gen,build-aux/stack.c.gen}]
diff --git a/build-aux/get-dscname b/build-aux/get-dscname
index c8b3681..34a1b08 100755
--- a/build-aux/get-dscname
+++ b/build-aux/get-dscname
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/usr/bin/env bash
 # build-aux/get-dscname - Get a file's self-described filename
 #
 # Copyright (C) 2024-2025  Luke T. Shumaker <lukeshu@lukeshu.com>
@@ -9,4 +9,28 @@ if [ $# -ne 1 ]; then
 	exit 2
 fi
 
-sed -n '1,3{ /^\#!/d; /^<!--$/d; /-\*- .* -\*-/d; s,[/*\# ]*,,; s/ - .*//;p; q; }' -- "$1"
+if [[ $1 == */Documentation/* ]] && [[ "$(sed 1q -- "$1")" == 'NAME' ]]; then
+	sed -n '
+		2{
+			s,[/.],_,g;
+			s,^\s*_,Documentation/,;
+			s,$,.txt,;
+
+			p;
+			q;
+		}
+		' -- "$1"
+else
+	sed -n '
+		1,3{
+			/^\#!/d;
+			/^<!--$/d;
+			/-\*- .* -\*-/d;
+			s,[/*\# ]*,,;
+			s/ - .*//;
+
+			p;
+			q;
+		}
+		' -- "$1"
+fi
diff --git a/build-aux/lint-generic b/build-aux/lint-generic
index 92addcd..58a65d2 100755
--- a/build-aux/lint-generic
+++ b/build-aux/lint-generic
@@ -31,7 +31,7 @@ for filename in "$@"; do
 	if ! grep -E -q 'Copyright \(C\) 202[4-9]((-|, )202[5-9])*  Luke T. Shumaker' "$filename"; then
 		err "$filename" 'is missing a copyright statement'
 	fi
-	if ! grep -q ' SPDX-License-Identifier[:] ' "$filename"; then
+	if ! grep -q '\sSPDX-License-Identifier[:] ' "$filename"; then
 		err "$filename" 'is missing an SPDX-License-Identifier'
 	fi
 
diff --git a/cmd/sbc_harness/CMakeLists.txt b/cmd/sbc_harness/CMakeLists.txt
index 5f58729..9025447 100644
--- a/cmd/sbc_harness/CMakeLists.txt
+++ b/cmd/sbc_harness/CMakeLists.txt
@@ -1,6 +1,6 @@
 # cmd/sbc_harness/CMakeLists.txt - Build script for main sbc_harness.uf2 firmware file
 #
-# 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
 
 if (PICO_PLATFORM STREQUAL "rp2040")
@@ -60,6 +60,8 @@ target_embed_sources(sbc_harness_objs sbc_harness static.h
 	static/Documentation/YOUR_RIGHTS_AND_OBLIGATIONS/printf.mit.txt
 	static/Documentation/YOUR_RIGHTS_AND_OBLIGATIONS/tinyusb.mit.txt
 	static/Documentation/YOUR_RIGHTS_AND_OBLIGATIONS/newlib.txt
+	static/Documentation/harness_rom_bin.txt
+	static/Documentation/harness_flash_bin.txt
 )
 
 endif()
diff --git a/cmd/sbc_harness/main.c b/cmd/sbc_harness/main.c
index 1c14762..18a649e 100644
--- a/cmd/sbc_harness/main.c
+++ b/cmd/sbc_harness/main.c
@@ -68,6 +68,12 @@ struct lib9p_srv_file root =
 		                                             .data_start = _binary_static_Documentation_YOUR_RIGHTS_AND_OBLIGATIONS_newlib_txt_start,
 		                                             .data_end   = _binary_static_Documentation_YOUR_RIGHTS_AND_OBLIGATIONS_newlib_txt_end),
 		                                 ),
+		                      STATIC_FILE("harness_rom_bin.txt",
+		                                  .data_start = _binary_static_Documentation_harness_rom_bin_txt_start,
+		                                  .data_end   = _binary_static_Documentation_harness_rom_bin_txt_end),
+		                      STATIC_FILE("harness_flash_bin.txt",
+		                                  .data_start = _binary_static_Documentation_harness_flash_bin_txt_start,
+		                                  .data_end   = _binary_static_Documentation_harness_flash_bin_txt_end),
 		                      ),
 		           STATIC_DIR("harness",
 		                      STATIC_FILE("rom.bin",
@@ -79,6 +85,7 @@ struct lib9p_srv_file root =
 		                                  .data_size  = PICO_FLASH_SIZE_BYTES),
 		                      // TODO: system.log
 		                      // TODO: proc.txt
+		                      // TODO: cpuinfo.txt
 		                      // TODO: ctl
 		                      ),
 		           STATIC_DIR("dut",
diff --git a/cmd/sbc_harness/static/Documentation/harness_flash_bin.txt b/cmd/sbc_harness/static/Documentation/harness_flash_bin.txt
new file mode 100644
index 0000000..982d7e0
--- /dev/null
+++ b/cmd/sbc_harness/static/Documentation/harness_flash_bin.txt
@@ -0,0 +1,24 @@
+NAME
+	/harness/flash.bin
+
+DESCRIPTION
+	Access to the flash storage chip (where the harness firmware
+	is stored).
+
+	Any number of readers may read the flash contents.
+
+BUGS
+	- The size of the chip is configured at compile-time.  If the
+	  firmware is loaded onto hardware with a larger flash chip
+	  than it was compiled for, then the upper part of the chip
+	  will not be accessible with this file.  If the firmware is
+	  loaded onto hardware with a smaller flash chip than it was
+	  compiled for, then accessing the missing upper part of the
+	  chip will crash.
+
+	- This file is not writable; it aught to be possible to update
+	  the harness firmware by writing to this file.
+
+AUTHOR
+	Copyright (C) 2025  Luke T. Shumaker <lukeshu@lukeshu.com>
+	SPDX-License-Identifier: AGPL-3.0-or-later
diff --git a/cmd/sbc_harness/static/Documentation/harness_rom_bin.txt b/cmd/sbc_harness/static/Documentation/harness_rom_bin.txt
new file mode 100644
index 0000000..63fd0a3
--- /dev/null
+++ b/cmd/sbc_harness/static/Documentation/harness_rom_bin.txt
@@ -0,0 +1,41 @@
+NAME
+	/harness/rom.bin
+
+DESCRIPTION
+	Read access to the RP2040 CPU's ROM.  This contains code that
+	initializes the chip to load the main firmware from the
+	external flash chip, provides a failsafe USB-programmable
+	mode, and provides a few functions that the main firmware can
+	call to.
+
+BUGS
+	This ROM is programmed into the chip at the factory; revising
+	it means issuing a new revison of the RP2040 CPU.  So while
+	the source code to the ROM is freely available to be used,
+	studied, and shared; one cannot install modified versions onto
+	the CPU.
+
+HISTORY
+	- RP2040 B0 : chips manufactured before September 2020 or so
+	- RP2040 B1 : chips manufactured after September 2020 or so
+	- Released to the public January 2021; chance whether you get
+	  a B0 or a B1 chip.
+	- RP2040 B2 : released September 2021
+
+	Printed on the physical CPU is a label that indicates which
+	revision it is.  For example:
+
+		RP2-B2  21/24
+
+	indicates that it is the "B2" revision (and was manufactured
+	the 21st week (late May) of 2024).
+
+SEE ALSO
+	- /harness/cpuinfo.txt can report which CPU version you have.
+
+	- The source code to each ROM revision is published at
+	  https://github.com/raspberrypi/pico-bootrom-rp2040
+
+AUTHOR
+	Copyright (C) 2025  Luke T. Shumaker <lukeshu@lukeshu.com>
+	SPDX-License-Identifier: AGPL-3.0-or-later