Module

Module#

oneAPI Level Zero Specification - Version 1.18.31

Module Functions#

zeModuleCreate#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleCreate(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_module_desc_t *desc, ze_module_handle_t *phModule, ze_module_build_log_handle_t *phBuildLog)#

Creates a module on the context.

  • Compiles the module for execution on the device.

  • The application must only use the module for the device, or its sub-devices, which was provided during creation.

  • The module can be copied to other devices and contexts within the same driver instance by using zeModuleGetNativeBinary.

  • A build log can optionally be returned to the caller. The caller is responsible for destroying build log using zeModuleBuildLogDestroy.

  • The module descriptor constants are only supported for SPIR-V specialization constants.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device

  • desc – [in] pointer to module descriptor

  • phModule – [out] pointer to handle of module object created

  • phBuildLog – [out][optional] pointer to handle of module’s build log.

Returns:

zeModuleDestroy#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleDestroy(ze_module_handle_t hModule)#

Destroys module.

  • The application must destroy all kernel handles created from the module before destroying the module itself.

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

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

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

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

Parameters:

hModule – [in][release] handle of the module

Returns:

zeModuleGetNativeBinary#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleGetNativeBinary(ze_module_handle_t hModule, size_t *pSize, uint8_t *pModuleNativeBinary)#

Retrieve native binary from Module.

  • The native binary output can be cached to disk and new modules can be later constructed from the cached copy.

  • The native binary will retain debugging information that is associated with a module.

  • The caller can pass nullptr for pModuleNativeBinary when querying only for size.

  • The implementation will copy the native binary into a buffer supplied by the caller.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hModule – [in] handle of the module

  • pSize – [in,out] size of native binary in bytes.

  • pModuleNativeBinary – [in,out][optional] byte pointer to native binary

Returns:

zeModuleGetGlobalPointer#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleGetGlobalPointer(ze_module_handle_t hModule, const char *pGlobalName, size_t *pSize, void **pptr)#

Retrieve global variable pointer from Module.

  • For modules created from SPIR-V the interpretation of pGlobalName is described in the SPIR-V programming guide.

  • For native modules not created from SPIR-V the interpretation of pGlobalName is implementation defined.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hModule – [in] handle of the module

  • pGlobalName – [in] name of global variable in module

  • pSize – [in,out][optional] size of global variable

  • pptr – [in,out][optional] device visible pointer

Returns:

zeModuleGetKernelNames#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleGetKernelNames(ze_module_handle_t hModule, uint32_t *pCount, const char **pNames)#

Retrieve all kernel names in the module.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hModule – [in] handle of the module

  • pCount – [in,out] pointer to the number of names. if count is zero, then the driver shall update the value with the total number of names available. if count is greater than the number of names available, then the driver shall update the value with the correct number of names available.

  • pNames – [in,out][optional][range(0, *pCount)] array of names of functions. if count is less than the number of names available, then driver shall only retrieve that number of names.

Returns:

zeModuleGetProperties#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleGetProperties(ze_module_handle_t hModule, ze_module_properties_t *pModuleProperties)#

Retrieve module properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hModule – [in] handle of the module

  • pModuleProperties – [in,out] query result for module properties.

Returns:

zeModuleGetFunctionPointer#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleGetFunctionPointer(ze_module_handle_t hModule, const char *pFunctionName, void **pfnFunction)#

Retrieve a function pointer from a module by name.

  • The function pointer is unique for the device on which the module was created.

  • The function pointer is no longer valid if module is destroyed.

  • The function name should only refer to callable functions within the module.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hModule – [in] handle of the module

  • pFunctionName – [in] Name of function to retrieve function pointer for.

  • pfnFunction – [out] pointer to function.

Returns:

zeModuleGetDeviceHandle#

Added in version 1.18

ZE_APIEXPORT ze_result_t ZE_APICALL zeModuleGetDeviceHandle(ze_module_handle_t hModule, ze_device_handle_t *phDevice)#

Retrieve the handle of the device on which the module was created.

  • The application may call this function from simultaneous threads.

Parameters:

  • hModule – [in] handle of the module

  • phDevice – [out] handle of the device the module was created for

Returns:

Module Enums#

ze_module_format_t#

Added in version 1.0

enum ze_module_format_t#

Supported module creation input formats.

Values:

enumerator ZE_MODULE_FORMAT_IL_SPIRV#

Format is SPIRV IL format.

enumerator ZE_MODULE_FORMAT_NATIVE#

Format is device native format.

enumerator ZE_MODULE_FORMAT_FORCE_UINT32#

Value marking end of ZE_MODULE_FORMAT_* ENUMs.

ze_module_property_flags_t#

Added in version 1.0

enum ze_module_property_flag_t#

Values:

enumerator ZE_MODULE_PROPERTY_FLAG_IMPORTS#

Module has imports (i.e. imported global variables and/or kernels). See zeModuleDynamicLink.

enumerator ZE_MODULE_PROPERTY_FLAG_FORCE_UINT32#

Value marking end of ZE_MODULE_PROPERTY_FLAG_* ENUMs.

Module Structures#

ze_module_constants_t#

Added in version 1.0

struct ze_module_constants_t#

Specialization constants - User defined constants.

Public Members

uint32_t numConstants#

[in] Number of specialization constants.

const uint32_t *pConstantIds#

[in][range(0, numConstants)] Array of IDs that is sized to numConstants.

const void **pConstantValues#

[in][range(0, numConstants)] Array of pointers to values that is sized to numConstants.

ze_module_desc_t#

Added in version 1.0

struct ze_module_desc_t#

Module 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_module_format_t format#

[in] Module format passed in with pInputModule

size_t inputSize#

[in] size of input IL or ISA from pInputModule.

const uint8_t *pInputModule#

[in] pointer to IL or ISA

const char *pBuildFlags#

[in][optional] string containing one or more (comma-separated) compiler flags. If unsupported, flag is ignored with a warning.

  • ”-ze-opt-disable”

    • Disable optimizations

  • ”-ze-opt-level”

    • Specifies optimization level for compiler. Levels are implementation specific.

      • 0 is no optimizations (equivalent to -ze-opt-disable)

      • 1 is optimize minimally (may be the same as 2)

      • 2 is optimize more (default)

  • ”-ze-opt-greater-than-4GB-buffer-required”

    • Use 64-bit offset calculations for buffers.

  • ”-ze-opt-large-register-file”

    • Increase number of registers available to threads.

  • ”-ze-opt-has-buffer-offset-arg”

    • Extend stateless to stateful optimization to more cases with the use of additional offset (e.g. 64-bit pointer to binding table with 32-bit offset).

  • ”-g”

    • Include debugging information.

const ze_module_constants_t *pConstants#

[in][optional] pointer to specialization constants. Valid only for SPIR-V input. This must be set to nullptr if no specialization constants are provided.

ze_module_properties_t#

Added in version 1.0

struct ze_module_properties_t#

Module properties.

Public Members

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

ze_module_property_flags_t flags#

[out] 0 (none) or a valid combination of ze_module_property_flag_t