feature: add support for metric markers

Related-To: NEO-12058

Signed-off-by: Joshua Santosh Ranjan <[email protected]>

Author: joshuaranjan

level_zero/api/driver_experimental/public/CMakeLists.txt

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2020-2024 Intel Corporation
+# Copyright (C) 2020-2025 Intel Corporation
 #
 # SPDX-License-Identifier: MIT
 #
@@ -14,4 +14,5 @@ target_sources(${L0_STATIC_LIB_NAME}
                ${CMAKE_CURRENT_SOURCE_DIR}/zex_event.cpp
                ${CMAKE_CURRENT_SOURCE_DIR}/zex_memory.cpp
                ${CMAKE_CURRENT_SOURCE_DIR}/zex_module.cpp
+               ${CMAKE_CURRENT_SOURCE_DIR}/zex_metric.cpp
 )

level_zero/api/driver_experimental/public/zex_metric.cpp

@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2025 Intel Corporation
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ */
+
+#include "level_zero/tools/source/metrics/metric.h"
+#include "level_zero/zet_intel_gpu_metric.h"
+
+namespace L0 {
+
+ze_result_t ZE_APICALL zetIntelCommandListAppendMarkerExp(zet_command_list_handle_t hCommandList,
+                                                          zet_metric_group_handle_t hMetricGroup,
+                                                          uint32_t value) {
+
+    auto metricGroupImp = static_cast<MetricGroupImp *>(L0::MetricGroup::fromHandle(hMetricGroup));
+    return metricGroupImp->getMetricSource().appendMarker(hCommandList, hMetricGroup, value);
+}
+
+} // namespace L0
+
+extern "C" {
+
+ze_result_t ZE_APICALL
+zetIntelCommandListAppendMarkerExp(
+    zet_command_list_handle_t hCommandList,
+    zet_metric_group_handle_t hMetricGroup,
+    uint32_t value) {
+    return L0::zetIntelCommandListAppendMarkerExp(hCommandList, hMetricGroup, value);
+}
+}

level_zero/core/source/driver/driver_handle_imp_helper.cpp

@@ -8,6 +8,7 @@
 #include "level_zero/core/source/driver/driver_handle_imp.h"
 #include "level_zero/driver_experimental/zex_common.h"
 #include "level_zero/ze_intel_gpu.h"
+#include "level_zero/zet_intel_gpu_metric.h"
 
 namespace L0 {
 const std::vector<std::pair<std::string, uint32_t>> DriverHandleImp::extensionsSupported = {
@@ -43,5 +44,8 @@ const std::vector<std::pair<std::string, uint32_t>> DriverHandleImp::extensionsS
     {ZEX_INTEL_EVENT_SYNC_MODE_EXP_NAME, ZEX_INTEL_EVENT_SYNC_MODE_EXP_VERSION_CURRENT},
     {ZE_INTEL_GET_DRIVER_VERSION_STRING_EXP_NAME, ZE_INTEL_GET_DRIVER_VERSION_STRING_EXP_VERSION_CURRENT},
     {ZE_INTEL_DEVICE_BLOCK_ARRAY_EXP_NAME, ZE_INTEL_DEVICE_BLOCK_ARRAY_EXP_PROPERTIES_VERSION_CURRENT},
-    {ZE_INTEL_KERNEL_GET_PROGRAM_BINARY_EXP_NAME, ZE_INTEL_KERNEL_GET_PROGRAM_BINARY_EXP_VERSION_CURRENT}};
+    {ZE_INTEL_KERNEL_GET_PROGRAM_BINARY_EXP_NAME, ZE_INTEL_KERNEL_GET_PROGRAM_BINARY_EXP_VERSION_CURRENT},
+
+    // Metrics Driver experimental extensions
+    {ZET_INTEL_METRIC_APPEND_MARKER_EXP_NAME, ZET_INTEL_METRIC_APPEND_MARKER_EXP_VERSION_CURRENT}};
 } // namespace L0

level_zero/core/source/driver/extension_function_address.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2024 Intel Corporation
+ * Copyright (C) 2024-2025 Intel Corporation
  *
  * SPDX-License-Identifier: MIT
  *
