Petalinux

Petalinux is the toolset of Xilinx used to create linux kernels on the Zynq or Microblaze. The current version of the control software uses Petalinux 2019.1.

Requirements:

Installing your key on the VPS

Just like with building, you should install your public key on the VPS for downloading hardware description files or when publishing new releases or SDKs.

Please follow the https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys–2 guide to set up your own key on the SPIDR4@spidr4.duckdns.org VPS server.

Building the 2019.1 Linux kernel

First you’ll need to set up for Petalinux:

# . <petalinux-install-dir>/settings.sh

After this you should be able to start a petalinux command.

There are only a few commands of importance:

  • petalinux-create - Create a new distribution or application

  • petalinux-config - Configure various aspects of Petalinux

  • petalinux-build - Build Petalinux, and also export to image

The controlboard_linux repo has a helper-script named petatool.py. You can use this tool to:

  • Import the hardware-description (normally not present in the repo)

  • Configure Petalinux (project, kernel and rootfs)

  • Build Petalinux

  • View the device tree

  • Package image with custom bootloader

  • Create an SDK

  • Publish distributions and SDKs

The first thing you need to do when a virgin controlboard_linux repo is checked out, is install the HDF file. For this we will use the petatool. Note that not all functions will work over a terminal connection, an X environment is recommended.

First source the Petalinux setup script as described above. Then run petatool:

./petatool.py or python3 petatool.py

You will see the following screen:

Select petalinux distribution
 1: create new
 2: ctrl2019_1
Or leave empty to exit

Select 2.

Select operation for ctrl2019_1
 1: Import hardware description*
 2: Configure distribution
 3: Build distribution
 4: Show current device tree
 5: Package distribution*
 6: Create an SDK installer (time for lunch!)*
Or leave empty to go back
* - Requires installed SSH key for up/down loading

For virgin installations you’ll first need to select option 1. This will only work if you installed your key on the VPS. You will see the following screen:

If the following gets 'stuck', you will need to install the remote server SSH key into your local environment
Select HDF file to use
1: SPIDR4_controlboard_TOP.hdf - Mar 19 11:54
Or leave empty to go back

Select 1. Now you will be able to configure, build and package your distribution.

TODO: - Installing the control image on an SD card - Creating updates

Important notes for using Petalinux

UG1144 is your friend

This guide contains most work flows.

Never use your project in a different Petalinux than what is was created for

Though tempting to simply use Petalinux 2020.2 for a project created in 2019.1 bad things will happen and you’ll likely corrupt the project. Don’t do it. To create a 2020.1 version create a new project, and slowly migrate all applications and configurations to this new version.

Understanding Petalinux

Petalinux is a sauce on top of OpenEmbedded and the Yocto project. Petalinux provides additional tools which help integration with Xilinx hardware. Still Petalinux building and configuring is mostly Yocto/bitbake and OpenEmbedded. As such I would recommend the following book:

Embedded Linux Systems with the Yocto Project by Rudolf J. Streif

Troubleshooting

I’m getting certificate errors when building the control application

Unfortunately because bitbake uses its own environment something goes wrong in the certificate chain when checking out external GIT repositories using SSL inside a CMake project. The only way to bypass this as far as I know, is to disable SSL verification globally for GIT:

git configure --global http.sslverify false

Creating a new control-board compatible Petalinux image

This part describes the workflow when generating a completely new Linux distribution for the Zynq platform from scratch. It is not Petalinux 2019.1 specific. Note that the guide below tries to accommodate for different versions, but as of this writing 2020.1 has just been released, I can’t know what 2020.2+ will be like. So adapt to your environment as needed. Also, I’m assuming common sense: not going to tell you every button you need to press.

Step 1: Creating a new project

Assuming you have sourced the required Petalinux version, first you need to create a project (a linux distribution).

petalinux-create --type project --template zynq --name <NAME>

Where name can be anything, but I propose <short project name><petalinux version>. E.g. ctrl2019.1 is the version I’ve chosen, as it is the SPIDR4 control board, with Petalinux 2019.1.

You can copy the petatool script to a directly above the project in order to use it, which is easier for some tasks than using the commands. However, for now I will use the command-line interface.

Step 2: Importing the hardware description and configuring the project

First step would be to configure the project and import the hardware description. This can be done in one go. I’m assuming you have an HDF (up to 2019.1) or XSA (2019.2 and up) file.

Note that an XSA file is simply an HDF file with some additional meta-data, but using the X to make it sound cool. To use an XSA file in an old project, rename it to hdf. To use an HDF in a new project, rename it to XSA (Note: YMMV)

Import the hardware description using petalinux-config:

petalinux-config --get-hw-description <dir where xsa or hdf file is>

Instead of specifying the actual file you must choose the directory. Also make sure no other hardware descriptions are present. Not sure why you can’t simply point to the file.

The following settings need tweaking:

Under Image package configuration >> Root filesystem type select SD Card (Petalinux 2019.1) or MTD (Petalinux 2019.2 and up) such that it uses the SD card for booting, instead of the RAM FS or the likes.

You can also change the project name and host name under Firmware Version Configuration. I’ve called both ‘plx2019_1’.

Step 3: Configuring the kernel

Open the kernel configuration by typing:

petalinux-config -c kernel

which will fail if it is unable to open an additional window (with something like ERROR: linux-xlnx-4.19-xilinx-v2019.1+gitAUTOINC+9811303824-r0 do_menuconfig: No valid terminal found, unable to open devshell).

Otherwise you get a new window containing a menuconfig for the kernel. The most important thing you can do here is configure device drivers.

Enter Device Drivers and select additional device drivers you wish to add. Most notably the user-space I2C driver is needed for the user-space I2C dependent drivers:

Go to Device Drivers >> I2C Support and check I2C device interface.

Also check whether or not the sys/class/gpio/... (sysfs interface) is enabled under GPIO Support.

Step 4: Configure the root FS

TODO

Caveats

This section contains information mostly related to issues with development, and their solutions. Just as a note-to-self, or for future reference.

SD card format to boot a Zynq

Though the updatetools project contains scripts to create a bootable SD, there are some notable caveats:

  • create partitions named BOOT (first) and rootfs (second)

  • make sure the BOOT partition is FAT32 formatted, and the rootfs ext4

  • make sure the BOOT martition has the flags ‘boot’ and ‘lba’

  • make sure the BOOT partition is 128 MB or more! This is important, it won’t boot otherwise

Load alternative FPGA firmware

To load an alternative (debug) firmware while the PS is running take the following steps:

  • create .bit file with the following:

all:
{
  ./<Bitstream_name>.bit
}

  • Convert the bitfile to binfile with the following command: bootgen -image <Bitstream_name>.bit -arch zynq -process_bitstream bin

  • Copy the generated .bin file to the SPIDR (using scp) to /lib/firmware

  • On the SPIDR set the full bitstream flag: echo 0 > /sys/class/fpga_manager/fpga0/flags

  • From the /lib/firmware folder run echo <Bitstream_name>.bin > /sys/class/fpga_manager/fpga0/firmware

Now the new firmware should be loaded in the PL.