2.4. PetaLinux Projects

Xilinx PetaLinux is a Linux distribution and Yocto-based build system for building custom Linux designs on Xilinx devices. Mango provides PetaLinux projects for reference hardware platforms. Mango also provides Yocto layers, applications, and utility scripts that can be used to quickly adopt the Mango 802.11 MAC/PHY design on a custom hardware platform.

The Mango PetaLinux projects include ready-to-run images which bundle the reference MAC/PHY/kernel designs. Each hardware platform has specific requirements for booting Linux. Refer to the section for each hardware platform for details.

The PetaLinux tools must be installed to rebuild the kernel, modules, or rootfs. The current 802.11 MAC/PHY design uses Xilinx PetaLinux 2019.1. The ready-to-boot images can be used without installing the PetaLinux tools.

The guide below assumes familiarity with the fundamentals of the PetaLinux distribution and build environment. New users should review the Xilinx PetaLinux documentation. Some resources:

Be sure to use the PetaLinux documentation for the same version used in the Mango 802.11 reference projects. The current reference projects are built in PetaLinux 2019.1.

PetaLinux Project

A PetaLinux Board Support Package (BSP) is a full PetaLinux project incorporating a kernel configuration, customized root filesystem, and custom Yocto layers, packaged into a portable archive. Mango provides a PetaLinux BSP for each of its reference platforms.

Note

The term “BSP” is also used as the hardware abstraction layer in the bare-metal software compilation flow in the Xilinx SDK. The SDK BSP and PetaLinux BSP are completely different things, despite sharing a name.

This section provides a brief introduction to expanding and building the PetaLinux BSPs provided by Mango. Refer to the Xilinx PetaLinux docs for more details on creating and using BSPs.

Create Project from the BSP

  1. Download the .bsp archive for your hardware platform
  2. Initialize the PetaLinux tools: source <path_to_petalinux>/settings64.sh
  3. Expand the BSP to a new project folder: petalinux-create -t project -s <path_to_bsp>/<bsp_filename>.bsp The folder and project name will use the default name used in the creation of the BSP. To specify your own name, use petalinux-create -t project -s <path_to_bsp>/<bsp_filename>.bsp -n <proj_name>

The new project is ready to be configured and built using the standard petalinux-config and petalinux-build commands.

Project Structure

The Mango 802.11 reference PetaLinux project has the following structure:

project_root/
├── components/
│   ├── meta-mango-wlan/
│   │   ├── meta-mango
│   │   ├── meta-mango-<PLATFORM>
│   │   ├── meta-mango-dev
│   └── wlan_mac_workspace
│       ├── create_ws.sh
│       ├── create_ws.tcl
│       ├── wlan-mac-sw
│       └── wlan-sdk
├── config.project
└── project-spec

This is the standard layout for a PetaLinux project with some Mango-specific additions to the components folder, detailed below.

Yocto Layers

The meta-mango-wlan folder contains Yocto layers which provide the Mango-specific code for the PetaLinux project. The source code for recipes provided by these layers can be in place. The modified code will be built by the next run of petalinux-build.

meta-mango Layer

The meta-mango layer provides recipes and source for kernel modules, utility scripts, and config files used by the reference PetaLinux projects for all platforms.

The source code for each recipe is in the files subfolder inside the recipe folder.

Recipe Description
recipes-apps/mango-files Provides scripts and config files copied diretly to the rootfs
recipes-apps/wlan-msg-net-server Mango application for acting as server side of remote Linux driver
recipes-kernel/mango-wlan Mango 802.11 wireless network interface Linux driver
recipes-kernel/mango-wlan-msg-fifo Driver for message FIFO connecting mango_wlan to MAC
recipes-core/base-files Creates a mount point for SD card
recipes-core/init-ifupdown Provides /etc/network/interfaces config file copied to rootfs
Platform-specific meta-mango- Layers

There is a separate meta-mango-PLATFORM for each supported reference platform. For example the meta-mango-ZCU layer provides recipes for the Xilinx MPSoC ZCU104 reference project.

Custom Development meta-mango-dev Layer

The meta-mango-dev layer is included the PetaLinux project search path by default. As provided, this layer contains a single recipe.

Recipe Description
recipes-apps/misc-files Copies a README directly to the rootfs and serves as an example of how to use a Yocto recipe to copy files.

Users can add custom Yocto recipes to meta-mango-dev. The process of including a new recipe into the build requires two steps:

  1. Modify <proj_root>/project-spec/meta-user/recipes-core/images/petalinux-image-full.bbappend to include the name of the new recipe.
  2. Execute petalinux-config -c rootfs and navigate to the user packages   ---> menu. The recipe named in petalinux-image-full.bbappend will appear and should be selected like the other custom recipes.

MAC Software Workspace

The Mango 802.11 MAC software always runs in dedicates CPUs. On Zynq-7000 devices the MAC runs in two MicroBlaze CPUs in the PL. On MPSoC/RFSoC devices the MAC runs in the two ARM R5 CPUs in the RPU subsystem. In both cases the MAC software must be compiled in the Xilinx SDK to create binary executables for the MAC CPUs.

The components/wlan_mac_workspace folder includes the MAC source code, SDK project definitions, and scripts to create the SDK workspace. The SDK creation scripts should only be run once. The resulting workspace can then be used via the SDK GUI. The SDK workspace will always use the same Vivado hardware design as the PetaLinux project.

