Global - Extensions

Global - Extensions#

oneAPI Level Zero Specification - Version 1.20.41

Global - Extension Structures#

ze_init_driver_app_version_ext_desc_t#

Added in version 1.18

struct ze_init_driver_app_version_ext_desc_t#

Declares the maximum core API version supported by the application.

  • This structure may be passed to zeInitDrivers, via the pNext member of ze_init_driver_type_desc_t, to declare the maximum core API version the application was built against and is able to handle.

  • ’oneAPI’ Level-Zero otherwise provides no mechanism for an application to communicate the API version it supports to a driver; zeDriverGetApiVersion only reports the version supported by the driver, not the application. A driver may use the application-declared version to gate version-dependent behavior for backward compatibility, for example only reporting enumerants or memory types introduced in newer API versions to applications that understand them.

  • If this structure is not provided, the driver must assume the application supports only the baseline behavior and must not rely on any version-gated behavior being understood by the application.

  • A driver should clamp version-gated behavior to the minimum of the version it supports and the version the application declares.

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_api_version_t apiVersionHint#

[in] maximum core ‘oneAPI’ Level-Zero API version supported by the application.

ze_init_driver_properties_ext_desc_t#

Added in version 1.20

struct ze_init_driver_properties_ext_desc_t#

Init Driver Properties descriptor.

  • This structure may be passed to zeInitDrivers, via the pNext member of ze_init_driver_type_desc_t, to declare driver-wide properties for the driver(s) being initialized. It is a general-purpose extension point; additional flags may be added to ze_init_driver_properties_ext_flags_t in the future without requiring a new structure or a new ze_structure_type_t value.

  • OPTIMIZE_MEMORY requests that the driver(s) being initialized reduce their memory footprint, mirroring ZE_CONTEXT_FLAG_OPTIMIZE_MEMORY but applied at driver initialization instead of per-context. When set, it establishes the default memory-optimization behavior for the driver(s) initialized by this call; contexts subsequently created via zeContextCreate or zeContextCreateEx without an explicit ZE_CONTEXT_FLAG_OPTIMIZE_MEMORY or ZE_CONTEXT_FLAG_OPTIMIZE_PERFORMANCE flag inherit this default. A context that explicitly sets its own ze_context_flags_t flags overrides the driver-level default for that context.

  • OPTIMIZE_PERFORMANCE explicitly requests that the driver(s) being initialized optimize for performance, mirroring ZE_CONTEXT_FLAG_OPTIMIZE_PERFORMANCE but applied at driver initialization instead of per-context. When set, it establishes the default performance-optimization behavior for the driver(s) initialized by this call in the same way that setting OPTIMIZE_MEMORY establishes the opposite default. OPTIMIZE_MEMORY and OPTIMIZE_PERFORMANCE are mutually exclusive; if both are set, zeInitDrivers returns ZE_RESULT_ERROR_INVALID_ARGUMENT.

  • If neither OPTIMIZE_MEMORY nor OPTIMIZE_PERFORMANCE is set, the memory/performance trade-off for the driver(s) initialized by this call is driver implementation specific.

  • The default context returned by zeDriverGetDefaultContext is created by the driver itself, not via zeContextCreate or zeContextCreateEx, so the application cannot supply ze_context_flags_t for it. The default context follows the driver-level default established by this structure, if one was established; otherwise its memory/performance trade-off is driver implementation specific.

  • If this structure is not provided, the driver must assume no driver-wide properties were requested and fall back to its standard default behavior for each unset flag.

  • This structure has no effect on drivers already initialized by a prior call to zeInitDrivers or zeInit; those drivers keep whatever behavior was in effect when they were first initialized.

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_init_driver_properties_ext_flags_t flags#

[in] driver property flags. must be 0 (default) or a valid combination of ze_init_driver_properties_ext_flag_t.