Standby

oneAPI Level Zero Specification - Version 1.18.31

Standby Functions

zesStandbyGetProperties

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesStandbyGetProperties(zes_standby_handle_t hStandby, zes_standby_properties_t *pProperties)

Get standby hardware component properties.

• The application may call this function from simultaneous threads.

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

Parameters:

• hStandby – [in] Handle for the component.

• pProperties – [in,out] Will contain the standby hardware properties.

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

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pProperties

zesStandbyGetMode

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesStandbyGetMode(zes_standby_handle_t hStandby, zes_standby_promo_mode_t *pMode)

Get the current standby promotion mode.

• The application may call this function from simultaneous threads.

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

Parameters:

• hStandby – [in] Handle for the component.

• pMode – [in,out] Will contain the current standby mode.

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

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pMode

zesStandbySetMode

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesStandbySetMode(zes_standby_handle_t hStandby, zes_standby_promo_mode_t mode)

Set standby promotion mode.

• The application may call this function from simultaneous threads.

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

Parameters:

• hStandby – [in] Handle for the component.

• mode – [in] New standby mode.

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_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 == hStandby

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • ZES_STANDBY_PROMO_MODE_NEVER < mode

• ZE_RESULT_ERROR_UNSUPPORTED_ENUMERATION

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

  • User does not have permissions to make these modifications.

Standby Enums

zes_standby_type_t

Added in version 1.0

enum zes_standby_type_t

Standby hardware components.

Values:

enumerator ZES_STANDBY_TYPE_GLOBAL

Control the overall standby policy of the device/sub-device.

enumerator ZES_STANDBY_TYPE_FORCE_UINT32

Value marking end of ZES_STANDBY_TYPE_* ENUMs.

zes_standby_promo_mode_t

Added in version 1.0

enum zes_standby_promo_mode_t

Standby promotion modes.

Values:

enumerator ZES_STANDBY_PROMO_MODE_DEFAULT

Best compromise between performance and energy savings.

enumerator ZES_STANDBY_PROMO_MODE_NEVER

The device/component will never shutdown. This can improve performance but uses more energy.

enumerator ZES_STANDBY_PROMO_MODE_FORCE_UINT32

Value marking end of ZES_STANDBY_PROMO_MODE_* ENUMs.

Standby Structures

zes_standby_properties_t

Added in version 1.0

struct zes_standby_properties_t

Standby hardware component 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_standby_type_t type

[out] Which standby hardware component this controls

ze_bool_t onSubdevice

[out] True if the 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