Parameter

Fully qualified name: cupva::Parameter

Defined in 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.

• Maturity: GA

Public Functions

Parameter() noexcept

Construct an empty Parameter object.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Pre:

None

~Parameter() noexcept

Destroy Parameter object.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Pre:

None

Parameter(Parameter const &other)

Copy constructor.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Pre:

None

Parameter(Parameter &&other) noexcept

Move constructor.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Pre:

None

Parameter &operator=(Parameter const &other)

Copy assignment.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Pre:

None

Parameter &operator=(Parameter &&other) noexcept

Move assignment.

Usage considerations

• Allowed context for the API call

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Pre:

None

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

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: Yes

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Throws:

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

Returns:

Pointer to a parameter in VMEM.

Pre:

None

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

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Parameters:

val – scalar value to be copied to VMEM.

Throws:

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

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

Pre:

None

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

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Parameters:

• dataPtr – The pointer to the host array.

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

Throws:

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

• cupva::Exception(InvalidArgument) – if count <=0

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

Pre:

None

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

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

Parameters:

ptr – The DRAM device pointer.

Throws:

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

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

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

Pre:

None

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

  • Interrupt handler: No

  • Signal handler: No

  • Thread-safe: No

  • Re-entrant: No

  • Async/Sync: Sync

• Required privileges: None

• Allowed execution state

  • Initialization: Yes

  • Operational: Yes

  • Reinit/Deinit Preparation: Yes

• Maturity: GA

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

Pre:

None