Debugging HW ILAs with PetaLinux over Ethernet

Introduction

When we are working with AMD SoC we often use Integrated Logic Analysers (ILA) to understand the behaviour of our designs in the programmable logic.

However, when we are running PetaLinux on the Processor System accessing the ILA over JTAG can cause issues with the application and OS running. There are several ways we can address this, in this project we are going to look at how we can implement a Xilinx Virtual Cable running in PetaLinux. This Virtual Cable running on the MPSoC processor cores will enable us to connect over Ethernet from Vivado hardware manager.

Of course this also enables remote debugging as well.

To get started with this we are going to update the base design which was used to created our recent ZUBoard Motor control.

Vivado Design

The ZUBoard motor control project opened or recreated, within Vivado we are going to add in to the design two AMD IP cores. The first of these is a System ILA this will be connected to the Master AXI interface from the processing block. In this way we can see all of the transactions which might be occurring on that interface.

The second IP block we are going to add is a Debug Bridge, when we have configured it correctly we will be able to connect from the AXI to the BSCAN. This allows the AXI to access the ILA BSCAN part.

With the debug bridge added the next step is to configure it to bridge between the AXI and the BSCAN. As we are not working with partial reconfiguration we can leave design type as default.

Once this is completed, we then need to run the connection automation. This will connect the debug bridge to the AXI network.

The final design will look like the following below.

Once this is completed the next step is to build the bitstream and export the XSA such that we can update the previously created PetaLinux project.

Obtaining the XVC Source

We can get the XVC source from the AMD GitHub here.

The source code provided will work with Zynq 7000 and Zynq MPSOC. We can clone the repo using the command

git clone https://github.com/Xilinx/xilinxVirtualCable.git

Once cloned we can explore the folder strucutre of what was just downloaded.

Under the top level JTAG folder you will see two directories which contain the source code one for the Zynq 7000 series and Zynq MP

With the source code downloaded, we can start to creating the elements needed in PetaLinux.

PetaLinux

For this project I used the existing ZUBoard Motor PetaLinux Project. Within PetaLinux we need to do three things

• Create an XVC kernel module.
• Create an application for the XVC in userspace.
• Update the Device Tree to include the Debug Bridge

To create the XVC kernel module and userspace application we will need to make some simple modifications to the downloaded code.

From within the Petalinux project run the command below to create an empty kernel module.

petalinux-create -t module -n xvc-driver --enable 

This will create a recipe under the meta-user layer which we can use to define the module contents.

The first thing to do is edit the xvc-driver.bb file this file defines the location and names of the source files we wish to include to build the kernel module.

From the XVC download driver folder we need to copy the files xvc_driver_base.c, xvc_driver.c xvc_driver.h, xvc_ioctl.h, xvc_user_confg.h

SRC_URI = "file://Makefile \
           file://COPYING \
           file://xvc_driver_base.c \
           file://xvc_driver.c \
           file://xvc_driver.h \
           file://xvc_ioctl.h \
           file://xvc_user_config.h \
          "

Save the changes to the recipe file.

We also need to make changes to the make file also

obj-m := xvc-driver.o 
xvc-driver-objs := xvc_driver.o xvc_driver_base.o

We also need to changes to the kernel module source files.

xvc_driver.h requires the following to be added

#define LOG_PREFIX

While xvc_driver_base.c requires the following changes

#if KERNEL_VERSION(5, 4, 0) >= LINUX_VERSION_CODE 
        mmiowb(); 
#endif

The next step is to create the user space application, use the command

petalinux-create -t apps -n xvc-driver --enable 

Similar to the kernel module this will create a new recipe under the meta-user layer under recipes-apps folder.

From the XVC clone, user area copy across the following files to the xvcServer recipe under the recipe-apps area of the meta-user layer.

• xvcServer.c
• xvc_ioctl.h

Edit the user application recipe as below

SRC_URI = "file://xvcServer.c \ 
           file://xvc_ioctl.h \
           file://Makefile \
          "

DEPENDS = "\
    xvc-driver \
    "

With these changes made the final stage is to modify the user system device tree to include the debug bridge and incorporate the bindings for the driver to be loaded.

&debug_bridge_0 {
        compatible = "xlnx,xvc";
};

With this completed we can issue the command to build PetaLinux

petalinux-build 

Once the build is completed we need to build the boot image also, this is created using the command

$ petalinux-package --boot --format BIN --fsbl /images/linux/zynqmp_fsbl.elf --u-boot /images/linux/u-boot.elf --pmufw /images/linux/pmufw.elf --fpga /images/linux/system.bit --force

This will provide the boot.bin copy the boot.bin boot.scr and image.ub onto a SD Card and insert it into the ZUBoard and boot.

Test with Vivado

Once the ZUBoard has booted and you have signed into PetaLinux using a terminal. We are then able to configure the ZUBoard run the xvcServer application, to do this first we need to load the kernel module and then the user space application.

To load the kernel module type

sudo modprobe xvc-driver 

Once this has been loaded the next step is to tart the xvcServer use the command

udo xvcServer &

We are now in a position that we are able to connect via Vivados hardware manager to the ZUBoard. Ensure the development machine and the ZUBoard are on the same network and that the <name>.ltx file is available.

The ltx file defines the connections of the ILAs within the design.

Within Vivado open the hardware manager - select new hardware target and then select Add Xilinx Virtual Cable using the XVC button.

Enter the hostname as given by the xvcServer running in the terminal

This should enable you to then open the connection and show the ILAs within the project.

When it first opens you may need to click on the debug hub and point it to the ltx file to ensure the signals and triggering options appear on the right hand side.

Once the ILA is loaded we can work with it as normal, using the XVC and Ethernet connection.

Wrap Up

This provides us a nice and simple way to use ILAs when we are running PetaLinux on our Zynq or Zynq MPSoC