1 VCU2 IP
- 1.1 Description
- 1.2 Example Design
- 1.3 Yocto Build
- 1.4 Booting Linux
- 1.5 Change CMA memory to greater than 1GB
- 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

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, 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.1 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.

set_dt_param -dir my_sdt
set_dt_param -xsa versal_gen2_platform_wrapper.xsa
set_dt_param -board_dts versal2-vek385-revA
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 reserving 2GB of memory for higher resolution usecases 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 Change CMA memory to greater than 1GB below.
memory-region = <&cma_reserved>;

Yocto Build

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

To generate a Yocto machine configuration using the gen-machineconf tool, run the following inside the repository’s build directory:

gen-machineconf parse-sdt --hw-description my_sdt -g full --machine-name versal-2ve-2vm-vek385-sdt-seg --add-config CONFIG_YOCTO_BBMC_CORTEXR52_1_BAREMETAL=y

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/versal-2ve-2vm-vek385-sdt-seg):

MACHINE=versal-2ve-2vm-vek385-sdt-seg bitbake xilinx-bootbin

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.
Change bootargs to increase CMA memory.

Note currently there is a limit of 1024M. The following section describes a work-around.

setenv bootargs "ttyAMA0 earlycon=pl011,mmio32,0xFF000000,115200n8 clk_ignore_unused root=/dev/ram0 rw init_fatal_sh=1 cma=1000M"

After booting, check if CMA has been reserved using dmesg or cat /proc/meminfo:

dmesg | grep cma

[    0.000000] cma: Reserved 1000 MiB at 0x000000002b200000 on node -1
[    0.000000] Kernel command line: ttyAMA0 earlycon=pl011,mmio32,0xFF000000,115200n8 clk_ignore_unused root=/dev/ram0 rw init_fatal_sh=1 cma=1000M
[    0.035978] Memory: 8605788K/10485760K available (16896K kernel code, 1086K rwdata, 4968K rodata, 3136K init, 482K bss, 850864K reserved, 1024000K cma-reserved)

Log in as shown in the below example:

amd-edf login: amd-edf
You are required to change your password immediately (administrator enforced).
New password: 
Retype new password: 

WARNING: AMD Embedded Development Framework is a reference Yocto Project
distribution that should be used for testing and development purposes only.
It is recommended that you create your own distribution for production use.

amd-edf:~$ sudo su

We trust you have received the usual lecture from the local System
Administrator. It usually boils down to these three things:

    #1) Respect the privacy of others.
    #2) Think before you type.
    #3) With great power comes great responsibility.

For security reasons, the password you type will not be visible.

Password: 
amd-edf:/home/amd-edf#

Change CMA memory to greater than 1GB

Add the below lines in sources/meta-xilinx-restricted/meta-xilinx-restricted-ea/meta-xilinx-restricted-vek385/recipes-bsp/device-tree/files/versal-2ve-2vm-vek385-sdt-seg-system-conf.dtsi inside the scope of the reserved-memory node at the bottom (If cma_reserved node is already present please modify it with below properties, this is necessary only for use cases that require more than 1 GB of memory). Also, the memory-region property needs to be added to the VCU nodes (see section Example Design above).
Next, repeat the Yocto Build (see above).

cma_reserved: cma_reserved@800000000 {
             no-map;
             compatible = "shared-dma-pool";
             reg = <0x08 0x00 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/versal-2ve-2vm-vek385-sdt-seg/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

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