VF Management - Experimental

oneAPI Level Zero Specification - Version 1.20.41

VF Management - Experimental Functions

zesVFManagementGetVFMemoryUtilizationExp2

Added in version 1.10

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFMemoryUtilizationExp2(zes_vf_handle_t hVFhandle, uint32_t *pCount, zes_vf_util_mem_exp2_t *pMemUtil)

Get memory activity stats for each available memory types associated with Virtual Function (VF)

• The application may call this function from simultaneous threads.

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

• If VF is disable/pause/not active, utilization will give zero value.

Parameters:

• hVFhandle – [in] Sysman handle for the component.

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

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

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

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

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

  • the implementation shall populate the vector pCount-1 number of VF memory 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 == hVFhandle

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zesVFManagementGetVFEngineUtilizationExp2

Added in version 1.10

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFEngineUtilizationExp2(zes_vf_handle_t hVFhandle, uint32_t *pCount, zes_vf_util_engine_exp2_t *pEngineUtil)

Get engine activity stats for each available engine group associated with Virtual Function (VF)

• The application may call this function from simultaneous threads.

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

• If VF is disable/pause/not active, utilization will give zero value.

Parameters:

• hVFhandle – [in] Sysman 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.

• pEngineUtil – [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 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 == hVFhandle

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zesVFManagementGetVFCapabilitiesExp2

Added in version 1.12

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFCapabilitiesExp2(zes_vf_handle_t hVFhandle, zes_vf_exp2_capabilities_t *pCapability)

Get virtual function management capabilities.

• The application may call this function from simultaneous threads.

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

Parameters:

• hVFhandle – [in] Sysman handle for the VF component.

• pCapability – [in,out] Will contain VF capability.

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 == hVFhandle

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCapability

VF Management - Experimental Structures

zes_vf_exp2_capabilities_t

Added in version 1.12

struct zes_vf_exp2_capabilities_t

Virtual function management capabilities.

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).

zes_pci_address_t address

[out] Virtual function BDF address

uint64_t vfDeviceMemSize

[out] Virtual function memory size in bytes

uint32_t vfID

[out] Virtual Function ID

zes_vf_util_mem_exp2_t

Added in version 1.10

struct zes_vf_util_mem_exp2_t

Provides memory utilization values for a virtual function.

Public Members

zes_structure_type_t stype

[in] type of this structure

const void *pNext

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

zes_mem_loc_t vfMemLocation

[out] Location of this memory (system, device)

uint64_t vfMemUtilized

[out] Utilized memory size in bytes.

zes_vf_util_engine_exp2_t

Added in version 1.10

struct zes_vf_util_engine_exp2_t

Provides engine utilization values for a virtual function.

• Percent utilization is calculated by taking two snapshots (s1, s2) and using the equation: util = (s2.activeCounterValue - s1.activeCounterValue) / (s2.samplingCounterValue - s1.samplingCounterValue)

Public Members

zes_structure_type_t stype

[in] type of this structure

const void *pNext

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

zes_engine_group_t vfEngineType

[out] The engine group.

uint64_t activeCounterValue

[out] Represents active counter.

uint64_t samplingCounterValue

[out] Represents counter value when activeCounterValue was sampled. Refer to the formulae above for calculating the utilization percent