.. _experimental-enqueue-native-command: ================================================================================ Enqueue Native Command ================================================================================ .. warning:: Experimental features: * May be replaced, updated, or removed at any time. * Do not require maintaining API/ABI stability of their own additions over time. * Do not require conformance testing of their own additions. Motivation -------------------------------------------------------------------------------- Interop is an important use case for many programming APIs. Through :ref:`urEnqueueNativeCommandExp` the user can immediately invoke some native API calls in a way that the UR is aware of. In doing so, the UR adapter can integrate its own scheduling of UR commands with native commands. In order for UR to guarantee correct synchronization of commands enqueued within the native API through the function passed to :ref:`urEnqueueNativeCommandExp`\, the function argument must only use the native queue accessed through :ref:`urQueueGetNativeHandle`\. Use of a native queue that is not the native queue returned by :ref:`urQueueGetNativeHandle` results in undefined behavior. Any args that are needed by the func must be passed through a ``void*`` and unpacked within the func. If ``ur_mem_handle_t`` arguments are to be used within ``pfnNativeEnqueue``, they must be accessed using :ref:`urMemGetNativeHandle`\. ``ur_mem_handle_t`` arguments must be packed in the void* argument that will be used in ``pfnNativeEnqueue``, as well as :ref:`urEnqueueNativeCommandExp`\'s ``phMemList`` argument. API -------------------------------------------------------------------------------- Enums ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :ref:`ur-device-info-t` * :ref:`UR_DEVICE_INFO_ENQUEUE_NATIVE_COMMAND_SUPPORT_EXP ` * :ref:`ur-command-t` * :ref:`UR_COMMAND_ENQUEUE_NATIVE_EXP ` * :ref:`ur-exp-enqueue-native-command-flags-t` Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :ref:`ur-exp-enqueue-native-command-properties-t` Functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :ref:`urEnqueueNativeCommandExp` Changelog -------------------------------------------------------------------------------- +-----------+---------------------------+ | Revision | Changes | +===========+===========================+ | 1.0 | Initial Draft | +-----------+---------------------------+ | 1.1 | Make ``phEvent`` optional | +-----------+---------------------------+ Support -------------------------------------------------------------------------------- Adapters which support this experimental feature *must* return true for the new ``:ref:`UR_DEVICE_INFO_ENQUEUE_NATIVE_COMMAND_SUPPORT_EXP `\`` device info query. Contributors -------------------------------------------------------------------------------- * Hugh Delaney `hugh.delaney@codeplay.com `_ * Kenneth Benzie (Benie) `k.benzie@codeplay.com `_ * Ewan Crawford `ewan@codeplay.com `_