# qcom-va-driver for Debian

This package provides a VA-API driver for hardware-accelerated video
encoding and decoding on supported Qualcomm platforms.

This document describes how to configure and use the driver on Debian
and Debian-based distributions.

## Kernel requirements

Some features of this driver depend on changes to the Linux Qualcomm
Iris video driver which are not yet available in mainline Linux. These
patches are shipped in the upstream source under patches/ and are being
actively upstreamed by the upstream developers.

The following features need these patches:

 - decode-order output
 - larger capture buffer pools
 - encoder deblocking filter controls
 - timestamps on buffers returned with errors
 - recycling of NOSHOW buffers for AV1 decoding

Until they are merged, use a kernel which includes these patches for
full functionality.

## Driver selection

The driver is installed as qcom_drv_video.so, with an msm_drv_video.so
alias. On Qualcomm devices libva falls back to the DRM driver name
(msm), so the driver is normally picked up without any configuration.

To select the driver explicitly, set:

    LIBVA_DRIVER_NAME=qcom

The legacy v4l2_drv_video.so name used by the upstream libva-v4l2
packaging is not installed, so LIBVA_DRIVER_NAME=v4l2 does not work
with this package. Change any existing configuration to use qcom.

## Video post-processing

Video post-processing (VPP) is supported using the GPU (EGL/GLES/GBM)
surface copy and Vulkan backends.

The CDSP VPP backend described in the upstream documentation is
disabled in this package. Building it requires toolchains downloaded at
build time and components of the Qualcomm Hexagon SDK, which cannot be
used to build packages in Debian.

## GStreamer integration

GStreamer's VA plugin only registers elements for VA-API drivers in its
allowlist, which does not include the qcom-va-driver. By default the
plugin exposes no elements, and logs the following warning:

    Unsupported driver: Iris V4L2 stateful VA-API backend

To enable the VA elements, set the following environment variable when
running GStreamer applications:

    GST_VA_ALL_DRIVERS=1

H.264, H.265 and VP9 can also be decoded in hardware without this
driver, using the V4L2 stateful decoders from gst-plugins-good
(v4l2h264dec, v4l2h265dec and v4l2vp9dec). As of GStreamer 1.26 these
have the same rank as the VA decoders (primary + 1, or 257), which is
one above the software decoders so that hardware decoders are preferred.
When decoders are plugged automatically, elements of equal rank are
ordered by name, and the v4l2* elements sort before the va* elements.
So the V4L2 decoders are used even when GST_VA_ALL_DRIVERS is set.
There is no V4L2 AV1 decoder, so vaav1dec is used for AV1 when the VA
elements are enabled, and a software decoder otherwise.

To prefer the VA decoders, raise their rank above the V4L2 decoders
using GST_PLUGIN_FEATURE_RANK. A rank of 258 is enough to win the tie
without affecting the ordering of other elements:

    GST_PLUGIN_FEATURE_RANK=vah264dec:258,vah265dec:258,vavp9dec:258

The VA encoders (vah264enc and vah265enc) have rank none and are never
selected automatically, so they must be used explicitly in pipelines.

These settings were previously installed system-wide by the upstream
packaging, but are not enabled by default in the Debian package because
they can affect unrelated applications and VA-API drivers.

## Hardware tests

The upstream hardware regression tests are shipped in the separate
qcom-va-driver-tests package and installed under:

    /usr/libexec/qcom-va-driver/tests

They need a supported Qualcomm device. To run all of them and print a
summary of the results, use:

    qcom-va-driver-tests

Each test is run even if an earlier one fails. Test output is kept in
a temporary directory for inspection, and the command exits with a
non-zero status if any test failed.