@@ -62,6 +62,7 @@ void *ExtensionFunctionAddressHelper::getExtensionFunctionAddress(const std::str
     RETURN_FUNC_PTR_IF_EXIST(zeIntelCommandListAppendWaitExternalSemaphoresExp);
     RETURN_FUNC_PTR_IF_EXIST(zeIntelCommandListAppendSignalExternalSemaphoresExp);
     RETURN_FUNC_PTR_IF_EXIST(zeIntelDeviceReleaseExternalSemaphoreExp);
+    RETURN_FUNC_PTR_IF_EXIST(zetIntelCommandListAppendMarkerExp);
 
 #undef RETURN_FUNC_PTR_IF_EXIST
 

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

@@ -725,6 +725,15 @@ class MockCommandListImmediateHw : public WhiteBox<::L0::CommandListCoreFamilyIm
         return executeCommandListImmediateWithFlushTaskReturnValue;
     }
 
+    ze_result_t appendWriteToMemory(void *desc, void *ptr,
+                                    uint64_t data) override {
+        ++appendWriteToMemoryCalledCount;
+        if (callAppendWriteToMemoryBase) {
+            return BaseClass::appendWriteToMemory(desc, ptr, data);
+        }
+        return appendWriteToMemoryCalledCountReturnValue;
+    }
+
     void checkAssert() override {
         checkAssertCalled++;
     }
@@ -750,6 +759,10 @@ class MockCommandListImmediateHw : public WhiteBox<::L0::CommandListCoreFamilyIm
 
     ze_result_t executeCommandListImmediateWithFlushTaskReturnValue = ZE_RESULT_SUCCESS;
     uint32_t executeCommandListImmediateWithFlushTaskCalledCount = 0;
