Add support for enabling/disabling tracing layer during runtime

* Add support for enabling/disabling tracing layer during runtime

Related-To: VLCLJ-2093

- Added new apis zelEnableTracingLayer & zelDisableTracingLayer to
  enable the tracing layer during runtime without needing to set
  ZE_ENABLE_TRACING_LAYER=1.
- Tracing Layer Library is now always loaded by the Loader enabling
  for tracing to be enabled dynamically.

Signed-off-by: Spruit, Neil R <[email protected]>

Author: nrspruit

doc/loader_api.md

@@ -35,9 +35,18 @@ To solve this issue, `zelLoaderTranslateHandle` is used to retrieve the raw driv
 - __**handleOut__ Output location to store the translated handle
 
 
+### zelEnableTracingLayer
 
+When a user wants to enable the Tracing Layer for API Tracing, one usually set `ZE_ENABLE_TRACING_LAYER=1` before the call to zeInit(), however if one wanted to enable and disable tracing during runtime, the only way previously would be to enable tracing with the tracers disabled. This causes a performance hit due to the tracing layer intercepts.
 
+To resolve this, the tracing layer additionally can be enabled thru this new api `zelEnableTracingLayer`. This will enable the api tracing layer until the program exits or the user calls `zelDisableTracingLayer`.
 
+This call enables the tracing layer for all calls to the Loader after this call completes for all initialized drivers.
 
+### zelDisableTracingLayer
 
+Disables the tracing layer intercepts at runtime by restoring the previous call path thru the loader before tracing was enabled.
 
+This does not unload the tracing layer library such that one can call `zelEnableTracingLayer` and `zelDisableTracingLayer` as many times one needs to during the application.
+
+NOTE: The each call to `zelEnableTracingLayer` tracks a reference count of how many calls to enable have been seen. The Tracing Layer intercepts will not be removed until the reference count has reached 0 indicating that all users of the tracing layer have called `zelDisableTracingLayer`.

include/loader/ze_loader.h

@@ -70,6 +70,18 @@ zelLoaderTranslateHandle(
 ZE_DLLEXPORT ze_result_t ZE_APICALL
 zelSetDriverTeardown();
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Exported function for Enabling the Tracing Layer During Runtime.
+///
+ZE_DLLEXPORT ze_result_t ZE_APICALL
+zelEnableTracingLayer();
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Exported function for Disabling the Tracing Layer During Runtime.
+///
+ZE_DLLEXPORT ze_result_t ZE_APICALL
+zelDisableTracingLayer();
+
 #if defined(__cplusplus)
 } // extern "C"
 #endif

samples/zello_world/zello_world.cpp

