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