nand: one layout, the kernel inside the root filesystem

[widgetii]

Rewrites en/nand-rootfs-layouts.md for the NAND layout the u-boot-xmedia SoCs now use: GK7205V500/V510/V530, Hi3516EV200/EV300/DV200 and Hi3518EV300. The table-of-contents entry becomes "NAND flash layouts".

The layout

• One UBI device from 1 MiB.
• A UBIFS root filesystem with the kernel inside as /boot/fitImage, hashed and checked by U-Boot.
• rootfs_data for the settings.
• No flash is set aside for a kernel. Both volumes are sized by their images.

What the page covers

• How to tell which layout a camera runs.
• sysupgrade:
  • the settings are copied out, the volumes rebuilt around the new image, and the settings restored;
  • otherwise the run stops with nothing written, and -r -n upgrades without the settings;
  • what a power cut costs.
• Installing from U-Boot:
  • nand erase.part ubi, so any chip size is erased fully;
  • nand write.trimffs, and why (#2519).
• The bootloader:
  • what it boots;
  • what it does with an environment saved by an earlier one, and that it waits until the new layout is on the flash.
• Retired layouts:
  • the split one, squashfs over ubiblock on these SoCs, and the first FIT layout with a kernel volume, which are reinstalled rather than upgraded;
  • the SoCs that no longer get NAND builds.
• Building a NAND package: the existing section stays, with its table and size limits updated.

Matches OpenIPC/u-boot-xmedia#11 and #12, OpenIPC/firmware#2537, OpenIPC/website#392 and #393, and OpenIPC/defib#147.

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Document the unified NAND layout with the kernel in rootfs

📝 Documentation 🕐 20-40 Minutes

AI Description

• Document the unified UBIFS NAND layout, with a verified kernel inside the root filesystem.
• Explain upgrades, installation, recovery risks, and migration from retired layouts.
• Update NAND package size limits and rename the wiki navigation entry.

Diagram

graph TD
  PKG["NAND package"] --> UP["sysupgrade"] --> UBI[("UBI device")] --> ROOT["UBIFS rootfs"] --> FIT["FIT kernel"]
  UBI --> DATA["Settings overlay"]
  UP -->|restores| DATA
  BOOT["U-Boot"] -->|loads and verifies| FIT

Loading

High-Level Assessment

A single current-layout guide with retired layouts identified separately is appropriate: keeping obsolete installation paths alongside current commands would make a risky flash procedure harder to follow. The PR changes documentation only and reflects the described bootloader and firmware behavior.

Files changed (2) +162 / -245

Documentation (2) +162 / -245

README.mdRename the NAND guide in the table of contents +1/-1

Rename the NAND guide in the table of contents

• Changes the navigation label to “NAND flash layouts” so it matches the guide’s new scope.

README.md

nand-rootfs-layouts.mdRewrite NAND guidance for the kernel-in-rootfs layout +161/-244

Rewrite NAND guidance for the kernel-in-rootfs layout

• Replaces the comparison of legacy layouts with the current u-boot-xmedia UBI layout, layout detection, sysupgrade behavior, U-Boot installation commands, and bootloader environment handling. Identifies layouts requiring reinstallation and updates NAND package contents and size limits while distinguishing other vendors’ layouts.

en/nand-rootfs-layouts.md

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. NAND installation can leave no image to boot 🐞 Bug ≡ Correctness

Description

The installation command puts tftpboot and nand write.trimffs ... ${filesize} on one U-Boot
line, so ${filesize} is expanded before the transfer sets it. When that value is empty or left
over from an earlier transfer, the command erases the UBI partition and then writes no image or the
wrong amount.

Code

en/nand-rootfs-layouts.md[112]

+tftpboot ${baseaddr} rootfs.ubi.<board> && nand erase.part ubi && nand write.trimffs ${baseaddr} 0x100000 ${filesize}

Evidence

The existing HiSilicon installation guide explicitly warns that joining a TFTP transfer and a write
using ${filesize} on one line expands the value too early; the new NAND command uses that pattern.

en/nand-rootfs-layouts.md[111-113]
en/install-hisi.md[119-122]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
U-Boot expands `${filesize}` before executing commands on the same line, so the UBI write cannot use the size set by the preceding transfer.
## Fix Focus Areas
- en/nand-rootfs-layouts.md[111-113]
## Recommended Fix
Put `tftpboot` on a separate command line before the erase and `nand write.trimffs` commands, so `${filesize}` is expanded after the transfer completes.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Readers get conflicting upgrade advice ✓ Resolved

Description

The NAND page says sysupgrade -r -n upgrades without settings, while the linked sysupgrade guide
says -n writes no firmware and only erases the overlay. Operators consulting both pages cannot
tell whether that combination flashes the image or merely resets settings when preservation fails.

Code

en/nand-rootfs-layouts.md[R91-92]

+written and the camera reboots as it was. `sysupgrade -r -n` upgrades without
+the settings.

Evidence

The new NAND instruction explicitly calls the combination an upgrade, whereas the existing guide
states without qualification that -n writes no firmware.

en/nand-rootfs-layouts.md[89-92]
en/sysupgrade.md[13-16]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The NAND page and the linked sysupgrade guide give incompatible descriptions of what `-n` does during an upgrade.
## Fix Focus Areas
- en/nand-rootfs-layouts.md[89-92]
- en/sysupgrade.md[15-16]
## Recommended Fix
Verify the behavior of `sysupgrade -r -n`, then make both pages distinguish `-n` alone from `-n` combined with an upgrade option, or correct the NAND command if it does not upgrade.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