Engine

Engine#

oneAPI Level Zero Specification - Version 1.18.31

Engine Functions#

zesEngineGetProperties#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesEngineGetProperties(zes_engine_handle_t hEngine, zes_engine_properties_t *pProperties)#

Get engine group properties.

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

  • pProperties – [in,out] The properties for the specified engine group.

Returns:

zesEngineGetActivity#

Added in version 1.7

ZE_APIEXPORT ze_result_t ZE_APICALL zesEngineGetActivity(zes_engine_handle_t hEngine, zes_engine_stats_t *pStats)#

Get the activity stats for an engine group.

  • This function also returns the engine activity inside a Virtual Machine (VM), in the presence of hardware virtualization (SRIOV)

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

  • pStats – [in,out] Will contain a snapshot of the engine group activity counters.

Returns:

Engine Enums#

zes_engine_group_t#

Added in version 1.0

enum zes_engine_group_t#

Accelerator engine groups.

Values:

enumerator ZES_ENGINE_GROUP_ALL#

Access information about all engines combined.

enumerator ZES_ENGINE_GROUP_COMPUTE_ALL#

Access information about all compute engines combined. Compute engines can only process compute kernels (no 3D content).

enumerator ZES_ENGINE_GROUP_MEDIA_ALL#

Access information about all media engines combined.

enumerator ZES_ENGINE_GROUP_COPY_ALL#

Access information about all copy (blitter) engines combined.

enumerator ZES_ENGINE_GROUP_COMPUTE_SINGLE#

Access information about a single compute engine - this is an engine that can process compute kernels. Note that single engines may share the same underlying accelerator resources as other engines so activity of such an engine may not be indicative of the underlying resource utilization - use ZES_ENGINE_GROUP_3D_RENDER_COMPUTE_ALL for that.

enumerator ZES_ENGINE_GROUP_RENDER_SINGLE#

Access information about a single render engine - this is an engine that can process both 3D content and compute kernels. Note that single engines may share the same underlying accelerator resources as other engines so activity of such an engine may not be indicative of the underlying resource utilization - use ZES_ENGINE_GROUP_3D_RENDER_COMPUTE_ALL for that.

enumerator ZES_ENGINE_GROUP_MEDIA_DECODE_SINGLE#

[DEPRECATED] No longer supported.

enumerator ZES_ENGINE_GROUP_MEDIA_ENCODE_SINGLE#

[DEPRECATED] No longer supported.

enumerator ZES_ENGINE_GROUP_COPY_SINGLE#

Access information about a single media encode engine. Note that single engines may share the same underlying accelerator resources as other engines so activity of such an engine may not be indicative of the underlying resource utilization - use ZES_ENGINE_GROUP_COPY_ALL for that.

enumerator ZES_ENGINE_GROUP_MEDIA_ENHANCEMENT_SINGLE#

Access information about a single media enhancement engine. Note that single engines may share the same underlying accelerator resources as other engines so activity of such an engine may not be indicative of the underlying resource utilization - use ZES_ENGINE_GROUP_MEDIA_ALL for that.

enumerator ZES_ENGINE_GROUP_3D_SINGLE#

[DEPRECATED] No longer supported.

enumerator ZES_ENGINE_GROUP_3D_RENDER_COMPUTE_ALL#

[DEPRECATED] No longer supported.

enumerator ZES_ENGINE_GROUP_RENDER_ALL#

Access information about all render engines combined. Render engines are those than process both 3D content and compute kernels.

enumerator ZES_ENGINE_GROUP_3D_ALL#

[DEPRECATED] No longer supported.

enumerator ZES_ENGINE_GROUP_MEDIA_CODEC_SINGLE#

Access information about a single media engine. Note that single engines may share the same underlying accelerator resources as other engines so activity of such an engine may not be indicative of the underlying resource utilization - use ZES_ENGINE_GROUP_MEDIA_ALL for that. (since v1.8)

enumerator ZES_ENGINE_GROUP_FORCE_UINT32#

Value marking end of ZES_ENGINE_GROUP_* ENUMs.

Engine Structures#

zes_engine_properties_t#

Added in version 1.0

struct zes_engine_properties_t#

Engine group properties.

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

[out] The engine group

ze_bool_t onSubdevice#

[out] True if this resource is located on a sub-device; false means that the resource is on the device of the calling Sysman handle

uint32_t subdeviceId#

[out] If onSubdevice is true, this gives the ID of the sub-device

zes_engine_stats_t#

Added in version 1.0

struct zes_engine_stats_t#

Engine activity counters.

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

  • The activeTime time units are implementation-specific since the value is only intended to be used for calculating utilization percentage.

  • The timestamp should only be used to calculate delta between snapshots of this structure.

  • The application should never take the delta of timestamp with the timestamp from a different structure since they are not guaranteed to have the same base.

  • When taking the delta, the difference between timestamp samples could be 0, if the frequency of sampling the snapshots is higher than the frequency of the timestamp update.

  • The absolute value of timestamp is only valid during within the application and may be different on the next execution.

Public Members

uint64_t activeTime#

[out] Monotonic counter where the resource is actively running workloads.

uint64_t timestamp#

[out] Monotonic counter when activeTime counter was sampled.

In this class