Engine - Extensions

oneAPI Level Zero Specification - Version 1.18.31

Engine - Extension Functions

zesEngineGetActivityExt

Added in version 1.7

ZE_APIEXPORT ze_result_t ZE_APICALL zesEngineGetActivityExt(zes_engine_handle_t hEngine, uint32_t *pCount, zes_engine_stats_t *pStats)

Get activity stats for Physical Function (PF) and each Virtual Function (VF) associated with engine group.

• The application may call this function from simultaneous threads.

• The implementation of this function should be lock-free.

Parameters:

• hEngine – [in] Handle for the component.

• pCount – [in,out] Pointer to the number of VF engine stats descriptors.

  • if count is zero, the driver shall update the value with the total number of engine stats available.

  • if count is greater than the total number of engine stats available, the driver shall update the value with the correct number of engine stats available.

  • The count returned is the sum of number of VF instances currently available and the PF instance.

• pStats – [in,out][optional][range(0, *pCount)] array of engine group activity counters.

  • if count is less than the total number of engine stats available, then driver shall only retrieve that number of stats.

  • the implementation shall populate the vector with engine stat for PF at index 0 of the vector followed by user provided pCount-1 number of VF engine stats.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hEngine

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE - “Engine activity extension is not supported in the environment.”

Engine - Extension Structures

zes_engine_ext_properties_t

Added in version 1.7

struct zes_engine_ext_properties_t

Extension properties related to Engine Groups.

• This structure may be passed to zesEngineGetProperties by having the pNext member of zes_engine_properties_t point at this struct.

• Used for SRIOV per Virtual Function device utilization by zes_engine_group_t

Public Members

zes_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint32_t countOfVirtualFunctionInstance

[out] Number of Virtual Function(VF) instances associated with engine to monitor the utilization of hardware across all Virtual Function from a Physical Function (PF) instance. These VF-by-VF views should provide engine group and individual engine level granularity. This count represents the number of VF instances that are actively using the resource represented by the engine handle.