AR# 69765

Zynq UltraScale+ MPSoC: NAND Programming/Booting Checklist


This is a list of required items, necessary actions, and points to be considered, when debugging NAND programming and booting on Zynq UltraScale+ MPSoC.

Some UBIFS tips are included in this article.


Before opening a Service Request, collect all of the information requested below.

Requirements are italicized below.


1) Is the NAND flash and configuration supported by Xilinx?


See (Xilinx Answer 65463) to determine the support category (Supported, known to work, Unverified, or Incompatible).

Note: For NAND requirements, see (UG1085) chapter 25.

Linux kernels prior to 2019.1 do not support 8-bit on-die ECC for Micron NAND flash.

The comments below can be found in

            * Some Micron NANDs have an on-die ECC of 4/512, some other
            * 8/512. We only support the former.

Starting from Linux kernel 2019.1, 8-bit on-die ECC is supported for Micron NAND flash.

The comments below can be found in

            * We only support on-die ECC of 4/512 or 8/512

The Linux kernel does not support MICRON_ON_DIE_MANDATORY NAND flash which does not allow for disabling of the on-die ECC.

The comments below can be found in

            * Try to detect if the NAND support on-die ECC. To do this, we enable
            * the feature, and read back if it has been enabled as expected. We
            * also check if it can be disabled, because some Micron NANDs do not
            * allow disabling the on-die ECC and we don't support such NANDs for
            * now.

Important: Please provide the full flash name, the configuration mode and the voltage.

If the configuration is not "standard" (muxes, level shifters or other), provide also provide the board schematics.


2) Are the signals properly connected to the memory device?

The board needs to follow the instructions for NAND in (UG583).

To boot from NAND, MIO10 should be connected to ready/busy 0 of the NAND device.


Please provide a schematic of the NAND part and monitor the data signals on the board to verify what kind of words are read.


3) Is it Zynq Production Silicon?

Use XSCT to read:

  • the IDCODE from 0xFFCA0040
  • the PS_VERSION from 0xFFCA0044

Important: Please provide the IDCODE and PS_VERSION

4) Is the JTAG chain operating properly?

Use XSCT to try to connect to the CPU.

Below is a list of relevant Answer Records:

(Xilinx Answer 67740)XSDB (or any other JTAG user) needs to hold TMS signal high for 5 TCK cycles to enable PL TAP linking to the JTAG chain.
(Xilinx Answer 67818)2016.3 PMU firmware loading via JTAG / SD Boot Modes and Running An Example


Important: Please provide JTAG chain description (how many devices on the chain, how many ZynqMP, ZynqMP in cascade or independent JTAG, any level shifter in the chain). Report any XSCT error.

5) In which phase of booting Zynq is failing? BootROM or FSBL?

For Known Issues related to the FSBL and CSU Boot Rom, Please check (Xilinx Answer 65467)

In order to determine this, program an image with FSBL debug prints enabled.

To do this, include the following in xfsbl_debug.h


If some printing comes out on the UART during boot:

Please provide a log of the FSBL print out on the UART. FSBL is a user application and can be easily debugged using SDK. Try to do a brief investigation before filing a Service Request.

If nothing comes out on the UART during boot, first double check the UART baudrate.

Please provide the status of INIT_B, PS_ERROR_OUT, CSU_BR_ERROR and BOOT_MODE_POR registers after the boot failure.

An easy way to provide this register dump is to use the attached .tcl script (boot_registers_log_revX_Y.tcl)

If the boot image was not programmed properly, continue to step 5.

6) Are SDK and Vivado failing to program?


  • Vivado and SDK flash programmer use mini u-boot to program flash. NAND read/write was previously supported in u-boot, but was not updated in Vivado/SDK 2017.2 and previous versions.

    In Vivado/SDK 2017.3, the mini u-boot image will be updated. Please use Vivado/SDK 2017.3 and later versions to program NAND flash.

  • For debug purposes, the Debug Environmental Variable XIL_CSE_ZYNQ_DISPLAY_UBOOT_MESSAGES can be set to 1.
    See (Xilinx Answer 59272) for more details.

Please provide the version of the tool used. Ensure that your image was built with the same version of the tool as was used to program.

Please provide the boot mode settings used for programming (booting from JTAG is recommended).

Please provide the log obtained using the XIL_CSE_ZYNQ_DISPLAY_UBOOT_MESSAGES variable.

7) Is it working using u-boot?

For known issues related to u-boot, Please check (Xilinx Answer 65467)

You can use PetaLinux to generate the u-boot ELF. PetaLinux uses ZCU102 defconfig by default. NAND is not enabled in that configuration.

"CONFIG_CMD_NAND=y" and "CONFIG_NAND_ARASAN=y" should be set.

To do this, you can open u-boot menuconfig with the following command

petalinux-config -c u-boot

You can find the two parameters separately at the following menu locations:

"Command line interface > Device access commands > nand" and "Device Drivers > NAND Device Support > Configure Arasan Nand".

You can also use an open source flow to generate the u-boot elf by following the steps in

You need to set "CONFIG_CMD_NAND=y" and "CONFIG_NAND_ARASAN=y" in the selected defconfig file.

Download and run u-boot elf with xsct/xsdb according to the flow in (UG1209).

Use the below commands to test NAND flash.

