Zybo Z7 Petalinux Demo

The Zybo Z7 Petalinux demo demonstrates the usage of various board features from within a Linux environment.

Available features:

• Ethernet with Unique MAC address and DHCP support
• USB Host support
• UIO drivers for onboard switches, buttons and LEDs
• SSH server
• Build essentials package group for on-board compilation using gcc, etc.
• HDMI output with KMS (kernel mode setting)
• HDMI input via UIO drivers
• Pcam 5C input via V4L2 drivers (only for Zybo Z7-20)

• Zybo Z7 (-10 or -20) with a MicroUSB Programming Cable.
• Petalinux Installation compatible with the latest release of this demo
  • See Xilinx's Petalinux Tools Documentation (2020.1) (UG1144) for installation instructions. Make sure that the documentation version and the project version that you want to use are the same.
• Serial Terminal application to receive messages printed by the demo
  • See Installing and Using a Terminal Emulator for more information.
• Micro SD card formatted as a FAT filesystem

For the Pcam 5C demo:

• Pcam 5C to use video for Linux functionality
• Ethernet cable to retrieve the pictures as .bin files (useful for testing the Ethernet feature as well)
• External 5V power supply

For testing the HDMI and USB features:

• 1 HDMI Type A to Type A or HDMI Type A to DVI-D cable
• HDMI or DVI monitor
• Keyboard with USB 2.0 cable

For changing or extending the hardware platform:

• Vivado installation compatible with the latest release of this demo
  • See Installing Vivado, Vitis, and Digilent Board Files for installation instructions.

First and foremost, releases - consisting of a set of files for download - are only compatible with a specific version of the Xilinx tools, as specified in the name of the release (referred to as a release tag). In addition, releases are only compatible with the specified variant of the board. For example, a release tagged “20/DMA/2020.1” for the Zybo Z7 is only to be used with the -20 variant of the board and Vivado 2020.1.

The latest release version for this demo is highlighted in green.

Note: Releases for FPGA demos from before 2020.1 used a different git structure, and used a different release tag naming scheme.

Note for Advanced Users: GitHub sources for this demo can be found in the 10/Petalinux/master and 20/Petalinux/master branches of the Zybo-Z7 repository. Further documentation on the structure of this repository can be found on this wiki's Digilent FPGA Demo Git Repositories page.

Instructions on the use of the latest release can be found in this dropdown:

Using the Latest Release

Note: This workflow is common across many Digilent Petalinux demos. Screenshots may not match the demo you are working with.

Important: These steps are only to be used with releases for Xilinx tools versions 2020.1 and newer. Older releases may require other flows, as noted in the table of releases.

First, download the '*.bsp' file from the demo release, linked above.

---

Open a Petalinux Project from a Release

Open a terminal and run the following commands. The install path is /opt/pkg/petalinux/ as exemplified in UG1144 v.2020.1. This will set up the Petalinux environment for this terminal only.

source <path-to-installed-PetaLinux>/settings.sh

---

In the same terminal navigate to the desired project folder and create the Petalinux project using the '*.bsp' by executing the following command. The resulting folder structure will contain a pre-built folder which has the necessary boot binaries for the current Demo

cd <path-to-project-folder>
petalinux-create -t project -s <path-to-bsp>

---

Build a Petalinux Project

In order to rebuild the project without changing anything in the configuration, first navigate to the root of the Petalinux project using the terminal which has the Petalinux environment set up.

Note: If the Petalinux environment is not set up it will not recognize the petalinux-* commands.

The root folder will contain the following folders and file: components, project-spec, pre-built (optional), config.project. Once in this folder execute the build command. This will start building the Petalinux project based on the current configuration. The execution time of the build command will depend on PC performance, project complexity, execution iteration (it takes longer for a clean project to build). Depending on the project complexity after the build, the project folder might take several GB of free space.

petalinux-build

After the build completion, the Boot.bin has to be explicitly built in order to have a Second Stage Boot Loader (SSBL) from Petalinux. This can be obtained by executing the command below from the root folder.

