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¶
- Download the
.bsp
archive for your hardware platform- Initialize the PetaLinux tools:
source <path_to_petalinux>/settings64.sh
- 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, usepetalinux-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:
- Modify
<proj_root>/project-spec/meta-user/recipes-core/images/petalinux-image-full.bbappend
to include the name of the new recipe. - Execute
petalinux-config -c rootfs
and navigate to theuser packages --->
menu. The recipe named inpetalinux-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:
- Source the Xilinx SDK settings:
source /path/to/SDK/2019.1/settings64.sh
cd <proj_root>/components/wlan_mac_workspace
- Run
bash ./create_ws.sh
- Launch the Vivado SDK:
xsdk
. A window titledEclipse Launcher
will appear. Click Browse… and navigate to thewlan_mac_workspace
folder then click OK. - The SDK will open. Look for the Project Navigator tab and verify there is one hardware are three projects listed:
- One hardware project, usually named
wlan_top_hw
- Two BSP projects named
wlan_bsp_cpu_high
andwlan_bsp_cpu_low
- One hardware project, usually named
- Select Next. . A new window will appear. In this window, select and click
- In the Import Projects window, ensure the following options are not checked.
Search for nested projects
Copy projects into workspace
- Click Browse… next to
Select root directory:
. Navigate towlan_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. Thehigh_linux_dev
andlow_dcf
projects are required, the other projects are optional. high_linux_dev
high_standalone_ap
high_standalone_ibss
high_standalone_sta
low_dcf
low_nomac
- Click Browse… next to
- 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.
- Format a micro-SD card with a single FAT32 partition
- Copy
BOOT.BIN
to the root of the SD card - Copy
image.ub
to the root of the SD card - (Optional) Copy custom RPU
elf
binaries to the SD card - (Optional) Copy any other files to the SD card required for your application
- Configure your MPSoC board for SD boot (see user guide section for specific reference platform)
- 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.
- Login to Linux as
root / root
via the UART console or SSH - (Optional) Copy custom MAC application
elf
binaries to the node usingscp
or to the SD card - Boot the RPU, either with reference or custom
elf
binaries:
- 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.
- Load the Mango 802.11 driver with
modprobe mango_wlan
. Check the kernel log withdmesg
to confirm the driver loaded successfully. - 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.).