This page details how to use the Certified Ubuntu on Xilinx Device release image with a SATA hard disk rather than via the typical SD Card-based filesystem.

Table of Contents

Introduction

By default, the Certified Ubuntu on Xilinx Devices image is configured to use an ext4 partition located on an SD card.  This can be limiting, both in terms of partition size as well as speed.  This page describes how to configure the Certified Ubuntu on Xilinx Devices to use an ext4 partition (and swap partition) located on a SATA hard disk on the ZCU102 evaluation platform (other platforms are similar so long as they have SATA available).

The instructions on this page use a command line environment via the USB UART terminal but the same commands can be run via a terminal emulator in the Ubuntu GUI from the running system.

Selecting the Hardware

Before beginning, you will need to acquire at lest the following items:

• SATA hard disk of a suitable size

• SATA cable

• SATA power connector

Selecting the SATA hard disk size is an important consideration, largely driven by your target application. As seen in the default configuration on the SD card, the Ubuntu installation can fit in a disk as small as ~8GB. Most SATA hard disks are considerably larger than this so it is wise to evaluate the packages that you intend to use and then choose a disk that is large enough to store all of those packages with some space left over for things such as temporary files and the swap partition. If budget allows it is recommended to start at 64GB in size as a minimum.

Additionally, this example uses a SATA-attached solid state drive because they are low-power devices. This example can work with a traditional magnetic storage drive.

As seen in the image below, this example used a combination power/data cable for SATA devices. This specific adapter can be purchased from Amazon.com here: https://smile.amazon.com/dp/B06XXZSHJS/ref=cm_sw_r_tw_dp_JRSRRE1KPVGKJ92E2K73

If you do not have this adapter, Molex-to-SATA power and SATA data cable will work.

Attach the Hardware

The ZCU102 evaluation board has everything needed to attach a SATA hard disk.  It has a SATA hard disk data connector as well as a 4-connector Molex power connector.  Start by attaching the hard disk to both data and power as shown in the image below.

Open

Partitioning the Hard Disk

To get started, first make sure that the disk is working properly.  The easiest way is to boot into Ubuntu like normal after attaching the hard disk.  Once Ubuntu starts, log in like normal and check the dmesg log to see if the hard disk was found.  By default, it will be located at /dev/sda (this may be different depending on the hard disk).

Open

In this example, a hard disk was found at /dev/sda and it has two partitions: sda1 (an existing ext4 partition) and sda2 (and existing swap partition).  Next, use the command line parted tool to re-initialize the disk and set up new partitions.

Start by launching parted

$ sudo parted /dev/sda

This will start the parted terminal interface.  You can see a current listing of the existing partitions by using the print command:

(parted) print

Next, clear the existing partition table by issuing:

(parted) mklabel msdos

You will be prompted to confirm since this is a destructive operation.  Types “Yes” to continue. 

After, initializing the disk, you can verify that the disk has been cleared by re-running the print command.

To create a new partition, use the mkpart command.  In this example, the partition is being created as a primary partition, formatted as ext4.  The size dimension will extend from the beginning of the disk (0%) to 239GB.  If your desired partition size is larger or smaller, alter the second size value accordingly.

(parted) mkpart primary ext4 0% 250GB

Next, create another partition that can be used for the swap space area. By definition, this partition will be an extended partition but a logical partition must also be created so that it can be assigned the linux-swap type. The specific size of the swap partition is a decision that is heavily dependent upon the intended use of the system. Red Hat has guidance on swap partition sizes (and whether or not a swap partition is needed at all) on their wiki.

(parted) mkpart extended 250GB 256GB

(parted) mkpart logical linux-swap 250GB 256GB

Now, you can verify the layout looks the way you expect.  The output should be similar to:

Once you are satisfied with the partition layout, exit the parted tool by simply using the quit command.

(parted) quit

Next, initialize the data and swap partitions by formatting them. First, the primary data partition must be formatted. In this example it is being formatted as an ext4 filesystem so the mkfs.ext4 command will be used. Substitute the appropriate mkfs command for other filesystems.

Next, initialize the swap area.  This can be down with the mkswap command. Again, remember to adjust the partition number values to reflect the ones on your system.

Populating the Filesystem

Now, it’s time to populate the primary ext4 partition with the contents of the Certified Ubuntu on Xilinx Devices filesystem.  There are two options:

1. Move your existing filesystem to the hard disk.  This is useful if you’ve already made customizations

2. Download the default filesystem image from Ubuntu.com and deploy it to the hard disk.  This is useful if you’d like to start over in a new configuration.

Either way, start by mounting the partition on the hard disk that you wish to populate. In the case above the primary partition was partition 1 so it is mounted as follows:

$ sudo mount /dev/sda1 /mnt

Be sure to adjust this as appropriate for the partition layout on your system.

