/harness/flash.bin: Accept ihex files instead of verbatim data

7 files changed, 481 insertions, 62 deletions

diff --git a/cmd/sbc_harness/CMakeLists.txt b/cmd/sbc_harness/CMakeLists.txt
index 0e904ab..7656ab6 100644
--- a/cmd/sbc_harness/CMakeLists.txt
+++ b/cmd/sbc_harness/CMakeLists.txt
@@ -14,6 +14,8 @@ add_library(sbc_harness_objs OBJECT
 
 	fs_harness_flash_bin.c
 	fs_harness_uptime_txt.c
+
+	ihex.c
 )
 target_include_directories(sbc_harness_objs PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/config)
 target_include_directories(sbc_harness_objs PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
@@ -79,3 +81,16 @@ target_embed_sources(sbc_harness_objs sbc_harness static.h
 )
 
 endif()
+
+# Tests ########################################################################
+if ((PICO_PLATFORM STREQUAL "host") AND (ENABLE_TESTS))
+	add_executable(test_ihex "tests/test_ihex.c" "ihex.c")
+	target_include_directories(test_ihex PRIVATE ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/tests)
+	target_link_libraries(test_ihex
+		libhw_generic
+	)
+	add_test(
+		NAME    "cmd/sbc_harness/test_ihex"
+		COMMAND "${CMAKE_SOURCE_DIR}/build-aux/valgrind" "./test_ihex"
+	)
+endif()
diff --git a/cmd/sbc_harness/fs_harness_flash_bin.c b/cmd/sbc_harness/fs_harness_flash_bin.c
index 07675d1..6ae9e77 100644
--- a/cmd/sbc_harness/fs_harness_flash_bin.c
+++ b/cmd/sbc_harness/fs_harness_flash_bin.c
@@ -60,50 +60,24 @@ static_assert(DATA_HSIZE % FLASH_SECTOR_SIZE == 0);
 }
 
 /**
- * Set the upper half of flash to all zero bytes.
+ * Set the upper half of flash to all "1" bits.
  *
  * @param buf : a scratch buffer that is at least FLASH_SECTOR_SIZE
  */
