Generating Machine Configuration

When building Linux with Yocto for Xilinx SoC platforms, a machine configuration is required to describe the hardware information.

The hardware design is exported from Vivado as an XSA (Xilinx Support Archive). Xilinx provides tools to generate the required machine configuration from the XSA or a generated SDT. SC-OBC XSA files and generated SDT archives are distributed from an artifact server instead of being stored in the meta-scobc layer.

There are two flows to generate the machine configuration:

  • SDT flow (recommended)

  • XSCT flow (deprecated)

In the SDT flow, the XSA is converted to an SDT (System Device Tree), and the machine configuration is generated from the SDT.

In the XSCT flow, the machine configuration is generated directly from the XSA using XSCT.

The SDT flow is the recommended method in recent Xilinx releases, starting from v2024.2.

This document explains both flows and the structure of the generated machine configuration.

Environment Setup

Before generating the machine configuration, prepare the build environment.

Clean previous output directory

If gen-machine-conf was executed previously, remove the output directory before running it again.

If the output directory remains, the generated files may reuse the previous machine name or configuration. This is a known issue in gen-machine-conf. Always remove the output directory before regenerating the configuration.

 
$ rm -rf output

Checkout Yocto sources

Fetch the required layers such as meta-xilinx using a kas configuration file.

It is recommended to use the configuration file that matches the build flow.

Example (SDT flow):

$ uv run kas checkout kas/scobc-v1.yml

The XSCT kas configuration is not available in current releases. When using meta-scobc tag scobc-v1-v0.3.0 or earlier, check out the XSCT sources as follows:

$ uv run kas checkout kas/scobc-v1-xsct.yml

Initialize submodules

gen-machine-conf is included as a git submodule in meta-xilinx, so it must be initialized.

$ pushd sources/meta-xilinx
$ git submodule update --init --recursive
$ popd

Enable gen-machine-conf

gen-machine-conf uses BitBake, so the Yocto environment must be initialized.

$ source sources/poky/oe-init-build-env
$ cd ..
$ export PATH=$PATH:$(pwd)/sources/meta-xilinx/meta-xilinx-core/gen-machine-conf

Enable sdtgen when generating an SDT locally

sdtgen is required when generating a new SDT from an XSA. It is not required when using an existing SDT archive through a machine YAML template.

It is provided by Xilinx Vivado or Vitis.

$ source /opt/xilinx/2025.1/Vitis/settings64.sh

SDT flow

In the SDT flow, the machine configuration is generated from an SDT (System Device Tree), which is created from the XSA exported by Vivado.

For an existing SC-OBC machine, use the YAML template stored under meta-scobc/conf/machineyaml/. The template records the SDT archive URI, machine name, output configuration directory, and PL overlay mode.

Generating machine configuration from a template

Pass the template for the target machine to gen-machine-conf parse-sdt:

$ gen-machine-conf parse-sdt \
  --template meta-scobc/conf/machineyaml/<machine-name>.yaml

The SDT archive referenced by --hw-description in the template is fetched from the artifact server through BitBake. This is the normal way to regenerate an existing machine configuration.

Generating SDT from XSA

When adding a new machine or updating its hardware design, obtain the XSA from the artifact server or export it from Vivado, and then generate an SDT locally.

A generic TCL script for SDT generation is provided at:

scripts/gen-sdt.tcl

Run sdtgen with the following arguments:

$ sdtgen scripts/gen-sdt.tcl <path-to-xsa> <path-to-generating-sdt-path>
Argument Description

<path-to-xsa>

Path to the XSA file exported from Vivado

<path-to-generating-sdt-path>

Output directory where the SDT will be generated

Generating machine configuration from SDT

After generating the SDT, use gen-machine-conf parse-sdt to create the machine configuration. --hw-description accepts a local SDT directory or an SDT archive URI that BitBake can fetch and unpack.

$ gen-machine-conf parse-sdt \
  --hw-description <sdt-directory-or-archive-uri> \
  --machine-name <machine-name> \
  -c <conf-path> \
  -g <pl-overlay>
Option Description

--hw-description

Path to the generated SDT directory or URI of an SDT archive

--machine-name

Name of the machine configuration

-c <conf-path>

Path to the conf directory where the machine will be generated

-g <pl-overlay>

PL overlay generation mode

The conf-path specifies the Yocto configuration directory.

Examples:

build/conf
meta-scobc/conf

Machine name format

We use the following machine configuration naming convention, based on the Xilinx naming style:

<soc>-<platform>-<variant>-<flow>-<feature>

Components

Component Description

soc

SoC family

platform

SC-OBC platform generation (example: scobc-v1)

variant

Hardware variant (example: ve2302e, ve2002e)

flow

Build flow (sdt or xsct)

feature

PL overlay mode (example: full, dfx)

PL overlay mode

The -g option selects the PL overlay generation mode.

Mode Description

full

PL is included in the base image

dfx

PL is loaded dynamically using DFX

Machine YAML template

After validating a new or updated SDT, publish its archive to the artifact server and record the generation arguments in meta-scobc/conf/machineyaml/<machine-name>.yaml:

args:
  - --hw-description <sdt-archive-uri>
  - --machine-name <machine-name>
  - -c meta-scobc/conf
  - -g <pl-overlay>

Keeping these arguments in the template makes regeneration independent of a developer’s local XSA and SDT directory layout.

If the machine configuration already exists, running gen-machine-conf will overwrite the existing files.

Any manual changes made to the machine configuration may be lost.

If you accidentally overwrite the file, you can restore it using Git:

$ git restore meta-scobc/conf/machine/<machine-name>.conf

XSCT flow

The XSCT flow is a legacy flow.

For new projects, use the SDT Flow instead. The XSCT flow is kept here for compatibility with existing projects.

In the XSCT flow, the machine configuration is generated directly from the XSA exported from Vivado.

Generating machine configuration from XSA

Use gen-machine-conf parse-xsa to generate the machine configuration directly from an XSA file.

$ gen-machine-conf parse-xsa \
  --hw-description <xsa-path-or-uri> \
  --machine-name <machine-name> \
  -c <conf-path>
Option Description

--hw-description

Path or fetchable URI of the XSA file exported from Vivado

--machine-name

Name of the machine configuration

-c <conf-path>

Path to the conf directory where the machine configuration will be generated

The conf-path specifies the Yocto configuration directory.

Examples:

build/conf
meta-scobc/conf

The machine configuration naming convention is the same as for the SDT flow.

Example

$ gen-machine-conf parse-xsa \
  --hw-description https://example.com/hardware/design.xsa \
  --machine-name <machine-name> \
  -c meta-scobc/conf

If the machine configuration already exists, running gen-machine-conf will overwrite the existing files.

Any manual changes made to the machine configuration may be lost.

If you accidentally overwrite the file, you can restore it using Git:

$ git restore meta-scobc/conf/machine/<machine-name>.conf