help-uboot: say what the layout macro is for, and that serial needs it too

[openipc-ai]

A full image carries the bootloader, and the bootloader's compiled-in default is the 8MB partition map. The 16MB map is a separate macro, and it does not merely lengthen the rootfs — it moves it:

mtdparts        = ...,2048k(kernel),5120k(rootfs),...    -> rootfs at 0x250000
mtdpartsnor16m  = ...,3072k(kernel),10240k(rootfs),...   -> rootfs at 0x350000

openipc.org builds its 16MB images to the second one, so skipping the macro leaves the kernel looking at 0x250000, finding erased flash, and panicking on root mount every 20 seconds. The kernel itself starts either way — it sits at 0x50000 in both maps — so the camera looks like it is booting right up to the panic.

What changed

The step now has a section of its own, with the symptom quoted, so it is findable by the panic and not only readable in order. The page did already say to run setnor16m — as one trailing sentence after the 16MB example, with no reason given and no mention of setnor8m or setnand. The reporter in OpenIPC/firmware#2381 hit the panic regardless, having been given the flash commands by hand; they had a bricked Hi3516CV300, got as far as a correctly written 16MB chip, and then a boot loop.

The serial full-image section did not mention it at all — and ended after sf write with no reset either. Same full image, same default, same panic. Both sections now point at the new one.

-nor- added to the two TFTP example filenames. openipc.org serves openipc-<soc>-nor-<release>-<size>mb.bin; the examples read openipc-${soc}-lite-8mb.bin, so a reader copying either line got a TFTP failure rather than an image.

Scope

Several other pages carry the older filename shape, some of them for FPV images that come from OpenIPC/builder rather than the site generator, and I have not verified how those are named. They are left alone rather than swept on an assumption — worth someone checking separately.

Testing

Documentation only. Verified the two claims against the sources rather than from memory:

• openipc/u-boot-hi3516cv200, include/configs/hi-common.h — the compiled-in mtdparts is the 8MB map, and setnor16m=run mtdpartsnor16m; setenv bootcmd ${bootcmdnor}; saveenv; reset, which is why nothing needs typing after it.
• openipc/website, app/models/flash_layout.rb — NOR[16] assembles with rootfs_offset: 0x350000, and its own comment notes that flashing a full image leaves the environment on the 8MB default.

The filename shape is Firmware.filename_for in the same repository, and matches the name the reporter downloaded successfully in the issue.

As with #517: this repository has no workflows, and its cspell.yaml is inert — the markdown ignoreRegExpList includes /[A-Z]*/g, which matches an empty string everywhere, so a deliberate misspelling in prose goes unreported. Nothing here spell-checks.

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

PR Summary by Qodo

Clarify U-Boot layout selection after full-image flashing

📝 Documentation 🐞 Bug fix 🕐 10-20 Minutes

AI Description

• Explain why full-image flashing requires selecting the matching U-Boot partition layout.
• Link serial and TFTP workflows to searchable layout recovery guidance.
• Correct NOR firmware filenames and reset devices after serial flashing.

Diagram

graph TD
  Serial["Serial Upload"] --> Flash["Write Full Image"] --> Reset["Reset Device"] --> Interrupt["Interrupt Boot"] --> Choice{"Flash Layout"} --> Macro["Run Layout Macro"] --> Boot["Boot Rootfs"]
  TFTP["TFTP Download"] --> Flash

Loading

High-Level Assessment

The shared layout section is the best approach because both serial and TFTP flashing require identical post-flash configuration. Duplicating the explanation in each workflow was considered but would reduce discoverability and risk documentation drift.

Files changed (1) +47 / -4

Other (1) +47 / -4

help-uboot.mdDocument required partition-layout selection after full-image flashing +47/-4

Document required partition-layout selection after full-image flashing

• Adds reset and partition-layout instructions to the serial workflow, corrects TFTP examples to use served NOR filenames, and replaces the brief 16MB note with searchable troubleshooting guidance. The new section explains rootfs offsets, panic symptoms, and the setnor8m, setnor16m, and setnand macros.

en/help-uboot.md

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

Code Review by Qodo

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

Great, no issues found!

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

Tip of the day

💡 Did you know, you can tweak Display preferences with a live preview to see your comment before it ships

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