ZUBoard - Boot Linux from eMMC

Introduction

This project provides instructions to help you quickly get up and running with booting Linux from the eMMC Flash on the DP-eMMC HSIO add-on module for the ZUBoard.

Prerequisites

The AMD Xilinx PetaLinux tools are installed and its environment variables are set. See AMD UG1144 for more details.

$ source <path-to-installed-PetaLinux>/settings64.sh

Instructions

• Download the PetaLinux 2022.2 BSP for the ZUBoard.

http://avnet.me/zub1cg_sbc_base_2022_2_bsp
(md5sum = a6b24eabfe1d00995909a3da07d48583)

• Install the BSP

$ petalinux-create -t project -s <PATH_TO_PETALINUX_PROJECT_BSP>

• Navigate to the pre-built folder of the extracted BSP where the pre-built Linux OS image files are and extract the pre-built Linux OS image to a microSD card. Eject the microSD card when the extraction is completed.

$ cd <PATH_TO_EXTRACTED_BSP>/pre-built/linux/images
$ sudo dd if=./rootfs.wic of=/dev/sd<x> bs=1M conv=fsync status=progress
$ sync && sync

• Copy the pre-built Linux OS image and rootfs tarball to a USB memory stick. Eject the USB stick when the file copy is completed.

$ cp ./rootfs.wic <PATH_TO_MOUNTED_USB_STICK>/. && sync && sync
$ cp ./rootfs.tar.gz <PATH_TO_MOUNTED_USB_STICK>/. && sync && sync

• Set the boot mode switches on the ZUBoard to SD card mode.
  (SW1-4; 0x5; off-on-off-on)
• Mate the DP-eMMC HSIO module to the HSIO connector (J2) on the ZUBoard.

• Connect a DisplayPort monitor to the miniDP connector (J3) on the DP-eMMC HSIO add-on board. A HDMI monitor may also be used with an active HDMI-to-miniDP adapter like this one.
• Insert the microSD card into microSD card cage (J12) on the ZUBoard. Connect the USB-C power cable (J15) and microUSB UART cables (J16) to the ZUBoard and press the power switch (SW7) to boot the board.

• Open a serial console on your host PC for the UART COM port connected to the ZUBoard (GTKTerm, minicom, TeraTerm, etc.) with UART settings:
  Baud: 115,200; Parity: None; Bits: 8; Stop bits: 1; Flow control: None

• View the Linux matchbox window environment on the attached DisplayPort monitor. A USB mouse and keyboard may also be used with the ZUBoard to complete the desktop GUI user experience.

• Log into the Linux OS (login = root).
• Insert the USB memory stick containing the Linux OS image file in the USB connector (J13) on the ZUBoard. Note the disk device sd<x> that Linux assigns to the USB stick.

• Verify the eMMC storage on the DP-eMMC HSIO board is recognized in Linux. The eMMC should be mounted on /run/media/mmcblk1.

# df |grep mmcblk1

• Extract the OS image from the USB stick to the eMMC storage. This OS image is a combination of a 1GB FAT partition (that the FSBL, u-boot, and Linux kernel boot from) and a EXT4 partition.

# dd if=/run/media/sda<x>/rootfs.wic of=/dev/mmcblk1/ bs=1M conv=fsync status=progress
# sync && sync

• Extract the rootfs tarball from the USB stick to the EXT4 partition on theMMC storage.

# tar -xf /run/media/sda<x>/rootfs.tar.gz -C /run/media/mmcblk1p2/

• The newly created EXT4 partition on the eMMC is much smaller than the actual capacity of the eMMC, so we now need to resize it to fill the available space on the eMMC device.

# umount /dev/mmcblk1*
# parted /dev/mmcblk1 resizepart 2 100%
# umount /dev/mmcblk1*
# e2fsck -f /dev/mmcblk1p2
# resize2fs /dev/mmcblk1p2
# umount /dev/mmcblk1*

