NAME
	/harness/flash.bin

DESCRIPTION
	Access the flash storage chip (where the harness firmware is
	stored).

	Reading from the file reads the raw flash contents.

	Writing to the file does not accept raw data; instead the data
	must be encapsulated in the [Intel Hex] format, with the Hex
	file writing to the region 0x1000_0000-0x1010_0000. While less
	convenient than verbatim data, the Hex format provides in-band
	checksums and EOF-markers that help prevent rendering the
	harness unbootable with corrupted or truncated writes.  Any
	holes in the Intel Hex file are filled with "1" bits.  Once a
	complete Intel Hex file has been written without error and the
	file is closed, the harness reboots into the new firmware.

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.

	- When writing to the flash using this file, only half of the
	  chip capacity is usable (the size of the region specified
	  above is half the chip size); the top half and bottom half
	  are mirrors of each-other.  This is to avoid the firmware
	  crashing as its program text is overwritten; the firmware is
	  executing out of the bottom half, and writing to the top
	  half; once the file is closed, a minimal in-RAM function
	  copies the top half to the bottom half and reboots.

SEE ALSO:
	[Intel Hex]: https://archive.org/details/IntelHEXStandard

AUTHOR
	Copyright (C) 2025  Luke T. Shumaker <lukeshu@lukeshu.com>
	SPDX-License-Identifier: AGPL-3.0-or-later