What You Will Learn

Prerequisites

Why NAND Is Different

Unlike an SD card, which presents a clean block-device abstraction to whoever’s using it, raw NAND flash exposes
its physical quirks directly to the software talking to it. Two properties matter most for boot images:

• Erase granularity — NAND can only be erased in large blocks (commonly 128KB-256KB), even though it can be programmed in much smaller pages. You cannot overwrite existing data directly; the containing block must be erased first.
• Bit errors and bad blocks — NAND cells wear out and occasionally flip bits even on healthy blocks, so error-correcting code (ECC) is applied on every write and checked on every read, and blocks that fail permanently get marked bad and skipped.

Enabling ECC

Before writing anything meaningful, make sure hardware or software ECC is active — writing without it risks
silent corruption that only surfaces later as a boot failure:

U-Boot# nandecc hw

Most modern SoCs implement ECC in a hardware NAND controller, so hw is typically correct; older or
simpler controllers may require U-Boot’s software ECC implementation instead.

Erasing a Region

Erase takes an offset and a size, both interpreted in the NAND’s own address space, not the RAM address space:

U-Boot# nand erase 0x280000 0x600000

NAND erase: device 0 offset 0x280000, size 0x600000
Erasing at 0x860000 -- 100% complete.
OK

The size must be a multiple of the NAND’s erase block size, and both offset and size are typically given in hex.
It’s common practice to erase a region somewhat larger than the current image, leaving headroom for the image to
grow across future builds without needing a layout change.

Writing the Image

With the target region freshly erased, write the image already sitting in RAM out to NAND:

U-Boot# nand write ${ep_kernel_addr} 0x280000 0x600000

NAND write: device 0 offset 0x280000, size 0x600000
6291456 bytes written: OK

Note that the write size here is the full erased region, not just the actual image size — U-Boot pads the
remainder, which is one reason the earlier erase size should comfortably exceed the image’s actual byte count.

Reading It Back

To boot from this image later (or just to verify the write immediately), read it from NAND back into RAM:

U-Boot# nand read ${ep_kernel_addr} 0x280000 0x600000

NAND read: device 0 offset 0x280000, size 0x600000
6291456 bytes read: OK
U-Boot# iminfo ${ep_kernel_addr}

Running iminfo right after a NAND write-then-read cycle is the fastest way to confirm the image
survived the round trip intact, using the same header checksum mechanism covered in the mkimage lecture.

Planning a NAND Layout

A board’s NAND is normally divided into fixed regions at design time — one for U-Boot itself, one for its
environment (often duplicated, as covered in the environment variables lecture), one for the kernel image, and one
for the root filesystem. These offsets get baked into both the board’s U-Boot configuration and its Linux MTD
partition table, so the two must always agree:

These offsets are illustrative — always confirm the actual layout from your board’s device tree or U-Boot config
rather than assuming.

Common Mistakes and Troubleshooting

Best Practices

• Never power-cycle a board mid-erase or mid-write — NAND operations are not safely interruptible.
• Leave headroom in your erase size for image growth across builds.
• Keep U-Boot itself and the environment in a separate, rarely-touched region from the kernel/rootfs you iterate on.
• Always verify with iminfo immediately after writing, while the board is still up and easy to recover.

Performance Considerations

NAND erase is significantly slower than write, which is itself slower than read — a full chip erase can take
tens of seconds, so erasing only the region you actually need (rather than the whole device) matters for iteration
speed during development.

Summary and Key Takeaways

• NAND requires erase-before-write, and erases operate on whole blocks, not arbitrary byte ranges.
• nandecc hw, nand erase, nand write, and nand read form the core workflow.
• Bad block handling is automatic but should never be disabled.
• NAND layout must stay consistent between U-Boot’s configuration and Linux’s MTD partition table.

Conclusion

With a kernel image safely written to NAND and verified, everything is finally in place to actually start Linux.
The last lecture in this chapter of our free linux device drivers course covers the command that
does exactly that — bootm.

FAQ