Add C API for printing UR objects

Add an /include header for printing Unified Runtime objects with a C API.

scripts/core/INTRO.rst

@@ -148,9 +148,12 @@ This allows the Unified Runtime shared library to be updated with additional sym
 Printing API
 ------------
 ## --validate=off
-The header "${x}_print.hpp" contains the "${x}::print" namespace with the output stream operator (<<) overloads for Unified Runtime objects.
+The header "${x}_print.hpp" contains output stream operator (<<) overloads for Unified Runtime objects.
 There is also the "${x}::extras::printFunctionParams" function for printing function parameters. These parameters have to be provided in a \*params_t struct format suitable for
 a given function.
+
+The ${x}_print.h header provides the same functionality with a C interface. Each object has a print function named urPrint<object name without both prefix and suffix>,
+ie. for printing ur_result_t use urPrintResult.
 ## --validate=on
 
 Tracing

scripts/generate_code.py

@@ -70,6 +70,44 @@ def _mako_ddi_h(path, namespace, tags, version, revision, specs, meta):
  specs=specs,
  meta=meta)
 
+"""
+ generates c/c++ files from the mako template
+"""
+def _mako_print_h(path, namespace, tags, version, specs, meta):
+ template = "print.h.mako"
+ fin = os.path.join("templates", template)
+
+ filename = "%s_print.h"%(namespace)
+ fout = os.path.join(path, filename)
+
+ print("Generating %s..."%fout)
+ return util.makoWrite(
+ fin, fout,
+ ver=version,
+ namespace=namespace,
+ tags=tags,
+ specs=specs,
+ meta=meta)
+
+"""
+ generates c/c++ files from the mako template
+"""
+def _mako_print_cpp(path, namespace, tags, version, specs, meta):
+ template = "print.cpp.mako"
+ fin = os.path.join("templates", template)
+
+ filename = "%s_print.cpp"%(namespace)
+ fout = os.path.join(path, filename)
+
+ print("Generating %s..."%fout)
+ return util.makoWrite(
+ fin, fout,
+ ver=version,
+ namespace=namespace,
+ tags=tags,
+ specs=specs,
+ meta=meta)
+
 """
  generates c/c++ files from the specification documents
 """
