Skip to content

Commit c7b12bd

Browse files
PatKaminPatKamin
committed
Add html docs for Printing C API
- add a helper script for generating Printing API HTML documentation and source files, - remove wrong comment on returning an error when the 'buffer' parameter is NULL, - remove redundant check for the 'params' parameter.
1 parent 19751cd commit c7b12bd

File tree

7 files changed

+515
-864
lines changed

7 files changed

+515
-864
lines changed

‎include/ur_print.h‎

Lines changed: 185 additions & 786 deletions
Large diffs are not rendered by default.

‎scripts/generate_docs.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
"""
2-
Copyright (C) 2022 Intel Corporation
2+
Copyright (C) 2022-2024 Intel Corporation
33
44
Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
55
See LICENSE.TXT
@@ -209,6 +209,7 @@ def generate_rst(docpath, section, namespace, tags, ver, rev, specs, meta):
209209
fout = os.path.join(dstpath, "api.rst")
210210
groupname = os.path.basename(dstpath).capitalize()
211211
util.makoWrite(fin, fout,
212+
namespace=namespace,
212213
groupname=groupname,
213214
ver=ver,
214215
rev=rev,

‎scripts/templates/api_listing.mako‎

Lines changed: 64 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<%!
22
import re
33
from templates import helper as th
4-
%><%
4+
from templates import print_helper as tph
55
%>
66

77
==============================
@@ -264,3 +264,66 @@ ${th.make_type_name(n, tags, obj)}
264264
%endfor # obj in objects
265265
266266
%endfor # s in specs
267+
268+
#################################################################
269+
## Print API not part of the spec, needs to be generated separately
270+
#################################################################
271+
<%
272+
x = tags['$x']
273+
api_types_funcs = tph.get_api_types_funcs(specs, meta, namespace, tags)
274+
%>\
275+
## Generate Print API links table
276+
Print
277+
============================================================
278+
The Print API functions are helpful for printing Unified Runtime API objects'
279+
values as human-readable strings using C interface. Those functions are complimentary
280+
to the set of operators in the Print API C++ header (ur_print.hpp).
281+
282+
Each function is named in the same style based on the Unified Runtime object name
283+
to be printed. See examples:
284+
285+
To print the :any:`${x}_function_t` object's value, call:
286+
:ref:`${x}PrintFunction`
287+
288+
To print the :any:`${x}_kernel_arg_local_properties_t` object's value, call:
289+
:ref:`${x}PrintKernelArgLocalProperties`
290+
291+
There is also one 'extras' function in this API, which can be used for printing
292+
all values of given function's parameters - :any:`${x}PrintFunctionParams`.
293+
294+
See :ref:`core/api:Print Functions` for the description of common parameters of Print API functions.
295+
296+
* Functions
297+
%for func in api_types_funcs:
298+
* :ref:`${func.c_name.replace("_", "-")}`
299+
%endfor
300+
301+
## 'Extras' functions
302+
* :ref:`${x}PrintFunctionParams`
303+
304+
<%def name="generate_api_doc(func_name)">\
305+
.. _${func_name.replace("_", "-")}:
306+
307+
${func_name}
308+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
309+
310+
.. doxygenfunction:: ${func_name}
311+
:project: UnifiedRuntime
312+
</%def>
313+
314+
## Generate Print API documentation
315+
Print Functions
316+
------------------------------------------------------------------------------
317+
All functions output strings to print to the :any:`buffer` of a given
318+
size :any:`buff_size`. The outputted string's size is retrieved
319+
with the :any:`out_size` parameter.
320+
It is required for :any:`buff_size` to be less than :any:`out_size` in order
321+
to write the output string to the :any:`buffer`. Otherwise, :any:`buffer`
322+
will not be modified.
323+
324+
%for func in api_types_funcs:
325+
${generate_api_doc(func.c_name)}
326+
%endfor
327+
328+
## 'Extras' functions
329+
${generate_api_doc(f'{x}PrintFunctionParams')}

‎scripts/templates/print.cpp.mako‎

Lines changed: 7 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<%!
22
import re
3-
from templates import helper as th
3+
from templates import print_helper as tph
44
%><%
55
n=namespace
66
N=n.upper()
@@ -9,7 +9,7 @@ from templates import helper as th
99
X=x.upper()
1010
%>/*
1111
*
12-
* Copyright (C) 2023 Intel Corporation
12+
* Copyright (C) 2023-2024 Intel Corporation
1313
*
1414
* Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
1515
* See LICENSE.TXT
@@ -52,41 +52,17 @@ ${x}_result_t str_copy(std::stringstream *ss, char *buff, const size_t buff_size
5252
return ${X}_RESULT_SUCCESS;
5353
}
5454

55-
%for spec in specs:
56-
%for obj in spec['objects']:
57-
## ENUM #######################################################################
58-
%if re.match(r"enum", obj['type']):
59-
${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) {
60-
${ss_copy("value")}
61-
}
62-
63-
## STRUCT #####################################################################
64-
%elif re.match(r"struct", obj['type']):
65-
${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) {
66-
${ss_copy("params")}
67-
}
68-
69-
%endif
70-
%endfor # obj in spec['objects']
71-
%endfor
72-
73-
%for tbl in th.get_pfncbtables(specs, meta, n, tags):
74-
%for obj in tbl['functions']:
7555
<%
76-
name = th.make_pfncb_param_type(n, tags, obj)
77-
%>\
78-
${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) {
79-
${ss_copy("params")}
56+
api_types_funcs = tph.get_api_types_funcs(specs, meta, n, tags)
57+
%>
58+
%for func in api_types_funcs:
59+
${x}_result_t ${func.c_name}(${func.c_args}) {
60+
${ss_copy(func.print_arg.name)}
8061
}
8162

82-
%endfor
8363
%endfor
8464

8565
${x}_result_t ${x}PrintFunctionParams(enum ${x}_function_t function, const void *params, char *buffer, const size_t buff_size, size_t *out_size) {
86-
if (!params) {
87-
return ${X}_RESULT_ERROR_INVALID_NULL_POINTER;
88-
}
89-
9066
std::stringstream ss;
9167
${x}_result_t result = ${x}::extras::printFunctionParams(ss, function, params);
9268
if (result != ${X}_RESULT_SUCCESS) {

‎scripts/templates/print.h.mako‎

Lines changed: 8 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<%!
22
import re
3-
from templates import helper as th
3+
from templates import print_helper as tph
44
%><%
55
n=namespace
66
N=n.upper()
@@ -9,7 +9,7 @@ from templates import helper as th
99
X=x.upper()
1010
%>/*
1111
*
12-
* Copyright (C) 2023 Intel Corporation
12+
* Copyright (C) 2023-2024 Intel Corporation
1313
*
1414
* Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
1515
* See LICENSE.TXT
@@ -27,50 +27,19 @@ from templates import helper as th
2727
extern "C" {
2828
#endif
2929

30-
## Declarations ###############################################################
31-
%for spec in specs:
32-
%for obj in spec['objects']:
33-
%if re.match(r"enum", obj['type']):
34-
///////////////////////////////////////////////////////////////////////////////
35-
/// @brief Print ${th.make_enum_name(n, tags, obj)} enum
36-
/// @returns
37-
/// - ::${X}_RESULT_SUCCESS
38-
/// - ::${X}_RESULT_ERROR_INVALID_NULL_POINTER
39-
/// - `NULL == buffer`
40-
/// - ::${X}_RESULT_ERROR_INVALID_SIZE
41-
/// - `buff_size < out_size`
42-
${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);
43-
44-
%elif re.match(r"struct", obj['type']):
45-
///////////////////////////////////////////////////////////////////////////////
46-
/// @brief Print ${th.make_type_name(n, tags, obj)} struct
47-
/// @returns
48-
/// - ::${X}_RESULT_SUCCESS
49-
/// - ::${X}_RESULT_ERROR_INVALID_NULL_POINTER
50-
/// - `NULL == buffer`
51-
/// - ::${X}_RESULT_ERROR_INVALID_SIZE
52-
/// - `buff_size < out_size`
53-
${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);
54-
55-
%endif
56-
%endfor # obj in spec['objects']
57-
%endfor
58-
59-
%for tbl in th.get_pfncbtables(specs, meta, n, tags):
60-
%for obj in tbl['functions']:
6130
<%
62-
name = th.make_pfncb_param_type(n, tags, obj)
31+
api_types_funcs = tph.get_api_types_funcs(specs, meta, n, tags)
6332
%>
33+
## Declarations ###############################################################
34+
%for func in api_types_funcs:
6435
///////////////////////////////////////////////////////////////////////////////
65-
/// @brief Print ${th.make_pfncb_param_type(n, tags, obj)} params struct
36+
/// @brief Print ${func.print_arg.type_name} ${func.print_arg.base_type}
6637
/// @returns
6738
/// - ::${X}_RESULT_SUCCESS
68-
/// - ::${X}_RESULT_ERROR_INVALID_NULL_POINTER
69-
/// - `NULL == buffer`
7039
/// - ::${X}_RESULT_ERROR_INVALID_SIZE
7140
/// - `buff_size < out_size`
72-
${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);
73-
%endfor
41+
${X}_APIEXPORT ${x}_result_t ${X}_APICALL ${func.c_name}(${func.c_args});
42+
7443
%endfor
7544

7645
///////////////////////////////////////////////////////////////////////////////
@@ -80,7 +49,6 @@ ${X}_APIEXPORT ${x}_result_t ${X}_APICALL ${th.make_func_name_with_prefix(f'{x}P
8049
/// - ::${X}_RESULT_ERROR_INVALID_ENUMERATION
8150
/// - ::${X}_RESULT_ERROR_INVALID_NULL_POINTER
8251
/// - `NULL == params`
83-
/// - `NULL == buffer`
8452
/// - ::${X}_RESULT_ERROR_INVALID_SIZE
8553
/// - `buff_size < out_size`
8654
${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);

0 commit comments

Comments
 (0)