Context

Context#

oneAPI Level Zero Specification - Version 1.18.31

Context Functions#

zeContextCreate#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextCreate(ze_driver_handle_t hDriver, const ze_context_desc_t *desc, ze_context_handle_t *phContext)#

Creates a context for the driver.

  • The application must only use the context for the driver which was provided during creation.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hDriver – [in] handle of the driver object

  • desc – [in] pointer to context descriptor

  • phContext – [out] pointer to handle of context object created

Returns:

zeContextDestroy#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextDestroy(ze_context_handle_t hContext)#

Destroys a context.

  • The application must ensure the device is not currently referencing the context before it is deleted.

  • The implementation of this function may immediately free all Host and Device allocations associated with this context.

  • The application must not call this function from simultaneous threads with the same context handle.

  • The implementation of this function must be thread-safe.

Parameters:

hContext – [in][release] handle of context object to destroy

Returns:

zeContextGetStatus#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextGetStatus(ze_context_handle_t hContext)#

Returns current status of the context.

  • The application may call this function from simultaneous threads with the same context handle.

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

Parameters:

hContext – [in] handle of context object

Returns:

zeContextSystemBarrier#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextSystemBarrier(ze_context_handle_t hContext, ze_device_handle_t hDevice)#

Ensures in-bound writes to the device are globally observable.

  • This is a special-case system level barrier that can be used to ensure global observability of writes; typically needed after a producer (e.g., NIC) performs direct writes to the device’s memory (e.g., Direct RDMA writes). This is typically required when the memory corresponding to the writes is subsequently accessed from a remote device.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of context object

  • hDevice – [in] handle of the device

Returns:

zeContextMakeMemoryResident#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextMakeMemoryResident(ze_context_handle_t hContext, ze_device_handle_t hDevice, void *ptr, size_t size)#

Makes memory resident for the device.

  • The application must ensure the memory is resident before being referenced by the device

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of context object

  • hDevice – [in] handle of the device

  • ptr – [in] pointer to memory to make resident

  • size – [in] size in bytes to make resident

Returns:

zeContextEvictMemory#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextEvictMemory(ze_context_handle_t hContext, ze_device_handle_t hDevice, void *ptr, size_t size)#

Allows memory to be evicted from the device.

  • The application must ensure the device is not currently referencing the memory before it is evicted

  • The application may free the memory without evicting; the memory is implicitly evicted when freed.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of context object

  • hDevice – [in] handle of the device

  • ptr – [in] pointer to memory to evict

  • size – [in] size in bytes to evict

Returns:

zeContextMakeImageResident#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextMakeImageResident(ze_context_handle_t hContext, ze_device_handle_t hDevice, ze_image_handle_t hImage)#

Makes image resident for the device.

  • The application must ensure the image is resident before being referenced by the device

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of context object

  • hDevice – [in] handle of the device

  • hImage – [in] handle of image to make resident

Returns:

zeContextEvictImage#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextEvictImage(ze_context_handle_t hContext, ze_device_handle_t hDevice, ze_image_handle_t hImage)#

Allows image to be evicted from the device.

  • The application must ensure the device is not currently referencing the image before it is evicted

  • The application may destroy the image without evicting; the image is implicitly evicted when destroyed.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of context object

  • hDevice – [in] handle of the device

  • hImage – [in] handle of image to make evict

Returns:

zeContextCreateEx#

Added in version 1.1

ZE_APIEXPORT ze_result_t ZE_APICALL zeContextCreateEx(ze_driver_handle_t hDriver, const ze_context_desc_t *desc, uint32_t numDevices, ze_device_handle_t *phDevices, ze_context_handle_t *phContext)#

Creates a context for the driver.

  • The application must only use the context for the driver which was provided during creation.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hDriver – [in] handle of the driver object

  • desc – [in] pointer to context descriptor

  • numDevices – [in][optional] number of device handles; must be 0 if nullptr == phDevices

  • phDevices – [in][optional][range(0, numDevices)] array of device handles which context has visibility. if nullptr, then all devices and any sub-devices supported by the driver instance are visible to the context. otherwise, the context only has visibility to the devices and any sub-devices of the devices in this array.

  • phContext – [out] pointer to handle of context object created

Returns:

Context Enums#

ze_context_flags_t#

Added in version 1.0

enum ze_context_flag_t#

Values:

enumerator ZE_CONTEXT_FLAG_TBD#

reserved for future use

enumerator ZE_CONTEXT_FLAG_FORCE_UINT32#

Value marking end of ZE_CONTEXT_FLAG_* ENUMs.

ze_power_saving_hint_type_t#

Added in version 1.2

enum ze_power_saving_hint_type_t#

Supported device types.

Deprecated:

since 1.18: Use ze_power_saving_hint_ext_type_t instead.

Values:

enumerator ZE_POWER_SAVING_HINT_TYPE_MIN#

Minimum power savings. The device will make no attempt to save power while executing work submitted to this context.

enumerator ZE_POWER_SAVING_HINT_TYPE_MAX#

Maximum power savings. The device will do everything to bring power to a minimum while executing work submitted to this context.

enumerator ZE_POWER_SAVING_HINT_TYPE_FORCE_UINT32#

Value marking end of ZE_POWER_SAVING_HINT_TYPE_* ENUMs.

Context Structures#

ze_context_desc_t#

Added in version 1.0

struct ze_context_desc_t#

Context descriptor.

Public Members

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

ze_context_flags_t flags#

[in] creation flags. must be 0 (default) or a valid combination of ze_context_flag_t; default behavior may use implicit driver-based heuristics.