Note: <zynq_type> may vary depending on Zynq7000 or Zynq Ultra Scale

petalinux-package --boot --force --fsbl images/linux/<zynq_type>_fsbl.elf --fpga images/linux/system.bit --u-boot

---

(Alternative for building the project) Use the pre-built image

Note: This procedure only works if you are using the .bsp release. If you cloned the project source directly from GitHub, skip this section.

If the project created from the .bsp release contains the pre-built folder you can copy the files BOOT.BIN, boot.scr, image.ub directly from there. The details on how to use these files to boot Petalinux on the board are described in the Booting Petalinux on a Zynq Board section below.

---

Set up the Zybo Z7-20

Set up for booting Petalinux on the Board:

• Plug the Zybo Z7-20 into the computer via the microUSB programming cable and power on the board (you can also use an external power supply, but make sure the JP6 is set properly). Make sure the JP5 jumper is set to SD. Use the steps described in Booting Petalinux on a Zynq Board.

Additional set up for the Pcam 5C demo:

• Make sure you are powering the Zybo Z7-20 with an external 5V power supply and have the JP6 jumper on the WALL option.
• For retrieving the pictures you can use multiple procedures described in the Using the demo section.
• Attach the Pcam 5C assembly (which includes the Pcam 5C and the attached 15-pin flat flexible cable) by inserting the other end of the FFC into the Pcam connector on the Zybo Z7 as shown in image below. Ensure the cable is securely latched by pressing down firmly on the connector with two fingers. For a more detailed set of instructions, see the Pcam section in the Zybo Z7 Reference Manual. If the cable has become disconnected from the Pcam 5C, please see the Pcam 5C reference manual for instructions on how to reattach it.

---

Booting Petalinux on a Zynq Board

Copy the BOOT.BIN, boot.scr, image.ub files from the <path-to-project-folder>/images/linux or the <path-to-project-folder>/pre-built folder onto a FAT32 formatted MicroSD Card. Once this has been done, safely remove the SD Card from the PC and slide it into the development board's MicroSD Card slot. Make sure that the board is set up to boot from SD Card.

Note: Some projects might contain an extra file, uEnv.txt, which should be added to the SD Card

Boot up the board and set up your preferred serial console to listen on the serial port using the default baud rate of 115200. On the console, you should be able to see the boot-up sequence of the board starting from U-Boot (SSBL) up to the login prompt of Linux.

Note: The default login username and password is root:root

---

At this point, the demo is now running on your board. Refer to the Description section of this document for more information on what it does.

A brief set of instructions to some of the configurations which can be done in Petalinux can be found in this dropdown:

Petalinux Configurations

Note: This a brief summary of what Petalinux can do. For more details please refer to the UG1144 v.2020.1

There are some components that can be modified in Petalinux in order to customize your Linux environment. These include the user space application, kernel drivers, u-boot configuration, generic Petalinux settings, and Hardware update components. Most of these changes can be done by executing the petalinux-config command with different parameters.

Note: By using petalinux-config -c <COMPONENT> the component changes will be stored in the workspace directory (<project-root-dir>/components/yocto/workspace). To apply workspace changes to the recipe in the meta-user, the user must run the -x finish command to return their build location, for example, “petalinux-build -c <COMPONENT> -x finish”.

---

Making Hardware Changes and Adding Them to Petalinux

In order to modify and switch out the hardware platform for a baremetal demo, you should first open the Vivado project from the release. Extract the previously downloaded '*.xpr.zip' file. Exporting the Vivado project for Petalinux is the same as exporting it for Vitis, therefore the instructions are identical.

---

Open a Block Design Project in Vivado

Launch Vivado

Select the dropdown corresponding to your operating system, below.

Windows

Open Vivado through the start menu or desktop shortcut created during the installation process.

Linux

Open a terminal, and change directory (cd) to a folder where log files for your Vivado session can be placed, then run the following commands:

source <install_path>/Vivado/<version>/settings64.sh
vivado

---

In Vivado's welcome screen, use the Open Project button to navigate to and open the XPR file contained in the folder the release was extracted into.