nand info
nand erase 0 1000000
mw.b 1000000 a8 1000000
nand write 1000000 0 1000000
nand read 2000000 0 1000000
cmp.b 1000000 2000000 1000000

If the read data is the same as the data written, NAND read/write should be good.

Please provide the log of the programming. Specify the u-boot version used.

If u-boot is working, use xsct/xsdb and the u-boot nand write command to program the NAND flash with the desired BOOT.bin.

8) Is the board design to support the NAND frequency used for programming?

Please provide the register settings and the calculation done to verify the NAND clock frequency.

9) Is the Xilinx stand-alone example working?

NAND examples are provided under the SDK install directory \data\embeddedsw\XilinxProcessorIPLib\drivers\nandpsu_v1_x\examples

Some Debug is needed to understand where the example is failing (through the SDK debugger or by adding debug prints).


Report the type of failure in the Xilinx standalone example


UBIFS support for NAND flash

UBI is an abstraction layer that works on top of MTD raw flash devices.

It is worth noting that raw flash is not the typical pen-drive, memory card, or SSD but it is a flash chip without a FTL (Flash Translation Layer).

UBI is usually used as a supporting layer for the UBIFS filesystem.

It is a successor to JJFS2 which does not use a supporting layer like UBI but works directly on MTD devices.


In 2017.2, u-boot supports UBIFS for ondie-ECC NAND flash. For NAND flash without ondie-ECC, UBIFS will be supported in u-boot 2018.1.

To use UBIFS in u-boot, we need to enable UBI commands in u-boot configuration. To do this, we need run the following command to open u-boot configuration.

petalinux-config -c u-boot

Enable the UBI command at "Command Line interface > Enable UBI - Unsorted block images commands". Verify that UBI is also enabled at "Device Drivers > UBI support".

With UBIFS is configured in u-boot, PetaLinux 2017.2 fails to compile u-boot with a link error for the missing reference.

See (Xilinx Answer 69757) PetaLinux 2017.2 - PetaLinux fails to compile u-boot with link error after UBI command line is enabled.

Steps to create a UBIFS image at the host:

  1. Download "" "ubinize_s.cfg" "devtable.txt" "" and extract the target root.
  2. Now generate the UBI image at the host using the script Run it as ./
  3. Now, the UBI image will be created in the current directory. "rootfs_nand_s.ubi" is pre-built and ready for use.


u-boot commands to format, copy and mount ubifs:

setenv partition "nand0,3"
setenv mtdids "nand0=nand0.0"
setenv mtdparts "mtdparts=nand0.0:896k(boot),128k(env),7m(kernel),8m(rootfs)"

Note: Before running the below steps, as per the example here, download the image created above (rootfs_nand_s.ubi) to DDR at 0x100000.

nand erase 800000 800000
nand write 100000 800000 800000
ubi part rootfs
ubifsmount ubi0:myubifs

You can refer to uboot_ubifs.log for details of each step.

To verify if ubifs works well, you can load the file in ubifs to memory in u-boot and compare with its source file.


In 2017.2, PetaLinux cannot correctly generate the NAND partition node in the device tree, and Linux cannot recognize the partitions defined with petalinux-config menuconfig.

See this article for a work-around.

(Xilinx Answer 69759) 2017.2 - Device tree generator cannot generate the NAND partition node according to the arasan nand template.

  • How do I enable UBI?

In the Linux configuration menu, go to "Device Drivers" > "Memory Technology Devices (MTD)" > "UBI - Unsorted block images", and mark the "Enable UBI" check-box.

  • How do I enable UBIFS?

Because UBIFS works on top of UBI, you have to enable UBI first.

Then in the Linux configuration menu, go to "File systems" > "Miscellaneous filesystems", and mark the "UBIFS file system support" check-box.


How do I enable the UBIFS command?

In the PetaLinux ROOTFS configuration menu, go to "Filesystem Packages" > "base" > "mtd-utils", and mark the "mtd-utils-ubifs" check-box.

PetaLinux 2017.2 can support UBIFS for NAND flash with ondie-ECC or HW-ECC only.

The following demo shows the commands to create UBIFS on mtd0. You can create it on other partitions.

You can find "total LEB size" and "available LEB size" with the ubiattach command.

Make sure the "available LEB size" is big enough (likely more than 100MB).

If not, you can increase the partition size.

ZynqMP> ubiformat /dev/mtd0 -e 0 -y
ZynqMP> ubiattach -p /dev/mtd0
ZynqMP> ubimkvol -N data -m /dev/ubi0
ZynqMP> mount -t ubifs ubi0:data /mnt

With these commands, UBIFS has been created in mtd0. You can copy files to it and the files will be saved on flash.

After a power cycle, you can use the ubiattach command to attach the UBIFS and mount again.

ZynqMP> cp /bin/* /mnt

board power off
board power on

ZynqMP> ubiattach -p /dev/mtd0
ZynqMP> mount -t ubifs ubi0:data /mnt
ZynqMP> ls /mnt


文件名 文件大小 File Type
boot_registers_log_rev1_0.tcl 1 KB TCL 495 Bytes SH
rootfs_nand_s.ubi 1 MB UBI
ubinize_s.cfg 140 Bytes CFG
devtable.txt 634 Bytes TXT 1014 Bytes ZIP
uboot_ubifs.log 12 KB LOG
AR# 69765
日期 07/27/2020
状态 Active
Type 综合文章