Skip to main content

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.

Know what is reversible before you run it
  • The array manifest at 0x50 is 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​

  1. Takes a manifest blob packed on the host by scripts/program_eeprom.py and baked into the image at build time (-DALP_MANIFEST_BIN=...).
  2. Opens the EEPROM over SoC I²C2 — the same bus the reader uses, not BRD_I2C — via the upstream DesignWare i2c_dw driver.
  3. 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.
  4. 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:

  1. 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.
  2. Cold-power-cycle the board (a RAM-run cannot prove anything survived a power cycle it never experienced).
  3. Lock, with both -DALP_LOCK_SECURE_PAGE=1 and -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​

Questions about this page? Email contact@alplab.ai