Project Overview

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 Xilinx Vitis. The Vitis 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

  1. Expand the BSP to a new project folder:

petalinux-create -t project -s <path_to_bsp>/<bsp_filename>.bsp -n <proj_name>

The <proj_name> can be any name you choose.

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/
│   │   └── src/
│   └── wlan_mac_workspace/
│       ├── build_apps.sh
│       ├── build_apps.tcl
│       ├── create_ws.sh
│       ├── create_ws.tcl
│       ├── destroy_ws.sh
│       ├── edca/
│       ├── edca_system/
│       ├── linux_dev/
│       ├── linux_dev_system/
│       └── wlan-mac-sw/
└── project-spec/
    ├── configs/
    ├── hw-description/
    │   ├── system.xsa
    │   ├── wlan_top_wrapper.bit
    └── meta-user/

This is the standard layout for a PetaLinux project with some Mango-specific additions to the components and project-spec folders, 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 edited 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.

Key recipes are organized into the following categories:

Category Description
recipes-apps

Applications including:

  • mango-wlan-nl-ref: A reference userspace application demonstrating direct netlink interface with the driver
  • hostapd, network tools, and other reference implementations
recipes-benchmark Performance testing tools like iperf3
recipes-connectivity Network connectivity packages like wpa-supplicant
recipes-core Core system files and services
recipes-devtools Development tools including Lua and Python packages
recipes-kernel Linux kernel customizations
recipes-mango

Mango-specific packages including:

  • mango-files: Minimal scripts and configs installed to the rootfs:
    • mango_wlan_util
    • run_ap.sh
    • run_monitor.sh
    • run_sta.sh
    • stop_ap.sh
    • stop_monitor.sh
    • stop_sta.sh
    • hostapd.conf
    • wpa_supplicant.conf
  • mango-wlan: Linux kernel driver for Mango 802.11 MAC/PHY

The source code for all Mango recipes is centralized in the meta-mango-wlan/src directory.

MAC Software Vitis Workspace

The Mango 802.11 MAC software always runs in dedicated CPUs. On MPSoC/RFSoC/Versal devices the MAC runs in the two ARM R5 CPUs in the RPU subsystem.

The PetaLinux project includes pre-compiled MAC binaries. The MAC source code is in the components/wlan_mac_workspace/wlan-mac-sw folder. The source can be modified and re-compiled using the Xilinx Vitis tools.

Vitis requires a “workspace” containing “platform” and “system” projects in order to compile the RPU applications. Mango provides scripts to simplify assembling this workspace and compiling the applicatinos.

  1. Source the Vitis settings:

    source /<Xilinx Tools Path>/vitis/settings64.sh

  2. Create the Vitis workspace:

    <proj_root>/components/wlan_mac_workspace/create_ws.sh

  3. Build the applications:

    <proj_root>/components/wlan_mac_workspace/build_apps.sh

The workspace must be re-created anytime the FPGA harddware design is updated (i.e. after running petalinux-config --get-hw-description).

The RPU binaries must be re-compiled whenever workspace is updated, or after any changes to the MAC software source code.

The compiled RPU binaries are elf files ready for use in hardware:

<proj_root>/components/wlan_mac_workspace/linux_dev/Debug/linux_dev.elf <proj_root>/components/wlan_mac_workspace/edca/Debug/edca.elf

These elf files must be copied to the node to boot the updated MAC software.

Importing new FPGA Design

Mango provides pre-built FPGA designs for supported hardware platforms. If you modify and re-implement the FPGA design in Vivado the updated FPGA design must be imported into the PetaLinux project. Refer to the Vivado Project page for details on rebuilding the FPGA design.

  1. Copy the updated XSA file to a temporary folder on the PC running the PetaLinux tools. Ensure the new XSA file is the only XSA file in this folder. Do not copy the new XSA file directly into the PetaLinux project folder.
  2. In the PetaLinux project run petalinux-config --get-hw-description <path_to_XSA_dir> where <path_to_XSA_dir> is the folder containing the new XSA file.
  3. An interactive project config menu will show in the terminal. Typically no changes are required here; select the Exit button.
  4. Rebuild the PetaLinux project with petalinux-build.

The MAC software Vitis workspace must also be updated with the new FPGA design. The safest option is to re-create the Vitis workspace from scratch after adopting the new XSA in the PetaLinux project. This process does not lose any customizations to the MAC software source code in the wlan-mac-sw folder.

  1. cd <proj_root>/components/wlan_mac_workspace
  2. Run ./destroy_ws.sh
  3. Re-create the Vitis workspace via the MAC Software Workspace process above.

The destroy_ws.sh script does not delete any source code. It only deletes the auto-generated BSP projects and Xilinx Vitis metadata stored in the wlan_mac_workspace folder. The BSPs and metadata will be re-created by the create_ws.sh script, adopting the source code in wlan-mac-sw.