Skip to content

axera-spi-nor: env-from-flash, for firmware that keeps its own U-Boot env - #342

Merged
dimerr merged 1 commit into
masterfrom
axera-spi-nor-env-from-flash
Nov 18, 2026
Merged

dimerr merged 1 commit into
masterfrom
axera-spi-nor-env-from-flash

Conversation

@dimerr

@dimerr dimerr commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

The AX620E SPI-NOR model serves a synthetic U-Boot environment in place of the env window, which the stock Xiongmai dumps need to boot. OpenIPC's own firmware for the AX620E (OpenIPC/firmware#2670, OpenIPC U-Boot) writes its env with saveenv/fw_setenv and needs it back.

  • New property env-from-flash (off by default, so stock dumps boot exactly as before): -global axera-spi-nor.env-from-flash=on serves the flash file's own bytes in the env window.
  • docs/axera.md mentions it.

Used to boot OpenIPC's AX620E image end to end in QEMU (OpenIPC U-Boot → 5.15 kernel → rootfs from NOR, all vendor modules loaded); an env set with fw_setenv reaches the next boot's command line.

Known, not in this PR: the AX620U SPI-NAND model ends a page program on a write of the controller's chip-select register, while Linux and OpenIPC's U-Boot drive chip select through a GPIO; OpenIPC's AX620U U-Boot writes the register once per message, which works, but the model should follow the CS GPIO.

… env

The AX620E SPI-NOR model answers reads of the U-Boot env window with a
synthetic env (what the stock Xiongmai firmware needs to boot). OpenIPC
firmware, with its own U-Boot and 'fw_setenv', needs the env it wrote
to the flash file back. -global axera-spi-nor.env-from-flash=on serves
the flash contents there; off by default, so the stock dumps boot as
before. Used to boot OpenIPC's AX620E image (OpenIPC/firmware#2670).
@qodo-free-for-open-source-projects

qodo-free-for-open-source-projects Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

PR Summary by Qodo

Allow AX620E SPI-NOR to serve its U-Boot environment from flash

✨ Enhancement 📝 Documentation 🕐 Less than 10 minutes

Grey Divider

AI Description

• Add an opt-in SPI-NOR property that serves the flash image’s U-Boot environment to OpenIPC
 firmware.
• Preserve the synthetic environment by default so stock Xiongmai images continue to boot.
• Document the QEMU option and its intended use.
Merge Risk 🟢 Low

Blast radius 🟢 Low 💥 1 capability

  • 1 affected end-to-end capability after fault-specific containment; implementation boundaries do not widen its functional scope.
  • The changed read gate, the SPI-NOR device instantiated by the AXERA machine, and the guest U-Boot/fw_setenv behavior form one bounded flash-environment integration.
  • The flash read is an implementation hop; the affected end-to-end outcome is U-Boot consuming and updating its environment, not a separate storage capability.
Behavioral complexity 🟢 Low 🧩 Straightforward

  • Before: complete reads in the environment window used the synthetic environment whenever env_overridden was false.
  • After: the same established branch also requires env_from_flash to be false, with a boolean property defaulting to false.
  • New correctness condition: when explicitly activated, the selected flash image must contain the environment intended for the guest.
  • No new algorithm, concurrent protocol, migration, precedence interaction, or coordinated invariant is introduced; the change is a direct gate over an existing transformation and preserves the existing write-triggered override behavior.
Potential damage 🟡 Medium 🩹 Temporary loss

  • An incompatible flash environment can produce incorrect boot configuration or prevent the intended guest boot, which is a loss of the configured boot capability rather than evidence of data loss or a serious integrity consequence.
  • Recovery requires a valid environment in the flash image, disabling the opt-in property to restore the synthetic environment, or manually repairing/replacing the environment; reverting QEMU code alone does not repair a flash environment that was already written.
  • The equal-importance baseline is used because no business-criticality declaration was supplied.
  • Recoverable by selecting the default synthetic environment, supplying a valid flash environment, or manually repairing the guest environment.
  • The source does not establish automatic repair or persistence of the in-memory modified flash image back to the host file.
Assessed commit d5749fd
Diagram

graph TD
  O["QEMU option"] --> D{"Use flash env?"} -->|yes| F["Flash bytes"] --> U["U-Boot env"]
  R["NOR env read"] --> D -->|no| S["Synthetic env"] --> U
Loading
High-Level Assessment

The opt-in property is appropriate: always serving flash bytes would break the stated stock-firmware requirement, while automatic detection could mistake a valid but unsuitable stock environment for a usable one. The existing read path already handles both sources, so no broader architectural change is needed.

Files changed (2) +9 / -1

Enhancement (1) +4 / -1
axera-spi-nor.cAdd opt-in flash-backed environment reads +4/-1

Add opt-in flash-backed environment reads

• Adds the default-off env-from-flash device property. When enabled, environment-window reads bypass synthetic environment generation and use the existing flash-byte read path; the default behavior remains unchanged.

qemu/hw/misc/axera-spi-nor.c

Documentation (1) +5 / -0
axera.mdDocument the OpenIPC environment option +5/-0

Document the OpenIPC environment option

• Explains that AX620E serves a synthetic U-Boot environment by default and shows the QEMU option for serving the flash image’s environment instead.

docs/axera.md

@qodo-free-for-open-source-projects

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Grey Divider

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Grey Divider

Tip of the day
💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

@dimerr
dimerr merged commit 744a809 into master Nov 18, 2026
56 checks passed
@dimerr
dimerr deleted the axera-spi-nor-env-from-flash branch November 18, 2026 19:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant