This page is a How To/ User Guide to accompany the AMD Yocto Native BSP, allowing users to boot AMD Evaluation boards with Yocto based pre-built Images, and to re-build or extend those images.

Table of Contents

Introduction

What is a Yocto Native Board Support Package?

A Yocto Native Board Support Package (BSP) is a BSP for AMD Evaluation boards, intended as a starting point for development work for custom software or hardware designs. They are built in a Yocto environment using System Device Tree (SDT) based development flows. All BSPs include:

• A pre-built system image which will boot the Evaluation Board to Linux and configure the Programable Logic with an example design Index of /sswreleases/rel-v2024.2/Yocto_Native_BSP

• A build script to generate the Vivado™ hardware design project and artifacts used by the pre-built system image https://github.com/Xilinx/amd-yocto-hw-platforms/tree/xlnx_rel_v2024.2

• Yocto Machine Configuration Layers and recipes to build and package the embedded software and hardware artifacts into a bootable system imagehttps://github.com/Xilinx/yocto-manifests

Intent of this page

The intent of this page is to allow users to:

• Boot AMD Evaluation boards to Linux and configure the Programable Logic using the provided pre-built system images

• Re-build the pre-built system image including re-generating all hardware and software artifacts

• Understand the basic steps to extend the pre-built system images (Programable Logic content or Embedded Software) and create a new system image

• Locate additional resources to enable further exploration or re-targeting of these flows to custom boards as part of a Yocto based pathway to release of a production system.

Release Information

System Boot Architecture and Default Image configuration

System Boot Architecture

AMD Yocto native BSP Images use a multi-stage boot process using Segmented Configuration on Versal™ devices. Boot starts with the bootROM on the device and then passes on to either the First Stage Boot Loader (FSBL) or Platform Management Controller (PMC) and Platform Management Controller executable (PLM) dependent on the hardware architecture ( Zynq™ UltraScale+™ MPSoCs or Versal™).  Once this step is complete, they hand off to Arm Trusted Firmware, and then U-boot which handles loading Linux.  The Programable Logic (PL) firmware is loaded from the Linux user space as a Device Tree Overlay (.dtbo) using the fpgautil command line utility.   

For details on the boot and configuration process, please see the following documentation:

• Zynq UltraScale+ MPSoCs:  Boot Process Overview • Zynq UltraScale+ MPSoC Software Developer Guide (UG1137) • Reader • AMD Technical Information Portal

• Versal: Boot and Configuration • Versal Adaptive SoC System Software Developers Guide (UG1304) • Reader • AMD Technical Information Portal

Example Vivado Hardware design

The AMD Yocto Native BSPs are targeted to a specific board and a specific SoC (PS and NOC) configuration. The configurations are contained within and automated at this repository.  For detail on the specific configuration, re-generate and view the Hardware design in Vivado following the steps here.

To replicate the steps to manually create the design or modify the hardware configuration, you will need to create a hardware project in Vivado, export it to .xsa  and then convert that .xsa  into a system device tree directory. These steps are covered in the relevant sections below.

Future content to follow, see https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3138977818/AMD+Yocto+Native+Board+Support+Packages#Future-content-to-follow%3A

Default Embedded Software Image Configuration

The configuration of the Embedded Software Image, Linux Kernel, RootFS, boot loaders and other items are contained in the Yocto Machine configurations and related configuration and setting files. Please see the relevant recipes and configuration files mentioned in the build sections for more information.

Future content to follow, see https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3138977818/AMD+Yocto+Native+Board+Support+Packages#Future-content-to-follow%3A

How to boot a board using the pre-built Images : SD Mode

1. Writing the Image to the boot media

