Parameter#

Fully qualified name: cupva::Parameter

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

class Parameter : public cupva::StaticStorage<impl::Parameter, priv::CUPVA_PARAMETER_SIZE>#

The Parameter object is the handle to the symbol in the VPU executable.

The user can get the device pointer to the VMEM target specified by the symbol or set value to it. If a value is specified (via operator= or set() APIs), this data will be captured by value and copied to VMEM on CmdProgram launch. This copy operation will take place as a pre-requisite for launching the CmdProgram, and can add to task launch overheads. For large copies, it may be beneficial to use DMA resources to perform this copy instead.

Parameter objects should be initialized from CmdProgram::operator[]. The CmdProgram must remain valid for the lifetime of the Parameter object.

Public Functions

Parameter() noexcept#

Construct an empty Parameter object.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

~Parameter() noexcept#

Destroy Parameter object.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameter(Parameter const&) = default#

Copy constructor.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameter(Parameter&&) = default#

Move constructor.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameter &operator=(Parameter const&) = default#

Copy assignment.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameter &operator=(Parameter&&) = default#

Move assignment.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

template<typename T = void, typename std::enable_if<std::is_class<T>::value || std::is_union<T>::value || std::is_arithmetic<T>::value, int>::type = 0>
inline auto ptr(
) const -> T*#

Gets the pointer to a parameter in VMEM.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: Yes

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Throws:

cupva::Exception(InvalidArgument) – if object not properly initialized from CmdProgram::operator[]

Returns:

Pointer to a parameter in VMEM.

template<typename T, typename std::enable_if<!std::is_pointer<T>::value && std::is_arithmetic<T>::value, int>::type = 0>
inline void set(
const T &val,
)#

Copy a scalar from the host to a parameter in VMEM.

Scalar value is stored directly in the parameter object.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameters:

val – scalar value to be copied to VMEM.

Throws:
template<typename T, typename std::enable_if<!std::is_same<T, void>::value && !std::is_pointer<T>::value, int>::type = 0>
inline void set(
const T *const dataPtr,
int64_t const numElements,
)#

Copy an array of elements of type T from the host to a parameter in VMEM.

The array contents is copied to the parameter object at the time this method is called and will be copied to VMEM upon program command submission.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameters:

  • dataPtr – The pointer to the host array.

  • numElements – The number of elements of type T to be copied.

Throws:
template<typename T, typename std::enable_if<std::is_pointer<T>::value, int>::type = 0>
inline void set(
T const ptr,
)#

Copy DRAM device pointer value to a parameter in VMEM.

Pointer value is stored directly in the parameter object.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameters:

ptr – The DRAM device pointer.

Throws:
template<typename T>
inline Parameter &operator=(const T &val)#

Assign value to the VMEM object handled by this Parameter.

If val has a pointer type, it must be a valid device pointer in L2SRAM, DRAM or CVSRAM, and this Parameter must refer to a ExtMemPointer in VMEM. If val has an arithmetic type, the Parameter must refer to a VMEM variable be of the same size, and the data will be copied to VMEM. For arrays and user defined structs, use cupva::Parameter::set directly.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Template Parameters:

T – The type of the value to be assigned.

Parameters:

val – the value to be assigned.

Throws:

  • cupva::Exception(InvalidArgument) – if object not properly initialized from CmdProgram::operator[]

  • cupva::Exception(InvalidArgument) – if T is a non-pointer integral or floating point type, and sizeof(T) <= 0, sizeof(T) > 8, or sizeof(T) is not a power of 2

  • cupva::Exception(InvalidArgument) – if T is a pointer type and val is not registered as a device pointer in DRAM or L2SRAM

  • cupva::Exception(DriverAPIError) – if driver API layer returned error while setting the parameter