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 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-dev/
│   │   ├── meta-mango-<PLATFORM>/
│   └── wlan_mac_workspace/
│       ├── build_apps.sh
│       ├── build_apps.tcl
│       ├── create_ws.sh
│       ├── create_ws.tcl
│       ├── destroy_ws.sh
│       ├── wlan-mac-sw/
│       └── wlan-sdk/
└── project-spec/
    ├── configs/
    ├── hw-description/
    └── 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.

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

Key recipes are listed below. The mango-mango layer provides additional recipes which adopt and customize packages from the Yocto repository.

Recipe Description
recipes-apps/mango-files Provides scripts and config files copied to the rootfs
recipes-kernel/mango-wlan Linux kernel driver for Mango 802.11 MAC/PHY

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. Mango provides this layer as an way for users to create custom recipes and integrate them into the reference project. By default 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. After creating a custom recipe it must be added to the project:

  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 SDK 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 an SDK workspace to compile new binaries.

The components/wlan_mac_workspace folder includes the MAC source code, SDK project definitions, and scripts to create the SDK workspace. The workspace creation script should be run once. The resulting workspace can then be used via the SDK GUI and xsct terminal. The SDK workspace uses 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. low_dcf
    3. 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.

The SDK compiles binaries to wlan-sdk/Projects/<app_name>/Debug/<app_name>.elf for each application.

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. Close any instances of the Xiilnx SDK
  2. Copy the updated HDF file to a temporary folder on the PC running the PetaLinux tools. Ensure the new HDF file is the only HDF file in this folder. Do not copy the new HDF file directly into the PetaLinux project folder.
  3. In the PetaLinux project run petalinux-config --get-hw-description <path_to_HDF_dir> where <path_to_HDF_dir> is the folder containing the new HDF file.
  4. An interactive project config menu will show in the terminal. Typically no changes are required here; select the Exit button.
  5. Rebuild the PetaLinux project with petalinux-build.

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

  1. Close the Xilinx SDK
  2. cd <proj_root>/components/wlan_mac_workspace
  3. Run ./destroy_ws.sh
  4. Re-create the SDK 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 SDK 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.