feature: Add support for Experimental zexSysmanMemoryGetBandwidth

Related-To: LOCI-3838

Signed-off-by: Mayank Raghuwanshi <[email protected]>

Source: d0d5a03

Author: mraghuwa

level_zero/api/core/ze_driver_api_entrypoints.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2020-2022 Intel Corporation
+ * Copyright (C) 2020-2023 Intel Corporation
  *
  * SPDX-License-Identifier: MIT
  *
@@ -52,7 +52,7 @@ ze_result_t zeDriverGetExtensionFunctionAddress(
     ze_driver_handle_t hDriver,
     const char *name,
     void **ppFunctionAddress) {
-    return L0::DriverHandle::fromHandle(hDriver)->getExtensionFunctionAddress(name, ppFunctionAddress);
+    return L0::BaseDriver::fromHandle(hDriver)->getExtensionFunctionAddress(name, ppFunctionAddress);
 }
 } // namespace L0
 

level_zero/api/driver_experimental/public/CMakeLists.txt

@@ -17,4 +17,6 @@ target_sources(${L0_STATIC_LIB_NAME}
                ${CMAKE_CURRENT_SOURCE_DIR}/zex_memory.h
                ${CMAKE_CURRENT_SOURCE_DIR}/zex_module.cpp
                ${CMAKE_CURRENT_SOURCE_DIR}/zex_module.h
+               ${CMAKE_CURRENT_SOURCE_DIR}/zex_sysman_memory.h
+               ${CMAKE_CURRENT_SOURCE_DIR}/zex_sysman_memory.cpp
 )

level_zero/api/driver_experimental/public/zex_api.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2022 Intel Corporation
+ * Copyright (C) 2022-2023 Intel Corporation
  *
  * SPDX-License-Identifier: MIT
  *
@@ -13,12 +13,15 @@
 
 // 'core' API headers
 #include <level_zero/ze_api.h>
+// 'sysman' API headers
+#include <level_zero/zes_api.h>
 
 // driver experimental API headers
 #include "level_zero/api/driver_experimental/public/zex_cmdlist.h"
 
 #include "zex_driver.h"
 #include "zex_memory.h"
 #include "zex_module.h"
+#include "zex_sysman_memory.h"
 
 #endif // _ZEX_API_H

level_zero/api/driver_experimental/public/zex_sysman_memory.cpp

@@ -0,0 +1,47 @@
+/*
+ * Copyright (C) 2023 Intel Corporation
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ */
+
+#include "level_zero/api/driver_experimental/public/zex_sysman_memory.h"
+
+#include "level_zero/api/driver_experimental/public/zex_api.h"
+#include "level_zero/core/source/driver/driver.h"
+#include "level_zero/core/source/driver/driver_handle.h"
+#include "level_zero/sysman/source/sysman_device.h"
+#include "level_zero/sysman/source/sysman_driver.h"
+#include "level_zero/sysman/source/sysman_driver_handle.h"
+#include "level_zero/tools/source/sysman/memory/memory.h"
+#include "level_zero/tools/source/sysman/sysman.h"
+
+namespace L0 {
+
+ze_result_t ZE_APICALL
+zexSysmanMemoryGetBandwidth(
+    zes_mem_handle_t hMemory,
+    uint64_t *pReadCounters,
+    uint64_t *pWriteCounters,
+    uint64_t *pMaxBandwidth,
+    uint64_t timeout) {
+    if (L0::sysmanInitFromCore) {
+        return L0::Memory::fromHandle(hMemory)->memoryGetBandwidthEx(pReadCounters, pWriteCounters, pMaxBandwidth, timeout);
+    }
+    return L0::Sysman::Memory::fromHandle(hMemory)->memoryGetBandwidthEx(pReadCounters, pWriteCounters, pMaxBandwidth, timeout);
+}
+
+} // namespace L0
+
+extern "C" {
+
+ZE_APIEXPORT ze_result_t ZE_APICALL
+zexSysmanMemoryGetBandwidth(
+    zes_mem_handle_t hMemory,
+    uint64_t *pReadCounters,
+    uint64_t *pWriteCounters,
+    uint64_t *pMaxBandwidth,
+    uint64_t timeout) {
+    return L0::zexSysmanMemoryGetBandwidth(hMemory, pReadCounters, pWriteCounters, pMaxBandwidth, timeout);
+}
+}

level_zero/api/driver_experimental/public/zex_sysman_memory.h