• Power off the ZUBoard by either typing the 'poweroff' command in the UART console or pressing the power switch (SW7).
• Eject the microSD card and change the ZUBoard boot mode switches to eMMC boot (SW1-4; 0x9; on-off-off-on).
• Turn on the ZUBoard (press the power switch (SW7)) and in the UART console press the space bar when prompted to pause u-boot execution.

• We need to change the boot arguments to tell the Linux kernel to fetch the root filesystem (rootfs) from eMMC storage (mmcblk1p2) instead of the microSD card. Save the changes to u-boot so the new bootargs will be used again in the future.

ZynqMP> setenv bootargs "console=ttyPS0,115200 earlycon root=/dev/mmcblk1p2 rw rootwait cma=1500M"
ZynqMP> saveenv

• Copy the Linux kernel image (image.ub) from eMMC (mmcblk1p1) and execute it to boot.

ZynqMP> fatload mmc 1:1 0x4000000 image.ub
ZynqMP> bootm 0x04000000

Linux will now boot and fetch the rootfs from eMMC storage!

Trust, But Verify

You will know that Linux has not only booted the kernel from the eMMC FAT partition but also the rootfs from the EXT4 partition by examining the system boot messages for 'mmcblk1'. See that the FAT-fs is mounted on mmcblk1p1 and the EXT4-fs partition is mounted on mmcblk1p2.

# dmesg |grep mmcblk1

eMMC Benchmarks

Test the performance of files reads and writes for the eMMC storage on the DP-eMMC HSIO module. This webpage provides a great description of a good way to evaluate the file read and write performance using common Linux utilities.

• Write a 1 GB test file

The Linux dd utility is great for quickly and easily creating and duplicating a file. In order to best test the performance of a file write it is important that the file is at least as large as the RAM in the system in order to avoid the whole file being cached in memory. For the ZUBoard this means a 1GB file. Running the dd command in a timed shell ensures the full file is written to eMMC before the shell exits. The sync command forces the process to write the entire file to disk before completing.

time sh -c "dd if=/dev/zero of=./test.tmp bs=4k count=256K && sync"

Now, let’s do the math. The dd command tells us how many bytes were written, and the time command tells us how long it took.

Use the real time measurement at the bottom of the output.

Convert bytes to MB to make more sensible numbers.

Bytes converted to MB / "real" time seconds
(1073741824/ 1024 / 1024) / (14.423)

This gives us an average of 71.00 MB per second over the duration of the test.

• Read a 1 GB test file

Before testing the file read it is important to first write a dummy file to disk. This will flush the file cache and force the file read to fetch the complete file from disk. Otherwise a portion of the file we just wrote may still be left in RAM and this would skew the read performance test result.

Create a file using dd which is about the same size as the RAM installed on the system. The below assumes 1GB of RAM is installed. You can check how much RAM is installed with the Linux free command.

# dd if=/dev/zero of=./clearcache.tmp bs=4k count=256K
# time sh -c "dd if=./test.tmp of=/dev/null bs=4K"

Use the same math as we did for the dd file write.

Convert bytes to MB to make more sensible numbers.

Bytes converted to MB / "real" time seconds.
(1073741824/ 1024 / 1024) / (14.533)

This gives us an average of 70.46 MB per second over the duration of the test.

Experiment with changing the dd block size (bs=<xx>) and loop (count=<xx>) arguments to see how this affects eMMC disk performance. Changing the block size will for sure influence eMMC disk performance in ways that may surprise you. Users don't generally have an influence on the block size the Linux OS uses to copy and create files so this exercise is largely academic, but the results are still interesting to see and it gives us a good idea of our eMMC disk performance.

Conclusion

I hope these instructions were helpful for you to be successful with the Avnet DP-eMMC HSIO add-on module for the ZUBoard. The combination of DisplayPort video output and eMMC storage on the DP-eMMC HSIO module with the compute power and I/O expansion of the ZUBoard opens up many compelling use cases. What will yours be?

Revision History

2023/11/16: First version