Executable

Fully qualified name: cupva::Executable

Defined in src/host/cpp_api/include/cupva_host.hpp

class Executable : public cupva::DynamicStorage<impl::Executable>

The Executable object holds binaries for execution on the PVA.

Executables are used to register VPU binaries with the PVA system. The Executable object must remain in a valid state until all workloads using the Executable have completed.

Public Functions

Executable() noexcept

Construct uninitialized Executable.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Executable(Executable &&obj) noexcept

Move constructor.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: No

  • Runtime: Yes

  • De-Init: No

Executable &operator=(Executable &&obj) & noexcept

Move assignment operator.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: No

  • Runtime: Yes

  • De-Init: No

Executable(Executable const&) = delete

Executable &operator=(Executable const&) & = delete

void finalize()

Destroy the resources created by the object.

This method is exposed to allow fine-grained control over error handling.

During destruction of the object, this method will be called but the destructor must not propagate exceptions. To handle exceptions, manually invoke this method prior to object destruction.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: No

  • Runtime: No

  • De-Init: Yes

Throws:

• cupva::Exception(DriverAPIError) – if driver returns error due to one of the following:

  • Releasing symbols previously obtained via CmdProgram::operator[] failed

  • Destroying and de-allocating driver resources failed

• cupva::Exception(NotAllowedInOperationalState) – if called when NVIDIA DRIVE OS VM state is “Operational”

~Executable() noexcept

Destroy the Executable object.

Usage considerations

• Allowed context for the API call

  • Thread-safe: No

• API group

  • Init: No

  • Runtime: No

  • De-Init: Yes

Public Static Functions

static Executable Create(const void *data, int32_t size)

Construct a new Executable object from a pre-loaded binary buffer.

The buffer must be 4-byte aligned, containing a binary recognized as an executable by CUPVA. Binaries are collections of one or more ELF files which are built using appropriate device toolchains. Binaries may be generated from multiple ELF files using pvasdkCreateBin.py, a tool which is distributed with CUPVA.

Each ELF file has certain requirements, for example certain reserved symbol names which are recognized by the PVA system. Users can ensure the correct symbol names are generated by compiling ELFs with CUPVA device runtime headers and statically linking against the CUPVA device runtime library.

For backwards compatibility, this API may be used with a single ELF which has not been processed by pvasdkCreateBin.py. In future, this functionality will be removed.

On some platforms, signatures for VPU ELFs must be included in a system-wide allowlist of trusted VPU ELFs.

There is a limit of 65535 Executables which may be registered concurrently per cupva::Context.

Usage considerations

• Allowed context for the API call

  • Thread-safe: Yes

• API group

  • Init: Yes

  • Runtime: No

  • De-Init: No

Parameters:

• data – The host pointer to the buffer holding the VPU binary. Should be 4-byte aligned.

• size – The buffer size in bytes, must obey 0 < size < 2MB.

Throws:

• std::bad_alloc – if DynamicStorage cannot be initialized for Executable

• cupva::Exception(InvalidArgument) – if size <= 0, data is nullptr, data is not correctly aligned, or data cannot be parsed

• cupva::Exception(IncompatibleVersion) – if Executable was built with an incompatible version of CUPVA

• cupva::Exception(DriverAPIError) – if driver returns error due to one of the following:

  • data was nullptr

  • size was zero

  • Internal driver memory allocation failed

  • Parsing executable object failed

  • PVA engine is in a bad state

• cupva::Exception(NotAllowedInOperationalState) – if called when NVIDIA DRIVE OS VM state is “Operational”