Utility Library#

Utility library for monitoring cuPVA host internals.

The cuPVA host library generates hardware configuration from user provided parameters. To assist the user in monitoring how well the host library is performing this role, and in debugging their own setup code, a utility library is provided. Note that this library is not intended to be used in a production setting.

Classes#

cupva_utils::ProfilingContext

Profiling Context.

cupva_utils::ProfilingStatistics

Profiling statitics.

Enumerations#

uint32_t cupva_utils::ProfilingBatchStatType

Profiling batch stat type.

uint32_t cupva_utils::ProfilingProgramStatType

Profiling program stat type.

Functions#

void * cupva_utils::AllocSurface(const PlaneSize *ps, const int32_t planeCount, const cupva::SurfaceFormatType format=cupva::SurfaceFormatType::BLOCK_LINEAR)

Allocate a surface that is accessable by PVA engine.

void cupva_utils::CopyFromPlane(void *dst, const void *srcPlaneBase, const int32_t imageWidth, const int32_t imageHeight)

copy a surface plane to a pitch linear buffer.

void cupva_utils::CopyToPlane(void *dstPlaneBase, const void *src, const int32_t imageWidth, const int32_t imageHeight)

copy a pitch linear buffer to a surface plane.

cupva::Stream cupva_utils::CreateProfilingStream(ProfilingContext &ctx, cupva::EngineType absEngine=cupva::EngineType::PVA0, cupva::AffinityType vpuAffinity=cupva::AffinityType::VPU_ANY)

Construct a new profiling sync Stream object.

cupva::Stream cupva_utils::CreateSyncStream(cupva::EngineType absEngine=cupva::EngineType::PVA0, cupva::AffinityType vpuAffinity=cupva::AffinityType::VPU_ANY)

Construct a new sync Stream object.

cupva::Stream cupva_utils::CreateSyncStream(cupva::Stream stream)

Construct a new sync Stream object from an existing Stream object.

std::string cupva_utils::DMAPerfWarnings(cupva::CmdProgram &program)

Report potential perf issues due to suboptimal DMA configs.

ProfilingStatistics cupva_utils::ProfilingContext::getStatistics(cupva::CmdProgram const &prog, ProfilingProgramStatType const type)

Get per CmdProgram statistics in nanoseconds from a context given a profiling statistics type.

ProfilingStatistics cupva_utils::ProfilingContext::getStatistics(ProfilingBatchStatType const type)

Get profiling statistics in nanoseconds from a context given a profiling statistics type.

ProfilingStatistics cupva_utils::ProfilingContext::getStatistics(cupva::Executable const &exec, ProfilingProgramStatType const type)

Get per Executable statistics in nanoseconds from a context given a profiling statistics type.

Data Structures#

cupva_utils::PlaneSize

Plane configuration.

cupva_utils::ProfilingStatisticsData

Profiling statitics data struct.

Enumerations#

enum class cupva_utils::ProfilingBatchStatType : uint32_t#

Profiling batch stat type.

Values:

enumerator EXECUTION_TIME#

VPU execution time

enumerator TASK_OVERHEAD#

Task overhead time

enumerator TOTAL_TIME#

Total batch time

enumerator MAX_TYPE#
enum class cupva_utils::ProfilingProgramStatType : uint32_t#

Profiling program stat type.

Values:

enumerator EXECUTION_TIME#

VPU execution time

enumerator SETUP_TIME#

setup time

enumerator TEARDOWN_TIME#

teardown time

enumerator MAX_TYPE#

Functions#

void *cupva_utils::AllocSurface(
const PlaneSize *ps,
const int32_t planeCount,
const cupva::SurfaceFormatType format = cupva::SurfaceFormatType::BLOCK_LINEAR,
)#

Allocate a surface that is accessable by PVA engine.

Parameters:

  • ps – [in] Pointer to PlaneSize structs.

  • planeCount – [in] Specifies the number of planes.

  • format – [in] Specifies surface format. There are two formats supported: PITCH_LINEAR and BLOCK_LINEAR.

Throws:

  • cupva::Exception(InvalidArgument) – The number of planes exceeds the maximum.

  • cupva::Exception(InvalidArgument) – An invalid allocation size was provided.

  • cupva::Exception(InternalError) – Failed to allocate VA.

Returns:

