Install and Run Ubuntu 20.04 on Xilinx Zynq-7000 SoC ZC706 Through a Bootable SD Card, and Access It Through the Serial Port
In a new research project we are going to use the Zynq-7000 SoC ZC 706 Evaluation Kit. Below I document the steps I took to prepare Ubuntu 20.04 for the evaluation board and make sure it is running by connecting through a serial port. Additionally I document how I enabled remote access for colleagues and myself (so I don’t have to use the UART port every time I want to connect to the board).
I thank Chathura Niroshan for writing up the steps for installing Ubuntu 16.04 on Zynq-7000 SoC ZC702. To ensure I followed the correct and most up-to-date steps, I used PetaLinux’s Reference Guide and his write up side by side to install Ubuntu on a bootable SD card for ZC706.
The main difference between the steps I took and Chathura’s steps is that I did not need Vivado to create a hardware design. Instead, I used a readily available board support packages (BSP) file for ZC706 that includes a default hardware design. (Nevertheless, because I thought I am going to need Vivado during the steps, I did download and install it. I experienced an issue during the installation which I could resolve with the solution mentioned in this comment which instructs to install packages libtinfo5 and libncurses5.)
I executed the steps below on my laptop with an Intel CPU E3-1505M v5 and 64GB RAM that is running Ubuntu 20.04. To create the bootable files I used PetaLinux Tools version 2020.2 and copied them to a 256 GB SD card.
Create Bootable SD Card
We need to format the SD card and create 2 partitions of which the first will contain the boot information and the second partition will contain the root filesystem. First three steps under the section Configuring SD Card ext File System Boot of the Reference Guide describe how these partitions should be configured. Following the steps below we can create such two partitions:
- Insert the SD card into the SD card reader slot connected to your machine.
- Open up a terminal (e.g. ctrl+alt+t) and run
sudo gparted. If you don’t have gparted, install it with
sudo apt install gparted.
- From the menu GParted > Devices select the SD card.
- On each partition that is on the SD card, right click and select Delete to get a single “unallocated” partition.
- Right click and select New on the “unallocated” partition. Configure the partition as follows:
- Free space preceding (MiB): 4
- New size (MiB): 500
- File system: fat32
- Label: BOOT
Don’t change the other settings. After done configuring, click Add.
- Right click and select New on the “unallocated” partition that follows the BOOT pratition (i.e. the “unallocated” partition that isn’t 4.00 MiB in size). This partition will occupy all the space that follows the BOOT partition. Configure the partition as follows:
- Free space preceding (MiB): 0
- Free space following (MiB): 0
- File system: ext4
- Label: RootFSDon’t change the other settings. After done configuring, click Add.
- Finally, to commit the changes select Edit > Apply All Operations from the menu.
Install PetaLinux Tools
As noted under the section Installation Steps in the Reference Guide, the recommended minimum workstation requirements are a 2 GHz CPU with 8 cores at minimum, 8 GB of RAM and 100 GB of free disk space. In my case, I did fine with a CPU of 4 cores and 2.8 GHz clock speed. Although Ubuntu 20.04 (running on my laptop) was not listed as a Supported OS, I had no issues installing and using PetaLinux Tools after getting the required packages. Steps for installing PetaLinux Tools v2020.2:
- As mentioned in the Reference Guide, PetaLinux requires that
/bin/shis ‘bash’. Check by executing
ls -l /bin/shif it is pointing to ‘bash’ or ‘dash’. If it is ‘dash’, reconfigure it by executing
sudo dpkg-reconfigure dash. Select
<No>when asked “Use dash as the default system shell (/bin/sh)?”.
/bin/shshould now be ‘bash’.
- Get the PetaLinux 2020.2 Installer file
- Verify that you have the correct and whole file. The command
md5sum petalinux-v2020.2-final-installer.runshould result in 687b018f7502a4258bd633dc483bde79.
- Create the directory where you would like to install PetaLinux. In the steps below I will use INSTALL_DIR to indicate the installation directory. As an example, you can set INSTALL_DIR to
INSTALL_DIR=~/tools/petalinux/v2020.2/and create the directory by executing
mkdir -p $INSTALL_DIRin the terminal.
- Execute the installer file to install PetaLinux at INSTALL_DIR:
bash ./petalinux-v2020.2-final-installer.run --dir $INSTALL_DIR
In my case, the installer reported missing the packages autoconf, libtool, gcc-multilib andzlib1g:i386. After installing them with
sudo apt installthe installer was able to continue. I ignored the warnings related to unsupported OS and missing tftp server. The tftp server is necessary if you are booting the board through tftp.
- Every time before working with PetaLinux Tools, set up the environment in the terminal by sourcing the settings.sh file in INSTALL_DIR, e.g.,
source $INSTALL_DIR/settings.sh. Sourcing settings.sh gives an error under the ZSH terminal. Make sure you are operating in a bash terminal (executing
bashwill give you a bash terminal). If setting up succeeded,
echo $PETALINUXshould output the directory path where PetaLinux is installed.
Prepare BOOT Partition Files
Next we prepare the boot files that we will copy to the SD card. More information about the performed steps below can be found under sections PetaLinux BSP Installation, PetaLinux Configuration and Build System Image, Boot Images Storage Configuration, Build System Image and Generate Boot Image for Zynq-7000 Devices of the Reference Guide.
- Download the board support package (BSP) file for your board, in our case
xilinx-zc706-v2020.2-final.bspfor ZC706, from https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools/2020-2.html. Important to highlight from the Reference Guide is that PetaLinux 2020.2 only works with hardware designs exported from Vivado Design Suite version 2020.2. So in case you are using a different version of PetaLinux, it might be better to get the BSP file from the download page of your version of PetaLinux.
- Open a ‘bash’ terminal (press
bash) and source the
settings.shfile residing in the installation directory of PetaLinux tools, e.g.
petalinux-createcreates a new project in the current working directory, pick the directory where you want to create a new project and enter that directory, e.g.:
mkdir -p ~/projects/zc706 && cd ~/projects/zc706
- Create a new petalinux project with
petalinux-create -t project -s ~/Downloads/xilinx-zc706-v2020.2-final.bsp -n plnx-files. Option
-nallows you to name your project. Note that building the boot files requires between 50–100 GB of free temporary space. By default the directory
build/tmpinside the project directory is used. If necessary, you can adjust the directory for the temporary files with the
- Next we configure our target system. Enter the new petalinux project directory (
plnx-filesin my case) and execute
petalinux-configto start the configuration. Note that we do not need to import the hardware description (
--get-hw-description), because it is already provided by the BSP file. If you get an error while executing the config command, you can check file
build/config.logto find more details about it. If you get an error that says
Failed to generate <..>/Kconfig.syshw, installing package
libtinfo5through apt might resolve your issue.
- In the opened System Configuration window, we go over the following settings:
- Under Image Packaging Configuration > Root filesystem type select EXT4 (SD/eMMC/SATA/USB).
- Under Subsystem AUTO Hardware Settings > Advanced bootable images storage Settings > boot image settings > image storage media select primary sd.
- Under Subsystem AUTO Hardware Settings > Advanced bootable images storage Settings > kernel image settings > image storage media select primary sd.
- Save and exit the configuarion window.
- Now start building with
petalinux-build. This is a long process that shows a progress bar. This step creates, among other files, the files
images/linux/boot.scr. We will copy these two files to the SD card in later steps.
- Finally create the
petalinux-package --boot --format BIN --fsbl images/linux/zynq_fsbl.elf --fpga images/linux/system.bit --u-boot. We will also copy this file to the SD card later.
Prepare RootFS Partition Files
We will install Ubuntu 20.04 LTS in the RootFS partition. Since the rootfs.tar.gz file, created during the petalinux build above, does not contain Ubuntu, we ignore that file and follow steps from digikey.com’s wiki page to get Ubuntu 20.04 LTS root filesystem.
- Download the tar file
- Verify that you have the correct and whole file. The command
md5sum ubuntu-20.04-minimal-armhf-2020–05–10.tar.xzshould result in 16da487c1178439d68e18cf55accb774.
- Extract the downloaded tar file:
tar xf ubuntu-20.04-minimal-armhf-2020–05–10.tar.xzThis will create a directory
armhf-rootfs-ubuntu-focal.tar. We will extract this tar file to the SD card in the next section.
Copy Files to the SD Card
- Insert the SD card into the SD card reader slot connected to your machine.
- If the partitions are not mounted, you can mount them to a directory with the commant
sudo mount /dev/<partition-on-device> <directory>, e.g.:
sudo mount /dev/mmcblk0p1 ~/sdcard/boot
sudo mount /dev/mmcblk0p2 ~/sdcard/rootfs
~/sdcard/rootfsalready exist in user’s home directory. You can find the device partitions either by running the command
lsblkor by starting up gparted with
- Copy the boot files
BOOT.BINto the BOOT partition, e.g.:
cp $ZC706_PLX_DIR/images/linux/image.ub ~/sdcard/boot
cp $ZC706_PLX_DIR/images/linux/boot.scr ~/sdcard/boot
cp $ZC706_PLX_DIR/images/linux/BOOT.BIN ~/sdcard/boot
$ZC706_PLX_DIRpoints to the petalinux project directory.
- Extract the Ubuntu rootfs tar file to the RootFS partition and set RootFS ownership to root and permissions to 755, e.g.:
tar xfvp $ZC706_UBUNTU_DIR/armhf-rootfs-ubuntu-focal.tar -C ~/sdcard/rootfs
sudo chown root:root ~/sdcard/rootfs
sudo chmod 755 ~/sdcard/rootfs
$ZC706_UBUNTU_DIRpoints to directory
ubuntu-20.04-minimal-armhf-2020-05-10created in the previous section Prepare RootFS Partition Files.
- Finalize by synchronizing the writes to the SD card by running
sync. The SD card is ready to be inserted into the board’s SD card slot.
Connect to the Board Through the Serial Port
To test our installation, we connect through the serial port and see if the board is booting into Ubuntu.
- Start with the board turned off.
- Insert the SD card to the board’s SD card slot.
- Configure the Boot Mode Switch on the board to boot from the SD card (see image below). Switches 1 to 5 are respectively configured to be 0, 0, 1, 1 and 0. With 1’s pointing towards the digits 1–5.
- Connect your machine to the board through its USB-to-UART bridge using an A-Male to Mini-B cable.
- Power on your board.
- In a terminal (ctrl+alt+t), execute the command
lsusbto find out if the board is successfully connected to your machine. If there is a line that contains
CP210x, it means your connection with the board succeeded and you can proceed. In my case this line looked like:
Bus 001 Device 021: ID 10c4:ea60 Silicon Labs CP210x UART Bridge.
Otherwise, you will probably need to install the Silabs drivers from https://www.silabs.com/support/resources. Search for VCP to list the drivers under Software. Download the drivers for your machine, extract the downloaded file and follow the instructions in
If you want to check if the drivers are installed on your machine by default, you can run the following commands:
dpkg -L linux-modules-extra-`uname -r` | grep cp210
If this lists a cp210x.ko file, you have the drivers installed and you should see the connection with the board with
lsusbwhen the board is powered on.
- Find out which USB tty port the board is connected to by executing the following in a terminal:
dmesg | grep -i cp210 | grep -i tty
In my case, it is
- Start up the serial port terminal:
If you don’t have it, install it first with:
sudo apt install gtkterm.
- Open the terminal configuration via Configuration > Port.
- Configure the Serial port as follows:
- Port: the tty port found in step 7 above.
ttyUSB0in my case.
- Bits: 8
- Baud Rate: 115200
- Stopbits: 1
- Parity: none
- Flow control: none
- Press OK and your serial port terminal is up. You should now be able to communicate with your board. If you don’t see anything, it might mean that there is currently no output ongoing. Press Enter or any other keyboard to start interacting. The default username and password for the installed Ubuntu is
temppwdrespectively. If you will enable remote access over the internet, mind changing the default password first.
Image supporting step 3 above:
References for the steps above:
Enable Remote Access From Outside Local Network
Finally, I will describe the steps I took to enable remote access to the boards to colleagues and myself. This will allow to connect through SSH and will save myself from having to connect through the serial port every time. Ubuntu installed on the board already allows connecting with SSH. However, because it is behind the firewall of my Verizon router, I had to adjust the firewall settings to allow incoming SSH requests and route them to the board.
Important: consider changing the default password of the ubuntu user on the board before making the board accessible over the internet.
Adjusting firewall settings:
- Make sure the board is ON and connected to the router with an Ethernet cable.
- Find the router IP address through https://whatismyipaddress.com/. Alternatively the router’s local network IP can be used which is usually of the form 192.168.X.Y, for example, 192.168.1.1 or 192.168.1.255.
- Browse to the router’s IP address by entering it in the browser’s address bar.
- Enter the login credentials which can be found on the sticker behind your router.
- Go to Firewall settings then Port Forwarding.
- Enable Advanced settings.
- Under “Create new port forwarding rule:” change “Select IP from menu” to the arm board’s IP. Also change “Application To Forward” to Custom Ports which will bring up a few extra input fields.
- Set the remaining input fields as follows:
- Protocol: TCP.
- Source Ports: Any.
- Destination Ports: Specify. By default SSH listens on port 22. So this would be the port you would specify. However, it is a good practice to change the default listening port to dodge brute force attacks on default ports. Generally ports between 30000 and 65535 are free to use. If you change the destination port, you have to add option -p to the ssh command to specify the destination port.
- Forward to Port: Specify. Put 22 in the input field or the listening port you have configured for SSH on the board. Since in my case the board is behind a router and not directly reachable from the internet, it is safe from brute force attacks on default ports. Therefore, I did not change the default port on the board. Whatever is specified under “Destination Ports” above, the router converts it to whatever is specified under “Forward to Port”.
- Finally Add the new port forwarding rule and wait for the router to restart.
- Now you should be able to connect with the board over SSH. Use the following command to connect to the board over SSH after replacing destination-port and router-ip with the appropriate values:
ssh -p <destination-port> ubuntu@<router-ip>
Thank you for reading! Please leave a comment if you have questions or issues related to the steps above.