@@ -90,6 +128,7 @@ def generate_api(incpath, srcpath, namespace, tags, version, revision, specs, me
  util.makePath(srcpath)
 
  loc = 0
+ loc += _mako_print_h(incpath, namespace, tags, version, specs, meta)
  loc += _generate_api_cpp(incpath, srcpath, namespace, tags, version, revision, specs, meta)
  print("Generated %s lines of code.\n"%loc)
 
@@ -330,6 +369,7 @@ def generate_loader(path, section, namespace, tags, version, specs, meta):
 
  loc = 0
  loc += _mako_loader_cpp(dstpath, namespace, tags, version, specs, meta)
+ loc += _mako_print_cpp(dstpath, namespace, tags, version, specs, meta)
  print("Generated %s lines of code.\n"%loc)
 
 """

scripts/templates/helper.py

@@ -937,6 +937,17 @@ def make_func_name(namespace, tags, obj):
  cname = ''
  return subt(namespace, tags, "%s%s"%(cname, obj['name']))
 
+"""
+Public:
+ returns the name of a function from a given name with prefix
+"""
+def make_func_name_with_prefix(prefix, name):
+ func_name = re.sub(r'^[^_]+_', '', name)
+ func_name = re.sub('_t$', '', func_name).capitalize()
+ func_name = re.sub(r'_([a-z])', lambda match: match.group(1).upper(), func_name)
+ func_name = f'{prefix}{func_name}'
+ return func_name
+
 """
 Public:
  returns the etor of a function

scripts/templates/print.cpp.mako

@@ -0,0 +1,96 @@
+<%!
+import re
+from templates import helper as th
+%><%
+ n=namespace
+ N=n.upper()
+
+ x=tags['$x']
+ X=x.upper()
+%>/*
+ *
+ * Copyright (C) 2023 Intel Corporation
+ *
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See LICENSE.TXT
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ *
+ * @file ${n}_print.cpp
+ *
+ */
+
+#include "${n}_print.h"
+#include "${n}_print.hpp"
+
+#include <algorithm>
+#include <sstream>
+#include <string.h>
+
+<%def name="ss_copy(item_name)">\
+ std::stringstream ss;
+ ss << ${item_name};
+ return str_copy(&ss, buffer, buff_size, out_size);
+</%def>
+
+${x}_result_t str_copy(std::stringstream *ss, char *buff, const size_t buff_size, size_t *out_size) {
+ size_t c_str_size = strlen(ss->str().c_str()) + 1;
+ if (out_size) {
+ *out_size = c_str_size;
+ }
+
+ if (buff) {
+ if (buff_size < c_str_size) {
+ return ${X}_RESULT_ERROR_INVALID_SIZE;
+ }
+
+#if defined(_WIN32)
+ strncpy_s(buff, buff_size, ss->str().c_str(), c_str_size);
+#else
+ strncpy(buff, ss->str().c_str(), std::min(buff_size, c_str_size));
+#endif
+ }
+ return ${X}_RESULT_SUCCESS;
+}
+
+%for spec in specs:
+%for obj in spec['objects']:
+## ENUM #######################################################################
+%if re.match(r"enum", obj['type']):
+ ${x}_result_t ${th.make_func_name_with_prefix(f'{x}Print', obj['name'])}(enum ${th.make_enum_name(n, tags, obj)} value, char *buffer, const size_t buff_size, size_t *out_size) {
+ ${ss_copy("value")}
+ }
+
+## STRUCT #####################################################################
+%elif re.match(r"struct", obj['type']):
+ ${x}_result_t ${th.make_func_name_with_prefix(f'{x}Print', obj['name'])}(const ${obj['type']} ${th.make_type_name(n, tags, obj)} params, char *buffer, const size_t buff_size, size_t *out_size) {
+ ${ss_copy("params")}
+ }
+
+%endif
+%endfor # obj in spec['objects']
+%endfor
+
+%for tbl in th.get_pfncbtables(specs, meta, n, tags):
+%for obj in tbl['functions']:
+<%
+ name = th.make_pfncb_param_type(n, tags, obj)
+%>\
+${x}_result_t ${th.make_func_name_with_prefix(f'{x}Print', name)}(const struct ${th.make_pfncb_param_type(n, tags, obj)} *params, char *buffer, const size_t buff_size, size_t *out_size) {
+ ${ss_copy("params")}
+}
+
+%endfor
+%endfor
+
+${x}_result_t ${x}PrintFunctionParams(enum ${x}_function_t function, const void *params, char *buffer, const size_t buff_size, size_t *out_size) {
+ if (!params) {
+ return ${X}_RESULT_ERROR_INVALID_NULL_POINTER;
+ }
+
+ std::stringstream ss;
+ ${x}_result_t result = ${x}::extras::printFunctionParams(ss, function, params);
+ if (result != ${X}_RESULT_SUCCESS) {
+ return result;
+ }
+ return str_copy(&ss, buffer, buff_size, out_size);
+}

scripts/templates/print.h.mako

@@ -0,0 +1,92 @@
+<%!
+import re
+from templates import helper as th
+%><%
+ n=namespace
+ N=n.upper()
+
+ x=tags['$x']
+ X=x.upper()
+%>/*
+ *
+ * Copyright (C) 2023 Intel Corporation
+ *
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See LICENSE.TXT
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ *
+ * @file ${n}_print.h
+ *
+ */
+#ifndef ${X}_PRINT_H
+#define ${X}_PRINT_H 1
+
+#include "${x}_api.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+## Declarations ###############################################################
+%for spec in specs:
+%for obj in spec['objects']:
+%if re.match(r"enum", obj['type']):
+ ///////////////////////////////////////////////////////////////////////////////
+ /// @brief Print ${th.make_enum_name(n, tags, obj)} enum
+ /// @returns
+ /// - ::${X}_RESULT_SUCCESS
+ /// - ::${X}_RESULT_ERROR_INVALID_NULL_POINTER
+ /// - `NULL == buffer`
+ /// - ::${X}_RESULT_ERROR_INVALID_SIZE
+ /// - `buff_size < out_size`
+ ${X}_APIEXPORT ${x}_result_t ${X}_APICALL ${th.make_func_name_with_prefix(f'{x}Print', obj['name'])}(enum ${th.make_enum_name(n, tags, obj)} value, char *buffer, const size_t buff_size, size_t *out_size);
+
+%elif re.match(r"struct", obj['type']):
+ ///////////////////////////////////////////////////////////////////////////////
+ /// @brief Print ${th.make_type_name(n, tags, obj)} struct
+ /// @returns
+ /// - ::${X}_RESULT_SUCCESS
+ /// - ::${X}_RESULT_ERROR_INVALID_NULL_POINTER
+ /// - `NULL == buffer`
+ /// - ::${X}_RESULT_ERROR_INVALID_SIZE
+ /// - `buff_size < out_size`
+ ${X}_APIEXPORT ${x}_result_t ${X}_APICALL ${th.make_func_name_with_prefix(f'{x}Print', obj['name'])}(const ${obj['type']} ${th.make_type_name(n, tags, obj)} params, char *buffer, const size_t buff_size, size_t *out_size);
+
+%endif
+%endfor # obj in spec['objects']
+%endfor
+
+%for tbl in th.get_pfncbtables(specs, meta, n, tags):
+%for obj in tbl['functions']:
+<%
+ name = th.make_pfncb_param_type(n, tags, obj)
+%>
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ${th.make_pfncb_param_type(n, tags, obj)} params struct
+/// @returns
+/// - ::${X}_RESULT_SUCCESS
+/// - ::${X}_RESULT_ERROR_INVALID_NULL_POINTER
+/// - `NULL == buffer`
+/// - ::${X}_RESULT_ERROR_INVALID_SIZE
+/// - `buff_size < out_size`
+${X}_APIEXPORT ${x}_result_t ${X}_APICALL ${th.make_func_name_with_prefix(f'{x}Print', name)}(const struct ${th.make_pfncb_param_type(n, tags, obj)} *params, char *buffer, const size_t buff_size, size_t *out_size);
+%endfor
+%endfor
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print function parameters
+/// @returns
+/// - ::${X}_RESULT_SUCCESS
+/// - ::${X}_RESULT_ERROR_INVALID_ENUMERATION
+/// - ::${X}_RESULT_ERROR_INVALID_NULL_POINTER
+/// - `NULL == params`
+/// - `NULL == buffer`
+/// - ::${X}_RESULT_ERROR_INVALID_SIZE
+/// - `buff_size < out_size`
+${X}_APIEXPORT ${x}_result_t ${X}_APICALL ${x}PrintFunctionParams(enum ${x}_function_t function, const void *params, char *buffer, const size_t buff_size, size_t *out_size);
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif /* ${X}_PRINT_H */

source/loader/CMakeLists.txt

@@ -89,6 +89,7 @@ target_sources(ur_loader
  ${CMAKE_CURRENT_SOURCE_DIR}/ur_lib.hpp
  ${CMAKE_CURRENT_SOURCE_DIR}/ur_lib.cpp
  ${CMAKE_CURRENT_SOURCE_DIR}/ur_codeloc.hpp
+ ${CMAKE_CURRENT_SOURCE_DIR}/ur_print.cpp
  ${CMAKE_CURRENT_SOURCE_DIR}/layers/validation/ur_valddi.cpp
  ${CMAKE_CURRENT_SOURCE_DIR}/layers/validation/ur_validation_layer.cpp
 )