The .wic.xz pre-built images (Seehttps://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#Release-Information) can be written to an SD card using either an application such as balenaEtcher or a command line utility such as 'dd'.   

Depending on the tool used, the .xz archive may need to be un-archived before it can be written.

BaleneEtcher : Follow the on-screen prompts to select the input file and output path.

Open

dd: Standard dd commands can be used (see dd command line help). If the target system is already booted to Linux, the image could be transfers to the Target system via Ethernet, and 'dd' could be run on the target. Below is example output using dd running on the target: Note: in the example below xzcat is being used to un-archive the .wic.gz prior to being passed to dd for writing to the boot media

2. Booting the Board to Linux

Once the image has been written to the boot media, boot the board using the boot settings for the boot source as documenting the relevant board user guide.

3. Loading the pre-built Programable Logic (PL) firmware

The pre-built images contain example PL firmware which can be loaded / configured from Linux user space as a Device Tree Overlay using the fpgautil Linux command line utility.   Once Linux has booted to user space the commands below can be used to configure the PL fabric.

# fpgautil -b /lib/firmware/xilinx/<.bin/.pdi> -o /lib/firmware/xilinx/<Device Tree Overlay>.dtbo 

Example Commands and Logs ZCU104

Example Commands and Logs VEK280

How to re-build the embedded software Images using pre-built hardware artifacts

1. Setting up the Yocto Environment to build the embedded software images

AMD provides a repo  tool manifest file for its Yocto Native BSP build environment to help ensure all layers needed for build are available and in sync. To recreate or re-build the BSP's, or for related projects, this manifest provides a recommended starting point. Refer to the AMD Xilinx Yocto wiki page for release versions, features, known issue and limitations.

Set up the Yocto environment using the repo tool:

2. Generating the Yocto Machine

The gen-machineconf tool provided by AMD is used to convert AMD style hardware description information ('System Device-tree Directory' created by the SDTGen Tool) into a Yocto style machine configuration.

• gen-machineconfis a Yocto environment tool included in meta-xilinx, and is separately downloadable.

• gen-machineconf can be re-run to update a machine configuration if the System Device-tree Directory has been updated.

• A pre-built 'System Device-tree Directory' is provided as part of the Yocto Native BSP for a board demonstrating the possible separation between the hardware and software build processes.

Use gen-machineconf to create a machine using a downloaded pre-built 'System Device-tree Directory'

See the readme for gen-machineconf for more information (Ensure you select the appropriate release branch - AMD does not use main as a development branch) :  https://github.com/Xilinx/gen-machine-conf

3. Building the image

Build the image using standard Yocto commands:

The generated SD images <yocto build directory>/tmp/deploy/images/<machine name specified on gen-machineconf command>/ can now be written to boot media and the board booted following https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#How-to-boot-a-board-using-the-pre-built-Images-%3A-SD-Mode

How to regenerate the Vivado Hardware Design, .xsa and System Device-tree Directory

AMD Yocto native BSPs are targeted to a specific board and use a multi-stage boot process that uses Segmented Configuration on Versal devices. This allows PL load to be deferred until Linux user mode, and for a different PL.pdi to be used with a common base.pdi for a specific SoC (PS / NOC) configuration. See https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#System-Boot-Architecture

The AMD Yocto native BSPs specific SoC (PS and NOC) configurations are defined within a board specific Vivado Hardware design, and are available and automated in this repository. 

• There is a base project for each board

• There might be multiple PL examples available, all built on the same common base.

Recommended Starting point: Re-Create the pre-built Vivado hardware project and .xsa (with no modifications).

Covered in later sections

• https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#Modifying-PS-%2F-NOC-Configuration-%3A--Full-Custom-flow-%3A--The-End-to-End-flow-for-custom-designs-where-the-Embedded-Software-image-must-be-re-built-and-may-also-require-changes-to-its-configuration-(new-boot.pdi-and-PL.pdi)

1. Recreating the pre-built Vivado hardware project and .xsa

The Vivado hardware design and .xsa for supported evaluation boards can be re-created and built using the AMD Tcl repo https://github.com/Xilinx/amd-yocto-hw-platforms

Follow the instructions in the amd-yocto-hw-platforms readme to recreate and compile the project https://github.com/Xilinx/amd-yocto-hw-platforms/blob/xlnx_rel_v2024.2/README.md

Example commands for generating the VEK280 Vivado Hardware design (following the steps in the linked readme above)

2. Generating the System Device-tree directory from the Vivado .xsa

AMD uses a two phase approach to hand over relevant files and information between the Hardware and Software development environments, and to create the Yocto Machine Configuration used in the embedded software image build.

1. The System Device Tree Generator SDTGen tool uses the Vivado Design output (.xsa) to generate a ‘System Device-tree Directory’ containing System Device Tree files (SDT), other firmware and configuration files extracted from the .xsa.

2. The gen-machineconf tool is then used with the System Device-tree Directory to create a Yocto Machine Configuration aligning industry standard approaches.

These processes use AMD provided Yocto "meta-" layers to carry out actions including the following:

• Re-creating the bootloader image binaries: The bootloaders generated by Vivado are effectively discarded.

• Copying the FPGA device image binaries (.bin,.pdi) into the correct locations so that they are available to the bootgen tool for inclusion in the new PDI file created by the Yocto Image build.

• Converting the system level hardware description (system device tree .sdt) into a device tree(s) appropriate for the OS being targeted (in this case Linux). This process consists of removing hardware that is not accessible to the targeted OS, as well as converting the device tree from a generic form into the form needed by the OS (this might include renaming, removing, or converting parameters for each device) 

Generate System Device-tree directory from the XSA

If you have generated your design from https://github.com/Xilinx/amd-yocto-hw-platforms using the make command, the .xsa and the System Device-tree directory will have been generated and you can skip this step.

To manually generate the System Device-tree directory, or if you made changes after Design Creation follow the steps below.

Complete instructions for SDTGen can be found in https://github.com/Xilinx/system-device-tree-xlnx

OPEN : Where are the SDT and PDI references in the Yocto build?

Next Steps

The System Device-Tree directory can be used with gen-machineconf to create or update the Yocto Machine Configuration, and then to generate the embedded software image. See https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#2.-Generating-the-Yocto-Machine for details.

Modifying PS / NOC Configuration and PL content : Full Custom flow

The Native Yocto Embedded Software images for AMD Evaluation boards are dependent on the PS Configuration and NoC settings in the Vivado Hardware Project. For a full custom flow where the PS configuration and NOC settings might change, all items will need to be re-generated as pre-built artifacts might not be compatible.

Additional manual steps might also be required to update the System Device Tree (recommended) or generated Device Trees to reflect IP added to the PL or available on the board.

The flows documented on this page can be used as a reference for a full custom design after initial design creation in Vivado:

1. Create your Hardware design in Vivado, or modify one of the provided pre-configured designs

   • https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#1.-Re-Creating-the-pre-built-Vivado-hardware-project-and-.xsa

2. https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#Generate-System-Device-tree-directory-from-the-XSA

3. https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#1.-Setting-up-the-Yocto-Environment-to-build-the-embedded-software-images

4. https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#2.-Generating-the-Yocto-Machine

5. https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#3.-Building-the-image

6. https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#1.-Writing-the-Image-to-the-boot-media

7. https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#2.-Booting-the-Board-to-Linux

8. https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#3.-Loading-the-pre-built-Programable-Logic-(PL)-firmware

How to update/change the Embedded Software Image

This section is for users who want to modify the simple existing configuration, adding rootfs contents, applying patches, changing SRCREV, BRANCH, SRCREPO etc.

Yocto Environment Setup:

Refer to https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3138977818#Setting-up-the-Yocto-Environment-to-build-the-embedded-software-images

Applying software component patches to the existing recipe:

1. Create the layer
   $ bitbake-layers create-layer ../sources/meta-user

2. Add the layer 
   $ bitbake-layers add-layer ../sources/meta-user

3. Create the files directory in the below path
   $ mkdir -p ../sources/meta-user/recipes-apps/ssw_components/files

4. Copy patches to the files directory
   $ cp -rf 0001.example.path sources/meta-user/recipes-apps/ssw_components/files

5. Add the patch to the SRC_URI variable .

   Please see the below ssw_component.bbappend as an example:

   FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

   SRC_URI:append = "  file://0001.example.path"