1 VCU2 IP
- 1.1 Description
- 1.2 Example Design
- 1.3 Yocto Build
- 1.4 Booting Linux
- 1.5 Using reserved memory for VCU2 drivers
- 1.6 VCU2 overlay requirements
  - 1.6.1 Content of shell.json
  - 1.6.2 Steps to generate pl.dtbo
- 1.7 How to apply overlay after Linux boot:
2 Releases
- 2.1 2025.1 Release
  - 2.1.1 New Feature Support
  - 2.1.2 JPEG Decoding examples
- 2.2 2025.2 Release
  - 2.2.1 New Feature Support

VCU2 IP

Description

This section covers the H.264/H.265/JPEG Video Codec Unit 2 Solutions v2.0 (VCU2) LogiCORE IP
for AMD Versal™ AI Edge Series Gen 2 and AMD Versal™ Prime Series Gen 2

See PG-447 for details on:

Product specification/core architecture
Design flow steps/example design
Application software; control software, GStreamer

Example Design

Follow the instructions in PG-447 Chapter 6 Application Example Design to obtain a .xsa file.
the default name is versal_gen2_platform_wrapper.xsa and this is used in the below text. Replace with the actual name if needed.
The MACHINE name is versal-2ve-2vm-vek385-sdt-seg for revA design and versal-2ve-2vm-vek385-revb-sdt-seg for revB design, which matches a prebuilt-machine name. Though it is recommended to use a new unique name, doing so will require extra changes to get boot.bin to boot into U-Boot.

Source the 2025.2 Vivado tools and run the sdtgen tool.

source Vivado/settings64.sh
sdtgen

Set the parameters and generate the SDT. The -dir parameter is the output folder that will be created. The -xsa parameter specifies the .xsa hardware design file generated with Vivado. The -board parameter specifies the target board and should be versal2-vek385-reva for revA design and versal2-vek385-revb for revB designs.

set_dt_param -dir my_sdt
set_dt_param -xsa versal_gen2_platform_wrapper.xsa
set_dt_param -board_dts versal2-vek385-reva/versal2-vek385-revb
generate_sdt
exit

Example with all parameters together:

sdtgen -eval "set_dt_param  -dir my_sdt -xsa versal_gen2_platform_wrapper.xsa -board_dts versal2-vek385-reva; generate_sdt"

For using reserved memory for VCU2 modify the pl.dtsi file generated in sdtgen’s o/p directory by adding below property in encoder(ale2xx) and decoder(ald3xx) node. Also see section AMD Versal AI Edge Series Gen 2 - Video Codec Unit 2 (VCU2) | Using reserved memory for VCU2 drivers below.
memory-region = <&cma_reserved>;

Yocto Build

Create a Yocto repository by following the steps in AMD EDF Getting started.

Please use a new shell for Yocto builds (don’t use the shell used for the Vivado tool).

To generate a Yocto machine configuration using the gen-machineconf tool, run the following inside the repository’s build directory:
The --template parameter requires the machine specific yaml file which has machine related configs and it should be <Path to sources folder>/meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp/conf/machineyaml/versal-2ve-2vm-vek385-sdt-seg.yaml for revA design and <Path to sources folder>/meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp/conf/machineyaml/versal-2ve-2vm-vek385-revb-sdt-seg.yaml for revB design

Example of revA design:
$ gen-machineconf parse-sdt --template sources/meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp/conf/machineyaml/versal-2ve-2vm-vek385-sdt-seg.yaml --hw-description <path-to-sdt-handoff-dir>

Example of revB design:
$ gen-machineconf parse-sdt --template sources/meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp/conf/machineyaml/versal-2ve-2vm-vek385-revb-sdt-seg.yaml --hw-description <path-to-sdt-handoff-dir>

Note: this also generates a pl.dtsi that is needed for vcu2_overlay creation (see below).

Build the boot.bin image (artifacts will be generated in build/tmp/deploy/images/${MACHINE}/):

revA example:
MACHINE=versal-2ve-2vm-vek385-sdt-seg bitbake edf-ospi

revB example:
MACHINE=versal-2ve-2vm-vek385-revb-sdt-seg bitbake edf-ospi

Build an SoC Common disk image (wic) containing general purpose (GP) Linux:

MACHINE=amd-cortexa78-mali-common bitbake edf-linux-disk-image

Booting Linux

Boot using the created images as described in AMD EDF Getting started - Discovery and Evaluation.
Booting using OSPI + SD is described here: How to boot a board using the pre-built images: Multi-stage boot (QSPI / OSPI -> SD/UFS) - Setup

Using reserved memory for VCU2 drivers

Add the below lines in sources/meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp/recipes-bsp/device-tree/files/versal-2ve-2vm-vek385-sdt-seg-system-conf.dtsi (or versal-2ve-2vm-vek385-revb-sdt-seg-system-conf.dtsi for revb) inside the scope of the reserved-memory node at the bottom (If cma_reserved node is already present please modify it with below properties). Also, the memory-region property needs to be added to the VCU2 nodes (see section AMD Versal AI Edge Series Gen 2 - Video Codec Unit 2 (VCU2) | Example Design above).
Next, repeat the Yocto Build (see above).

