VF Management - Experimental

Contents

VF Management - Experimental#

oneAPI Level Zero Specification - Version 1.18.31

VF Management - Experimental Functions#

zesVFManagementGetVFPropertiesExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFPropertiesExp(zes_vf_handle_t hVFhandle, zes_vf_exp_properties_t *pProperties)#

Get virtual function management properties.

  • [DEPRECATED] No longer supported. Use zesVFManagementGetVFCapabilitiesExp.

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

  • pProperties – [in,out] Will contain VF properties.

Returns:

zesVFManagementGetVFMemoryUtilizationExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFMemoryUtilizationExp(zes_vf_handle_t hVFhandle, uint32_t *pCount, zes_vf_util_mem_exp_t *pMemUtil)#

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

  • [DEPRECATED] No longer supported. Use zesVFManagementGetVFMemoryUtilizationExp2.

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

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

  • 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:

zesVFManagementGetVFEngineUtilizationExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFEngineUtilizationExp(zes_vf_handle_t hVFhandle, uint32_t *pCount, zes_vf_util_engine_exp_t *pEngineUtil)#

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

  • [DEPRECATED] No longer supported. Use zesVFManagementGetVFEngineUtilizationExp2.

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

  • 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:

zesVFManagementSetVFTelemetryModeExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementSetVFTelemetryModeExp(zes_vf_handle_t hVFhandle, zes_vf_info_util_exp_flags_t flags, ze_bool_t enable)#

Configure utilization telemetry enabled or disabled associated with Virtual Function (VF)

  • [DEPRECATED] No longer supported.

  • 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 component.

  • flags – [in] utilization flags to enable or disable. May be 0 or a valid combination of zes_vf_info_util_exp_flag_t.

  • enable – [in] Enable utilization telemetry.

Returns:

zesVFManagementSetVFTelemetrySamplingIntervalExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementSetVFTelemetrySamplingIntervalExp(zes_vf_handle_t hVFhandle, zes_vf_info_util_exp_flags_t flag, uint64_t samplingInterval)#

Set sampling interval to monitor for a particular utilization telemetry associated with Virtual Function (VF)

  • [DEPRECATED] No longer supported.

  • 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 component.

  • flag – [in] utilization flags to set sampling interval. May be 0 or a valid combination of zes_vf_info_util_exp_flag_t.

  • samplingInterval – [in] Sampling interval value.

Returns:

zesVFManagementGetVFCapabilitiesExp#

Added in version 1.10

ZE_APIEXPORT ze_result_t ZE_APICALL zesVFManagementGetVFCapabilitiesExp(zes_vf_handle_t hVFhandle, zes_vf_exp_capabilities_t *pCapability)#

Get virtual function management capabilities.

  • [DEPRECATED] No longer supported. Use zesVFManagementGetVFCapabilitiesExp2.

  • 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:

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:

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:

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:

VF Management - Experimental Enums#

zes_vf_info_mem_type_exp_flags_t#

Added in version 1.9

enum zes_vf_info_mem_type_exp_flag_t#

Values:

enumerator ZES_VF_INFO_MEM_TYPE_EXP_FLAG_MEM_TYPE_SYSTEM#

System memory.

enumerator ZES_VF_INFO_MEM_TYPE_EXP_FLAG_MEM_TYPE_DEVICE#

Device local memory.

enumerator ZES_VF_INFO_MEM_TYPE_EXP_FLAG_FORCE_UINT32#

Value marking end of ZES_VF_INFO_MEM_TYPE_EXP_FLAG_* ENUMs.

zes_vf_info_util_exp_flags_t#

Added in version 1.9

enum zes_vf_info_util_exp_flag_t#

Values:

enumerator ZES_VF_INFO_UTIL_EXP_FLAG_INFO_NONE#

No info associated with virtual function.

enumerator ZES_VF_INFO_UTIL_EXP_FLAG_INFO_MEM_CPU#

System memory utilization associated with virtual function.

enumerator ZES_VF_INFO_UTIL_EXP_FLAG_INFO_MEM_GPU#

Device memory utilization associated with virtual function.

enumerator ZES_VF_INFO_UTIL_EXP_FLAG_INFO_ENGINE#

Engine utilization associated with virtual function.

enumerator ZES_VF_INFO_UTIL_EXP_FLAG_FORCE_UINT32#

Value marking end of ZES_VF_INFO_UTIL_EXP_FLAG_* ENUMs.

VF Management - Experimental Structures#

zes_vf_exp_properties_t#

Added in version 1.9

struct zes_vf_exp_properties_t#

Virtual function management properties (deprecated)

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

zes_uuid_t uuid#

[out] universal unique identifier of the device

zes_vf_info_util_exp_flags_t flags#

[out] utilization flags available. May be 0 or a valid combination of zes_vf_info_util_exp_flag_t.

zes_vf_util_mem_exp_t#

Added in version 1.9

struct zes_vf_util_mem_exp_t#

Provides memory utilization values for a virtual function (deprecated)

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_vf_info_mem_type_exp_flags_t memTypeFlags#

[out] Memory type flags.

uint64_t free#

[out] Free memory size in bytes.

uint64_t size#

[out] Total allocatable memory in bytes.

uint64_t timestamp#

[out] Wall clock time from VF when value was sampled.

zes_vf_util_engine_exp_t#

Added in version 1.9

struct zes_vf_util_engine_exp_t#

Provides engine utilization values for a virtual function (deprecated)

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 type#

[out] The engine group.

uint64_t activeCounterValue#

[out] Represents active counter.

uint64_t samplingCounterValue#

[out] Represents counter value when activeCounterValue was sampled.

uint64_t timestamp#

[out] Wall clock time when the activeCounterValue was sampled.

zes_vf_exp_capabilities_t#

Added in version 1.10

struct zes_vf_exp_capabilities_t#

Virtual function management capabilities (deprecated)

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

uint32_t vfDeviceMemSize#

[out] Virtual function memory size in kilo bytes

uint32_t vfID#

[out] Virtual Function ID

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