aen-eeprom-provision
Write the 128-byte Alp hardware-info manifest into the on-module 24C128 EEPROM on an E1M-AEN SoM, then read it back and verify. The write sibling of aen-eeprom-manifest, which reads the same bytes.
Source: examples/aen/aen-eeprom-provision/. New in alp-sdk v0.17.0.
This is the step that gives a module its identity — SKU, hardware revision, serial and manufacturing date — run once per unit on the production line. Modules ship already provisioned. It is published because it is the only SDK path that writes a manifest, and because it shows the EEPROM write rules any re-provisioning must follow.
- The array manifest at
0x50is rewritable — a wrong one is a re-run. - The Secure Data Page lock (the optional second step below) is permanent. After it, every write to that page NAKs at the hardware level; there is no unlock.
- Do this before anything that burns a fuse: the CC3501E's root-of-trust and MAC fuses are one-time and OR-only — a mistake there scraps the part.
What it does
- Takes a manifest blob packed on the host by
scripts/program_eeprom.pyand baked into the image at build time (-DALP_MANIFEST_BIN=...). - Opens the EEPROM over SoC I²C2 — the same bus the reader uses, not
BRD_I2C— via the upstream DesignWarei2c_dwdriver. - Writes the 128 bytes with
eeprom_24c128_write(). The 24C128 has 64-byte pages, so that is two page writes with an internal write cycle between them; the driver handles the split and ACK-polling. A bare 128-byte I²C write would silently wrap inside one page and corrupt the manifest. - Reads it back and verifies it on the device.
It runs as a RAM-run over SWD (bench Flow C). Nothing is written to MRAM, so the module is left carrying whatever application the line intends — not this tool.
Two refusals, both deliberate
- The build fails without
-DALP_MANIFEST_BIN. There is no default blob: a placeholder identity written onto a module is indistinguishable from a real one later. - It will not overwrite an existing valid manifest. Replacing one silently orphans the serial someone recorded. Re-provisioning (a mis-programmed unit, a schema migration) must be deliberate:
-DALP_PROVISION_FORCE=1, with the reason in the unit's record.
board.yaml
som:
sku: E1M-AEN801
preset: e1m-evk
cores:
a32_cluster:
os: "off"
m55_he:
app: ./src
peripherals:
- i2c
chips:
- eeprom_24c128 # on-module Alp manifest EEPROM @ 0x50.
diagnostics:
log_level: info
Run it
# 1. Pack this unit's identity on the host. The serial comes from the
# allocation ledger, not from your head.
python3 scripts/program_eeprom.py \
--board-yaml examples/aen/aen-eeprom-provision/board.yaml \
--serial <SERIAL> \
--mfg-date <MFG-DATE> \
--output /tmp/manifest-<SERIAL>.bin
# 2. Build ITCM-linked, with that blob baked in.
B=scripts/bench/aen
bash $B/build.sh "$PWD/examples/aen/aen-eeprom-provision" \
-DALP_MANIFEST_BIN=/tmp/manifest-<SERIAL>.bin \
"-DEXTRA_CONF_FILE=$PWD/$B/aen-bench-shared.conf;$PWD/$B/aen-flowc-itcm.conf" \
"-DEXTRA_DTC_OVERLAY_FILE=$PWD/$B/aen-flowc-itcm.overlay"
# 3. Write it (RAM-run over J-Link).
bash $B/ram-run.sh "$PWD/build/aen-eeprom-provision"
<SERIAL> and <MFG-DATE> are placeholders on purpose — a worked example is not a provisioning record.
Expected output
On a blank module:
[provision] to write: family=aen sku=E1M-AEN801 hw_rev=r2 serial=<SERIAL> mfg=<MFG-DATE>
[provision] wrote 128 bytes at offset 0
[provision] verified on device: family=aen sku=E1M-AEN801 hw_rev=r2 serial=<SERIAL> mfg=<MFG-DATE>
RESULT PASS: manifest written and verified on device
Verify independently with the reader, aen-eeprom-manifest — a different binary on a different code path is the stronger check. Any later build's boot banner then prints the real identity (E1M-AEN801 r2) instead of the board name.
Secure Data Page mirror + lock (optional, later, irreversible)
The same EEPROM answers a second I²C address, 0x58 — the same physical part, not a second chip. Selector 0x00 there is a 64-byte Secure Data Page that can be permanently locked. The app carries the write + lock tooling for it as two further build-time modes, run only after the array manifest is written and verified and the board has been cold power-cycled:
- Build the 64-byte mirror blob with
scripts/program_eeprom_secure_page.py, then build and RAM-run with-DALP_SECURE_PAGE_BIN=...— this writes the page and verifies the read-back in the same run. It never locks. - Cold-power-cycle the board (a RAM-run cannot prove anything survived a power cycle it never experienced).
- Lock, with both
-DALP_LOCK_SECURE_PAGE=1and-DALP_SECURE_PAGE_COLD_CYCLED=1. The second flag is your attestation that step 2 happened — nothing inside a RAM-run can observe the power rail, so set it only when the rail was confirmed at 0.0 V and record that in the run log.
Before it locks, the app refuses if: the cold-cycle attestation is missing; the blob fails its own magic / schema / CRC check; 0x58 does not answer; the page is already locked and differs from the blob; the page on the device is not byte-exact against the blob or does not parse as a mirror; or the array manifest at 0x50 disagrees with the mirror on SKU, hw_rev, serial or manufacturing date (the message names the field and both values). After the lock it re-reads Lock Status and the page, and prints PASS only if the lock bit is confirmed and the payload still matches.
On a board fitted with the footprint-compatible alternate EEPROM, M24128-BFMH6TG, which has no second device-select header, both Secure-Data-Page modes fail cleanly without touching anything; the array manifest is unaffected, and nothing in the SDK's runtime read path depends on the mirror.
Known gap: no manufacturer field
The manifest schema (<alp/hw_info.h>) carries family, sku, hw_rev, serial and the manufacturing date, but no manufacturer. Adding one needs a schema_version bump, and alp_hw_info_classify_manifest() rejects schema_version != 1 as ALP_ERR_IO — so a v2 module would read as a corrupt EEPROM to any v1-built firmware.
See also
aen-eeprom-manifest— the read sibling<alp/hw_info.h>- E1M-AEN — boot + identification