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

2 files changed, 65 insertions, 0 deletions

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