+
+    bool callAppendWriteToMemoryBase = true;
+    ze_result_t appendWriteToMemoryCalledCountReturnValue = ZE_RESULT_SUCCESS;
+    uint32_t appendWriteToMemoryCalledCount = 0;
 };
 
 struct CmdListHelper {

level_zero/include/level_zero/zet_intel_gpu_metric.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2023-2024 Intel Corporation
+ * Copyright (C) 2023-2025 Intel Corporation
  *
  * SPDX-License-Identifier: MIT
  *
@@ -22,6 +22,29 @@ extern "C" {
 #define ZET_INTEL_MAX_METRIC_GROUP_NAME_PREFIX_EXP 64u
 #define ZET_INTEL_METRIC_PROGRAMMABLE_PARAM_TYPE_GENERIC_EXP (0x7ffffffe)
 
+#ifndef ZET_INTEL_METRIC_APPEND_MARKER_EXP_NAME
+/// @brief Extension name for query to read the Intel Level Zero Driver Version String
+#define ZET_INTEL_METRIC_APPEND_MARKER_EXP_NAME "ZET_intel_metric_append_marker"
+#endif // ZET_INTEL_APPEND_MARKER_EXP_NAME
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Append Marker extension Version(s)
+typedef enum _zet_intel_metric_append_marker_exp_version_t {
+    ZET_INTEL_METRIC_APPEND_MARKER_EXP_VERSION_1_0 = ZE_MAKE_VERSION(1, 0),     ///< version 1.0
+    ZET_INTEL_METRIC_APPEND_MARKER_EXP_VERSION_CURRENT = ZE_MAKE_VERSION(1, 0), ///< latest known version
+    ZET_INTEL_METRIC_APPEND_MARKER_EXP_VERSION_FORCE_UINT32 = 0x7fffffff
+} zet_intel_metric_append_marker_exp_version_t;
+
+#define ZET_INTEL_METRIC_GROUP_TYPE_EXP_FLAG_MARKER (static_cast<zet_metric_group_type_exp_flag_t>(ZE_BIT(3))) // NOLINT(clang-analyzer-optin.core.EnumCastOutOfRange), NEO-12901
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Appends a metric marker to the command list based on the metricGroup
+/// Metrics can be generated by multiple sources in the HW
+/// This API generates a marker through the same source as the metric group
+ze_result_t ZE_APICALL zetIntelCommandListAppendMarkerExp(zet_command_list_handle_t hCommandList,
+                                                          zet_metric_group_handle_t hMetricGroup,
+                                                          uint32_t value);
+
 #if defined(__cplusplus)
 } // extern "C"
 #endif

level_zero/tools/source/metrics/metric.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2020-2024 Intel Corporation
+ * Copyright (C) 2020-2025 Intel Corporation
  *
  * SPDX-License-Identifier: MIT
  *
@@ -89,6 +89,7 @@ class MetricSource {
                                                       const char description[ZET_MAX_METRIC_GROUP_DESCRIPTION],
                                                       uint32_t *maxMetricGroupCount,
                                                       std::vector<zet_metric_group_handle_t> &metricGroupList) = 0;
+    virtual ze_result_t appendMarker(zet_command_list_handle_t hCommandList, zet_metric_group_handle_t hMetricGroup, uint32_t value) = 0;
 
   protected:
     uint32_t type = MetricSource::metricSourceTypeUndefined;

level_zero/tools/source/metrics/metric_ip_sampling_source.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2022-2024 Intel Corporation
+ * Copyright (C) 2022-2025 Intel Corporation
  *
  * SPDX-License-Identifier: MIT
  *
@@ -48,10 +48,14 @@ class IpSamplingMetricSourceImp : public MetricSource {
                                               std::vector<zet_metric_group_handle_t> &metricGroupList) override {
         return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE;
     }
+    ze_result_t appendMarker(zet_command_list_handle_t hCommandList, zet_metric_group_handle_t hMetricGroup, uint32_t value) override {
+        return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE;
+    }
 
     void setActivationTracker(MultiDomainDeferredActivationTracker *inputActivationTracker) {
         activationTracker.reset(inputActivationTracker);
     }
+
     uint32_t metricSourceCount = 0;
 
   protected:

level_zero/tools/source/metrics/metric_oa_source.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2022-2024 Intel Corporation
+ * Copyright (C) 2022-2025 Intel Corporation
  *
  * SPDX-License-Identifier: MIT
  *
@@ -59,6 +59,9 @@ class OaMetricSourceImp : public MetricSource {
                                               const char description[ZET_MAX_METRIC_GROUP_DESCRIPTION],
                                               uint32_t *maxMetricGroupCount,
                                               std::vector<zet_metric_group_handle_t> &metricGroupList) override;
+    ze_result_t appendMarker(zet_command_list_handle_t hCommandList, zet_metric_group_handle_t hMetricGroup, uint32_t value) override {
+        return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE;
+    }
     void metricGroupCreate(const char name[ZET_MAX_METRIC_GROUP_NAME],
                            const char description[ZET_MAX_METRIC_GROUP_DESCRIPTION],
                            zet_metric_group_sampling_type_flag_t samplingType,

level_zero/tools/test/unit_tests/sources/metrics/mock_metric_source.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2020-2024 Intel Corporation
+ * Copyright (C) 2020-2025 Intel Corporation
  *
  * SPDX-License-Identifier: MIT
  *
@@ -38,6 +38,10 @@ class MockMetricSource : public L0::MetricSource {
                                           uint32_t *pCountPerConcurrentGroup) override {
         return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE;
     }
+    ze_result_t appendMarker(zet_command_list_handle_t hCommandList, zet_metric_group_handle_t hMetricGroup, uint32_t value) override {
+        return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE;
+    }
+
     void setType(uint32_t type) {
         this->type = type;
     }

level_zero/tools/test/unit_tests/sources/metrics/test_metric_ip_sampling_enumeration.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2022-2024 Intel Corporation
+ * Copyright (C) 2022-2025 Intel Corporation
  *
  * SPDX-License-Identifier: MIT
  *
@@ -262,6 +262,8 @@ HWTEST2_F(MetricIpSamplingEnumerationTest, GivenEnumerationIsSuccessfulThenUnsup
         EXPECT_EQ(zetContextActivateMetricGroups(context->toHandle(), device->toHandle(), 1, &metricGroups[0]), ZE_RESULT_SUCCESS);
         static_cast<DeviceImp *>(device)->activateMetricGroups();
         EXPECT_EQ(zetContextActivateMetricGroups(context->toHandle(), device->toHandle(), 0, nullptr), ZE_RESULT_SUCCESS);
+
+        EXPECT_EQ(zetIntelCommandListAppendMarkerExp(nullptr, metricGroups[0], 0), ZE_RESULT_ERROR_UNSUPPORTED_FEATURE);
     }
 }
 

level_zero/tools/test/unit_tests/sources/metrics/test_metric_oa_enumeration_1.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2020-2024 Intel Corporation
+ * Copyright (C) 2020-2025 Intel Corporation
  *
  * SPDX-License-Identifier: MIT
  *
@@ -3346,5 +3346,86 @@ TEST_F(MetricEnumerationTest, givenValidArgumentsWhenZetGetMetricGroupProperties
     EXPECT_EQ(metricGroupType.type, ZET_METRIC_GROUP_TYPE_EXP_FLAG_OTHER);
 }
 
+TEST_F(MetricEnumerationTest, givenValidArgumentsWhenAppendMarkerIsCalledThenReturnUnsupportedError) {
+
+    // Metrics Discovery device.
+    metricsDeviceParams.ConcurrentGroupsCount = 1;
+
+    // Metrics Discovery concurrent group.
+    Mock<IConcurrentGroup_1_13> metricsConcurrentGroup;
+    TConcurrentGroupParams_1_13 metricsConcurrentGroupParams = {};
+    metricsConcurrentGroupParams.MetricSetsCount = 1;
+    metricsConcurrentGroupParams.SymbolName = "OA";
+    metricsConcurrentGroupParams.Description = "OA description";
+    metricsConcurrentGroupParams.IoMeasurementInformationCount = 1;
+
+    Mock<MetricsDiscovery::IEquation_1_0> ioReadEquation;
+    MetricsDiscovery::TEquationElement_1_0 ioEquationElement = {};
+    ioEquationElement.Type = MetricsDiscovery::EQUATION_ELEM_IMM_UINT64;
+    ioEquationElement.ImmediateUInt64 = 0;
+
+    ioReadEquation.getEquationElement.push_back(&ioEquationElement);
+
+    Mock<MetricsDiscovery::IInformation_1_0> ioMeasurement;
+    MetricsDiscovery::TInformationParams_1_0 oaInformation = {};
+    oaInformation.SymbolName = "BufferOverflow";
+    oaInformation.IoReadEquation = &ioReadEquation;
+    metricsConcurrentGroup.GetIoMeasurementInformationResult = &ioMeasurement;
+    ioMeasurement.GetParamsResult = &oaInformation;
+
+    // Metrics Discovery:: metric set.
+    Mock<MetricsDiscovery::IMetricSet_1_13> metricsSet;
+    MetricsDiscovery::TMetricSetParams_1_11 metricsSetParams = {};
+    metricsSetParams.ApiMask = MetricsDiscovery::API_TYPE_OCL;
+    metricsSetParams.MetricsCount = 0;
+    metricsSetParams.SymbolName = "Metric set name";
+    metricsSetParams.ShortName = "Metric set description";
+
+    // One api: metric group handle.
+    zet_metric_group_handle_t metricGroupHandle = {};
+
+    openMetricsAdapter();
+
+    setupDefaultMocksForMetricDevice(metricsDevice);
+
+    metricsDevice.getConcurrentGroupResults.push_back(&metricsConcurrentGroup);
+
+    metricsConcurrentGroup.GetParamsResult = &metricsConcurrentGroupParams;
+    metricsConcurrentGroup.getMetricSetResult = &metricsSet;
+
+    metricsSet.GetParamsResult = &metricsSetParams;
+
+    // Metric group count.
+    uint32_t metricGroupCount = 0;
+    EXPECT_EQ(zetMetricGroupGet(device->toHandle(), &metricGroupCount, nullptr), ZE_RESULT_SUCCESS);
+    EXPECT_EQ(metricGroupCount, 1u);
+
+    // Metric group handle.
+    EXPECT_EQ(zetMetricGroupGet(device->toHandle(), &metricGroupCount, &metricGroupHandle), ZE_RESULT_SUCCESS);
+    EXPECT_EQ(metricGroupCount, 1u);
+    EXPECT_NE(metricGroupHandle, nullptr);
+
+    EXPECT_EQ(zetIntelCommandListAppendMarkerExp(nullptr, metricGroupHandle, 0), ZE_RESULT_ERROR_UNSUPPORTED_FEATURE);
+}
+
+using DriverVersionTest = Test<DeviceFixture>;
+
+TEST_F(DriverVersionTest, givenSupportedExtensionsWhenCheckIfAppendMarkerIsSupportedThenCorrectResultsAreReturned) {
+    uint32_t count = 0;
+    ze_result_t res = driverHandle->getExtensionProperties(&count, nullptr);
+    EXPECT_NE(0u, count);
+    EXPECT_EQ(ZE_RESULT_SUCCESS, res);
+
+    std::vector<ze_driver_extension_properties_t> extensionProperties;
+    extensionProperties.resize(count);
+
+    res = driverHandle->getExtensionProperties(&count, extensionProperties.data());
+    EXPECT_EQ(ZE_RESULT_SUCCESS, res);
+
+    auto it = std::find_if(extensionProperties.begin(), extensionProperties.end(), [](const auto &extension) { return (strcmp(extension.name, ZET_INTEL_METRIC_APPEND_MARKER_EXP_NAME) == 0); });
+    EXPECT_NE(it, extensionProperties.end());
+    EXPECT_EQ((*it).version, ZET_INTEL_METRIC_APPEND_MARKER_EXP_VERSION_CURRENT);
+}
+
 } // namespace ult
 } // namespace L0