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
  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-2019.1/
│   │   ├── meta-mango-dev/
│   │   └── 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/
│       ├── nomac/
│       ├── nomac_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: Scripts and config files for the rootfs
  • 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.

Users wishing to modify the MAC software must create a Vitis workspace to compile new binaries. The workspace creation and build process is automated through scripts in the components/wlan_mac_workspace folder:

  1. Source the Vitis settings:

    source /path/to/vitis/settings64.sh

  2. Create the 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 uses the same hardware design as the PetaLinux project. The compiled binaries can be found in their respective application directories after building.

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 descroy_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.