Building Custom SDSoC Platform with PetaLinux

Disclaimer: This tutorial extends the Xilinx tutorial “SDSoC Platform Creation Labs” with details of PetaLinux setup and some quirks of Ultra96. Thus, many images and text have been reused here from original tutorial and Xilinx manuals, links to which are present in last section of this tutorial.

Assumptions: This tutorial assumes basic knowledge of Vivado and SDSoC tool flows and is designed for advance users of SDSoC.

Introduction

The SDSoC™ development environment provides the tools necessary for implementing heterogeneous embedded systems using the Zynq®-7000 SoC or the Zynq UltraScale+™ MPSoC devices.

This tutorial shows how to create an SDSoC platform on which an example SDSoC application is created and run. The Vivado® Design Suite is used to create the hardware platform and the SDx™ Integrated Design Environment (IDE) is used to build the software platform including an SDSoC application.

The concept of a platform is integral to the SDSoC environment and it defines the hardware, software, and meta-data components that SDSoC applications build upon. An SDSoC platform defines a base hardware and software architecture along with an application context, including the processing system, external memory interfaces, custom input/output, and software runtime. The software runtime may include an operating system (possibly “bare metal”), boot loaders, drivers for platform peripherals and a root file system. Every project you create within the SDx environment targets a specific hardware platform and utilizes tools such as the sds++/sdscc (referred to as sds++) system compiler to customize the platform’s application-specific hardware accelerators and data motion networks.

In this tutorial, you will be guided through four labs that target a Zynq UltraScale+ MPSoC-based ZCU102 / Ultra96 board operating in a standalone or bare metal software runtime environment. Step-by-step instructions are provided on how to build the hardware and software components that constitute a platform:

• Create the hardware component known as the Device Support Archive (DSA) for a platform.- The DSA contains the IP integrator hardware design and the design meta-data properties.
• Create the PetaLinux Image for the software platform of SDSoC.
• Create the SDSoC platform by defining the software components, and matching them to the hardware DSA.- Use the SDx IDE and its four (4) step process to create a custom platform.
• Create and run an SDSoC hardware accelerated application on the new platform.

Platforms supported by the Zynq family of devices combine an Arm-based processor system (PS) with high performance programmable logic (PL) to develop products that can be optimized by partitioning the system design across hardware and software. The figure below shows the high-level Zynq device features on which platforms are created.

Zynq-based platforms can utilize the PS Arm processor cores, the integrated PS I/O (MIO) peripheral blocks, the PS external DDR memory controller, the multitude of configurable PS to PL and PL to PS interfaces, as well as logic blocks designed for the PL.

Maintained version of this tutorial can be found here: https://docs.google.com/document/d/16nauyelKHW9XDt-uB9zhCefaJ70Ko4I8l4dmKpV7aXs/edit?usp=sharing

Step 1. Hardware Platform : Create Logical design and export it as DSA

• Create a Project with Board
• Create Block design
• Instantiate Zynq core
• Apply preset

• Do not use "Run automation" directly for next steps (It may select wrongly)
• Create Clock with different frequencies (up to 7 for least routing errors)

• Create Processor reset for each

• Create 2 Concat 1-bit wide

• Instantiate your custom IPs
• Remove AXI ports which are not needed from Zynq IP
• Add IRQ 2 of 8-bit wide in Zynq

• Configure the Clocks as needed- Select Reset Type: Active Low

• Connect them all appropriately by hand

• Enable the Platform Interfaces Tab- Window -> Platform Interfaces -> Enable platform interfaces

• Identify PFM properties for exposed APIs (Enable)- Clocks- IRQs- AXI buses

• Set 100 MHz clock as default in PFM property window

• Save and Validate Block design
• Create HDL wrapper (Automatic)
• Generate bitstream
• Export hardware including bitstream (create HDF as normal)

• Generate DSA

write_dsa -force -include_bit /<PATH>/<BLOCK_DESIGN_NAME>.dsa

• Validate DSA

validate_dsa /<PATH>/<BLOCK_DESIGN_NAME>.dsa

Visual tutorial for basic design can be found here:

https://github.com/Xilinx/SDSoC-Tutorials/blob/master/platform-creation-tutorial/Lab3-Creating-Custom-Platform-Using-the-SDx-IDE.md

Step 2: Creating Petalinux for SDSoC

Before starting, you should complete the following:

1. Set up your shell environment with PetaLinux tools in your PATH environment variable.2. Create and cd into a working directory.

3. Create a new PetaLinux project targeting a BSP that corresponds to the type of board you are targeting:

petalinux-create –t project -n < project_name > -s <path_to_base_BSP>

4. Obtain a copy of the hardware handoff file (.hdf) from the Vivado project for your hardware platform.

Building the PetaLinux Image

1. Configure PetaLinux with the HDF derived earlier for the associated platform (the production of which is described in the introduction):

petalinux-config -p < petalinux_project > --get-hw-description= <HDF path>

2. Configure PetaLinux kernel:

petalinux-config -p < petalinux_project > -c kernel

Set CMA size to be larger, for SDS-alloc buffers:

• for Zynq MPSoC: Device Drivers→ Generic Driver Options → Size in MB(1024)• for Zynq-7000: Device Drivers→ Generic Driver Options → Size in MB(256)

Enable staging drivers:

• Device Drivers → Staging drivers (ON)

Enable APF management driver:

• Device Drivers → Staging drivers → Xilinx APF Accelerator driver (ON)

Enable APF DMA driver:

• Device Drivers → Staging drivers → Xilinx APF Accelerator driver → Xilinx APF DMA engines support (ON)

Note :

For Zynq MPSoC, you must turn off CPU idle and frequency scaling. To do so, mark the following options:

• CPU Power Management->CPU idle->CPU idle PM support (OFF)• CPU Power Management->CPU Frequency scaling->CPU Frequency scaling (OFF)

3. Configure petalinux rootfs:

petalinux-config -p < petalinux_project > -c rootfs

Add stdc++ libs:

• Filesystem Packages → misc → gcc-runtime → libstdc++ (ON)

4. Add device tree fragment for APF driver. At the bottom of <>/project-spec/meta-

user/recipes-bsp/device-tree/files/system-user.dtsi, add the following entry:

/{
    xlnk {
    compatible = "xlnx,xlnk-1.0";
    };
};

5. Build the PetaLinux image:

petalinux-build

Preparing the Image for the SDSoC Platform Utility

In the directory <petalinux_project >/images/linux/ there are a number of important files that are partitioned into two categories:

1. Files that end up compiled into BOOT.BIN, referred to collectively as ‘boot files’, that should be copied into a boot folder. Boot files include the following: u-boot.elf, zynq-fsbl.elf or zynqmp-fsbl.elf, along with bl31.elf and pmufw.elf for Zynq UltraScale+ devices.

2. Files that must reside on the SD card but are not compiled into BOOT.BIN, referred to as ‘image files’, that should be copied into an image folder. The only image file from a PetaLinux build is image.ub, but you can add other files to the image folder that you want to make available to users of the platform.

From within the <petalinux_project >/images/linux/ folder run the following commands:

mkdir ./boot
mkdir ./image
cp u-boot.elf ./boot/u-boot.elf
cp *fsbl.elf ./boot/fsbl.elf
cp bl31.elf ./boot/bl31.elf
cp linux/pmufw.elf ./boot/pmufw.elf
cp image.ub ./image/image.ub

3. Finally, create a boot image format, or BIF file, that is used to compile the contents of the boot

folder into a BOOT.BIN file.

The following is an example BIF for a Zynq-UltraScale+ MPSoC device:

the_ROM_image:
{
    [fsbl_config] a53_x64
    [bootloader]<fsbl.elf>
    [pmufw_image]<pmufw.elf>
    [destination_device=pl] <bitstream>
    [destination_cpu=a53-0, exception_level=el-3, trustzone] <bl31.elf>
    [destination_cpu=a53-0, exception_level=el-2] <u-boot.elf>
}

Taken together, the boot directory, the image directory, and the BIF file, constitute the software elements that the SDSoC platform project needs as input for the Linux OS.

For SDSoC 2018.3 and above with PetaLinux

Libsds_lib.so needs to be dynamically linked. It can be found in:

<SDX_Install_Dir>/target/<architecture>-linux/lib

1. Ensure that the pre-compiled code has been compiled for your PetaLinux target architecture (For example, MicroBlaze, Arm etc.).

2. Create an application with the following command.

petalinux-create -t apps --template install --name mylib --enable

3. Change to the newly created application directory.

cd <plnx-proj-root>/project-spec/meta-user/recipes-apps/mylib/files/

4. Remove existing mylib file and copy the prebuilt mylib.so into mylib/filesdirectory.

rm mylib
cp <path-to-prebuilt-libsds_lib.so.so> ./

5. Edit <plnx-proj-root>/project-spec/meta-user/recipes-apps/mylib/mylib.bb. The file should look like the following.

