PVA SDK Samples#

The PVA SDK includes samples demonstrating how to write complete applications using the cuPVA runtime APIs. The samples also demonstrate how to build PVA applications using the build tools which are included with the PVA SDK.

Overview#

Sample applications are installed in /opt/nvidia/pva-sdk-2.10/samples, with each sample in a separate subdirectory.

Executing some of the samples requires assets. For convenience, sample assets are provided in the directory /opt/nvidia/pva-sdk-2.10/samples/assets. The assets directory should be deployed with the sample, and the path specified with --assets <PATH_TO_ASSETS>.

Note

The assets path for tutorials is /opt/nvidia/pva-sdk-2.10/samples/tutorial/assets. The majority of tutorials require data from this directory. Refer to Step-by-Step Tutorials for more information.

The following samples are present:

Sample	Requires –assets <PATH_TO_ASSETS>?	Description
c_api_interop	No	Shows how to convert cuPVA C++ API objects to C API objects. This is convenient for applications where the definition of the PVA workload can benefit from the cuPVA C++ APIs, but it is desirable to provide a pure C interface to an external component to handle scheduling of those workloads.
convolution_cb	No	Shows how to construct and submit simple 2D filter workload with cuPVA APIs.
delay	No	Shows a workload which spins a VPU in a busy-loop for a set number of cycles.
device_test	No	Shows usage of the PVA SDK’s device function unit testing framework. This enables test applications to call device functions directly without needing to use cuPVA host APIs to explicitly schedule a workload.
fft	No	Shows how to utilize the PVA for finding discrete fourier transforms.
image_pyramid	No	Shows how to compute a ‘pyramid’ of successively lower resolution output images from a given input image.
mat_add	No	Shows how to add two 2D arrays and return the result.
mat_transpose	No	Shows how to transpose matrices. The DMA engine transposes tiles within an image, while the VPU transposes each pixel within the tile.
nvmedia_interop	No	Shows how to construct a zero-copy pipeline involving NvMedia and PVA.
pipeline	No	Shows how to utilize cuPVA APIs for scheduling pipelines with complex dependencies across multiple VPUs.
planar_to_interleaved4	No	Shows how to use `cupva::RasterDataFlow` handler aliasing to perform a raster scan over multiple image planes with the same dimensions. Equivalent implementations are provided in both C and C++ APIs.
tone_mapping	Yes	Shows how to use the `CupvaSampler` device side APIs by implementing a tone mapping application. Pre-computed look-up tables for each channel maps RGB input data in the range of [LOW, HIGH] to the output range[0, 1], with gamma correction.
tutorial	No	Contains all of the code used by the Tutorials.
vpu_printf	No	Shows how to use the `printf` function on the VPU to output debugging information.
warp_gsdf	Yes	Shows how to use `cupva::GatherScatterDataFlow` to implement an image warping kernel.

Building Samples#

Environment Setup#

Most users do not have write access to the default sample installation directory, so it can be difficult to use for building or experimenting with sample modifications. For convenience, PVA SDK includes a simple script that copies the samples to a directory where you have write access.

To copy the samples to your home directory, enter the following command on a terminal:

/opt/nvidia/pva-sdk-2.10/bin/pva-sdk_install_samples.sh $HOME

This copies the samples to the directory $HOME/NVIDIA_PVA_SDK-2.10.1-samples.

Note

The PVA SDK build system automatically uses ccache to accelerate repeated builds when it is available. ccache is a recommended package of the PVA SDK; if apt recommendations are disabled, install it with:

sudo apt update
sudo apt install ccache

See Build System for more information.

The CUDA interop features require CUDA cross-compile packages on the development machine and CUDA libraries on the target. CUDA SBSA packages require CMake 3.28 or newer.

The NvSci interop features require headers and libraries from the target system image. Follow the DRIVE OS or L4T instructions to configure these optional dependencies.

Some of the samples/tutorials distributed with the PVA SDK have dependencies on NvSci and/or NvMedia. Set the following environment variables to let the build find these dependencies. The examples assume a DRIVE OS Docker container. Tutorials are skipped when their dependencies are unavailable.

Environment Variable	Example for DRIVE OS 7.0.1.0 docker container
NVMEDIA_INCLUDE_PATH	/drive/drive-linux/include/nvmedia_6x
NVMEDIA_LIBRARY_PATH	/drive/drive-linux/lib-target
NVSCI_INCLUDE_PATH	/drive/drive-linux/include
NVSCIBUF_LIBRARY_PATH	/drive/drive-linux/lib-target
NVSCISYNC_LIBRARY_PATH	/drive/drive-linux/lib-target

Note

Samples and tutorials distributed with the PVA SDK use CMake to locate CUDA, which may require nvcc to be present in your PATH environment variable. If CMake is unable to locate an appropriate version of the CUDA toolkit, you may need export PATH=$PATH:/usr/local/cuda/bin or similar.

Building for EMU#

The core PVA SDK includes an x86 emulator that runs NVVPU-compiled VPU programs on the development host.

mkdir build_emu && cd build_emu
cmake -DPVA_BUILD_MODE=EMU -DPVA_USE_NVVPU=ON ..
cmake --build .

Select the emulated PVA generation at run time with PVA_GEN. Samples default to GEN2 when the variable is unset. For example, from the top-level samples build:

PVA_GEN=GEN2 ./mat_add/mat_add_c
PVA_GEN=GEN3 ./mat_add/mat_add_c
PVA_GEN=GEN2 ./mat_add/mat_add_cpp
PVA_GEN=GEN3 ./mat_add/mat_add_cpp

To attach LLDB or VS Code to an emulated VPU, see VPU Debugging with LLDB. EMU provides the RSP server directly and does not use the DoIP utility.

Linux Platforms#

The below instructions are applicable when building for DRIVE OS Linux or Jetson.

The build can be performed from the top-level samples directory (to build all samples), or from a standalone sample directory whose CMakeLists.txt calls project(), such as mat_add (to build only that sample). Tutorial lesson directories are composed by the top-level tutorial project and are not all standalone CMake projects.

mkdir build_l4t && cd build_l4t
cmake -DPVA_BUILD_MODE=L4T -DPVA_USE_NVVPU=ON ..
cmake --build .

QNX Platforms#

The below instructions are applicable when building for DRIVE OS QNX Standard or Safety.

Note

Builds use a non-safety configuration by default. To link to the safety versions of cuPVA libraries intended for safety-certified DRIVE OS installations, add the cmake flag -DPVA_SAFETY=ON.

The procedure is similar to building for Linux platforms; however, some QNX toolchain environment variables are also required:

# QNX_HOST/QNX_TARGET can alternatively be set by standard scripts usually packaged with QCC
export QNX_HOST=<QNX_BASE>/host/linux/x86_64
export QNX_TARGET=<QNX_BASE>/target/qnx
mkdir build_qnx && cd build_qnx
cmake -DPVA_BUILD_MODE=QNX -DPVA_USE_NVVPU=ON ..
cmake --build .

To follow these instructions with ASIP Programmer, see Following the PVA SDK Tutorials with ASIP Programmer.

Deploying Samples#

Refer to deploying applications for information on how to deploy built applications to the SOC.