---

The project's block diagram, which contains the design, with all of the existing components and their connections, can be opened by either double-clicking on the “*.bd” file in the sources pane (which also includes other source files, such as constraints), or by clicking the Open Block Design button in the Flow Navigator pane.

---

Making changes to the design is out of the scope of this particular document. More information on how to use IP Integrator to create or modify a project can be found through Getting Started with Vivado and Vitis for Baremetal Software Projects. The remainder of this document will discuss how to generate a bitstream, export a new hardware platform, and load it into Vitis.

---

Before the Vivado project can be built, the block design must be validated. This step runs an automatic check of the block design to see if there are any potential issues with it. Click the Validate Design button () in the Diagram pane's toolbar (or press the F6 key).

If the design has issues, a dialog will pop up that lists them. It should be noted that most Warnings can be ignored, as can some Critical Warnings. These issues can also be viewed in the Messages tab of the pane at the bottom of the window.

If there are no issues, a dialog will pop up that will tell you so. Click OK to continue.

Note: Some Zynq boards may produce critical warnings at this stage relating to PCW_UIPARAM_DDR_DQS_TO_CLK_DELAY parameters. These warnings are ignorable and will not affect the functionality of the project. See the Hardware Errata section of your board's reference manual for more information.

---

Build a Vivado Project

At this point, the Vivado Project is ready to be built, by running it through Synthesis and Implementation, and finally generating a bitstream. Click the Generate Bitstream button in the Program and Debug section of the Flow Navigator pane at the left side of the window.

---

A dialog will pop up with several options for how Synthesis and Implementation should be run. Most should be left as defaults. Of particular importance is the Number of jobs dropdown, which is used to specify how much of the resources of your computer should be dedicated to the build. A larger number of jobs will dedicate more resources, which will allow the build to be completed faster. It is recommended to choose the highest available number.

Note: Critical warnings about how IPs included within another IP were packaged with a different board value can be safely ignored. The same is true for warnings related to negative CK-to-DQS delays seen on some Zynq boards.

Depending on the complexity of the design, the board used, and the strength of your computer, the process of building the project can take between 5 and 60 minutes.

---

When complete, a dialog will pop up that presents several options for what to do next:

• Open Implemented Design can be used to view the actual hardware design that has been implemented and will be placed onto the chip.
• View Reports can be used to view additional information about the design, including how much of the resources of the FPGA will be used by the design.
• Open Hardware Manager can be used to go directly to Vivado's Hardware Manager, which can be used to program a hardware design onto a board. This is typically used for designs that do not involve a software component.
• Generate Memory Configuration File can be used to create a file for programming an FPGA-only design into flash memory.

If none of these options are desired, click Cancel to continue.

---

Export a Hardware Platform

Once the project has been built, the design must be exported from Vivado so that Vitis has access to information about the hardware that a software application is being developed for. This includes the set of IP connected to the processor, their drivers, their addresses, and more. Exporting hardware after the bitstream has been generated allows you to program your board directly from within Vitis.

---

To export the hardware design, click Export → Export Hardware in the File menu.

---

The wizard that pops up guides you through the options available for hardware export. The first screen allows you to select a Fixed or Expandable platform. In this case, choose a Fixed platform and click Next to continue.

This screen is not present in Vivado 2022.1, proceed to the next

---

The Output screen allows you to select whether only the hardware specification (Pre-synthesis) should be exported, or whether the bitstream should be included. Since the bitstream has already been generated, it should be included in the platform so that Vitis can automatically figure out where it is when programming a board. Select Include bitstream and click Next to continue.

---

The Files screen gives you the option to choose a name for the Xilinx Shell Architecture (XSA) file, and provide a path to a folder that the file will be placed within. Give your XSA file a name, and choose a memorable location to place it in. This file will later be imported into Vitis, so take a note of where it is placed and what it is called.

Important: Do not use spaces in the file name or export path. Underscores or camelCase are recommended instead.

Click Next to continue.

---

The final screen of the wizard summarizes the options you selected. Click Finish.

