/
AMD Versal AI Edge Series Gen 2 - Video Codec Unit 2 (VCU2)

AMD Versal AI Edge Series Gen 2 - Video Codec Unit 2 (VCU2)

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 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) 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}/):
edf-ospi recipe will build the OSPI boot mode compatible Images, while xilinx-bootbin can be used for generating the SD boot mode compatible Images.

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

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-multidomain.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-multidomain.yaml for revB design. -O flag will be required to add additional machine specific overrides, versal-2ve-2vm-vek385-sdt-seg for revA design and versal-2ve-2vm-vek385-revb-sdt-seg 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-multidomain.yaml --hw-description <path-to-sdt-handoff-dir> -O versal-2ve-2vm-vek385-sdt-seg 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-multidomain.yaml --hw-description <path-to-sdt-handoff-dir> -O versal-2ve-2vm-vek385-revb-sdt-seg

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

Build the boot.bin image (artifacts will be generated in build/tmp/deploy/images/${MACHINE}/):
edf-ospi recipe will build the OSPI boot mode compatible Images, while xilinx-bootbin can be used for generating the SD boot mode compatible Images.

revA example: MACHINE=versal-2ve-2vm-vek385-multidomain bitbake edf-ospi revB example: MACHINE=versal-2ve-2vm-vek385-revb-multidomain 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

This is optional from 2026.1 onward releases as 2026.1 release already has 4GB of CMA memory which will be enough for all the VCU2 usecases. 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) 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/pl.dtso 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

To apply the overlay run the below command.

dfx-mgr-client -load vcu2_overlay
dfx-mgr-client -loadByName 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.

2026.1 Release

New Feature Support

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

  • LLP2 support for HDMI Rx → Encode → Decode → HDMI-Tx/DP-Tx live pipeline usecase.