@@ -0,0 +1,46 @@
+/*
+ * Copyright (C) 2023 Intel Corporation
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ */
+
+#ifndef _ZEX_SYSMAN_MEMORY_H
+#define _ZEX_SYSMAN_MEMORY_H
+#if defined(__cplusplus)
+#pragma once
+#endif
+
+#include "level_zero/api/driver_experimental/public/zex_api.h"
+
+namespace L0 {
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Get memory bandwidth
+///
+/// @details
+///     - The application may call this function from simultaneous threads.
+///     - The implementation of this function should be lock-free.
+///
+/// @returns
+///     - ::ZE_RESULT_SUCCESS
+///     - ::ZE_RESULT_ERROR_UNINITIALIZED
+///     - ::ZE_RESULT_ERROR_DEVICE_LOST
+///     - ::ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY
+///     - ::ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY
+///     - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `nullptr == hMemory`
+///     - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `nullptr == pBandwidth`
+///     - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS
+///         + User does not have permissions to query this telemetry.
+ze_result_t ZE_APICALL
+zexSysmanMemoryGetBandwidth(
+    zes_mem_handle_t hMemory, ///<[in] Handleforthecomponent.
+    uint64_t *pReadCounters,  ///<[out] Total bytes read from memory in duration
+    uint64_t *pWriteCounters, ///<[out] Total bytes written to memory in duration
+    uint64_t *pMaxBandwidth,  ///<[out] Maximum bandwidth in units of bytes/sec
+    uint64_t duration         ///<[in] duration in milliseconds
+);
+
+} // namespace L0
+#endif

level_zero/core/source/driver/driver_handle.h

