AMD Yocto Native Board Support Packages
- Hatch, Christopher
- Cassells, William
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
- 1 Introduction
- 2 Release Information
- 3 System Boot Architecture and Default Image configuration
- 4 How to boot a board using the pre-built Images : SD Mode
- 5 How to re-build the embedded software Images using pre-built hardware artifacts
- 6 How to regenerate the Vivado Hardware Design, .xsa and System Device-tree Directory
- 7 Modifying PS / NOC Configuration and PL content : Full Custom flow
- 8 How to update/change the Embedded Software Image
- 9 How to build and boot using QEMU
- 10 Yocto Layer descriptions
- 11 Future content to follow:
- 12 Related Links
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 GitHub - Xilinx/amd-yocto-hw-platforms
Yocto Machine Configuration Layers and recipes to build and package the embedded software and hardware artifacts into a bootable system imageGitHub - Xilinx/yocto-manifests: Repo Manifests for the Yocto Project Build System
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.
The Vivado tool set is required to re-build or edit the hardware design
To download Vivado Downloads
Vivado user guide AMD Technical Information Portal
Release Information
The 2024.2 Developer Preview Early Access release of Yocto Native BSPs makes use of the Yocto based PetaLinux DISTRO and Package Feed and ‘PetaLinux’ is displayed on the terminal prompt and other areas. This is scheduled to be updated in the next release."
Content and Download Links |
|---|
Release |
| Release Notes |
|---|---|---|
2024.2 | Initial Developer Preview release with support for the following AMD Evaluation boards:
Download links for pre-built system images and build artifacts by board: VEK280
ZCU104
Top level Download locations, structure and naming scheme
| Yocto Native BSP Release Notes - 2024.2 Update2 Yocto Project related Release Notes - Xilinx Wiki - Confluence |
|
|
|
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
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.
The "system device tree" is a text file or files that that describe the hardware available to the software. The "system device tree directory" includes the system device tree and additional files necessary for a successful device boot, including the CDO files needed for NOC configuration.
Future content to follow, see AMD Yocto Native Board Support Packages | Future content to follow:
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 AMD Yocto Native Board Support Packages | Future content to follow:
How to boot a board using the pre-built Images : SD Mode
QEMU: QEMU Binaries are not generated by default but are supported, see the following section :AMD Yocto Native Board Support Packages | How to build and boot using QEMU
1. Writing the Image to the boot media
The .wic.xz pre-built images (SeeAMD Yocto Native Board Support Packages | 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.
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
user@enho:~$ xzcat petalinux-image-minimal-versal-vek280-sdt-seg-20241226190706.wic.gz | sudo dd of=/dev/mmcblk0 bs=1M status=progress
[sudo] password for user:
728449024 bytes (728 MB, 695 MiB) copied, 4 s, 182 MB/s
0+109379 records in
0+109379 records out
898891776 bytes (899 MB, 857 MiB) copied, 66.8311 s, 13.5 MB/s
For zcu104 petalinux-image-minimal-zynqmp-zcu104-sdt-full-20241226193813.wic.gz2. 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
Note the location of the PL firmware binaries (.bin /.pdi) and device tree overlay (.dtbo) files
Example Commands and Logs ZCU104
zynqmp-zcu104-sdt-full:/home/petalinux# fpgautil -b /lib/firmware/xilinx/zcu104-pl-vcu-fw/zcu104-pl-vcu-fw.bin -o /lib/firmware/xilinx/zcu104-pl-vcu-fwzcu104-pl-vcu-fw.dtbo |
Example Commands and Logs VEK280
versal-vek280-sdt-seg:/home/petalinux# fpgautil -b /lib/firmware/xilinx/vek280-pl-aie-vdu-fw/vek280-pl-aie-vdu-fw.pdi -o /lib/firmware/xilinx/vek280-pl-aie-vdu-fw/vek280-pl-aie-vdu-fw.dtbo |
How to re-build the embedded software Images using pre-built hardware artifacts
The default build flow (steps below) uses pre-built artifacts from the Vivado Hardware Design flow and System Device Tree generation flows. Later sections cover detail on re-generating these 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:
$ repo init -u https://github.com/Xilinx/yocto-manifests.git -b rel-v2024.2
$ repo sync
$ source setupsdk2. 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 inmeta-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 AMD Yocto Native Board Support Packages | Release Information for download links
$ gen-machineconf parse-sdt --hw-description <System Device-tree Directory> -c conf -l conf/local.conf --machine-name <Name for your machine/board>
#Example for VEK280 using pre-built System Device-tree Directory, see release links for download path
$ gen-machineconf parse-sdt --hw-description <path to download directory>/versal-vek280-sdt-seg_2024.2_1106_1/ -c conf -l conf/local.conf --machine-name versal-vek280-sdt-segSee the readme for gen-machineconf for more information (Ensure you select the appropriate release branch - AMD does not use main as a development branch) : GitHub - Xilinx/gen-machine-conf: Parse hardware design information to generate project specific machine configuration
Users should not modify the machine layer created by
gen-machineconf, instead they should create modifications inlocal.confor in their own layers.gen-machineconfcan overwrite any changes made in the layers it manages.gen-machineconfcopies configuration files, not binaries. Items such as FSBL or PLM that are included in binary form from Vivado will be re-created with the build tools included in Yocto replacing those built by VivadoThe SDTGen created 'System Device-tree Directory' can also be re-generated from the provided Vivado Hardware Design for a BSP by following the steps in AMD Yocto Native Board Support Packages | How to regenerate the Vivado™ Hardware Design, .xsa and System Device tree Dire...
The 'System Device-tree Directory' would also need to be re-generated if there were changes made to the to the Vivado Hardware Design.
3. Building the image
Build the image using standard Yocto commands:
$ MACHINE=<Name for your machine/board> bitbake petalinux-image-minimal
#Example for VEK280
$ MACHINE=versal-vek280-sdt-seg bitbake petalinux-image-minimalThe 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 AMD Yocto Native Board Support Packages | How to boot a board using the pre built Images : SD Mode
The 2024.2 Developer Preview Early Access release of Yocto Native BSPs makes use of the Yocto based PetaLinux DISTRO and Package Feed, and ‘PetaLinux’ is displayed on the terminal prompt and other areas. This is scheduled to be updated in the next release."
How to regenerate the Vivado Hardware Design, .xsa and System Device-tree Directory
The Vivado tools are required to re-build or modify the hardware design
To download Vivado Downloads
Vivado user guide AMD Technical Information Portal
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 AMD Yocto Native Board Support Packages | 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
This guide does not cover AI engine images, how to generate them, or how to add them to your final image, that will be added at a later date.
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)
#Clone the amd-yocto-hw-platforms to your local machine
$ git clone --recursive https://github.com/Xilinx/amd-yocto-hw-platforms.git
#Setup the Vivado Tools from there instalation directory
$ source <vivado-install-path>/settings64.sh
#Move to the directory for the VEK280 Board, and run the build by calling 'make all'
$ cd amd-yocto-hw-platforms/eval_board_base/vek280_base
$ make all2. 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.
The System Device Tree Generator
SDTGentool 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.The
gen-machineconftool is then used with the System Device-tree Directory to create a Yocto Machine Configuration aligning industry standard approaches.
The "system device tree file(s)" is a text file or files that describe the hardware available to the software. The "system Device-tree Directory" includes the system device tree and additional files necessary for a successful device boot, including the CDO files needed for NOC configuration.
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.
$ source vivado/settings64.sh
$ xsct
xsct% sdtgen set_dt_param -xsa <your xsa from vivado>.xsa -dir sdt_outdir -board_dts <board dts file>
xsct% sdtgen generate_sdt
xsct% exitComplete 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:
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#3.-Building-the-image
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:
Applying software component patches to the existing recipe:
Create the layer
$ bitbake-layers create-layer ../sources/meta-userAdd the layer
$ bitbake-layers add-layer ../sources/meta-userCreate the files directory in the below path
$ mkdir -p ../sources/meta-user/recipes-apps/ssw_components/filesCopy patches to the files directory
$ cp -rf 0001.example.path sources/meta-user/recipes-apps/ssw_components/filesAdd 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"
Customizing the Root File System
The linked content below has mapped steps in Yocto (and equivalent in PetaLinux) to customize the Rootfs if a user wants to include prebuilt applications, or create / add custom applications, creating and adding custom kernel modules, application auto run at startup, adding layers, adding an existing recipe into the root file system and adding a package group
Building from Remote SRC
vim sources/meta-user/recipes-apps/ssw_components/ssw_component.bbappend
REPO = "https://github.com/Xilinx/embeddedsw "
BRANCH = "master"
SRCREV = "33750739285bbc8e51355b91cd274a1651e97e8f"
Building from local external repo
# Build components from external src.
INHERIT += "externalsrc"
EXT_SRC_ESW = "<local repopath >"
EXTERNALSRC:pn-plm-firmware = "${EXT_SRC_ESW}"
EXTERNALSRC_BUILD:pn-plm-firmware = "${EXT_SRC_ESW}/build/plm"
SRCREV:pn-plm-firmware = "84be8c5dce9325e9f7bb4279682c18846ecfd3b3"
Skip Packaging Boot components into boot.bin
Add the below line to the local.conf file to skip packaging boot components into boot.bin
BIF_PARTITION_ATTR:remove = "plmfw"BIF_PARTITION_ATTR:remove = "psmfw"
BIF_PARTITION_ATTR:remove = "fsbl"
BIF_PARTITION_ATTR:remove = "pmufw"
Optimizing the build time
The Yocto build infrastructure has smart caching of downloads and build state. This allows for a build to be vastly accelerated in cases where the artifacts have previously been built in the exact configuration required.
In order to take advantage of this, the build infrastructure allows the user to point to centralized SSTATE and Download directories or servers.
Add the below lines to conf/local.conf
# Add Pre-mirrors
SOURCE_MIRROR_URL = "https?://.*/.* https://petalinux.xilinx.com/sswreleases/rel-v2024.2/downloads"
# Sstate mirror settings
SSTATE_MIRRORS = " \
file://.* https://petalinux.xilinx.com/sswreleases/rel-v2024.2/aarch64/sstate-cache/PATH;downloadfilename=PATH \n \How to build and boot using QEMU
To use QEMU you must first build the QEMU binaries, as they are not generated by default.
1 Build the qemu-helper-native package to set up QEMU network tap devices
$ MACHINE=versal-vek280-sdt-seg bitbake qemu-helper-native
For ZCU104 zynqmp-zcu104-sdt-full2 Now you can simulate the image using the QEMU emulator
Note: To terminate qemu, the normal command is Ctrl-a x
$ MACHINE=versal-vek280-sdt-seg runqemu nographic slirp
For ZCu104 zynqmp-zcu104-sdt-full
Yocto Layer descriptions
AMD provides a number of "meta-" layers that users can add to their Yocto project(s) in order to allow users of AMD hardware access to the following: initial bootloaders (FSBL/PLM) and their build tooling, AMD's vendor branch of U-Boot, AMD's vendor branch of the Linux kernel, tooling to combine and modify open source components, and recommended defaults for open source components.
These layers are described in detail at this wiki page.
meta-amd-adoptive-socs:
https://github.com/Xilinx/meta-amd-adaptive-socs
Layer containing the AMD Adaptive SoC's BSP features such as evaluation board machine configuration files, multiconfig files, multiconfig device tree files, boot pdi, kernel configuration fragments, series configuration compiler(.scc) files etc.
Future content to follow:
Example Hardware Design Configuration, and links to design methodology for Segmented Configuration enabled designs.
Image Layout, embedded software stack content, kernel configuration, rootfs content, Yocto Layers
Basic Yocto How To targeting AMD Hardware and Embedded Software Development flows
Alternative or additional PL payloads, Xen, OpenAMP
Related Links
Zynq™ UltraScale+™ MPSoCs Boot Process Overview • Zynq UltraScale+ MPSoC Software Developer Guide (UG1137) • Reader • AMD Technical Information Portal
Decoupling : githib then wiki once done
Yocto Mega Manual, Yocto Wiki tips, Peta to Yocto
https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2787311617
https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2824503297
https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18842475
https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18841883
Overview • Versal Adaptive SoC Design Guide (UG1273) • Reader • AMD Technical Information Portal
Related content
© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy