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>/edf-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-openamp

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. 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.

Use the installed tool to check global and SDT-specific options:

$ gen-machine-conf --help
$ gen-machine-conf parse-sdt --help

The following examples use -l (--localconf) to append the machine selection and applicable sanity-check settings to the specified file. Without this option, the tool prints these settings for you to add to conf/local.conf. It does not update that file automatically.

Generation defaults to the minimal multiconfig set selected for the hardware and domain configuration. Use --menuconfig or repeated --add-config CONFIG_YOCTO_BBMC_<target>=y options to select additional targets. Use --multiconfigfull only when you need the full available set. See Domain Configuration Files Usage in Yocto Machine Definitions for domain YAML configuration.

To regenerate configuration files regardless of cached input hashes, add --force to the command.

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.

Use -g full or -g dfx only when the hardware design contains PL. Omit -g for PS-only designs.

Note

Users still have to load the reconfigurable partition manually, or use an AMD provided recipe. Either way, make sure the logic load and the device tree overlay operations happen in the correct order. The following flows only guarantee that the device tree files describe the hardware the OS has available at 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

gen-machine-conf generates the static overlay, not the reconfigurable partition overlays. Use the partial overlays and matching partial PDI or bitstream files from the SDT handoff for 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

When you enable bare-metal multiconfigs, gen-machine-conf includes the following settings in its local.conf output. The tool appends them to the file specified by -l or prints them when -l is omitted. The sanity-check settings are optional.

# 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
# safely disabled.
SKIP_META_VIRT_SANITY_CHECK = "1"
SKIP_META_SECURITY_SANITY_CHECK = "1"
SKIP_META_TPM_SANITY_CHECK = "1"