---

Importing the New Hardware

In order to import the new hardware description to Petalinux, the following command must be executed. This will prompt a configuration window where all the new Zynq generic changes for the new hardware will be visible.

petalinux-config --get-hw-description=<path-to-new-xsa>

Other changes which can be configured from this window are: boot-flow, default password, FPGA reconfiguration, image packaging, and other important settings. This window can also be accessed by simply executing petalinux-config without any parameters.

petalinux-config

---

Configuring U-boot

When first importing the hardware, some U-boot customization is generated by the import feature. U-boot customization includes drivers for boot mediums, file system support, boot console arguments, network support, and many more. In order to bring up the configuration window, the following command must be executed.

petalinux-config -c u-boot

---

Configuring the Kernel

When first importing the hardware, some kernel customization is generated by the import feature, which usually includes supported drivers for PL IPs. U-boot customization includes drivers for drivers, logging levels, debugging flags, and many more. In order to bring up the configuration window, the following command must be executed:

petalinux-config -c kernel

---

Configuring the RootFS

The packages which will be built into the rootfs need to be added manually by the user. The default package manager for Petalinux currently is RPM and any additional packages which the user wants to add need to be built using Petalinux. In order to bring up the configuration window, the following command must be executed:

petalinux-config -c rootfs

---

Changes to the Device Tree

