Lopper Processing Pipeline and Direct Invocations - Lopper Processing Pipeline and Direct Invocations - 2026.1 English - UG1186

Libmetal and OpenAMP User Guide (UG1186)
Document ID
UG1186
Release Date
2026-06-24
Version
2026.1 English

Standard Yocto Pipeline

The standard Lopper pipeline consumes the overlay YAML files:

1. sdtgen: XSA -> system-top.dts
   Generates the full hardware description.

2. Lopper Step 1 -- YAML overlay application:
   lopper --enhanced -x '*.yaml' -i <overlay.yaml> system-top.dts rpu-yaml.dts
   Merges the overlay into the system device tree.
   Preserves domain and relation metadata.

3. Lopper Step 2 -- OpenAMP node generation:
   lopper --enhanced rpu-yaml.dts cortexr52_0-openamp.dts -- openamp <cpu> zephyr_dt
   Generates IPI, shared-memory, and chosen nodes from the relation metadata.

4. Lopper Step 3 -- R52 IMUX address mapping:
   lopper --enhanced -i lop-r52-imux.dts cortexr52_0-openamp.dts cortexr52_0-imux.dts -- gen_domain_dts <cpu>
   Adjusts addresses for the R52 memory view.

5. Lopper Step 4 -- Zephyr domain formatting:
   lopper --enhanced cortexr52_0-imux.dts cortexr52_0-zephyr.dts -- gen_domain_dts <cpu> zephyr_dt
   Converts the device tree to Zephyr bindings.
   Produces the final Zephyr DTS.

Direct Lopper Invocations for Firmware Configuration

Outside the Yocto pipeline, you can run Lopper directly. You can generate application-level CMake configuration files and linker metadata from the domain YAML relations. These commands parse the device tree after overlay application. They extract IPI, shared-memory, and timer assignments into files that the firmware build system can consume.

Libmetal — Generate Application .cmake Files

The openamp assist can generate a .cmake configuration file. It extracts IPI channel assignments, shared-memory addresses, and timer configuration from the libmetal,ipc-v1 relation in the device tree.

The following is an example for the Linux host side:

python3 lopper.py <input.dts> <output.dts> -- openamp \
    --libmetal_output_file \
    --compatible-string=libmetal,ipc-v1 \
    --processor=psv_cortexa72_0 \
    --os=linux_dt \
    --openamp_output_filename=a72ipi.cmake

The following is an example for the RPU bare-metal side:

python3 lopper.py <input.dts> <output.dts> -- openamp \
    --libmetal_output_file \
    --compatible-string=libmetal,ipc-v1 \
    --processor=psv_cortexr5_1 \
    --os=baremetal_dt \
    --openamp_output_filename=ipi.cmake
Table 1. Parameter Reference
Parameter Description
--libmetal_output_file Tells the assist to generate a CMake configuration file instead of modifying the device tree.
--compatible-string Selects the relation compatible string to match. Use libmetal,ipc-v1 for libmetal. Use openamp,rpmsg-v1 for OpenAMP.
--processor Identifies the target processor node name. It must match an AMD Vitis™ processor target name in the system device tree.
--os Selects the output format. Use linux_dt for the Linux host side. Use baremetal_dt for the RPU bare-metal side.
--openamp_output_filename Sets the generated .cmake output file name.
Note: The --processor value must match the processor target names that AMD Vitis™ uses.

The assist uses that value to find the correct domain and parse its relation data. It then extracts the IPI channels, shared-memory carveouts, and timer assignments for that domain.

Linker Metadata Generation for OpenAMP and Libmetal

For OpenAMP and libmetal bare-metal firmware, you can use the baremetallinker_xlnx assist to generate linker script metadata. This assist extracts the sram and reserved-memory entries from the remote domain. It then generates linker-compatible output.

export LOPPER_DTC_FLAGS="-b 0 -@"
export CONFIG_DTFILE=rpu.dts

python3 lopper.py -O ${S} rpu.dts \
    -- baremetallinker_xlnx <processor> <output_dir> openamp

Following is an example for Versal, R5 core 0:

python3 lopper.py -O ./build rpu.dts \
    -- baremetallinker_xlnx psv_cortexr5_0 ./build/linker openamp

Parameter Reference

Parameter Description
rpu.dts Specifies the input device tree after overlay application and OpenAMP node generation.
<processor> Specifies the target RPU processor node name, such as psv_cortexr5_0 or cortexr52_0.
<output_dir> Specifies the directory where the linker metadata files are written.
openamp Sets the context flag. It tells the assist to include OpenAMP or libmetal memory regions.

The generated linker metadata includes memory-region start addresses and sizes for:

  • TCM banks: ATCM, BTCM, and CTCM
  • DDR boot or firmware load region
  • Shared-memory regions, including vrings, buffers, and descriptors

The AMD embedded build system typically consumes this output. It uses the data to produce the final linker script for bare-metal or RTOS firmware.