/
Running `gen-machine-conf`

Running `gen-machine-conf`

This page describes the process to create a Yocto Machine Configuration/BSP starting with a System Device Tree for AMD™ SoCs.

Table of Contents

Assumptions

SDT

This document assumes you are using a System Device Tree (SDT) produced by SDTGen as input. If you do not yet have an SDT follow the tutorial in the SDTGen README

Yocto environment

This document assumes you have a Yocto environment based on an AMD release set up. If you do not, please follow the steps in Environment setup. It also assumes you have an active Yocto environment. You can ensure it is active using source <Yocto source directory>/poky/oe-init-build-env

AMD provides a helper script setupsdk in the yocto-scripts repository, this helper will also run oe-init-build-env

Layer dependency

Ensure that meta-openamp is in your environment, by adding it to conf/bblayers.conf or using bitbake-layers add-layer.

bitbake-layers add-layer <path to sources>/meta-openembedded/meta-oe

AMD manifests automatically include meta-openamp. This step is included here for users that might have seen older documentation or are manually building an environment.

Note: Linux builds for the following devices are not supported in the 2024.2 release. See Limitations of the SHEL flow | AMD MicroBlaze™ Processor and AMD MicroBlaze™ V Processor for further details

  • MicroBlaze

  • MicroBlaze-V

Tool availability

Ensure that gen-machine-conf is available in your path.

$ export PATH=$PATH:<ABSOLUTE_PATH>/gen-machine-conf

Execution environment

gen-machine-conf assumes you are in ${TOPDIR} Ensure you are in your Yocto build directory (${TOPDIR}), and your Yocto environment is active.

Examples

Note: Please see the gen-machine-conf README file for details on its command line options.

Designs that do not use dynamic reconfiguration

Some applications use a static Programmable Logic (PL) image that is fixed for the entire power cycle of the device. In applications like this we can use gen-machine-conf without the -g option. Without this option, gen-machine-conf creates a single .dts file that includes all hardware available to the OS.

Warning: If your design does use dynamic configuration and you fail to use the -g option, it is very likely your kernel will freeze on boot as your kernel will be attempting to communicate with hardware that hasn't been loaded.

Example

$ gen-machine-conf parse-sdt --hw-description <path_to_sdtgen_output_directory> -c <conf-directory> -l <path-to-build-directory>/build/conf/local.conf --machine-name <soc-family>-<board-name>-sdt-<design-name>

Designs with dynamic reconfiguration

AMD Adaptive SoCs are designed to allow users to load and even reconfigure part or all of the logic after boot of the software. This falls into two categories "Dynamic Function Exchange" (DFX) and "Segmented Configuration". DFX is available all AMD Adaptive SoCs currently in production. Segmented Configuration allows flexibility boot with Processor System (PS) based software first and load or reload PL later.

Note Users will still have to manually load the reconfigurable partition or use an AMD provided recipe, and ensure that the logic load and device tree overlay operations occur in the correct order. Using the below flows will only ensure that the device tree files only contain information available to the OS on boot. See meta-xilinx/docs/README.dfx.user.dts.md at master · Xilinx/meta-xilinx for more details.

Dynamic Function Exchange

Dynamic Function Exchange is a process by which users can replace "reconfigurable blocks" within their PL design using software. If the replaced and replacing block contain logic that has differing OS drivers, gen-machine-conf can be used to separate the device tree of the hardware that the OS boots with from the hardware loaded by DFX using the -g dfx option.

Example

$ gen-machine-conf parse-sdt --hw-description <path_to_sdtgen_output_directory> -c <conf-directory> -l <path-to-build-directory>/build/conf/local.conf --machine-name <soc-family>-<board-name>-sdt-<design-name> -g dfx

Note: The DFX partial .dtsi is not processed by the gen-machineconf (lopper) tool. Users need to use the *_partial.dtsi and *_partial.pdi/bit from sdtgen output artifacts to manage DFX partial firmware recipes.

Segmented Configuration

Some AMD Adaptive SoCs support loading the PL by software after boot, which can provide benefits for boot time, power, recovery and platform management. This approach is called Segmented Configuration. gen-machine-conf can be used to separate the device tree of the hardware that the OS boots with from the hardware loaded by DFX using the -g full option.

Example

$ gen-machine-conf parse-sdt --hw-description <path_to_sdtgen_output_directory> -c <conf-directory> -l <path-to-build-directory>/build/conf/local.conf --machine-name <soc-family>-<board-name>-sdt-<design-name> -g full

Dynamic Function Exchange regions within a Segmented Configuration

Currently AMD does not support having a DFX region while using segmented configuration.

Bare Metal configurations

Because gen-machine-conf is used to produce bare metal configurations in addition to Yocto configurations, the following will be written to the end of the build/conf/local.conf file. Users that do not use bare metal software can remove these lines if they wish.

# Use the newly generated MACHINE MACHINE = "<machine-name>" # Avoid errors in some baremetal configs as these layers may be present # but are not used. Note the following lines are optional and can be # safetly disabled. SKIP_META_VIRT_SANITY_CHECK = "1" SKIP_META_SECURITY_SANITY_CHECK = "1" SKIP_META_TPM_SANITY_CHECK = "1"