@@ -39,7 +39,7 @@ void print_loader_versions(){
 //////////////////////////////////////////////////////////////////////////
 int main( int argc, char *argv[] )
 {
-
+    bool tracing_runtime_enabled = false;
     if( argparse( argc, argv, "-null", "--enable_null_driver" ) )
     {
         putenv_safe( const_cast<char *>( "ZE_ENABLE_NULL_DRIVER=1" ) );
@@ -57,6 +57,10 @@ int main( int argc, char *argv[] )
     {
         putenv_safe( const_cast<char *>( "ZE_ENABLE_TRACING_LAYER=1" ) );
     }
+    if( argparse( argc, argv, "-tracerun", "--enable_tracing_layer_runtime" ) )
+    {
+        tracing_runtime_enabled = true;
+    }
 
     ze_result_t status;
     const ze_device_type_t type = ZE_DEVICE_TYPE_GPU;
@@ -68,6 +72,15 @@ int main( int argc, char *argv[] )
 
         print_loader_versions();
 
+        if (tracing_runtime_enabled) {
+            std::cout << "Enabling Tracing Layer after init" << std::endl;
+            status = zelEnableTracingLayer();
+            if(status != ZE_RESULT_SUCCESS) {
+                std::cout << "zelEnableTracingLayer Failed with return code: " << to_string(status) << std::endl;
+                exit(1);
+            }
+        }
+
         uint32_t driverCount = 0;
         status = zeDriverGet(&driverCount, nullptr);
         if(status != ZE_RESULT_SUCCESS) {
@@ -154,5 +167,14 @@ int main( int argc, char *argv[] )
     zeEventDestroy(event);
     zeEventPoolDestroy(event_pool);
 
+    if (tracing_runtime_enabled) {
+        std::cout << "Disable Tracing Layer after init" << std::endl;
+        status = zelDisableTracingLayer();
+        if(status != ZE_RESULT_SUCCESS) {
+            std::cout << "zelDisableTracingLayer Failed with return code: " << to_string(status) << std::endl;
+            exit(1);
+        }
+    }
+
     return 0;
 }

scripts/templates/ldrddi.cpp.mako

@@ -361,7 +361,13 @@ ${tbl['export']['name']}(
             GET_FUNCTION_PTR(loader::context->tracingLayer, "${tbl['export']['name']}") );
         if(!getTable)
             return ${X}_RESULT_ERROR_UNINITIALIZED;
-        result = getTable( version, pDdiTable );
+        ${tbl['type']} dditable;
+        memcpy(&dditable, pDdiTable, sizeof(${tbl['type']}));
+        result = getTable( version, &dditable );
+        loader::context->tracing_dditable.${n}.${tbl['name']} = dditable;
+        if ( loader::context->tracingLayerEnabled ) {
+            result = getTable( version, pDdiTable );
+        }
     }
 
     %endif

scripts/templates/libapi.cpp.mako

@@ -69,7 +69,7 @@ ${th.make_func_name(n, tags, obj)}(
         return ${X}_RESULT_ERROR_UNINITIALIZED;
     }
 
-    auto ${th.make_pfn_name(n, tags, obj)} = ${x}_lib::context->${n}DdiTable.${th.get_table_name(n, tags, obj)}.${th.make_pfn_name(n, tags, obj)};
+    auto ${th.make_pfn_name(n, tags, obj)} = ${x}_lib::context->${n}DdiTable.load()->${th.get_table_name(n, tags, obj)}.${th.make_pfn_name(n, tags, obj)};
     if( nullptr == ${th.make_pfn_name(n, tags, obj)} ) {
         if(!ze_lib::context->isInitialized)
             return ${X}_RESULT_ERROR_UNINITIALIZED;
@@ -89,7 +89,7 @@ ${th.make_func_name(n, tags, obj)}(
             return ${X}_RESULT_ERROR_UNINITIALIZED;
         }
 
-        auto ${th.make_pfn_name(n, tags, obj)} = ${x}_lib::context->${n}DdiTable.${th.get_table_name(n, tags, obj)}.${th.make_pfn_name(n, tags, obj)};
+        auto ${th.make_pfn_name(n, tags, obj)} = ${x}_lib::context->${n}DdiTable.load()->${th.get_table_name(n, tags, obj)}.${th.make_pfn_name(n, tags, obj)};
         if( nullptr == ${th.make_pfn_name(n, tags, obj)} ) {
             if(!ze_lib::context->isInitialized)
                 return ${X}_RESULT_ERROR_UNINITIALIZED;
@@ -113,7 +113,13 @@ ${th.make_func_name(n, tags, obj)}(
         return ${X}_RESULT_ERROR_UNINITIALIZED;
     }
 
-    auto ${th.make_pfn_name(n, tags, obj)} = ${x}_lib::context->${n}DdiTable.${th.get_table_name(n, tags, obj)}.${th.make_pfn_name(n, tags, obj)};
+%if re.match("DriverGet", obj['name']):
+    if (${x}_lib::context->${n}DdiTable == nullptr) {
+        return ${X}_RESULT_ERROR_UNINITIALIZED;
+    }
+
+%endif
+    auto ${th.make_pfn_name(n, tags, obj)} = ${x}_lib::context->${n}DdiTable.load()->${th.get_table_name(n, tags, obj)}.${th.make_pfn_name(n, tags, obj)};
     if( nullptr == ${th.make_pfn_name(n, tags, obj)} ) {
         if(!ze_lib::context->isInitialized)
             return ${X}_RESULT_ERROR_UNINITIALIZED;

scripts/templates/libddi.cpp.mako

@@ -35,7 +35,7 @@ namespace ${x}_lib
         {
             auto getTable = reinterpret_cast<${tbl['pfn']}>(
                 GET_FUNCTION_PTR(loader, "${tbl['export']['name']}") );
-            result = getTable( ${X}_API_VERSION_CURRENT, &${n}DdiTable.${tbl['name']} );
+            result = getTable( ${X}_API_VERSION_CURRENT, &initial${n}DdiTable.${tbl['name']} );
         }
 
     %endfor
@@ -49,7 +49,7 @@ namespace ${x}_lib
     %for tbl in th.get_pfntables(specs, meta, n, tags):
         if( ${X}_RESULT_SUCCESS == result )
         {
-            result = ${tbl['export']['name']}( ${X}_API_VERSION_CURRENT, &${n}DdiTable.${tbl['name']} );
+            result = ${tbl['export']['name']}( ${X}_API_VERSION_CURRENT, &initial${n}DdiTable.${tbl['name']} );
         }
 
     %endfor

source/lib/ze_lib.cpp

@@ -67,6 +67,13 @@ namespace ze_lib
 
 #endif
 
+        if ( ZE_RESULT_SUCCESS == result )
+        {
+            ze_lib::context->zeDdiTable.exchange(&ze_lib::context->initialzeDdiTable);
+            ze_lib::context->zetDdiTable.exchange(&ze_lib::context->initialzetDdiTable);
+            ze_lib::context->zesDdiTable.exchange(&ze_lib::context->initialzesDdiTable);
+        }
+
         if( ZE_RESULT_SUCCESS == result )
         {
             result = zeInit();
@@ -87,6 +94,11 @@ namespace ze_lib
             result = zelTracingInit();
         }
 
+        if( ZE_RESULT_SUCCESS == result )
+        {
+            result = zelLoaderTracingLayerInit(this->pTracingZeDdiTable, this->pTracingZetDdiTable, this->pTracingZesDdiTable);
+        }
+
         if( ZE_RESULT_SUCCESS == result && !sysmanOnly)
         {
             //Check which drivers support the ze_driver_flag_t specified
@@ -137,7 +149,6 @@ zelLoaderTranslateHandle(
 
 ze_result_t ZE_APICALL
 zelSetDriverTeardown()
-
 {
     ze_result_t result = ZE_RESULT_SUCCESS;
     if (!ze_lib::destruction) {
@@ -146,7 +157,26 @@ zelSetDriverTeardown()
     return result;
 }
 
+ze_result_t ZE_APICALL
+zelEnableTracingLayer()
+{
+    if (ze_lib::context->tracingLayerEnableCounter.fetch_add(1) == 0) {
+        ze_lib::context->zeDdiTable.exchange(ze_lib::context->pTracingZeDdiTable);
+        ze_lib::context->zetDdiTable.exchange(ze_lib::context->pTracingZetDdiTable);
+        ze_lib::context->zesDdiTable.exchange(ze_lib::context->pTracingZesDdiTable);
+    }
+    return ZE_RESULT_SUCCESS;
+}
 
-
+ze_result_t ZE_APICALL
+zelDisableTracingLayer()
+{
+    if (ze_lib::context->tracingLayerEnableCounter.fetch_sub(1) <= 1) {
+        ze_lib::context->zeDdiTable.exchange(&ze_lib::context->initialzeDdiTable);
+        ze_lib::context->zetDdiTable.exchange(&ze_lib::context->initialzetDdiTable);
+        ze_lib::context->zesDdiTable.exchange(&ze_lib::context->initialzesDdiTable);
+    }
+    return ZE_RESULT_SUCCESS;
+}
 
 } //extern "c"

source/lib/ze_lib.h

@@ -19,6 +19,7 @@
 #include "ze_util.h"
 #include <vector>
 #include <mutex>
+#include <atomic>
 
 namespace ze_lib
 {
@@ -38,16 +39,23 @@ namespace ze_lib
         ze_result_t Init(ze_init_flags_t flags, bool sysmanOnly);
 
         ze_result_t zeInit();
-        ze_dditable_t   zeDdiTable = {};
+        std::atomic<ze_dditable_t *>  zeDdiTable = {nullptr};
 
         ze_result_t zetInit();
-        zet_dditable_t  zetDdiTable = {};
+        std::atomic<zet_dditable_t *> zetDdiTable = {nullptr};
 
         ze_result_t zesInit();
-        zes_dditable_t  zesDdiTable = {};
+        std::atomic<zes_dditable_t *> zesDdiTable = {nullptr};
 
         ze_result_t zelTracingInit();
         zel_tracing_dditable_t  zelTracingDdiTable = {};
+        std::atomic<ze_dditable_t *> pTracingZeDdiTable = {nullptr};
+        std::atomic<zet_dditable_t *> pTracingZetDdiTable = {nullptr};
+        std::atomic<zes_dditable_t *> pTracingZesDdiTable = {nullptr};
+        ze_dditable_t initialzeDdiTable;
+        zet_dditable_t initialzetDdiTable;
+        zes_dditable_t initialzesDdiTable;
+        std::atomic_uint32_t tracingLayerEnableCounter;
 
         HMODULE tracing_lib = nullptr;
         bool isInitialized = false;