docs: make the README's counts and claims match the tree - #91
Merged
Conversation
Everything the README documents was re-run against the tree. The build and test commands work verbatim, including the note that EOS_PRODUCT=vbox_test is required for the OTA, sensor, motor and power cases — that is correct and was worth confirming rather than assuming. Three counts were stale: 83 boards is 84, "~40 product profiles" is 48. The board line needed more than a number. "carries descriptors for 84 boards" reads as 84 supported boards, and 71 of the 84 are named generic-*. The sentence now says a descriptor is not a port and that none has been validated on hardware, which is what STATUS.md records. Added a Status section, because the README had no maturity signal at all and a reader had no way to learn the two things that most change how they would use this: - Networking is Planned. net/ is an API with a POSIX backend for host builds; there is no IP stack for bare-metal targets and eos_net_connect() returns -1 there. ADR-014 records lwIP as the decision. - RSA and ECC signature verification is Planned. Those routines are stubs and refuse to run without EOS_ALLOW_STUB_CRYPTO. AES, SHA-256 and SHA-512 are implemented and pass NIST vectors, so the distinction matters. Also states plainly that nothing has been observed to boot on hardware, and that no latency, throughput or power figure is published because no reproducible benchmark exists to link to — §25 requires the link, and the absence of numbers is easier to misread than their presence. Added the cross-compiling section. It works and was undocumented: three of the six toolchain files build clean and produce armv7e-m and armv7 objects, and the full library set measures 15.8 KB flash and 26.0 KB RAM on Cortex-M4 via arm-none-eabi-size -t. RISC-V and AArch64 are named as unverified rather than listed alongside the three that work. Verified: every count re-counted from the tree; both documented test commands run (ctest 30/30, run_all_tests.py 10 passed); the new cross-compile block run verbatim with 0 build errors. Depends on #88 for STATUS.md, which this links twice. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Everything the README documents was re-run against the tree. The build and test commands work verbatim — including the note that
EOS_PRODUCT=vbox_testis required for the OTA, sensor, motor and power cases, which is correct and worth confirming rather than assuming.Stale counts
The board line needed more than a number
That reads as 83 supported boards. 71 of the 84 are named
generic-*. The sentence now says a descriptor is not a port and that none has been validated on hardware — which is whatSTATUS.mdrecords.Added a Status section
The README had no maturity signal at all. A reader had no way to learn the two things that most change how they'd use this:
Planned.net/is an API with a POSIX backend for host builds; there's no IP stack for bare-metal targets andeos_net_connect()returns-1there. ADR-014 records lwIP as the decision.Planned. Those routines are stubs and refuse to run withoutEOS_ALLOW_STUB_CRYPTO. AES, SHA-256 and SHA-512 are implemented and pass NIST vectors — the distinction matters.It also states plainly that nothing has been observed to boot on hardware, and that no latency/throughput/power figure is published because no reproducible benchmark exists to link to. §25 requires the link, and the absence of numbers is easier to misread than their presence.
Added cross-compiling
It works and was undocumented. Three of the six toolchain files build clean and produce
armv7e-mandarmv7objects; the full library set measures 15.8 KB flash / 26.0 KB RAM on Cortex-M4. RISC-V and AArch64 are named as unverified rather than listed alongside the three that work.Verification
Every count re-counted from the tree. Both documented test commands run —
ctest30/30,run_all_tests.py10 passed. The new cross-compile block run verbatim: 0 build errors.Depends on #88 for
STATUS.md, which this links twice.🤖 Generated with Claude Code