cma_reserved: cma_reserved@840000000 {
             no-map;
             compatible = "shared-dma-pool";
             reg = <0x08 0x40000000 0x00 0x80000000>;
};

Above node will allocate 2GB Reserved memory that can be used by Encoder/Decoder driver (strictly speaking this region is not CMA anymore as it is now not shared but dedicated to the Encoder/Decoder only).

Do not provide any CMA via bootargs while trying to boot with cma_reserved memory node. It will overwrite the CMA settings and will allocate from LOW_DDR(32-bit) space and you will end up with maximum 1GB CMA.

VCU2 overlay requirements

VCU2 overlay will be applied using the dfx-mgr-client utility and it requires the below items:
-> pl.dtbo
-> pl.pdi
-> shell.json

Create a folder called vcu2_overlay with these items.

Note: pl.pdi is the *_pld.pdi from the sdt output directory (my_sdt in the above description).

Content of shell.json

{
    "shell_type": "XRT_FLAT",
    "num_slots": "1"
}

Steps to generate pl.dtbo

pl.dtsi will be generated in the build/conf/dts/${MACHINE}/pl-overlay-full by the gen_machineconf step above.
Convert pl.dtsi to pl.dtbo:

dtc -I dts -O dtb -o pl.dtbo pl.dtsi

How to apply overlay after Linux boot:

Copy the overlay package that is generated using the above artifacts and copy that into /lib/firmware/xilinx/ folder.

<mount network drive>
cd <path with overlay> 
cp -r vcu2_overlay /lib/firmware/xilinx

dfx-mgr-client will display the current overlay packages that can be applied.

dfx-mgr-client -listPackage

                   Accelerator  Accel_type                    Base    Pid   Base_type  #slots(RPU+PL+AIE)    slot->handle
        vek385-pl-bram-gpio-fw    XRT_FLAT  vek385-pl-bram-gpio-fw  id_ok    XRT_FLAT             (0+0+0)              -1
                  vcu2_overlay    XRT_FLAT            vcu2_overlay  id_ok    XRT_FLAT             (0+0+0)              -1

dfx-mgr-client -load <Accelerator name or Package name> will apply the overlay.

dfx-mgr-client -load vcu2_overlay

vcu2_overlay: Loaded with slot_handle 0

dmesg
...
[  589.107414] ale2_riscv e8040000.ale2xx: Probing ...
[  589.107424] ald3_riscv e8080000.ald3xx: Probing ...
[  589.107426] ale2_riscv e8040000.ale2xx: Unable to get mcu clock, will keep default value
[  589.107432] ald3_riscv e8080000.ald3xx: Unable to get mcu clock, will keep default value
[  589.120869] ale2_riscv e8040000.ale2xx: request fw ale2xx.fw
[  589.120869] ald3_riscv e8080000.ald3xx: request fw ald3xx.fw
[  589.120877] ald3_riscv e8080000.ald3xx: Probing done successfully 000000009134fa6f
[  589.120880] ale2_riscv e8040000.ale2xx: Probing done successfully 0000000093822ab7
[  589.121160] ald3_riscv e8080000.ald3xx: fw version 0.48.0
[  589.121165] ald3_riscv e8080000.ald3xx: machineid     = 2
[  589.121187] ale2_riscv e8040000.ale2xx: fw version 0.48.0
[  589.121192] ale2_riscv e8040000.ale2xx: machineid     = 2
[  589.125926] ald3_riscv e8080000.ald3xx: Copy 262488 bytes of fw
[  589.125960] ald3_riscv e8080000.ald3xx: mcu clock rate is 920000000
[  589.129189] ale2_riscv e8040000.ale2xx: Copy 397224 bytes of fw
[  589.129241] ale2_riscv e8040000.ale2xx: mcu clock rate is 950000000
[  589.133494] ald3_riscv e8080000.ald3xx: mcu has boot successfully
[  589.133599] decoder server started
[  589.136027] ale2_riscv e8040000.ale2xx: mcu has boot successfully
[  589.136137] encoder server started

See PG-447 Section III, which describe the Control Software and Section IV, which describes the GStreamer software.

Releases

2025.1 Release

New Feature Support

See PG447 for a full description of the features that are supported.

AVC/HEVC encoding
JPEG decoding
Control software (proprietary) and OpenMax-IL based applications
GStreamer OMX based plugin
Encoder dynamic parameters:
- Resolution
- GOP length, number of B-frames, force IDR
- Region Of Interest
- QP values
- Long term reference pictures
Tiled and YUV444 formats
8/10/12 bits per pixel component

JPEG Decoding examples

ctrlsw_decoder -jpeg -in in.jpeg -out out.yuv

gst-launch-1.0 multifilesrc location=in.jpeg caps="image/jpeg,framerate=60/1" stop-index=0 ! jpegparse ! omxmjpegdec ! omxh265enc ! filesink location=out.h265

2025.2 Release

New Feature Support

See PG447 for a full description of the features that are supported.