Efuse logical-map override: end-user loadable patch file (RAM-only)

Open
#284 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Quiet
Tech stack
c, json
Domain
embedded-iot

Research direction

Start with the four materialization sites named in the issue: src/jaguar1/EepromManager.cpp, src/jaguar2/HalJaguar2.cpp, and both variant paths in src/jaguar3/HalJaguar3.cpp; also inspect examples/common/env_config.cpp and the existing replay_wseq handling. Begin by establishing machine-readable logical-map dumps and headless tests, then cover sparse patch parsing, each generation’s apply point, and the 8814A late re-read. Done means tests cover ID behavior and reapplication, and diagnostics make overrides visible; the issue also calls for hardware validation.

Written by the indexing model from the issue text.

Description

enhancement

Motivation

The efuse logical map is the root of almost every per-adapter parameter we consume: MAC, xtal cap, thermal baseline, RFE type, PA/LNA types, per-channel TX-power PG base. Today it is read-only and invisible except for the stderr DEVOURER_EFUSE_DUMP text (Jaguar2/3 only). A RAM-only override lets us:

  • test "what would this adapter do with rfe_type=N / xtal=M" without touching hardware state,
  • resurrect adapters with corrupted efuse (force the autoload-OK ID, supply a sane map),
  • act as the validation harness for physical efuse programming (see follow-up issue): dump → edit → run with override → validate on-air → only then burn.

Shape

A sparse patch file applied after logical-map materialization, before field parsing.

  • DeviceConfig::Debug::efuse_override (path, std::optional<std::string>), env-mapped as DEVOURER_EFUSE_OVERRIDE in examples/common/env_config.cpp — same pattern as replay_wseq, which is the existing precedent for a library-loaded file path.
  • Grammar: 0xCA=0x04 single bytes, 0x22:8=xxxxxxxxxxxxxxxx runs. A full-map binary replace can be a second, explicitly named mode later — it must not be the default (a full dump from adapter X replayed on adapter Y silently clobbers Y's calibration).
  • The patch parser and the apply helper are generation-neutral pure functions → live in src/ next to PhyTableLoader, unit-testable headlessly (ctest).

Implementation details / hazards

  1. Four materialization sites, not one. Jaguar1 decodes into efuse_eeprom_data (src/jaguar1/EepromManager.cpp:1382), Jaguar2 into _efuse_map (src/jaguar2/HalJaguar2.cpp:305), Jaguar3 has two variant paths — 8822C standard walk and 8822E packed 2-byte headers into a one-shot cache (src/jaguar3/HalJaguar3.cpp:621-719). One shared apply_efuse_override(map, len) called at each site.
  2. 8814A re-reads efuse after FW download (LateInitFor8814A, src/jaguar1/EepromManager.cpp:89). The override must re-apply on that second read or the 8814 silently loses the patch. Needs a dedicated test.
  3. 8822E PA bias bypasses the logical map — it reads physical addresses 0x5c5–0x5c8 during the power-cut bracket (src/jaguar3/HalJaguar3.cpp:580). A logical override cannot affect it. v1: document the hole; a phys: patch plane doubles the surface and is not worth it yet.
  4. Autoload/ID semantics cut both ways. Jaguar1 gates on ID 0x8129 at offset 0x00 (Hal_EfuseParseIDCode8812A). A wrong override flips the device into autoload-fail defaults; forcing it right is how you resurrect a corrupt-efuse adapter. Both directions need tests.
  5. Dump tooling is a prerequisite. You cannot author an override without a dump in the same grammar. Extend DEVOURER_EFUSE_DUMP to emit a machine-readable logical map on all three generations (JSONL efuse.map event or file) — today it is stderr text and Jaguar2/3 only; Jaguar1 only has the physical ReadPhysicalEfuseMap health probe.
  6. Footgun visibility. One-shot W diagnostic diffing every overridden byte + an efuse.override JSONL event, so test scripts can assert the patch took effect and nobody benchmarks on doctored calibration without noticing.

Suggested milestones

  1. Machine-readable logical-map dump, all generations (efuse.map event).
  2. Sparse-patch parser + apply_efuse_override in src/, headless selftests.
  3. Wire into the four materialization sites (incl. the 8814A late re-read) + efuse.override event.
  4. Hardware validation: override rfe_type / xtal on a bench adapter, confirm the parsed-field logs and on-air behavior follow.
Dominant language
C
Stars
56
Forks
29
Avg merge
3h 43m
Merged PRs (30d)
75

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OpenIPC/devourer

All issues in OpenIPC/devourer

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.