To create the SDK workspace:

  1. Source the Xilinx SDK settings: source /path/to/SDK/2019.1/settings64.sh
  2. cd <proj_root>/components/wlan_mac_workspace
  3. Run bash ./create_ws.sh
  4. Launch the Vivado SDK: xsdk. A window titled Eclipse Launcher will appear. Click Browse… and navigate to the wlan_mac_workspace folder then click OK.
  5. The SDK will open. Look for the Project Navigator tab and verify there is one hardware are three projects listed:
    1. One hardware project, usually named wlan_top_hw
    2. Two BSP projects named wlan_bsp_cpu_high and wlan_bsp_cpu_low
  6. Select File ‣ Import…. A new window will appear. In this window, select General ‣ Existing Projects into Workspace and click Next.
  7. In the Import Projects window, ensure the following options are not checked.
    1. Search for nested projects
    2. Copy projects into workspace
  8. Click Browse… next to Select root directory:. Navigate to wlan_mac_workspace/wlan-sdk and click OK. The list will update to show projects that will be imported. Select the desired projects then click Finish. The high_linux_dev and low_dcf projects are required, the other projects are optional.
    1. high_linux_dev
    2. high_standalone_ap
    3. high_standalone_ibss
    4. high_standalone_sta
    5. low_dcf
    6. low_nomac
  9. Close the SDK Welcome tab (if shown). The SDK Project Explorer tab will list all projects (one hardware, two BSPs, multiple applications).

At this point the SDK Workspace is ready to use for development and debug of the MAC applications.

Building the PetaLinux Project

The Mango PetaLinux projects are ready to build as-is. In the project root run petalinux-build. When the build finishes the boot images will be copied to /tftpboot for retrieval by u-boot via TFTP.

The PetaLinux build system uses caching to speed the build process. Generally petalinux-build will only rebuild components that have changed since the previous build. For example, to iterate on the mango_wlan driver module, edit the source in components/meta-mango/recipes-kernel/mango-wlan, then re-run petalinux-build to compile the updated module. The build flow always regenerates the boot images and copies them to /tftpboot.

The petalinux-build command has many optional arguments. For example petalinux-build -c mango_wlan -x do_devshell will launch a new shell in the mango_wlan build folder with the complete cross-compilation environment setup. Refer to the PetaLinux documentation for more details.

Booting the PetaLinux Project

Booting Linux on a Xilinx device is a multi-step process that varies across different devices and boards. The sections below explain the high-level boot process for Zynq-7000 and Zynq UltraScale+ MPSoC/RFSoC devices. Refer to the user guide sections for the reference hardware platforms for specific boot requirements of each platform.

Booting MPSoC Nodes

Required Binaries

Booting Linux on an MPSoC device requires the following binaries:

  • PMU Firmware
  • ARM Trusted Firmware (bl31)
  • First Stage Bootloader (FSBL)
  • PL Bitstream
  • Second stage bootloader (u-boot)
  • RPU applications
  • Device tree blob
  • Linux kernel image
  • RAM filesystem

The Mango reference PetaLinux projects can generate all of these binaries, and the PetaLinux tools can package the binaries into a few archives that simplify the boot process.

BOOT.BIN

The first boot archive is BOOT.BIN which bundles:

  • PMU Firmware
  • ARM Trusted Firmware (bl31)
  • First Stage Bootloader (FSBL)
  • PL Bitstream
  • Second stage bootloader (u-boot)

Generate this archive by running petalinux-package --boot --u-boot --pmufw --fpga --force, confirm output:

Find BOOT.BIN in proj_root/images/linux/.

image.ub

The second boot archive is a FIT image containing:

  • Device tree blob
  • Linux kernel image
  • RAM filesystem

This image is automatically generated by petalinux-build. Find image.ub in proj_root/images/linux/.

RPU Applications

The MAC software runs in the two ARM R5 CPUs in the MPSoC RPU. One elf binary must be provided for each CPU. For normal 802.11 applications CPU R5_0 runs the high_linux_dev application and CPU R5_1 runs low_dcf application.

Prebuilt elf binaries are provided in the PetaLinux reference projects. These reference binaries are copied to /lib/firmware in the root filesystem by default (see Booting the Node below).

Custom binaries can be built via the Xilinx SDK. Refer to the “MAC Software Workspace” section above for creating the SDK Workspace and compiling the applications. In the SDK workspace the elf binaries are located at components/wlan_mac_workspace/wlan-sdk/projects/<app>/Debug/<app>.elf for each MAC application.

Booting the Node

The MPSoC device supports a variety of boot modes. The Mango 802.11 reference PetaLinux projects default to booting the node from an SD card.

  1. Format a micro-SD card with a single FAT32 partition
  2. Copy BOOT.BIN to the root of the SD card
  3. Copy image.ub to the root of the SD card
  4. (Optional) Copy custom RPU elf binaries to the SD card
  5. (Optional) Copy any other files to the SD card required for your application
  6. Configure your MPSoC board for SD boot (see user guide section for specific reference platform)
  7. Insert the SD card, power on the node, and watch the UART console output. A normal boot prints output from the FSBL, PMUFW, ATF, u-boot, and Linux. A login prompt will appear on the UART console when boot is finished.
  8. Login to Linux as root / root via the UART console or SSH
  9. (Optional) Copy custom MAC application elf binaries to the node using scp or to the SD card
  10. Boot the RPU, either with reference or custom elf binaries:
  1. Watch the UART output for RPU boot messages. On platforms with multiple UARTS (e.g. ZCU104) the R5 CPUs may print to a different UART than the Linux console.
  2. Load the Mango 802.11 driver with modprobe mango_wlan. Check the kernel log with dmesg to confirm the driver loaded successfully.
  3. Use the 802.11 wireless network interface like any other interface. The reference projects include some example scripts (run_ap.sh, run_monitor.sh, etc.) and utility programs (tcpdump, etc.).