@@ -28,7 +28,12 @@ namespace L0 {
 struct Device;
 struct L0EnvVariables;
 
-struct DriverHandle : _ze_driver_handle_t {
+struct BaseDriver : _ze_driver_handle_t {
+    virtual ze_result_t getExtensionFunctionAddress(const char *pFuncName, void **pfunc) = 0;
+    static BaseDriver *fromHandle(ze_driver_handle_t handle) { return static_cast<BaseDriver *>(handle); }
+};
+
+struct DriverHandle : BaseDriver {
     virtual ze_result_t createContext(const ze_context_desc_t *desc,
                                       uint32_t numDevices,
                                       ze_device_handle_t *phDevices,
@@ -37,7 +42,6 @@ struct DriverHandle : _ze_driver_handle_t {
     virtual ze_result_t getProperties(ze_driver_properties_t *properties) = 0;
     virtual ze_result_t getApiVersion(ze_api_version_t *version) = 0;
     virtual ze_result_t getIPCProperties(ze_driver_ipc_properties_t *pIPCProperties) = 0;
-    virtual ze_result_t getExtensionFunctionAddress(const char *pFuncName, void **pfunc) = 0;
     virtual ze_result_t getExtensionProperties(uint32_t *pCount,
                                                ze_driver_extension_properties_t *pExtensionProperties) = 0;
 

level_zero/core/source/get_extension_function_lookup_map.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2020-2022 Intel Corporation
+ * Copyright (C) 2020-2023 Intel Corporation
  *
  * SPDX-License-Identifier: MIT
  *
@@ -25,6 +25,7 @@ std::unordered_map<std::string, void *> getExtensionFunctionsLookupMap() {
 
     addToMap(lookupMap, zexCommandListAppendWaitOnMemory);
     addToMap(lookupMap, zexCommandListAppendWriteToMemory);
+    addToMap(lookupMap, zexSysmanMemoryGetBandwidth);
 #undef addToMap
 
     return lookupMap;

level_zero/doc/experimental_extensions/SYSMAN_MEMORY_BANDWIDTH.md

@@ -0,0 +1,71 @@
+<!---
+
+Copyright (C) 2023 Intel Corporation
+
+SPDX-License-Identifier: MIT
+
+-->
+
+# Sysman Memory Bandwidth
+
+* [Overview](#Overview)
+* [Interfaces](#Interfaces)
+* [Known Issues and Limitations](#Known-Issues-and-Limitations)
+
+# Overview
+
+`zesMemoryGetBandwidth` exposes memory read, write counters and timestamp. The expectation is these
+counters are monotonically increasing and user can get bandwidth information using two snapshots of
+the read and write counters taken at different instances. However, the counters could overflow
+depending on underlying width of the counter presented by the hardware, and currently there is no
+mechanism with which user can detect these overflows. Therefore `zexSysmanMemoryGetBandwidth` is
+introduced to resolve this problem it takes care of overflow internally. 
+`zexSysmanMemoryGetBandwidth` takes duration as input argument and provides reads and write counter
+values that elapsed in that duration. This interface blocks host thread progress for the duration 
+specified by the user.
+To calculate the bandwidth using `zexSysmanMemoryGetBandwidth` use the formula
+`Bandwidth = (Readcounters + WriteCounters) / duration`
+
+# Interfaces
+
+```cpp
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Get memory bandwidth
+///
+/// @details
+///     - The application may call this function from simultaneous threads.
+///     - The implementation of this function should be lock-free.
+///
+/// @returns
+///     - ::ZE_RESULT_SUCCESS
+///     - ::ZE_RESULT_ERROR_UNINITIALIZED
+///     - ::ZE_RESULT_ERROR_DEVICE_LOST
+///     - ::ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY
+///     - ::ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY
+///     - ::ZE_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `nullptr == hMemory`
+///     - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `nullptr == pBandwidth`
+///     - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS
+///         + User does not have permissions to query this telemetry.
+ze_result_t ZE_APICALL
+zexSysmanMemoryGetBandwidth(
+    zes_mem_handle_t hMemory, ///<[in] Handleforthecomponent.
+    uint64_t *pReadCounters,  ///<[out] Total bytes read from memory in duration
+    uint64_t *pWriteCounters, ///<[out] Total bytes written to memory in duration
+    uint64_t *pMaxBandwidth,  ///<[out] Maximum bandwidth in units of bytes/sec
+    uint64_t duration         ///<[in] duration in milliseconds
+);
+```
+
+```cpp
+typedef ze_result_t (*pFnzexSysmanMemoryGetBandwidth)(zes_mem_handle_t, uint64 *, uint64 *, uint64 *, uint64);
+...
+
+pFnzexSysmanMemoryGetBandwidth zexSysmanMemoryGetBandwidth = nullptr;
+ze_result_t res = zeDriverGetExtensionFunctionAddress(hDriver, "zexSysmanMemoryGetBandwidth", reinterpret_cast<void **>(&zexSysmanMemoryGetBandwidth)));
+```
+
+# Known Issues and Limitations
+
+* Implemented and validation only on Xe HPC (PVC).

level_zero/sysman/source/memory/memory.h

@@ -23,6 +23,7 @@ class Memory : _zes_mem_handle_t {
     virtual ze_result_t memoryGetProperties(zes_mem_properties_t *pProperties) = 0;
     virtual ze_result_t memoryGetBandwidth(zes_mem_bandwidth_t *pBandwidth) = 0;
     virtual ze_result_t memoryGetState(zes_mem_state_t *pState) = 0;
+    virtual ze_result_t memoryGetBandwidthEx(uint64_t *pReadCounters, uint64_t *pWriteCounters, uint64_t *pMaxBandwidth, uint64_t timeout) = 0;
 
     static Memory *fromHandle(zes_mem_handle_t handle) {
         return static_cast<Memory *>(handle);

level_zero/sysman/source/memory/memory_imp.cpp

@@ -23,6 +23,10 @@ ze_result_t MemoryImp::memoryGetProperties(zes_mem_properties_t *pProperties) {
     return ZE_RESULT_SUCCESS;
 }
 
+ze_result_t MemoryImp::memoryGetBandwidthEx(uint64_t *pReadCounters, uint64_t *pWriteCounters, uint64_t *pMaxBandwidth, uint64_t timeout) {
+    return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}
+
 void MemoryImp::init() {
     this->initSuccess = pOsMemory->isMemoryModuleSupported();
     if (this->initSuccess == true) {

level_zero/sysman/source/memory/memory_imp.h

@@ -20,6 +20,7 @@ class MemoryImp : public Memory, NEO::NonCopyableOrMovableClass {
     ze_result_t memoryGetProperties(zes_mem_properties_t *pProperties) override;
     ze_result_t memoryGetBandwidth(zes_mem_bandwidth_t *pBandwidth) override;
     ze_result_t memoryGetState(zes_mem_state_t *pState) override;
+    ze_result_t memoryGetBandwidthEx(uint64_t *pReadCounters, uint64_t *pWriteCounters, uint64_t *pMaxBandwidth, uint64_t timeout) override;
 
     MemoryImp(OsSysman *pOsSysman, bool onSubdevice, uint32_t subDeviceId);
     ~MemoryImp() override;

level_zero/sysman/source/sysman_driver_handle.h

@@ -15,7 +15,7 @@
 namespace L0 {
 namespace Sysman {
 
-struct SysmanDriverHandle : _ze_driver_handle_t {
+struct SysmanDriverHandle : BaseDriver {
     static SysmanDriverHandle *fromHandle(zes_driver_handle_t handle) { return static_cast<SysmanDriverHandle *>(handle); }
     inline zes_driver_handle_t toHandle() { return this; }
 

level_zero/sysman/source/sysman_driver_handle_imp.cpp

@@ -13,6 +13,7 @@
 #include "shared/source/helpers/hw_info.h"
 #include "shared/source/os_interface/os_interface.h"
 
+#include "level_zero/core/source/get_extension_function_lookup_map.h"
 #include "level_zero/sysman/source/sysman_device.h"
 #include "level_zero/sysman/source/sysman_driver.h"
 
@@ -44,6 +45,15 @@ ze_result_t SysmanDriverHandleImp::initialize(NEO::ExecutionEnvironment &executi
     return ZE_RESULT_SUCCESS;
 }
 
+ze_result_t SysmanDriverHandleImp::getExtensionFunctionAddress(const char *pFuncName, void **pfunc) {
+    auto funcAddr = extensionFunctionsLookupMap.find(std::string(pFuncName));
+    if (funcAddr != extensionFunctionsLookupMap.end()) {
+        *pfunc = funcAddr->second;
+        return ZE_RESULT_SUCCESS;
+    }
+    return ZE_RESULT_ERROR_INVALID_ARGUMENT;
+}
+
 SysmanDriverHandle *SysmanDriverHandle::create(NEO::ExecutionEnvironment &executionEnvironment, ze_result_t *returnValue) {
     SysmanDriverHandleImp *driverHandle = new SysmanDriverHandleImp;
     UNRECOVERABLE_IF(nullptr == driverHandle);
@@ -56,6 +66,7 @@ SysmanDriverHandle *SysmanDriverHandle::create(NEO::ExecutionEnvironment &execut
         return nullptr;
     }
 
+    driverHandle->extensionFunctionsLookupMap = getExtensionFunctionsLookupMap();
     GlobalSysmanDriver = driverHandle;
     *returnValue = res;
     return driverHandle;

level_zero/sysman/source/sysman_driver_handle_imp.h

@@ -8,6 +8,9 @@
 #pragma once
 #include "level_zero/sysman/source/sysman_driver_handle.h"
 
+#include <string>
+#include <unordered_map>
+
 namespace L0 {
 namespace Sysman {
 struct SysmanDevice;
@@ -18,6 +21,9 @@ struct SysmanDriverHandleImp : SysmanDriverHandle {
     ze_result_t getDevice(uint32_t *pCount, zes_device_handle_t *phDevices) override;
     std::vector<SysmanDevice *> sysmanDevices;
     uint32_t numDevices = 0;
+
+    ze_result_t getExtensionFunctionAddress(const char *pFuncName, void **pfunc) override;
+    std::unordered_map<std::string, void *> extensionFunctionsLookupMap;
 };
 
 extern struct SysmanDriverHandleImp *GlobalSysmanDriver;

level_zero/tools/source/sysman/memory/linux/os_memory_imp.cpp

@@ -41,6 +41,10 @@ ze_result_t LinuxMemoryImp::getState(zes_mem_state_t *pState) {
     return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE;
 }
 
+ze_result_t LinuxMemoryImp::getBandwidthEx(uint64_t *pReadCounters, uint64_t *pWriteCounters, uint64_t *pMaxBandwidth, uint64_t timeout) {
+    return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}
+
 std::unique_ptr<OsMemory> OsMemory::create(OsSysman *pOsSysman, ze_bool_t onSubdevice, uint32_t subdeviceId) {
     std::unique_ptr<LinuxMemoryImp> pLinuxMemoryImp = std::make_unique<LinuxMemoryImp>(pOsSysman, onSubdevice, subdeviceId);
     return pLinuxMemoryImp;

level_zero/tools/source/sysman/memory/linux/os_memory_imp.h

@@ -21,6 +21,8 @@ class LinuxMemoryImp : public OsMemory, NEO::NonCopyableOrMovableClass {
     ze_result_t getProperties(zes_mem_properties_t *pProperties) override;
     ze_result_t getBandwidth(zes_mem_bandwidth_t *pBandwidth) override;
     ze_result_t getState(zes_mem_state_t *pState) override;
+    ze_result_t getBandwidthEx(uint64_t *pReadCounters, uint64_t *pWriteCounters, uint64_t *pMaxBandwidth, uint64_t timeout) override;
+
     bool isMemoryModuleSupported() override;
     LinuxMemoryImp(OsSysman *pOsSysman, ze_bool_t onSubdevice, uint32_t subdeviceId);
     LinuxMemoryImp() = default;

level_zero/tools/source/sysman/memory/linux/os_memory_imp_dg1.cpp

@@ -41,6 +41,10 @@ ze_result_t LinuxMemoryImp::getBandwidth(zes_mem_bandwidth_t *pBandwidth) {
     return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE;
 }
 
+ze_result_t LinuxMemoryImp::getBandwidthEx(uint64_t *pReadCounters, uint64_t *pWriteCounters, uint64_t *pMaxBandwidth, uint64_t timeout) {
+    return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}
+
 ze_result_t LinuxMemoryImp::getState(zes_mem_state_t *pState) {
     std::vector<NEO::MemoryRegion> deviceRegions;
     if (pDrm->queryMemoryInfo() == false) {