#
# This file is the libsds_lib recipe.
#
SUMMARY = "Simple mylib application"
SECTION = "PETALINUX/apps"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
SRC_URI = "file://libsds_lib.so \
   "
S = "${WORKDIR}"
TARGET_CC_ARCH += "${LDFLAGS}"
do_install() {
    install -d ${D}/${libdir}
    install -m 0755 ${S}/libsds_lib.so ${D}${libdir}
}
FILES_${PN} += "${libdir}"
FILES_SOLIBSDEV = ""

6. Run

petalinux-build -c rootfs.

7. Repeat the process for libsds_lib_dbg.so

Look at guide UG 1146 Chapter 4, Linux Boot files, Page 48 in v2017.4 or newer one for details

Step 3. Software Platform: Create a platform from SDSoC indicating the OS/standalone support available

• Import DSA

• Set up Standalone/Linux configuration and domains.- [Standalone] Use prebuilt components to point to Boot files generated from SDK/Petalinux -> make sure BSP is configured correctly for the board- [Linux] Point them to the Boot dir and BIF file created from Petalinux- Modify Stack and Heap space if needed.- Generate Platform

Step 4. Applications: Building applications on custom platform

• Create new SDSoC Application Project and select the custom platform

• Write your application or select from the Xilinx Examples
• Build as normal SDSoC application

• In case of M_AXI_GM not found error. Make sure the Block design and DSA and platform name are same.

ERROR: [DMAnalysis 83-4503] No M_AXI_GP port found in the platform!

• copy contents of SD_CARD dir to sd card- In the Assistant view, right-click SD Card Image and select Open > Open in File Browser

• make sure rootfs if already copied onto sd card

sudo cp rootfs.cpio /media/<USER_NAME>/rootfs
cd /media/<USER_NAME>/rootfs
sudo pax -rvf rootfs.cpio
cd -
sync

• put sd card on board and make sure the boot mode is set to sd_card (Ultra96: OFF ON) look at output on UART

sudo screen /dev/ttyUSB1 115200

• login with user: “root” password: “root”
• If you are not using the Wifi or Bluetooth, in order to help keep our terminal clear of unnecessary messages, run

ifconfig wlan0 down
ifconfig wlan1 down

• mount sdcard

cd /media
mkdir sdcard
mount /dev/mmcblk0p1 /media/sdcard/

• execute application

cd /media/sdcard/
./ <project Name>.elf

For Ultra96

• Special BSP need to be created with changes from uart_0 to uart_1
• Make sure you have the right board files (ultra96v1 / ultra96v2) in Vivado installation dir
• Default BSP for Petalinux is for 2018.2 not 2018.3
• Details of how to make a BSP for Petalinux 2018.3 can be found at the following link: https://github.com/Avnet/Ultra96-PYNQ
  Note, it has a bug and workaround included for Ultra 96.
• Standalone SDSoC tutorial project does not compile with error no M_AXI_GM port found. This is due to difference in the name of their block design and platform name. Use Petalinux tutorial files instead for FSBL

Adding I/Os to Ultra96:

• Connecting Monitor- Use mini-display port (20 pin Male) to VGA adapter (15 pin Male)
• Connecting Keyboard and mouse:- Plug in the USB ports

Advance features

Example designs for following features can be found in UG1146 Manual from Xilinx.

• Direct I/O in an SDSoC Platform (converting I/O into AXI stream)
• Sharing a Platform IP AXI Port

Weird unsolved errors

Sometimes screen/minicom do not get/send all the bytes from UART on Linux host. I encountered it after configuring the rootfs differently. Error is not stable and keeps changing.

Work-around:

• Re-install cable drivers with no FPGA USB cables attached.
• Build Petalinux, platform and application again.
• Update SDCard entirely.

Links

Xilinx tutorial:

https://github.com/Xilinx/SDSoC-Tutorials/tree/master/platform-creation-tutorial

SDSoC platform development manual:

https://www.xilinx.com/support/documentation/sw_manuals/xilinx2018_3/ug1146-sdsoc-platform-development.pdf

PetaLinux:

https://www.xilinx.com/support/documentation/sw_manuals/xilinx2018_2/ug1144-petalinux-tools-reference-guide.pdf

Ultra 96 (board files, BSP and tutorials):

http://zedboard.org/support/design/24166/156

Maintained version of this tutorial:

https://docs.google.com/document/d/16nauyelKHW9XDt-uB9zhCefaJ70Ko4I8l4dmKpV7aXs/edit?usp=sharing