Copy the Live Root Filesystem from SD Card (Recommended)

For many users, the desire to switch to a SATA hard disk after some initial effort has already been put into using the Certified Ubuntu for Xilinx Devices image. There may be customizations already in place in terms of packages, configuration, or optimizations and the user wishes to maintain these changes after migrating to the SATA hard disk. The best way to accomplish this is to synchronize the existing (running) filesystem with the new partitions created above on the SATA drive.

This method of populating the new primary partition uses the rsync command to mirror the current contents of the SD card-based Ubuntu filesystem onto the new SATA-attached disk. The example rsync command below includes some options to ensure that the command only includes what is really required.

$ sudo rsync -aAX --info=progress2 --exclude=/dev/* --exclude=/proc/* --exclude=/sys/* --exclude=/mnt/* --exclude=/media/* --exclude=/run/* --exclude="swapfile" --exclude="lost+found" / /mnt

This is a long, complex set of arguments to the rsync command so they are summarized below:

• -a - this option actives "archive mode" which preserves metadata on files & directories such as owner, group, permissions.

• -A - this option preserves any ACLs that have been set on files & directories

• -X - this option preserves any extended attributes (eg, xattr)

• --info=progress2 - this is an information argument to provide a relative progress bar during the operation

• --exclude=/dev/* - omit the this directory and its contents since it is a special system directory recreated during each system startup

• --exclude=/proc/* - omit the this directory and its contents since it is a special system directory recreated during each system startup

• --exclude=/sys/* - omit the this directory and its contents since it is a special system directory recreated during each system startup

• --exclude=/mnt/* - omit the this directory since it is the path being copied into by this operation

• --exclude=/media/* - omit this directory because in modern Linux distributions it contains special directories representing mounted removeable media

• --exclude=/run/* - omit the this directory and its contents since it is a special system directory recreated during each system startup

• --exclude="swapfile" - omit the dedicated swap file since these steps will enable a swap partition anyway

• --exclude="lost+found" - omit this directory because it is a special filesystem related directory for file recovery and its contents would be out of sync on the new target anyway

Depending on the current size of the source filesystem on the SD card and speed of the target disk this operation can take as little as one minute or in excess of 10 minutes.

After completing the rsync operation, unmount the target disk.

$ sudo umount /mnt

Extract the Certified Ubuntu for Xilinx Devices rootfs.tar.gz Image (Optional)

Sometimes the user may wish to use the Certified Ubuntu for Xilinx Devices image from the very beginning of their experience. That is, there will be no extant customizations that need to be maintained when moving to the SATA drive experience.

To use the official Certified Ubuntu on Xilinx Devices image as the starting point, begin by making sure you are in the $HOME directory of your current user.

$ cd ~

Next, download the root filesystem archive from http://ubuntu.com

$ wget https://people.canonical.com/~platform/images/xilinx/iot-zcu10x-classic-desktop-2004-x07-20210728-85-rootfs.tar.gz

The tar command can be used to extract the archive into the target filesystem in situ. Note that this should be run with sudo privileges.

$ sudo tar xvpfz ~/iot-zcu10x-classic-desktop-2004-x07-20210728-85-rootfs.tar.gz -C /mnt

Running the command in this way will ensure that all file permissions are maintained.

This can take a while as it is copying from a relatively slow SD card interface over to the SATA hard disk one file at a time.

Note that the .tar.gz file does not contain the /etc/passwd or /etc/shadow files which are required for login. Be sure to copy these files from the running system into the filesystem on the SATA drive (maintaining ownership and permissions values):

$ cp -ap /etc/passwd /mnt/etc/

$ cp -ap /etc/shadow /mnt/etc/

Once all of the files have been successfully moved to the SATA drive, unmount the target disk.

$ sudo umount /mnt

Updating the System to Boot from the SATA Hard Disk

The first thing that must be updated to redirect the boot process to the SATA hard disk is to change the Linux kernel bootargs.

Next, update the fstab file inside the hard disk filesystem to make sure that the swap area will be after reboot.

First,(re-)mount the SATA hard disk

$ sudo mount /dev/sda1 /mnt

Then open the fstab file:

$ sudo vi /mnt/etc/fstab

Inside this file, add a new line with the following information:

LABEL=swap /dev/sda5 none  swap  sw    0     0

Be sure to replace sda5 with the appropriate partition number as configured based on your drive above.

Also, be sure to copy the /etc/default/u-boot-xlnx file into the hard disk filesystem

$ cp /etc/default/u-boot-xlnx /mnt/etc/default

Finally, unmount the hard disk filesystem before rebooting.

$ sudo umount /mnt

When the system reboots, the system will now use the hard disk mounted at /dev/sda1. 

After all of the updates are done, reboot the system

$ sudo reboot