feature: add host functions api entry

Related-To: NEO-14577
Signed-off-by: Kamil Kopryk <kamil.kopryk@intel.com>

level_zero/api/driver_experimental/public/zex_cmdlist.cpp

@@ -72,6 +72,20 @@ zexCommandListAppendWriteToMemory(
         return ZE_RESULT_ERROR_UNKNOWN;
     }
 }
+
+ze_result_t ZE_APICALL
+zexCommandListAppendHostFunction(
+    zex_command_list_handle_t hCommandList,
+    void *pHostFunction,
+    void *pUserData,
+    void *pNext,
+    zex_event_handle_t hSignalEvent,
+    uint32_t numWaitEvents,
+    zex_event_handle_t *phWaitEvents) {
+
+    return L0::CommandList::fromHandle(hCommandList)->appendHostFunction(pHostFunction, pUserData, pNext, static_cast<ze_event_handle_t>(hSignalEvent), numWaitEvents, static_cast<ze_event_handle_t *>(phWaitEvents));
+}
+
 } // namespace L0
 
 extern "C" {
@@ -105,4 +119,16 @@ zexCommandListAppendWriteToMemory(
     return L0::zexCommandListAppendWriteToMemory(hCommandList, desc, ptr, data);
 }
 
+ZE_APIEXPORT ze_result_t ZE_APICALL
+zexCommandListAppendHostFunction(
+    zex_command_list_handle_t hCommandList,
+    void *pHostFunction,
+    void *pUserData,
+    void *pNext,
+    zex_event_handle_t hSignalEvent,
+    uint32_t numWaitEvents,
+    zex_event_handle_t *phWaitEvents) {
+    return L0::zexCommandListAppendHostFunction(hCommandList, pHostFunction, pUserData, pNext, hSignalEvent, numWaitEvents, phWaitEvents);
+}
+
 } // extern "C"

level_zero/core/source/cmdlist/cmdlist.h

