Building a Project

The Mango PetaLinux projects are ready to build as-is. In the project root run petalinux-build. When the build finishes the boot image image.ub will be copied to <proj_root>/images/linux. This image.ub can be copied to the node’s SD card, or retrieved via TFTP when netbooting.

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/src/mango-wlan, then re-run petalinux-build to compile the updated module. The build flow always regenerates the boot images if the build succeeds.

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 Mango PetaLinux reference project requires BOOT.BIN and image.ub images. In a local PetaLinux project these files are generated in <proj_root>/images/linux after running petalinux-build (and packaging BOOT.BIN as described below).

Mango release archives also include a ready-to-boot sd_root folder containing pre-built BOOT.BIN and image.ub along with the required RPU binaries and a helper boot script. When building from a BSP-derived project, these files are generated in <proj_root>/images/linux by the commands below.

The sections below describe the contents of these images and how to generate these images after making changes to the reference project.

Required Binaries

The Mango reference design provides all required binaries to boot the design on the reference hardware platform. Users can re-generate all the binaries if desired.

Booting Linux on an MPSoC device requires the following binaries:

  • PMU Firmware
  • ARM Trusted Firmware (bl31)
  • First Stage Bootloader (FSBL)
  • 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)
  • Second stage bootloader (u-boot)

The BOOT.BIN file must be copied to a FAT-formatted SD card. Mango provides a pre-built BOOT.BIN with the reference design.

The BOOT.BIN file must be updated any time the FSBL or u-boot changes in the PetaLinux project. Typically this only occurs for changes to the PS/PL configuration in the Vivado FPGA design. For software-only changes or FPGA design changes which do not modify the PS configuration, there is no need to update BOOT.BIN.

To generate BOOT.BIN from a PetaLinux project, run petalinux-package --boot --u-boot --pmufw --force, confirm output:

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

The Xilinx tools support bundling the FPGA bitstream into BOOT.BIN via the petalinux-package --fpga option. Mango recommends not including the bitstream here, instead configuring the PL from Linux userspace after the node has booted. This simplifies iterating on the FPGA design.

image.ub

The second boot archive is a FIT image containing:

  • Device tree blob
  • Linux kernel image
  • RAM filesystem

Mango provides a pre-built image.ub with the reference design. The image.ub image can be loaded via the SD card or via TFTP.

This image is automatically generated by petalinux-build after any software or hardware changes. Find the newly built image.ub in <proj_root>/images/linux/.

FPGA Bitstream

The programmable logic (PL) section of the Xilinx device is configured with a bitstream. The bitstream is generated by the Vivado hardware synthesis/implementation tools. The Mango PetaLinux projects include a prebuilt bitstream that can be used without re-running the Vivado flow. The bitstream is stored in the PetaLinux project at <proj_root>/project-spec/hw-description/wlan_top_wrapper.bit.

Mango recommends configuring the PL when loading the rest of the design via the mango_wlan_util script (see Utilities).

The FPGA bitstream must be loaded into the PL before booting the MAC applications in the RPU cores, and before loading mango_wlan driver. Mango provides the mango_wlan_util script in the root filesystem to streamline this boot process.

If you re-run the hardware tools to generate a new bitstream, you must then:

  • Export the bitstream as an XSA file
  • Import the XSA file in the PetaLinux project
  • Re-create the MAC software Vitis workspace and rebuild the MAC applications
  • Rebuild the PetaLinux Project
  • Copy the updated binaries to the node

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 linux_dev application and CPU R5_1 runs the edca application.

Prebuilt elf binaries are provided in the PetaLinux reference projects.

Custom binaries can be built via Xilinx Vitis. Refer to MAC Software Workspace for creating the Vitis Workspace and compiling the applications.

In the Vitis workspace the elf binaries are located at components/wlan_mac_workspace/<app>/Debug/<app>.elf for each MAC application.