diff options
Diffstat (limited to 'cmd/sbc_harness/static/Documentation')
| -rw-r--r-- | cmd/sbc_harness/static/Documentation/harness_flash_bin.txt | 24 | ||||
| -rw-r--r-- | cmd/sbc_harness/static/Documentation/harness_uptime_txt.txt | 22 |
2 files changed, 33 insertions, 13 deletions
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/static/Documentation/harness_uptime_txt.txt b/cmd/sbc_harness/static/Documentation/harness_uptime_txt.txt index 1ab86f7..09e9243 100644 --- a/cmd/sbc_harness/static/Documentation/harness_uptime_txt.txt +++ b/cmd/sbc_harness/static/Documentation/harness_uptime_txt.txt @@ -3,14 +3,24 @@ NAME DESCRIPTION Reading this file gives a text string of the format - `sprintf("%uns\n", uptime_ns)` indicating the harness's uptime - in an integer number of nanoseconds. + + {ns}ns + [[[[{y}y]{d}d ]{h}h]{m}m]{s.09}s + + That is: the first line is simply the harness's uptime in an + integer number of nanoseconds; and the second line is this + same number in a more human-readable form; divided into + seconds, minutes, hours, days, and years. BUGS - Using nanoseconds gives the illusion of more precision than - there actually is; the harness' clock only has microsecond - resolution; the last 3 digits of the returned nanosecond count - will always be 0. + - Using nanoseconds gives the illusion of more precision than + there actually is; the harness' clock only has microsecond + resolution; the last 3 digits of the returned nanosecond + count will always be 0. + + - In the human-readable form, the days are always exactly + 60*60*24 seconds (leap seconds are ignored), and the years + are always exactly 365 days (leap years are ignored). AUTHOR Copyright (C) 2025 Luke T. Shumaker <lukeshu@lukeshu.com> |