@@ -228,6 +228,13 @@ struct CommandList : _ze_command_list_handle_t {
     virtual ze_result_t appendCommandLists(uint32_t numCommandLists, ze_command_list_handle_t *phCommandLists,
                                            ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents) = 0;
 
+    virtual ze_result_t appendHostFunction(void *pHostFunction,
+                                           void *pUserData,
+                                           void *pNext,
+                                           ze_event_handle_t hSignalEvent,
+                                           uint32_t numWaitEvents,
+                                           ze_event_handle_t *phWaitEvents) = 0;
+
     static CommandList *create(uint32_t productFamily, Device *device, NEO::EngineGroupType engineGroupType,
                                ze_command_list_flags_t flags, ze_result_t &resultValue,
                                bool internalUsage);

level_zero/core/source/cmdlist/cmdlist_hw.h

@@ -235,7 +235,12 @@ struct CommandListCoreFamily : public CommandListImp {
     MOCKABLE_VIRTUAL void appendSynchronizedDispatchCleanupSection();
     ze_result_t appendCommandLists(uint32_t numCommandLists, ze_command_list_handle_t *phCommandLists,
                                    ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents) override;
-
+    ze_result_t appendHostFunction(void *pHostFunction,
+                                   void *pUserData,
+                                   void *pNext,
+                                   ze_event_handle_t hSignalEvent,
+                                   uint32_t numWaitEvents,
+                                   ze_event_handle_t *phWaitEvents) override;
     ze_result_t reserveSpace(size_t size, void **ptr) override;
     ze_result_t reset() override;
     size_t getReserveSshSize();

level_zero/core/source/cmdlist/cmdlist_hw.inl

@@ -1797,6 +1797,18 @@ bool CommandListCoreFamily<gfxCoreFamily>::isSharedSystemEnabled() const {
     return neoDevice->areSharedSystemAllocationsAllowed() && (NEO::debugManager.flags.TreatNonUsmForTransfersAsSharedSystem.get() == 1);
 }
 
+template <GFXCORE_FAMILY gfxCoreFamily>
+ze_result_t CommandListCoreFamily<gfxCoreFamily>::appendHostFunction(
+    void *pHostFunction,
+    void *pUserData,
+    void *pNext,
+    ze_event_handle_t hSignalEvent,
+    uint32_t numWaitEvents,
+    ze_event_handle_t *phWaitEvents) {
+
+    return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}
+
 template <GFXCORE_FAMILY gfxCoreFamily>
 ze_result_t CommandListCoreFamily<gfxCoreFamily>::appendMemoryCopy(void *dstptr,
                                                                    const void *srcptr,

level_zero/core/source/cmdlist/cmdlist_hw_immediate.h

@@ -203,6 +203,13 @@ struct CommandListCoreFamilyImmediate : public CommandListCoreFamily<gfxCoreFami
                                                              std::unique_lock<std::mutex> *outerLockForIndirect);
     ze_result_t appendCommandLists(uint32_t numCommandLists, ze_command_list_handle_t *phCommandLists,
                                    ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents) override;
+    ze_result_t appendHostFunction(
+        void *pHostFunction,
+        void *pUserData,
+        void *pNext,
+        ze_event_handle_t hSignalEvent,
+        uint32_t numWaitEvents,
+        ze_event_handle_t *phWaitEvents) override;
 
     NEO::CompletionStamp flushRegularTask(NEO::LinearStream &cmdStreamTask, size_t taskStartOffset, bool hasStallingCmds, bool hasRelaxedOrderingDependencies, NEO::AppendOperations appendOperation, bool requireTaskCountUpdate);
     NEO::CompletionStamp flushImmediateRegularTask(NEO::LinearStream &cmdStreamTask, size_t taskStartOffset, bool hasStallingCmds, bool hasRelaxedOrderingDependencies, NEO::AppendOperations appendOperation, bool requireTaskCountUpdate);

level_zero/core/source/cmdlist/cmdlist_hw_immediate.inl

@@ -1032,6 +1032,17 @@ ze_result_t CommandListCoreFamilyImmediate<gfxCoreFamily>::appendWriteToMemory(v
     return flushImmediate(ret, true, false, false, NEO::AppendOperations::nonKernel, false, nullptr, requireTaskCountUpdate, nullptr, nullptr);
 }
 
+template <GFXCORE_FAMILY gfxCoreFamily>
+ze_result_t CommandListCoreFamilyImmediate<gfxCoreFamily>::appendHostFunction(
+    void *pHostFunction,
+    void *pUserData,
+    void *pNext,
+    ze_event_handle_t hSignalEvent,
+    uint32_t numWaitEvents,
+    ze_event_handle_t *phWaitEvents) {
+    return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}
+
 template <GFXCORE_FAMILY gfxCoreFamily>
 ze_result_t CommandListCoreFamilyImmediate<gfxCoreFamily>::appendWaitExternalSemaphores(uint32_t numExternalSemaphores, const ze_external_semaphore_ext_handle_t *hSemaphores,
                                                                                         const ze_external_semaphore_wait_params_ext_t *params, ze_event_handle_t hSignalEvent,

level_zero/core/source/driver/extension_function_address.cpp

@@ -76,6 +76,7 @@ void *ExtensionFunctionAddressHelper::getExtensionFunctionAddress(const std::str
     RETURN_FUNC_PTR_IF_EXIST(zetIntelCommandListAppendMarkerExp);
     RETURN_FUNC_PTR_IF_EXIST(zetDeviceEnableMetricsExp);
     RETURN_FUNC_PTR_IF_EXIST(zetDeviceDisableMetricsExp);
+    RETURN_FUNC_PTR_IF_EXIST(zexCommandListAppendHostFunction);
 
     // mutable command list extension
     RETURN_FUNC_PTR_IF_EXIST(zeCommandListGetNextCommandIdExp);

level_zero/core/test/unit_tests/mocks/mock_cmdlist.h

@@ -641,6 +641,11 @@ struct Mock<CommandList> : public CommandList {
     ADDMETHOD_NOBASE(getDeviceHandle, ze_result_t, ZE_RESULT_SUCCESS, (ze_device_handle_t * phDevice));
     ADDMETHOD_NOBASE(getContextHandle, ze_result_t, ZE_RESULT_SUCCESS, (ze_context_handle_t * phContext));
     ADDMETHOD_NOBASE(getOrdinal, ze_result_t, ZE_RESULT_SUCCESS, (uint32_t * pOrdinal));
+    ADDMETHOD_NOBASE(appendHostFunction, ze_result_t, ZE_RESULT_SUCCESS,
+                     (void *pHostFunction,
+                      void *pUserData,
+                      void *pNext,
+                      ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents));
 
     uint8_t *batchBuffer = nullptr;
     NEO::GraphicsAllocation *mockAllocation = nullptr;

level_zero/core/test/unit_tests/sources/cmdlist/CMakeLists.txt

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2020-2024 Intel Corporation
+# Copyright (C) 2020-2025 Intel Corporation
 #
 # SPDX-License-Identifier: MIT
 #
@@ -26,6 +26,8 @@ target_sources(${TARGET_NAME} PRIVATE
                ${CMAKE_CURRENT_SOURCE_DIR}/test_cmdlist_append_wait_on_events.cpp
                ${CMAKE_CURRENT_SOURCE_DIR}/test_cmdlist_blit.cpp
                ${CMAKE_CURRENT_SOURCE_DIR}/test_cmdlist_fill.cpp
+               ${CMAKE_CURRENT_SOURCE_DIR}/test_cmdlist_host_functions.cpp
+               ${CMAKE_CURRENT_SOURCE_DIR}/test_cmdlist_api.cpp
                ${CMAKE_CURRENT_SOURCE_DIR}/test_cmdlist_memory_extension.cpp
                ${CMAKE_CURRENT_SOURCE_DIR}/test_in_order_cmdlist_1.cpp
                ${CMAKE_CURRENT_SOURCE_DIR}/test_in_order_cmdlist_2.cpp

level_zero/core/test/unit_tests/sources/cmdlist/test_cmdlist_host_functions.cpp

@@ -0,0 +1,42 @@
+/*
+ * Copyright (C) 2025 Intel Corporation
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ */
+
+#include "shared/test/common/test_macros/hw_test.h"
+
+#include "level_zero/core/test/unit_tests/fixtures/device_fixture.h"
+#include "level_zero/core/test/unit_tests/mocks/mock_cmdlist.h"
+#include <level_zero/driver_experimental/zex_cmdlist.h>
+
+namespace L0 {
+namespace ult {
+
+using HostFunctionTests = Test<DeviceFixture>;
+
+HWTEST_F(HostFunctionTests, givenRegularCommandListWhenZexCommandListAppendHostFunctionIsCalledThenUnsupportedFeatureIsReturned) {
+
+    ze_result_t returnValue;
+    std::unique_ptr<L0::CommandList> commandList(CommandList::create(productFamily, device, NEO::EngineGroupType::renderCompute, 0u, returnValue, false));
+
+    auto result =
+        zexCommandListAppendHostFunction(commandList->toHandle(), nullptr, nullptr, nullptr, nullptr, 0, nullptr);
+    EXPECT_EQ(ZE_RESULT_ERROR_UNSUPPORTED_FEATURE, result);
+}
+
+HWTEST_F(HostFunctionTests, givenImmediateCommandListWhenZexCommandListAppendHostFunctionIsCalledThenUnsupportedFeatureIsReturned) {
+
+    ze_result_t returnValue;
+    ze_command_queue_desc_t queueDesc = {};
+    queueDesc.mode = ZE_COMMAND_QUEUE_MODE_SYNCHRONOUS;
+    std::unique_ptr<L0::CommandList> commandList(CommandList::createImmediate(productFamily, device, &queueDesc, false, NEO::EngineGroupType::renderCompute, returnValue));
+
+    auto result =
+        zexCommandListAppendHostFunction(commandList->toHandle(), nullptr, nullptr, nullptr, nullptr, 0, nullptr);
+    EXPECT_EQ(ZE_RESULT_ERROR_UNSUPPORTED_FEATURE, result);
+}
+
+} // namespace ult
+} // namespace L0

level_zero/core/test/unit_tests/sources/driver/test_driver.cpp

@@ -1294,6 +1294,8 @@ TEST_F(DriverExperimentalApiTest, whenRetrievingApiFunctionThenExpectProperPoint
     decltype(&zexCounterBasedEventOpenIpcHandle) expectedCounterBasedEventOpenIpcHandle = zexCounterBasedEventOpenIpcHandle;
     decltype(&zexCounterBasedEventCloseIpcHandle) expectedCounterBasedEventCloseIpcHandle = zexCounterBasedEventCloseIpcHandle;
 
+    decltype(&zexCommandListAppendHostFunction) expectedCommandListAppendHostFunction = zexCommandListAppendHostFunction;
+
     void *funPtr = nullptr;
 
     EXPECT_EQ(ZE_RESULT_SUCCESS, zeDriverGetExtensionFunctionAddress(driverHandle, "zexDriverImportExternalPointer", &funPtr));
@@ -1358,6 +1360,9 @@ TEST_F(DriverExperimentalApiTest, whenRetrievingApiFunctionThenExpectProperPoint
 
     EXPECT_EQ(ZE_RESULT_SUCCESS, zeDriverGetExtensionFunctionAddress(driverHandle, "zexCounterBasedEventCloseIpcHandle", &funPtr));
     EXPECT_EQ(expectedCounterBasedEventCloseIpcHandle, reinterpret_cast<decltype(&zexCounterBasedEventCloseIpcHandle)>(funPtr));
+
+    EXPECT_EQ(ZE_RESULT_SUCCESS, zeDriverGetExtensionFunctionAddress(driverHandle, "zexCommandListAppendHostFunction", &funPtr));
+    EXPECT_EQ(expectedCommandListAppendHostFunction, reinterpret_cast<decltype(&zexCommandListAppendHostFunction)>(funPtr));
 }
 
 TEST_F(DriverExperimentalApiTest, givenHostPointerApiExistWhenImportingPtrThenExpectProperBehavior) {

level_zero/include/level_zero/driver_experimental/zex_cmdlist.h

@@ -42,6 +42,16 @@ zexCommandListAppendWriteToMemory(
     void *ptr,
     uint64_t data);
 
+ZE_APIEXPORT ze_result_t ZE_APICALL
+zexCommandListAppendHostFunction(
+    zex_command_list_handle_t hCommandList,
+    void *pHostFunction,
+    void *pUserData,
+    void *pNext,
+    zex_event_handle_t hSignalEvent,
+    uint32_t numWaitEvents,
+    zex_event_handle_t *phWaitEvents);
+
 #if defined(__cplusplus)
 } // extern "C"
 #endif