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.

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, follow the steps in Environment setup. It also assumes you have an active Yocto environment. You can make sure 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 also runs oe-init-build-env

Layer Dependency

Make sure 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 for further details

  • MicroBlaze

Tool Availability

Make sure 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} Make sure you are in your Yocto build directory (${TOPDIR}), and your Yocto environment is active.

Examples

Note: 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 you 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, your kernel is very likely to freeze on boot as it then attempts 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 let users load and even reconfigure part or all 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 still have to manually load the reconfigurable partition or use an AMD provided recipe, and make sure that the logic load and device tree overlay operations occur in the correct order. Using the following flows only make sure that the device tree files only contain information available to the OS on boot. See https://github.com/Xilinx/meta-xilinx/blob/master/docs/README.dfx.user.dts.md 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-machine-conf (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 is 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 want.

# 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"