The device pointer pointing to the allocated memory.

void cupva_utils::CopyFromPlane(
void *dst,
const void *srcPlaneBase,
const int32_t imageWidth,
const int32_t imageHeight,
)#

copy a surface plane to a pitch linear buffer.

Parameters:

  • dst – [in] The host pointer to destination buffer.

  • srcPlaneBase – [in] The device pointer to plane base of source surface.

  • imageWidth – [in] The width of destination buffer in bytes.

  • imageHeight – [in] The height of destination buffer in lines.

Throws:

cupva::Exception(InvalidArgument) – Invalid device pointer.

void cupva_utils::CopyToPlane(
void *dstPlaneBase,
const void *src,
const int32_t imageWidth,
const int32_t imageHeight,
)#

copy a pitch linear buffer to a surface plane.

Parameters:

  • dstPlaneBase – [in] The device pointer to plane base of destination surface.

  • src – [in] The host pointer to source buffer.

  • imageWidth – [in] The width of source buffer in bytes.

  • imageHeight – [in] The height of source buffer in lines.

Throws:

cupva::Exception(InvalidArgument) – Invalid device pointer.

cupva::Stream cupva_utils::CreateProfilingStream(
ProfilingContext &ctx,
cupva::EngineType absEngine = cupva::EngineType::PVA0,
cupva::AffinityType vpuAffinity = cupva::AffinityType::VPU_ANY,
)#

Construct a new profiling sync Stream object.

A profiling stream will collect profiling statistics for all workloads submitted to it. To retrieve the collected statistics, the user must call appropriate methods on the ProfilingContext object that was used to create the Stream. The Stream must be destroyed before the ProfilingContext which owns it.

Parameters:

  • ctx – The reference to a ProfilingContext object.

  • absEngine – The PVA engine Id.

  • vpuAffinity – The queue submission affinity.

Throws:

  • std::bad_alloc – Allocating the Stream object failed.

  • cupva::Exception(InvalidArgument) – The AffinityType is invalid.

  • cupva::Exception(DriverAPIError) – The PVA driver returned an unexpected error.

cupva::Stream cupva_utils::CreateSyncStream(
cupva::EngineType absEngine = cupva::EngineType::PVA0,
cupva::AffinityType vpuAffinity = cupva::AffinityType::VPU_ANY,
)#

Construct a new sync Stream object.

A cupva::Stream which is created via this method will implicitly synchronize all submissions with the host-side CPU. Synchronization will occur before returning from the submit() method. This can be useful for debugging purposes.

Parameters:

  • absEngine – The PVA engine Id.

  • vpuAffinity – The queue submission affinity.

Throws:

  • std::bad_alloc – Allocating the Stream object failed.

  • cupva::Exception(InvalidArgument) – The AffinityType is invalid.

  • cupva::Exception(DriverAPIError) – The PVA driver returned an unexpected error.

cupva::Stream cupva_utils::CreateSyncStream(cupva::Stream stream)#

Construct a new sync Stream object from an existing Stream object.

This API allows users to convert an existing cupva::Stream to a cupva::Stream which synchronizes with the CPU before returning from the submit() method.

One example of using this API may be to conditionally replace an existing, fully initialized Stream with a SyncStream: 

void SomeFunction(cupva::Stream &s)
{
    // s was initialized upstream as an ordinary cupva::Stream
    #if DEBUG
        s = cupva_utils::CreateSyncStream(std::move(s));
        // From now on, submissions to s will synchronize with CPU before returning from submit()
    #endif
}

Parameters:

stream – The pre-existing cupva::Stream

Throws:

std::bad_alloc – internal allocations failed

std::string cupva_utils::DMAPerfWarnings(cupva::CmdProgram &program)#

Report potential perf issues due to suboptimal DMA configs.

This function will detect and generate these DMA warnings:

  1. A RDF or GSDF is decomposed to SWSEQ.

  2. Line pitch of an inbound SDF or RDF’s source buffer is not 64-byte aligned.

  3. Tile width of an SDF or RDF is not 64-byte aligned.

  4. Any data flow requires more than 1 round trips to MC to fetch the data.

This method should be called only after the CmdProgram has had the cupva::CmdProgram::compileDataFlows method invoked.

Parameters:

program – The program to log information about

Returns:

The perf warning string