When first building the project by executing petalinux-build or if you are using the *.bsp version of the project, the generated device tree will be available in <path-to-project-folder>/components/plnx_workspace/device-tree/device-tree. Any changes to this folder will be overwritten at the next build. In order to make permanent changes, the <path-to-project-folder>/project-spec/meta-user/recipes-bsp/device-tree/files/*.dtsi need to be changed.

Note: Changes to the device tree components will have to be done by referring to the already existing nodes in the auto-generated device trees.

---

Warning

After configuring some of the previous settings might be lost. This is a known issue in Petalinux 2019.2 and 2020.1; more information about the workaround can be found here: Xilinx Support Case

---

The functionality of the demo features are presented in the sections below.

Testing the Ethernet connection

After you connect the Ethernet cable to the network (wall outlet, router, PC) run the following command in the serial terminal. You can choose as address your PC's Ethernet or Wi-Fi IP address (depending on how your PC is connected to the network).

ping <address>

Upon success you should see no packet loss.

Alternatively you can run the command:

ip a

If there is a successful connection, you should be able to read the board's eth0's assigned ip address

2: eth0: (...)
   (...)
   inet <ip address>
   (...)

Testing the USB support

For testing USB support you can insert a FAT-formatted USB stick into the board's USB port. If the device is detected you should see in the terminal a message similar to:

usb-storage 1-1:1.0: USB Mass Storage device detected

Next, run the command

fdisk -l

This way you can identify the device location, e.g. /dev/sda1. If that location is different in your case, you should use it instead of /dev/sda1 next.

To mount the USB drive you should run the following commands

mkdir /media/usb-data # create a mount point directory
mount /dev/sda1 /media/usb-data # mount the detected device into the newly created directory

You could use that directory to transfer data between the board and your PC.

Before removing the USB stick from the board you can unmount it using the command

umount /media/usb-data

Testing the LEDs, switches and buttons using UIO drivers

The boards LEDs, switches and buttons can be accessed through UIO drivers. In some of the earlier versions of the project (before 2020) a series of apps were available for testing some of the GPIOs. However these are no longer maintained. In the newer versions of petalinux, the user can select whether or not to include the gpio-demo and peekpoke apps.

Testing the SSH server

One way to test the SSH server is to connect to the board from your PC via SSH.

First, get your board's eth0 IP address (as explained in Testing the Ethernet connection above). Then open a command line on your PC and connect to the board using:

ssh root@<board eth0 IP address>

You should be able to interact with the linux environment similarly to the serial terminal.

Testing the packages

To view all installed packages run the command

ls /usr/bin

For testing for instance your gcc package you can try to create and compile a C source file. Create a source file:

cd ~
touch source_file.c

Open it using the vi editor:

vi source_file.c

Insert a simple C program code. Press i and copy-paste the following code using Ctrl+Insert - Shift+Insert:

#include <stdio.h>

int main() {
    printf("Hello World!\n");
    return 0;
}

Save it by pressing Esc and typing :wq

Compile and run it

gcc source_file.c -o my_app
./my_app

Upon success you should see the output: Hello World

Testing the HDMI output and USB input from keyboard

To test the HDMI output with kernel mode setting, connect a HDMI cable between your HDMI TX port and an HDMI monitor. Next, connect your keyboard to the USB port.

You should be able to use the monitor the same way as the serial terminal, type in commands using the connected keyboard and access all features in the demo.

---

Note: For the HDMI input there is currently no demo application that uses the UIO drivers.

Taking pictures using V4L2 and the Pcam 5C (Z7-20 only)

Run the following commands in the serial console connected to your board.

Set the width, height, and frame rate of your capture.

width=1920 && height=1080 && rate=15

Before running the next commands make sure to use arguments that correspond to the data in the device topology. To view the information about the video device run the command:

media-ctl /dev/media0 -p

You should be able to view the device topology with various entities and pads. Pay attention to the ov5640 2-003c and 43c60000.mipi_csi2_rx_subsystem entities whose names could slightly change. If any of the names differ from the ones used in the commands below make sure to modify them to include the correct name.

Prepare your media and video pipeline.

media-ctl -d /dev/media0 -V '"ov5640 2-003c":0 [fmt:UYVY/'"$width"x"$height"'@1/'"$rate"' field:none]'
media-ctl -d /dev/media0 -V '"43c60000.mipi_csi2_rx_subsystem":1 [fmt:UYVY/'"$width"x"$height"' field:none]'
v4l2-ctl -d /dev/video0 --set-fmt-video=width="$width",height="$height",pixelformat='YUYV'

Capture 14 frames.

yavta -c14 -f YUYV -s "$width"x"$height" -F /dev/video0

As a result you should obtain 14 .bin files

Warning

The camera module takes some time to automatically adjust the exposure and white balance. While this is happening, the frames will come out dark and with green tints. Capture more frames than needed for your usecase.

Retrieving the pictures

To retrieve the pictures you need to transfer the .bin files on your Linux machine. Next they are processed and converted to .png using the ffmpeg tool. There are multiple ways to move the pictures from the board to the PC: through scp (make sure to have the board and PC connected to the same network), through the SD card (by copying the binary files to /mnt/sd-mmcblk0p1), or through a USB stick (as described in the Testing the USB support).

Make sure no data was lost during the transfer of the files.

Run the following commands in a terminal on your Linux machine to copy the files via SSH.

Replace 10.113.0.117 with your board's IP address.

scp [email protected]:~/*.bin .

You can also find the IP address of your board by running the following command in your serial console.

ip addr show

Set the width, height, and framerate of your capture.

width=1920 && height=1080 && rate=15

Using ffmpeg, convert the files you copied into PNG.

for f in *.bin; do mv "$f" "${f%.bin}.yuv"; done
for f in *.yuv; do ffmpeg -s "$width"x"$height" -pix_fmt yuyv422 -i "$f" -y "${f%.yuv}.png"; done

(Non-functional) Audio input / output

Warning

Audio features are currently completely non-functional.

Run the following commands in the serial console connected to your board.

Start a pulseaudio server.

pulseaudio --start

If you see a message similar to the following one, you need to start the pulseaudio server again.

ALSA lib ../../alsa-plugins-1.1.9/pulse/pulse.c:242:(pulse_connect) PulseAudio: Unable to connect: Connection refused

See the Soundcard Testing page of the ALSA project to find out how to capture and play back sound.

All materials related to the use of the Zybo Z7 can be found on its Resource Center.

All materials related to the use of the Pcam 5C can be found on its Resource Center.

For additional and in-depth information about how Petalinux works please consult the UG1144 v.2020.1

For technical support, please visit the Embedded Linux section of the Digilent Forum.