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 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.
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.
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).
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:
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:
Model: ATA LITEONIT LCS-256 (scsi)
Disk /dev/sda: 256GB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Number Start End Size Type File system Flags
1 1049kB 250GB 250GB primary ext4 lba
2 250GB 256GB 6060MB extended lba
5 250GB 256GB 6059MB logical linux-swap(v1) lba
Once you are satisfied with the partition layout, exit the parted tool by simply using the quit command.
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.
ubuntu@zynqmp:~$ sudo mkfs.ext4 /dev/sda1
mke2fs 1.45.5 (07-Jan-2020)
/dev/sda1 contains a ext4 file system
last mounted on / on Wed Dec 15 15:59:28 2021
Proceed anyway? (y,N) y
Discarding device blocks: done
Creating filesystem with 61035008 4k blocks and 15261696 inodes
Filesystem UUID: db2ad263-853e-44b4-8fa3-40cb2c2e5405
Superblock backups stored on blocks:
32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208,
4096000, 7962624, 11239424, 20480000, 23887872
Allocating group tables: done
Writing inode tables: done
Creating journal (262144 blocks): done
Writing superblocks and filesystem accounting information: done
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.
ubuntu@zynqmp:~$ sudo mkswap /dev/sda5
mkswap: /dev/sda5: warning: wiping old swap signature.
Setting up swapspace version 1, size = 5.7 GiB (6058668032 bytes)
no label, UUID=a4c4aa57-dd00-46d5-b506-fd47f3e8b366
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:
Move your existing filesystem to the hard disk. This is useful if you’ve already made customizations
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.
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.
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.
If you need to return to using the ext4 partition on the SD card, you can simply run the dpkg-reconfigure u-boot-zynqmp command with no options stored in /etc/default/u-boot-xlnx and it will return the Linux kernel boot arguments to the default value (eg, booting with the ext4 partition on the SD card.
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