Programming the QSPI Flash Through U-Boot or Linux¶

The QSPI NOR flash on the MitySOM-A5E and MitySBC-A5E holds the FPGA periphery bitstream and U-Boot SPL: everything the module needs to start the HPS before it can reach the microSD card or eMMC. It is normally programmed over JTAG, but the board can write it itself, from either the U-Boot prompt or Linux.

You will need the a5e_hps_auto.sof and a5e.core.rbf from the FPGA build you are installing, and a host with Quartus for step 1.

Before you start: there is no second boot source and no fallback image on these modules, so a bad write leaves a board that prints nothing at all and can only be recovered over JTAG. Do not cut power during the write. Keep a programmer within reach the first time you do this on a given board.

1. Create the flash image¶

Quartus writes programming data least significant bit first and a NOR flash needs the opposite, so the image must be produced with bitswap=ON. Ask for the .rpd as a second output of the command that makes the .jic:

$ quartus_pfg -c -o hps=on -o device=MT25QU256 -o mode=ASX4 -o bitswap=ON \
      -o flash_loader={QUARTUS_DEVICE} a5e_hps_auto.sof a5e.jic a5e.hps.rpd

{QUARTUS_DEVICE} is a placeholder for your module's FPGA part number, which differs from module to module. Read it out of the SOF you are converting:

$ quartus_pfg -i a5e_hps_auto.sof
==================================================
General
==================================================
Device name: A5ED065BB32AI4S

bitswap=ON changes only the .rpd, so the .jic beside it still programs over JTAG as usual.

The command writes three files: a5e.hps.jic, a5e.core.rbf and a5e.hps.rpd.

Check the file before writing it. An image in the wrong bit order verifies perfectly against itself and then does not boot, with no error reported anywhere.

$ xxd -l 4 a5e.hps.rpd
00000000: 9548 2962                                .H)b

The first four bytes must be 9548 2962. A file starting a912 9446 is the same image with bitswap left off.

2. Copy the FPGA core image to the board¶

/lib/firmware/a5e.core.rbf holds the fabric image that is loaded against the periphery bitstream at every boot. Both come from the same build and have to be replaced together, so copy it across before writing the flash:

$ scp a5e.core.rbf root@BOARD:/usr/lib/firmware/a5e.core.rbf

If the board is not running, take the microSD card out and copy the file into /usr/lib/firmware/ on its root filesystem partition instead.

Skip this and the next boot stops at the U-Boot prompt with *** FPGA configuration failed, not continuing the boot ***. That is recoverable rather than a brick, but it costs a trip to the console. If the release notes also call for a new u-boot.itb or boot.scr, put those on the FAT partition now as well.

3. Write the flash image¶

Either route below gives the same result. Use Linux if the board is running; use U-Boot if it will not boot that far.

From Linux¶

Copy the image to the board, check it arrived intact, and write it. flashcp erases, writes and verifies in one step, and -A erases the whole device so nothing from a previous, longer image is left behind.

root@mity-a5e:~# cat /proc/mtd
dev:    size   erasesize  name
mtd0: 02000000 00010000 "u-boot" 
root@mity-a5e:~# md5sum /tmp/a5e.hps.rpd
4ff31d6b58e2b6ee951b62d27854065d  /tmp/a5e.hps.rpd
root@mity-a5e:~# flashcp -A -v /tmp/a5e.hps.rpd /dev/mtd0
Erasing blocks: 512/512 (100%)
Writing data: 2432k/2432k (100%)
Verifying data: 2432k/2432k (100%)

Compare that md5 against the file on your host before writing. Your value will differ from the example.

Notes and Tips

• An empty /proc/mtd with no /dev/mtd0 means QSPI is not enabled in the running device tree. Install the kernel and device trees from the latest release, where the MitySOM-A5E, MitySOM-A5E Mini and MitySBC-A5E development kit device trees enable it. A custom carrier device tree needs &qspi { status = "okay"; };.

From the U-Boot prompt¶

Copy a5e.hps.rpd onto the FAT partition of the microSD card, power on, and press any key to stop the autoboot countdown. Erasing is safe here because U-Boot is already running from DDR, and its environment lives on the FAT partition rather than in QSPI.

MITYSOM_A5E # sf probe
SF: Detected n25q256ax1 with page size 256 Bytes, erase size 64 KiB, total 32 MiB
MITYSOM_A5E # load mmc 0:1 0x90000000 a5e.hps.rpd
2490368 bytes read in 115 ms (20.7 MiB/s)
MITYSOM_A5E # md.b 0x90000000 4
90000000: 95 48 29 62                                      .H)b

0x90000000 is a scratch address clear of U-Boot's own. Both checks matter: load must report the size of the file, and md.b must show the same four bytes as step 1. If load fails, the previous ${filesize} is still in the environment and the next command would write whatever happens to be at 0x90000000.

MITYSOM_A5E # sf erase 0 0x2000000
SF: 33554432 bytes @ 0x0 Erased: OK
MITYSOM_A5E # sf update 0x90000000 0 ${filesize}
device 0 offset 0x0, size 0x260000
2228224 bytes written, 262144 bytes skipped in 2.341s, speed 1087478 B/s

Erasing the whole device takes about four seconds and is safe, because the flash holds nothing but this image. sf update skips blocks that already match, so the byte counts do not add up to the file size; that is normal.

Read the image back and compare it against what was written:

MITYSOM_A5E # sf read 0x92000000 0 ${filesize}
device 0 offset 0x0, size 0x260000
SF: 2490368 bytes @ 0x0 Read: OK
MITYSOM_A5E # cmp.b 0x90000000 0x92000000 ${filesize}
Total of 2490368 byte(s) were the same

Notes and Tips

• The image can come over the network instead of the card: dhcp, then setenv serverip to your host's address, then tftpboot 0x90000000 a5e.hps.rpd. Set serverip after dhcp, which overwrites it with the address of the DHCP server.
• sf probe reporting Invalid bus 0 (err=-19) means the U-Boot build predates QSPI support. Use the Linux route, or update u-boot.itb first.

4. Power cycle and check¶

Power cycle the board. A warm reset from U-Boot does reload the new image from flash, but a cold boot is the path the board takes in the field and is what proves it comes up unattended. The SPL banner carries the build string of the image you just wrote.

U-Boot SPL 2026.01-g0adb56f13c87 (Aug 09 2026 - 22:12:18 +0000)
...
.FPGA reconfiguration OK!
...
mity-a5e login:

A completely silent console means the image was rejected and the HPS never started. Recover over JTAG:

$ quartus_pgm -c 1 -m jtag -o "piv;a5e.hps.jic@1" 

Notes and Tips

• In that command -c 1 is the cable number, and the number appended to the file name is the device's position in the JTAG chain. Read jtagconfig output rather than assuming either.
• QSPI access needs the 20260809 release or later, but only on the side you are using: its U-Boot for the sf commands, or its kernel and device trees for /dev/mtd0. Earlier releases do not enable the QSPI node.