-static void ab_flash_initialize_zero(uint8_t *buf) {
+static void ab_flash_initialize(void *buf) {
 	assert(buf);
 
-	memset(buf, 0, FLASH_SECTOR_SIZE);
+	memset(buf, 0xFF, FLASH_SECTOR_SIZE);
 
-	log_infoln("zeroing upper flash...");
+	log_infoln("erasing upper flash...");
 	for (size_t off = DATA_HSIZE; off < DATA_SIZE; off += FLASH_SECTOR_SIZE) {
 		if (memcmp(buf, DATA_START+off, FLASH_SECTOR_SIZE) == 0)
 			continue;
 		bool saved = cr_save_and_disable_interrupts();
-		/* No need to `flash_range_erase()`; the way the flash
-		 * works is that _erase() sets all bits to 1, and
-		 * _program() sets some bits to 0.  If we don't need
-		 * any bits to be 1, then we can skip the
-		 * _erase().  */
-		flash_range_program(off, buf, FLASH_SECTOR_SIZE);
-		cr_restore_interrupts(saved);
-	}
-	log_debugln("... zeroed");
-}
-
-/**
- * Copy the lower half of flash to the upper half of flash.
- *
- * @param buf : a scratch buffer that is at least FLASH_SECTOR_SIZE
- */
-static void ab_flash_initialize(uint8_t *buf) {
-	assert(buf);
-
-	log_infoln("initializing upper flash...");
-	for (size_t off = 0; off < DATA_HSIZE; off += FLASH_SECTOR_SIZE) {
-		memcpy(buf, DATA_START+off, FLASH_SECTOR_SIZE);
-		if (memcmp(buf, DATA_START+DATA_HSIZE+off, FLASH_SECTOR_SIZE) == 0)
-			continue;
-		bool saved = cr_save_and_disable_interrupts();
-		flash_range_erase(DATA_HSIZE+off, FLASH_SECTOR_SIZE);
-		flash_range_program(DATA_HSIZE+off, buf, FLASH_SECTOR_SIZE);
+		flash_range_erase(off, FLASH_SECTOR_SIZE);
 		cr_restore_interrupts(saved);
 	}
-	log_debugln("... initialized");
+	log_debugln("... erased");
 }
 
 /**
@@ -210,7 +184,6 @@ static size_t_and_error flashio_pwritev(struct flashio *self, const struct iovec
 			total_done += len;
 			iov_done += len;
 			offset += len;
-			self->written = true;
 		}
 	}
 	return ERROR_AND(size_t, total_done, ERROR_NULL);
@@ -219,11 +192,11 @@ static size_t_and_error flashio_pwritev(struct flashio *self, const struct iovec
 static error flashio_close(struct flashio *self) {
 	assert(self);
 
-	if (self->wbuf.ok)
-		ab_flash_write_sector(self->wbuf.pos, self->wbuf.dat);
-
-	if (self->written)
+	if (self->finalize) {
+		if (self->wbuf.ok)
+			ab_flash_write_sector(self->wbuf.pos, self->wbuf.dat);
 		ab_flash_finalize(self->wbuf.dat);
+	}
 
 	return ERROR_NULL;
 }
@@ -237,7 +210,7 @@ struct lib9p_qid flash_file_qid(struct flash_file *self) {
 	assert(self);
 
 	return (struct lib9p_qid){
-		.type = LIB9P_QT_FILE|LIB9P_QT_EXCL,
+		.type = LIB9P_QT_FILE|LIB9P_QT_EXCL|LIB9P_QT_APPEND,
 		.vers = 1,
 		.path = self->pathnum,
 	};
@@ -249,7 +222,7 @@ lib9p_srv_stat_or_error flash_file_stat(struct flash_file *self, struct lib9p_sr
 
 	return ERROR_NEW_VAL(lib9p_srv_stat, ((struct lib9p_srv_stat){
 		.qid                 = flash_file_qid(self),
-		.mode                = LIB9P_DM_EXCL|0666,
+		.mode                = LIB9P_DM_EXCL|LIB9P_DM_APPEND|0666,
 		.atime_sec           = UTIL9P_ATIME,
 		.mtime_sec           = UTIL9P_MTIME,
 		.size                = DATA_SIZE,
@@ -275,21 +248,24 @@ error flash_file_remove(struct flash_file *self, struct lib9p_srv_ctx *ctx) {
 
 LIB9P_SRV_NOTDIR(, struct flash_file, flash_file);
 
+static error flash_handle_ihex_data(void *, uint32_t off, uint8_t count, uint8_t *dat);
+static error flash_handle_ihex_eof(void *);
+
 lib9p_srv_fio_or_error flash_file_fopen(struct flash_file *self, struct lib9p_srv_ctx *ctx,
-                                        bool LM_UNUSED(rd), bool wr, bool trunc) {
+                                        bool LM_UNUSED(rd), bool wr, bool LM_UNUSED(trunc)) {
 	assert(self);
 	assert(ctx);
 
 	memset(&self->io, 0, sizeof(self->io));
 	if (wr) {
-		if (trunc) {
-			ab_flash_initialize_zero(self->io.wbuf.dat);
-			self->io.written = true;
-		} else {
-			ab_flash_initialize(self->io.wbuf.dat);
-		}
+		ab_flash_initialize(self->io.wbuf.dat);
 	}
 
+	memset(&self->ihex, 0, sizeof(self->ihex));
+	self->ihex.handle_arg = self;
+	self->ihex.handle_data = flash_handle_ihex_data;
+	self->ihex.handle_eof = flash_handle_ihex_eof;
+
 	return ERROR_NEW_VAL(lib9p_srv_fio, LO_BOX(lib9p_srv_fio, self));
 }
 
@@ -318,19 +294,33 @@ static error flash_file_pread(struct flash_file *self, struct lib9p_srv_ctx *ctx
 	return flashio_pread_to(&self->io, dst, byte_offset, byte_count).err;
 }
 
-/* TODO: Short/corrupt writes are dangerous.  This should either (1)
- * check a checksum, (2) use uf2 instead of verbatim data, or (3) use
- * ihex instead of verbatim data.  */
+static error flash_handle_ihex_data(void *_self, uint32_t off, uint8_t count, uint8_t *dat) {
+	struct flash_file *self = _self;
+
+	if (off < XIP_BASE || off >= XIP_BASE + DATA_HSIZE)
+		return error_new(E_POSIX_ENOSPC, "cannot write outside of the first half of the chip: ",
+			(base16_u32_, off), " is outside of [", (base16_u32_, XIP_BASE), ",", (base16_u32_, XIP_BASE + DATA_HSIZE), ")");
+
+	return flashio_pwritev(&self->io,
+	                       &((struct iovec){.iov_base = dat, .iov_len = count}), 1,
+	                       off - XIP_BASE).err;
+}
+static error flash_handle_ihex_eof(void *_self) {
+	struct flash_file *self = _self;
+	self->io.finalize = true;
+	return ERROR_NULL;
+}
+
+/* TODO: Also support uf2, not just ihex.  */
 static uint32_t_or_error flash_file_pwrite(struct flash_file *self, struct lib9p_srv_ctx *ctx,
                                            void *buf,
                                            uint32_t byte_count,
-                                           uint64_t byte_offset) {
+                                           uint64_t LM_UNUSED(byte_offset)) {
 	assert(self);
 	assert(ctx);
 
-	size_t_and_error r = flashio_pwritev(&self->io,
-	                                      &((struct iovec){.iov_base = buf, .iov_len = byte_count}), 1,
-	                                      byte_offset);
+	size_t_and_error r = ihex_decoder_writev(&self->ihex,
+	                                         &((struct iovec){.iov_base = buf, .iov_len = byte_count}), 1);
 	if (r.size_t == 0 && !ERROR_IS_NULL(r.err))
 		return ERROR_NEW_ERR(uint32_t, r.err);
 	return ERROR_NEW_VAL(uint32_t, (uint32_t) r.size_t);
diff --git a/cmd/sbc_harness/fs_harness_flash_bin.h b/cmd/sbc_harness/fs_harness_flash_bin.h
index 050f4a7..84cc494 100644
--- a/cmd/sbc_harness/fs_harness_flash_bin.h
+++ b/cmd/sbc_harness/fs_harness_flash_bin.h
@@ -11,8 +11,10 @@
 
 #include <lib9p/srv.h>
 
+#include "ihex.h"
+
 struct flashio {
-	bool            written;
+	bool            finalize;
 	struct {
 		bool            ok;
 		size_t          pos;
@@ -25,7 +27,8 @@ struct flash_file {
 	uint64_t         pathnum;
 
 	BEGIN_PRIVATE(FS_HARNESS_FLASH_BIN);
-	struct flashio   io;
+	struct flashio          io;
+	struct ihex_decoder     ihex;
 	END_PRIVATE(FS_HARNESS_FLASH_BIN);
 };
 LO_IMPLEMENTATION_H(lib9p_srv_file, struct flash_file, flash_file);
diff --git a/cmd/sbc_harness/ihex.c b/cmd/sbc_harness/ihex.c
new file mode 100644
index 0000000..565ad16
--- /dev/null
+++ b/cmd/sbc_harness/ihex.c
@@ -0,0 +1,225 @@
+/* sbc_harness/ihex.c - Intel Hex decoder
+ *
+ * Copyright (C) 2025  Luke T. Shumaker <lukeshu@lukeshu.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+/* https://archive.org/details/IntelHEXStandard */
+
+#include <string.h> /* for memchr() */
+
+#include <libmisc/assert.h>
+#include <libmisc/endian.h>
+
+#define IMPLEMENTATION_FOR_IHEX_H YES
+#include "ihex.h"
+
+LO_IMPLEMENTATION_C(io_writer, struct ihex_decoder, ihex_decoder);
+
+enum ihex_record_type {
+	/* [U]SBA: [Upper] Segment Base Address : SBA = USBA<< 4 */
+	/* [U]LBA: [Upper] Linear Base Address  : LBA = ULBA<<16 */
+	/* _EXT records define where DATA records are written to */
+	/* _START records define where execution should start */
+	IHEX_REC_DATA           = 0x00, /* .dat is .len bytes of data, which go at either (USBA<<4)+(.off%64KiB) or ((ULBA<<16)+.off)%4GiB */
+	IHEX_REC_EOF            = 0x01, /* .len=0, .off=0 */
+	IHEX_REC_ADDR_SEG_EXT   = 0x02, /* .len=2, .off=0, .dat is u16be USBA */
+	IHEX_REC_ADDR_SEG_START = 0x03, /* .len=4, .off=0, .dat is u16be CS register then u16be IP register */
+	IHEX_REC_ADDR_LIN_EXT   = 0x04, /* .len=2, .off=0, .dat is u16be ULBA */
+	IHEX_REC_ADDR_LIN_START = 0x05, /* .len=4, .off=0, .dat is u32be EIP register */
+};
+
+struct ihex_record {
+	uint8_t                  len;
+	uint16_t                 off;
+	enum ihex_record_type    typ;
+	uint8_t                 *dat;
+};
+
+static error ihex_handle_record(struct ihex_decoder *self, struct ihex_record *rec) {
+	switch (rec->typ) {
+	case IHEX_REC_ADDR_SEG_EXT:
+		self->addr_mode = _IHEX_MODE_SEG;
+		self->addr_base = ((uint32_t)uint16be_decode(rec->dat)) << 4;
+		return ERROR_NULL;
+	case IHEX_REC_ADDR_LIN_EXT:
+		self->addr_mode = _IHEX_MODE_LIN;
+		self->addr_base = ((uint32_t)uint16be_decode(rec->dat)) << 16;
+		return ERROR_NULL;;
+	case IHEX_REC_DATA:
+		switch (self->addr_mode) {
+		case _IHEX_MODE_NONE:
+			return error_new(E_POSIX_EINVAL, "ihex: data record before base-address record");
+		case _IHEX_MODE_SEG:
+			if (!self->handle_data)
+				return ERROR_NULL;
+			if (rec->len <= UINT16_MAX - rec->off) {
+				/* 1 write */
+				return self->handle_data(self->handle_arg, self->addr_base + rec->off, rec->len, rec->dat);
+			} else {
+				/* wraps around; split into 2 writes */
+				uint8_t first_len = (uint8_t) (UINT16_MAX - rec->off);
+				if (first_len) {
+					error err = self->handle_data(self->handle_arg, self->addr_base + rec->off, first_len, rec->dat);
+					if (!ERROR_IS_NULL(err))
+						return err;
+				}
+				return self->handle_data(self->handle_arg, self->addr_base, rec->len - first_len, &rec->dat[first_len]);
+			}
+		case _IHEX_MODE_LIN:
+			if (!self->handle_data)
+				return ERROR_NULL;
+			uint32_t off = self->addr_base + rec->off;
+			if (rec->len <= UINT32_MAX - off) {
+				/* 1 write */
+				return self->handle_data(self->handle_arg, off, rec->len, rec->dat);
+			} else {
+				/* wraps around; split into 2 writes */
+				uint8_t first_len = (uint8_t) (UINT32_MAX - off);
+				if (first_len) {
+					error err = self->handle_data(self->handle_arg, off, first_len, rec->dat);
+					if (!ERROR_IS_NULL(err))
+						return err;
+				}
+				return self->handle_data(self->handle_arg, 0, rec->len - first_len, &rec->dat[first_len]);
+			}
+		default:
+			assert_notreached("bad addr_mode");
+		}
+	case IHEX_REC_EOF:
+		self->seen_eof = true;
+		if (!self->handle_eof)
+			return ERROR_NULL;
+		return self->handle_eof(self->handle_arg);
+	case IHEX_REC_ADDR_SEG_START:
+		if (!self->handle_set_exec_start_seg)
+			return ERROR_NULL;
+		uint16_t cs = uint16be_decode(&rec->dat[0]);
+		uint16_t ip = uint16be_decode(&rec->dat[2]);
+		return self->handle_set_exec_start_seg(self->handle_arg, cs, ip);
+	case IHEX_REC_ADDR_LIN_START:
+		if (!self->handle_set_exec_start_lin)
+			return ERROR_NULL;
+		uint32_t eip = uint32be_decode(rec->dat);
+		return self->handle_set_exec_start_lin(self->handle_arg, eip);
+	default:
+		assert_notreached("bad record type");
+	}
+}
+
+/**
+ * Hex-decode the byte 0xAB, and push it onto self->buf.  If this
+ * completes the record in self->buf, then handle that record.
+ *
+ * @return the number of ASCII bytes consumed (0, 1, or 2) before
+ * encountering an error.
+ */
+static size_t_and_error ihex_decode_byte(struct ihex_decoder *self, char a, char b) {
+	uint8_t byte;
+	if ('0' <= a && a <= '9')
+		byte = (a - '0') << 4;
+	else if ('A' <= a && a <= 'F')
+		byte = (a - 'A' + 10) << 4;
+	else
+		return ERROR_AND(size_t, 0, error_new(E_POSIX_EILSEQ, "ihex: invalid hexadecimal: ", (qbyte, a)));
+	if ('0' <= b && b <= '9')
+		byte |= b - '0';
+	else if ('A' <= b && b <= 'F')
+		byte |= b - 'A' + 10;
+	else
+		return ERROR_AND(size_t, 1, error_new(E_POSIX_EILSEQ, "ihex: invalid hexadecimal: ", (qbyte, b)));
+	self->buf[self->buf_len++] = byte;
+	if (self->buf_len == self->buf[0]+5) {
+		uint8_t sum = 0;
+		for (size_t i = 0; i < (size_t)self->buf[0]+5; i++)
+			sum += self->buf[i];
+		if (sum != 0) {
+			self->sticky_err = error_new(E_POSIX_EPROTO, "ihex: checksum mismatch");
+			return ERROR_AND(size_t, 2, error_dup(self->sticky_err));
+		}
+		struct ihex_record rec = {
+			.len = self->buf[0],
+			.off = uint16be_decode(&self->buf[1]),
+			.typ = self->buf[3],
+			.dat = &self->buf[4],
+		};
+		error err = ihex_handle_record(self, &rec);
+		if (!ERROR_IS_NULL(err)) {
+			self->sticky_err = err;
+			return ERROR_AND(size_t, 2, error_dup(err));
+		}
+		self->in_record = false;
+		self->buf_len = 0;
+	}
+	return ERROR_AND(size_t, 2, ERROR_NULL);
+}
+
+static size_t_and_error ihex_decoder_write(struct ihex_decoder *self, const char *dat, size_t len_in) {
+	assert(self);
+	if (!len_in)
+		return ERROR_AND(size_t, 0, ERROR_NULL);
+	assert(dat);
+
+	if (!ERROR_IS_NULL(self->sticky_err))
+		return ERROR_AND(size_t, 0, error_dup(self->sticky_err));
+
+	size_t len_consumed = 0;
+
+	if (self->buf_char) {
+		assert(self->in_record);
+		size_t_and_error r = ihex_decode_byte(self, self->buf_char, dat[0]);
+		if (r.size_t)
+			len_consumed += r.size_t - 1;
+		self->buf_char = 0;
+		if (!ERROR_IS_NULL(r.err))
+			return ERROR_AND(size_t, len_consumed, r.err);
+	}
+
+	while (len_consumed < len_in) {
+		if (!self->in_record) {
+			const char *marker = memchr(&dat[len_consumed], ':', len_in-len_consumed);
+			if (!marker) {
+				len_consumed = len_in;
+				continue;
+			}
+			len_consumed += marker - &dat[len_consumed];
+
+			assert(dat[len_consumed] == ':');
+			if (self->seen_eof)
+				return ERROR_AND(size_t, len_consumed, error_new(E_POSIX_EPROTO, "ihex: record after EOF record"));
+			len_consumed++;
+			self->in_record = true;
+		}
+		while (len_in - len_consumed >= 2 && self->in_record) {
+			size_t_and_error r = ihex_decode_byte(self, dat[len_consumed], dat[len_consumed+1]);
+			len_consumed += r.size_t;
+			if (!ERROR_IS_NULL(r.err))
+				return ERROR_AND(size_t, len_consumed, r.err);
+		}
+		if (len_in - len_consumed && self->in_record) {
+			assert(len_in - len_consumed == 1);
+			if (!(('0' <= dat[len_consumed] && dat[len_consumed] <= '9') ||
+			      ('A' <= dat[len_consumed] && dat[len_consumed] <= 'F')))
+				return ERROR_AND(size_t, len_consumed, error_new(E_POSIX_EILSEQ, "ihex: invalid hexadecimal: ", (qbyte, dat[len_consumed])));
+			self->buf_char = dat[len_consumed++];
+		}
+	}
+
+	assert(len_consumed == len_in);
+	return ERROR_AND(size_t, len_in, ERROR_NULL);
+}
+
+size_t_and_error ihex_decoder_writev(struct ihex_decoder *self, const struct iovec *iov, int iovcnt) {
+	assert(self);
+	assert(iov);
+	assert(iovcnt);
+
+	size_t total = 0;
+	for (int i = 0; i < iovcnt; i++) {
+		size_t_and_error r = ihex_decoder_write(self, iov[i].iov_base, iov[i].iov_len);
+		total += r.size_t;
+		if (!ERROR_IS_NULL(r.err))
+			return ERROR_AND(size_t, total, r.err);
+	}
+	return ERROR_AND(size_t, total, ERROR_NULL);
+}
diff --git a/cmd/sbc_harness/ihex.h b/cmd/sbc_harness/ihex.h
new file mode 100644
index 0000000..d5ac70c
--- /dev/null
+++ b/cmd/sbc_harness/ihex.h
@@ -0,0 +1,48 @@
+/* sbc_harness/ihex.h - Intel Hex decoder
+ *
+ * Copyright (C) 2025  Luke T. Shumaker <lukeshu@lukeshu.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+/* https://archive.org/details/IntelHEXStandard */
+
+#ifndef _SBC_HARNESS_IHEX_H_
+#define _SBC_HARNESS_IHEX_H_
+
+#include <stdbool.h> /* for bool */
+#include <stddef.h>  /* for size_t */
+#include <stdint.h>  /* for uint{n}_t */
+
+#include <libhw/generic/io.h>
+#include <libmisc/private.h>
+
+struct ihex_decoder {
+	void    *handle_arg;
+	error   (*handle_data)(void *arg, uint32_t off, uint8_t count, uint8_t *dat);
+	error   (*handle_set_exec_start_seg)(void *arg, uint16_t cs, uint16_t ip);
+	error   (*handle_set_exec_start_lin)(void *arg, uint32_t eip);
+	error   (*handle_eof)(void *arg);
+
+	BEGIN_PRIVATE(IHEX_H);
+
+	bool     seen_eof;
+	error    sticky_err;
+
+	/* ihex_decoder_write: deal with ASCII soup */
+	bool     in_record;
+	char     buf_char; /* the first nibble of a byte (still in ASCII) */
+
+	/* ihex_decode_byte: build records from decoded bytes  */
+	/* The currently-being-decoded record, after hex decoding.  */
+	uint16_t buf_len;
+	uint8_t  buf[0xFF+5];
+
+	/* ihex_handle_record: handle record semantics */
+	enum { _IHEX_MODE_NONE, _IHEX_MODE_SEG, _IHEX_MODE_LIN }        addr_mode;
+	uint32_t                                                        addr_base;
+
+	END_PRIVATE(IHEX_H);
+};
+LO_IMPLEMENTATION_H(io_writer, struct ihex_decoder, ihex_decoder);
+
+#endif /* _SBC_HARNESS_IHEX_H_ */
diff --git a/cmd/sbc_harness/static/Documentation/harness_flash_bin.txt b/cmd/sbc_harness/static/Documentation/harness_flash_bin.txt
index 115f2ee..1b58d6d 100644
--- a/cmd/sbc_harness/static/Documentation/harness_flash_bin.txt
+++ b/cmd/sbc_harness/static/Documentation/harness_flash_bin.txt
@@ -2,14 +2,20 @@ NAME
 	/harness/flash.bin
 
 DESCRIPTION
-	Access to the flash storage chip (where the harness firmware
-	is stored).
+	Access the flash storage chip (where the harness firmware is
+	stored).
 
-	Any number of readers may read the flash contents.
+	Reading from the file reads the raw flash contents.
 
-	Only one writer can have the file open at a time; once the
+	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.
-	Writes to the top half of the chip will fail.
 
 BUGS
 	- The size of the chip is configured at compile-time.  If the
@@ -21,13 +27,17 @@ BUGS
 	  chip will crash.
 
 	- When writing to the flash using this file, only half of the
-	  chip capacity is usable; the top half and bottom half are
-	  mirrors of each-other.  This is to avoid the firmware
+	  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
diff --git a/cmd/sbc_harness/tests/test_ihex.c b/cmd/sbc_harness/tests/test_ihex.c
new file mode 100644
index 0000000..143e3b4
--- /dev/null
+++ b/cmd/sbc_harness/tests/test_ihex.c
@@ -0,0 +1,128 @@
+/* cmd/sbc_harness/tests/test_ihex.c - Tests for ihex.c
+ *
+ * Copyright (C) 2025  Luke T. Shumaker <lukeshu@lukeshu.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+#include <stdio.h> /* for putchar() */
+#include <string.h>
+
+#include <libmisc/fmt.h>
+
+#include "ihex.h"
+
+struct stdout { size_t len; };
+LO_IMPLEMENTATION_STATIC(fmt_dest, struct stdout, stdout);
+static void stdout_putb(struct stdout *self, uint8_t b) {
+	putchar(b);
+	self->len++;
+}
+static size_t stdout_tell(struct stdout *self) {
+	return self->len;
+}
+
+static lo_interface fmt_dest fmt_stdout = lo_box_stdout_as_fmt_dest(&((struct stdout){}));
+
+#define test_assert(expr) do {                                                            \
+		if (!(expr))                                                              \
+			fmt_print(                                                        \
+				fmt_stdout,                                               \
+				"test failure: ", __FILE__, ":", __LINE__, ":", __func__, \
+				": " #expr "\n");                                         \
+	} while (0)
+
+static char *input =
+	/* ,-byte count
+	 * | ,-address
+	 * | |   ,-record type
+	 * | |   |                                 ,- checksum
+	 *[][--][][..............................][]\r\n */
+	":020000041000EA\r\n"                             /* base_addr = linear(0x1000) = 0x1000<<16 */
+	":1000000000B5324B212058609868022188439860DF\r\n" /* memcpy(chip[base_addr+0x0000], "\x00\xB5\x32\x4B\x21\x20\x58\x60\x98\x68\x02\x21\x88\x43\x98\x60", 16) */
+	":10001000D860186158612E4B002199600221596106\r\n" /* memcpy(chip[base_addr+0x0010], "\xD8\x60\x18\x61\x58\x61\x2E\x4B\x00\x21\x99\x60\x02\x21\x59\x61", 16) */
+	":10BE9C000000000000000000000000000000000096\r\n" /* memcpy(chip[base_addr+0xBE9C], "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", 16) */
+	":04BEAC00CC4A00205C\r\n"                         /* memcpy(chip[base_addr+0xBEAC], "\x00\xCC\x4A\x00\x20", 5) */
+	":04000005100001E9FD\r\n"                         /* start_exec_at = linear(0x100001E9) */
+	":00000001FF\r\n";                                /* EOF */
+
+static int cnt = 0;
+
+static error handle_data(void *, uint32_t off, uint8_t count, uint8_t *dat) {
+	switch (cnt) {
+	case 0:
+		test_assert(off == UINT32_C(0x10000000));
+		test_assert(count == 16);
+		test_assert(memcmp(dat, "\x00\xB5\x32\x4B\x21\x20\x58\x60\x98\x68\x02\x21\x88\x43\x98\x60", 16) == 0);
+		break;
+	case 1:
+		test_assert(off == UINT32_C(0x10000010));
+		test_assert(count == 16);
+		test_assert(memcmp(dat, "\xD8\x60\x18\x61\x58\x61\x2E\x4B\x00\x21\x99\x60\x02\x21\x59\x61", 16) == 0);
+		break;
+	case 2:
+		test_assert(off == UINT32_C(0x1000BE9C));
+		test_assert(count == 16);
+		test_assert(memcmp(dat, "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", 16) == 0);
+		break;
+	case 4:
+		test_assert(off == UINT32_C(0x1000BE9C));
+		test_assert(count == 5);
+		test_assert(memcmp(dat, "\x00\xCC\x4A\x00\x20", 5) == 0);
+		break;
+	default:
+		test_assert(false);
+	}
+	cnt++;
+	return ERROR_NULL;
+}
+static error handle_set_exec_start_seg(void *, uint16_t LM_UNUSED(cs), uint16_t LM_UNUSED(ip)) {
+	switch (cnt) {
+	default:
+		test_assert(false);
+	}
+	cnt++;
+	return ERROR_NULL;
+}
+static error handle_set_exec_start_lin(void *, uint32_t eip) {
+	switch (cnt) {
+	case 5:
+		test_assert(eip == UINT32_C(0x100001E9));
+		break;
+	default:
+		test_assert(false);
+	}
+	cnt++;
+	return ERROR_NULL;
+}
+static error handle_eof(void *) {
+	switch (cnt) {
+	case 6:
+		break;
+	default:
+		test_assert(false);
+	}
+	cnt++;
+	return ERROR_NULL;
+}
+
+int main() {
+	struct ihex_decoder dec = {
+		.handle_data = handle_data,
+		.handle_set_exec_start_seg = handle_set_exec_start_seg,
+		.handle_set_exec_start_lin = handle_set_exec_start_lin,
+		.handle_eof = handle_eof,
+	};
+
+	size_t_and_error ret = ihex_decoder_writev(&dec, &((struct iovec){
+				.iov_base = input,
+				.iov_len = strlen(input),
+			}), 1);
+	fmt_print(fmt_stdout,
+	          "ret = (", ret.size_t, ", ", (error, ret.err), ")\n",
+	          "cnt = ", cnt, "\n");
+	test_assert(ret.size_t == strlen(input));
+	test_assert(ERROR_IS_NULL(ret.err));
+	test_assert(cnt == 6);
+
+	return 0;
+}