Add call to urSetLoggerCallback to loader mako template, and add adapter implementations.

Modified logger constructor to also take a CallbackSink pointer.
Added new unit test to verify urSetLoggerCallbackLevel.
Updated description of urSetLoggerCallback to say the callback must be made thread safe by creator of callback.
Added a logger level enum to spec to replace logger::level.

Author: martygrant

include/ur_api.h

@@ -227,6 +227,7 @@ typedef enum ur_function_t {
     UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_SEMAPHORE_EXP = 227,      ///< Enumerator for ::urBindlessImagesImportExternalSemaphoreExp
     UR_FUNCTION_ENQUEUE_NATIVE_COMMAND_EXP = 228,                         ///< Enumerator for ::urEnqueueNativeCommandExp
     UR_FUNCTION_SET_LOGGER_CALLBACK = 230,                                ///< Enumerator for ::urSetLoggerCallback
+    UR_FUNCTION_SET_LOGGER_CALLBACK_LEVEL = 231,                          ///< Enumerator for ::urSetLoggerCallbackLevel
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -987,16 +988,32 @@ typedef enum ur_adapter_backend_t {
 
 } ur_adapter_backend_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Minimum level of messages to be processed by the logger.
+typedef enum ur_logger_level_t {
+    UR_LOGGER_LEVEL_DEBUG = 0, ///< Debugging messages used for development purposes.
+    UR_LOGGER_LEVEL_INFO = 1,  ///< General messages not related to debugging, warnings or errors.
+    UR_LOGGER_LEVEL_WARN = 2,  ///< Used to warn users about potential problems.
+    UR_LOGGER_LEVEL_ERR = 3,   ///< Used when an error has occurred.
+    UR_LOGGER_LEVEL_QUIET = 4, ///< Restrict logger processing any messages.
+    /// @cond
+    UR_LOGGER_LEVEL_FORCE_UINT32 = 0x7fffffff
+    /// @endcond
+
+} ur_logger_level_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Callback function to retrieve output from the logger.
 typedef void (*ur_logger_output_callback_t)(
-    const char *pLoggerMsg, ///< [in][out] pointer to data to be passed to callback
-    void *pUserData         ///< [in][out] pointer to data to be passed to callback
+    ur_logger_level_t level, ///< [out] Minimum level of messages to be processed by the logger.
+    const char *pLoggerMsg,  ///< [in][out] pointer to data to be passed to callback
+    void *pUserData          ///< [in][out] pointer to data to be passed to callback
 );
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Set a callback function for use by the logger to retrieve logging
-///        output.
+/// @brief Set a callback function for use by the logger to retrieve logging output.
+///        It is a requirement that the callback function is thread safe and the
+///        creator of the function will be responsible for this.
 ///
 /// @returns
 ///     - ::UR_RESULT_SUCCESS
@@ -1007,11 +1024,32 @@ typedef void (*ur_logger_output_callback_t)(
 ///         + `NULL == hAdapter`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pfnLoggerCallback`
+///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
+///         + `::UR_LOGGER_LEVEL_QUIET < level`
 UR_APIEXPORT ur_result_t UR_APICALL
 urSetLoggerCallback(
     ur_adapter_handle_t hAdapter,                  ///< [in] handle of the adapter
     ur_logger_output_callback_t pfnLoggerCallback, ///< [in] Function pointer to callback from the logger.
-    void *pUserData                                ///< [in][out][optional] pointer to data to be passed to callback
+    void *pUserData,                               ///< [in][out][optional] pointer to data to be passed to callback
+    ur_logger_level_t level                        ///< [in] logging level
+);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Set the minimum logging level for the logger Callback function.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hAdapter`
+///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
+///         + `::UR_LOGGER_LEVEL_QUIET < level`
+UR_APIEXPORT ur_result_t UR_APICALL
+urSetLoggerCallbackLevel(
+    ur_adapter_handle_t hAdapter, ///< [in] handle of the adapter
+    ur_logger_level_t level       ///< [in] logging level
 );
 
 #if !defined(__GNUC__)
@@ -10587,8 +10625,18 @@ typedef struct ur_set_logger_callback_params_t {
     ur_adapter_handle_t *phAdapter;
     ur_logger_output_callback_t *ppfnLoggerCallback;
     void **ppUserData;
+    ur_logger_level_t *plevel;
 } ur_set_logger_callback_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urSetLoggerCallbackLevel
+/// @details Each entry is a pointer to the parameter passed to the function;
+///     allowing the callback the ability to modify the parameter's value
+typedef struct ur_set_logger_callback_level_params_t {
+    ur_adapter_handle_t *phAdapter;
+    ur_logger_level_t *plevel;
+} ur_set_logger_callback_level_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urEnqueueKernelLaunch
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_ddi.h

@@ -1042,7 +1042,14 @@ typedef ur_result_t(UR_APICALL *ur_pfnAdapterGetInfo_t)(
 typedef ur_result_t(UR_APICALL *ur_pfnSetLoggerCallback_t)(
     ur_adapter_handle_t,
     ur_logger_output_callback_t,
-    void *);
+    void *,
+    ur_logger_level_t);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urSetLoggerCallbackLevel
+typedef ur_result_t(UR_APICALL *ur_pfnSetLoggerCallbackLevel_t)(
+    ur_adapter_handle_t,
+    ur_logger_level_t);
 
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Table of Global functions pointers
@@ -1053,6 +1060,7 @@ typedef struct ur_global_dditable_t {
     ur_pfnAdapterGetLastError_t pfnAdapterGetLastError;
     ur_pfnAdapterGetInfo_t pfnAdapterGetInfo;
     ur_pfnSetLoggerCallback_t pfnSetLoggerCallback;
+    ur_pfnSetLoggerCallbackLevel_t pfnSetLoggerCallbackLevel;
 } ur_global_dditable_t;
 
 ///////////////////////////////////////////////////////////////////////////////

include/ur_print.h

@@ -114,6 +114,14 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintAdapterInfo(enum ur_adapter_info_t va
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintAdapterBackend(enum ur_adapter_backend_t value, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_logger_level_t enum
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintLoggerLevel(enum ur_logger_level_t value, char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_platform_info_t enum
 /// @returns
@@ -1810,6 +1818,14 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintAdapterGetInfoParams(const struct ur_
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintSetLoggerCallbackParams(const struct ur_set_logger_callback_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_set_logger_callback_level_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintSetLoggerCallbackLevelParams(const struct ur_set_logger_callback_level_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_enqueue_kernel_launch_params_t struct
 /// @returns

include/ur_print.hpp

@@ -232,6 +232,7 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_loader_config_info_t v
 inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_code_location_t params);
 inline std::ostream &operator<<(std::ostream &os, enum ur_adapter_info_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_adapter_backend_t value);
+inline std::ostream &operator<<(std::ostream &os, enum ur_logger_level_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_platform_info_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_api_version_t value);
 inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_platform_native_properties_t params);
@@ -945,6 +946,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
     case UR_FUNCTION_SET_LOGGER_CALLBACK:
         os << "UR_FUNCTION_SET_LOGGER_CALLBACK";
         break;
+    case UR_FUNCTION_SET_LOGGER_CALLBACK_LEVEL:
+        os << "UR_FUNCTION_SET_LOGGER_CALLBACK_LEVEL";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -1961,6 +1965,33 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_adapter_backend_t valu
     return os;
 }
 ///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_logger_level_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, enum ur_logger_level_t value) {
+    switch (value) {
+    case UR_LOGGER_LEVEL_DEBUG:
+        os << "UR_LOGGER_LEVEL_DEBUG";
+        break;
+    case UR_LOGGER_LEVEL_INFO:
+        os << "UR_LOGGER_LEVEL_INFO";
+        break;
+    case UR_LOGGER_LEVEL_WARN:
+        os << "UR_LOGGER_LEVEL_WARN";
+        break;
+    case UR_LOGGER_LEVEL_ERR:
+        os << "UR_LOGGER_LEVEL_ERR";
+        break;
+    case UR_LOGGER_LEVEL_QUIET:
+        os << "UR_LOGGER_LEVEL_QUIET";
+        break;
+    default:
+        os << "unknown enumerator";
+        break;
+    }
+    return os;
+}
+///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_platform_info_t type
 /// @returns
 ///     std::ostream &
@@ -12770,6 +12801,30 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
     ur::details::printPtr(os,
                           *(params->ppUserData));
 
+    os << ", ";
+    os << ".level = ";
+
+    os << *(params->plevel);
+
+    return os;
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_set_logger_callback_level_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_set_logger_callback_level_params_t *params) {
+
+    os << ".hAdapter = ";
+
+    ur::details::printPtr(os,
+                          *(params->phAdapter));
+
+    os << ", ";
+    os << ".level = ";
+
+    os << *(params->plevel);
+
     return os;
 }
 
@@ -17608,6 +17663,9 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os, ur_function_
     case UR_FUNCTION_SET_LOGGER_CALLBACK: {
         os << (const struct ur_set_logger_callback_params_t *)params;
     } break;
+    case UR_FUNCTION_SET_LOGGER_CALLBACK_LEVEL: {
+        os << (const struct ur_set_logger_callback_level_params_t *)params;
+    } break;
     case UR_FUNCTION_ENQUEUE_KERNEL_LAUNCH: {
         os << (const struct ur_enqueue_kernel_launch_params_t *)params;
     } break;

scripts/core/INTRO.rst

@@ -204,10 +204,10 @@ By default, there is a guarantee that *error* messages are flushed immediately.
 
 Loggers redirect messages to *stdout*, *stderr*, a file or a user configurable callback function (default: *stderr*).
 
-All of these logging options can be set with **UR_LOG_LOADER** and **UR_LOG_NULL** environment variables described in the **Environment Variables** section below.
+All of these logging options (except the callback) can be set with **UR_LOG_LOADER** and **UR_LOG_NULL** environment variables described in the **Environment Variables** section below.
 Both of these environment variables have the same syntax for setting logger options:
 
-  "[level:debug|info|warning|error];[flush:<debug|info|warning|error>];[output:stdout|stderr|file,<path>|callback]"
+  "[level:debug|info|warning|error];[flush:<debug|info|warning|error>];[output:stdout|stderr|file,<path>]"
 
   * level - a log level, meaning that only messages from this level and above are printed,
             possible values, from the lowest level to the highest one: *debug*, *info*, *warning*, *error*,
@@ -232,6 +232,10 @@ An example of an environment variable for setting up the null adapter library wi
 
   UR_LOG_NULL="level:warning;output:stdout"
 
+Logging callback
+^^^^^^^^^^^^^^^^^^^^^
+An API is available to configure the logging callback function :ref:`urSetLoggerCallback`. Additionally, the logging level can be set using :ref:`urSetLoggerCallbackLevel`.
+
 Adapter Discovery
 ---------------------
 UR is capable of discovering adapter libraries in the following ways in the listed order:

scripts/core/adapter.yml

@@ -201,11 +201,36 @@ etors:
       value: "5"
       desc: "The backend is Native CPU"
 --- #--------------------------------------------------------------------------
+type: enum
+desc: "Minimum level of messages to be processed by the logger."
+class: $x
+name: $x_logger_level_t
+etors:
+    - name: DEBUG
+      value: "0"
+      desc: "Debugging messages used for development purposes."
+    - name: INFO
+      value: "1"
+      desc: "General messages not related to debugging, warnings or errors."
+    - name: WARN
+      value: "2"
+      desc: "Used to warn users about potential problems."
+    - name: ERR
+      value: "3"
+      desc: "Used when an error has occurred."
+    - name: QUIET
+      value: "4"
+      desc: "Restrict logger processing any messages."
+--- #--------------------------------------------------------------------------
 type: fptr_typedef
 desc: "Callback function to retrieve output from the logger."
 name: $x_logger_output_callback_t
 return: "void"
 params:
+    - type: $x_logger_level_t
+      name: level
+      desc: "[out] Minimum level of messages to be processed by the logger."
+      init: DEBUG
     - type: const char*
       name: pLoggerMsg
       desc: "[in][out] pointer to data to be passed to callback"
@@ -214,7 +239,10 @@ params:
       desc: "[in][out] pointer to data to be passed to callback"
 --- #--------------------------------------------------------------------------
 type: function
-desc: "Set a callback function for use by the logger to retrieve logging output."
+desc: |
+      Set a callback function for use by the logger to retrieve logging output.
+      It is a requirement that the callback function is thread safe and the
+      creator of the function will be responsible for this.
 class: $x
 name: SetLoggerCallback
 decl: static
@@ -228,3 +256,20 @@ params:
     - type: void*
       name: pUserData
       desc: "[in][out][optional] pointer to data to be passed to callback"
+    - type: $x_logger_level_t
+      name: level
+      desc: "[in] logging level"
+      init: 0
+--- #--------------------------------------------------------------------------
+type: function
+desc: "Set the minimum logging level for the logger Callback function."
+class: $x
+name: SetLoggerCallbackLevel
+decl: static
+params:
+    - type: $x_adapter_handle_t
+      name: hAdapter
+      desc: "[in] handle of the adapter"
+    - type: $x_logger_level_t
+      name: level
+      desc: "[in] logging level"

scripts/core/registry.yml

@@ -595,6 +595,9 @@ etors:
 - name: SET_LOGGER_CALLBACK
   desc: Enumerator for $xSetLoggerCallback
   value: '230'
+- name: SET_LOGGER_CALLBACK_LEVEL
+  desc: Enumerator for $xSetLoggerCallbackLevel
+  value: '231'
 ---
 type: enum
 desc: Defines structure types

scripts/templates/ldrddi.cpp.mako

@@ -51,12 +51,6 @@ namespace ur_loader
         add_local = False
     %>
 
-        %if re.match(r"\w+SetLoggerCallback$", th.make_func_name(n, tags, obj)):
- 
-        ur_loader::urSetLoggerCallback(${obj['params'][0]['name']}, ${obj['params'][1]['name']}, ${obj['params'][2]['name']});
-
-        %endif
-
         %if re.match(r"\w+AdapterGet$", th.make_func_name(n, tags, obj)):
 
         size_t adapterIndex = 0;