feature: Improve API Call Tracing and add ults

- Updated API Call Tracing to dereference [out] parameters when the api
  call succeeds for tracking output structures.
- Updated spdlog trace to output the thread id in the log string and
  have the log string to be configurable.
- Add ULTs for the validation layer api tracing to ensure stability.

Signed-off-by: Neil R. Spruit <neil.r.spruit@intel.com>

Author: nrspruit

CHANGELOG.md

@@ -1,4 +1,6 @@
 # Level zero loader changelog
+## v1.28.1
+* feature: Improve API Call Tracing and add ults
 ## v1.28.0
 * feature: Update to support L0 Spec v1.15.31
 * Loader Driver Interaction conformance tests for Sysman Exp and Ext APIs (#418)

CMakeLists.txt

@@ -13,7 +13,7 @@ if(MSVC AND (MSVC_VERSION LESS 1900))
 endif()
 
 # This project follows semantic versioning (https://semver.org/)
-project(level-zero VERSION 1.28.0)
+project(level-zero VERSION 1.28.1)
 include(GNUInstallDirs)
 
 find_package(Git)

PRODUCT_GUID.txt

@@ -1,2 +1,2 @@
-1.28.0
-152a1567-448a-42b3-9cdd-83c1bdc21421
+1.28.1
+3622767c-2b40-4af8-961d-06eda1231409

README.md

@@ -58,17 +58,26 @@ The Level Zero Loader uses spdlog logging and can be controlled via environment
 
 `ZEL_ENABLE_LOADER_LOGGING=1`
 
-[DEPRECATED] `ZEL_LOADER_LOG_FILE=/path/to/logfile`
-
 `ZEL_LOADER_LOG_DIR='/directory/path'`
 
 `ZEL_LOADER_LOGGING_LEVEL=debug`
 
+Default Log Pattern (Does not need to be set, please see below):
+`ZEL_LOADER_LOG_PATTERN='[%Y-%m-%d %H:%M:%S.%e] [thread-id: %t] [%^%l%$] %v'`
+
 Valid logging levels are trace, debug, info, warn, error, critical, off.
 Logging is disabled by default but when enabled the default level is 'warn'.
 The default log file is 'ze_loader.log' in '.oneapi_logs' in the current
 user's home directory.
 
+The default log pattern includes timestamps, thread IDs, log levels, and messages.
+You can customize the pattern using `ZEL_LOADER_LOG_PATTERN`. Common pattern flags:
+- `%t` - thread id
+- `%Y-%m-%d %H:%M:%S.%e` - timestamp with milliseconds
+- `%l` - log level
+- `%v` - the actual log message
+See spdlog documentation for more pattern options.
+
 This feature is in early development and is preview only.
 
 # Logging API calls

scripts/templates/validation/valddi.cpp.mako

@@ -71,11 +71,32 @@ namespace validation_layer
         %else:
         std::ostringstream oss;
         oss << status << " (" << loader::to_string(result) << ") in ${func_name}(";
-        %for i, param in enumerate([p for p in th.make_param_lines(n, tags, obj, format=['name'])]):
+        <%
+        params_list = obj.get('params', [])
+        %>
+        %for i, param_name in enumerate([p for p in th.make_param_lines(n, tags, obj, format=['name'])]):
+        <%
+        # Get parameter metadata
+        param_obj = params_list[i] if i < len(params_list) else None
+        param_type = param_obj.get('type', '') if param_obj else ''
+        param_desc = param_obj.get('desc', '') if param_obj else ''
+        is_output_param = '[out]' in param_desc
+        is_pointer = '*' in param_type and param_type.strip().endswith('*')
+        %>
         %if i > 0:
         oss << ", ";
         %endif
-        oss << "${param}=" << loader::to_string(${param});
+        oss << "${param_name}=";
+        %if is_output_param and is_pointer:
+        // Dereference output parameter if not null and result is success
+        if (result == ${X}_RESULT_SUCCESS && ${param_name} != nullptr) {
+            oss << loader::to_string(*${param_name});
+        } else {
+            oss << loader::to_string(${param_name});
+        }
+        %else:
+        oss << loader::to_string(${param_name});
+        %endif
         %endfor
         oss << ")";
         context.logger->log_trace(oss.str());
@@ -102,7 +123,14 @@ namespace validation_layer
             << "hContext=" << static_cast<const void*>(hContext) << ", "
             << "hDevice=" << static_cast<const void*>(hDevice) << ", "
             << "desc=" << desc << ", "
-            << "phEvent=" << static_cast<const void*>(phEvent) << ")";
+            << "phEvent=";
+        // Dereference output parameter if not null and result is success
+        if (result == ${X}_RESULT_SUCCESS && phEvent != nullptr) {
+            oss << loader::to_string(*phEvent);
+        } else {
+            oss << static_cast<const void*>(phEvent);
+        }
+        oss << ")";
         context.logger->log_trace(oss.str());
         return result;
     }