Hi all,
After merging the printk tree, today's linux-next build (htmldocs)
produced this warning:
kernel/printk/printk.c:1: warning: 'printk' not found
Introduced by commit
337015573718 ("printk: Userspace format indexing support")
I presume that "printk" is referred to elsewhere in the documentation
as being in this file.
--
Cheers,
Stephen Rothwell
+Cc: Jonathan Corbet <[email protected]>, [email protected]
Stephen Rothwell writes:
>After merging the printk tree, today's linux-next build (htmldocs)
>produced this warning:
>
>kernel/printk/printk.c:1: warning: 'printk' not found
>
>Introduced by commit
>
> 337015573718 ("printk: Userspace format indexing support")
>
>I presume that "printk" is referred to elsewhere in the documentation
>as being in this file.
Hmm, this is an interesting one, because I think we still generally just want
to refer to the API as being `printk()`. Changing it all over the place seems
wrong. As you'd imagine, there are quite a few references to this name, so it
requires a lot of noise all over the docs and inline comments.
Jonathan and other docs folks, how can one tell Sphinx that when it sees
printk() it's referring to a function-like macro, or otherwise squelch this
reasonably? :-)
Chris Down writes:
>+Cc: Jonathan Corbet <[email protected]>, [email protected]
Well, let's actually Cc them this time...
>Stephen Rothwell writes:
>>After merging the printk tree, today's linux-next build (htmldocs)
>>produced this warning:
>>
>>kernel/printk/printk.c:1: warning: 'printk' not found
>>
>>Introduced by commit
>>
>> 337015573718 ("printk: Userspace format indexing support")
>>
>>I presume that "printk" is referred to elsewhere in the documentation
>>as being in this file.
>
>Hmm, this is an interesting one, because I think we still generally
>just want to refer to the API as being `printk()`. Changing it all
>over the place seems wrong. As you'd imagine, there are quite a few
>references to this name, so it requires a lot of noise all over the
>docs and inline comments.
>
>Jonathan and other docs folks, how can one tell Sphinx that when it
>sees printk() it's referring to a function-like macro, or otherwise
>squelch this reasonably? :-)
The commit 337015573718b161 ("printk: Userspace format indexing support")
caused the following warning when building htmldocs:
kernel/printk/printk.c:1: warning: 'printk' not found
The problem is that printk() became a macro that is defined
in include/linux/printk.h instead of kernel/printk.c. The original
function was renamed to _printk().
Fixes: 337015573718b161 ("printk: Userspace format indexing support")
Reported-by: Stephen Rothwell <[email protected]>
Signed-off-by: Petr Mladek <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
---
This should do the trick. I do not longer see the warning.
Documentation/core-api/printk-basics.rst | 6 +++---
include/linux/printk.h | 12 ++++++++++++
kernel/printk/printk.c | 3 ++-
3 files changed, 17 insertions(+), 4 deletions(-)
diff --git a/Documentation/core-api/printk-basics.rst b/Documentation/core-api/printk-basics.rst
index 965e4281eddd..3160a73c27b1 100644
--- a/Documentation/core-api/printk-basics.rst
+++ b/Documentation/core-api/printk-basics.rst
@@ -108,8 +108,8 @@ Function reference
==================
.. kernel-doc:: kernel/printk/printk.c
- :functions: printk
+ :functions: _printk
.. kernel-doc:: include/linux/printk.h
- :functions: pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info
- pr_fmt pr_debug pr_devel pr_cont
+ :functions: printk pr_emerg pr_alert pr_crit pr_err pr_warn
+ pr_notice pr_info pr_fmt pr_debug pr_devel pr_cont
diff --git a/include/linux/printk.h b/include/linux/printk.h
index 2651b82ed352..e0e3411db67b 100644
--- a/include/linux/printk.h
+++ b/include/linux/printk.h
@@ -431,6 +431,18 @@ struct pi_entry {
})
+/**
+ * printk - Print a message
+ * @fmt: format string
+ * @...: arguments for the format string
+ *
+ * This macro generates metadata for printk indexing and prints the message
+ * using _printk(). It uses pr_fmt() to generate the format string.
+ *
+ * The default log level is used when a particular one is not part of
+ * the message prefix. pr_<level>() macros are preferred because each
+ * caller should know the exact purpose of the message.
+ */
#define printk(fmt, ...) printk_index_wrap(_printk, fmt, ##__VA_ARGS__)
#define printk_deferred(fmt, ...) \
printk_index_wrap(_printk_deferred, fmt, ##__VA_ARGS__)
diff --git a/kernel/printk/printk.c b/kernel/printk/printk.c
index 765f7af6ce56..2e5559175214 100644
--- a/kernel/printk/printk.c
+++ b/kernel/printk/printk.c
@@ -2187,7 +2187,8 @@ EXPORT_SYMBOL_GPL(vprintk_default);
* _printk - print a kernel message
* @fmt: format string
*
- * This is _printk(). It can be called from any context. We want it to work.
+ * This is printk() implementation. It can be called from any context.
+ * We want it to work.
*
* If printk indexing is enabled, _printk() is called from printk_index_wrap.
* Otherwise, printk is simply #defined to _printk.
--
2.26.2
On Fri 2021-07-23 13:09:43, Petr Mladek wrote:
> The commit 337015573718b161 ("printk: Userspace format indexing support")
> caused the following warning when building htmldocs:
>
> kernel/printk/printk.c:1: warning: 'printk' not found
>
> The problem is that printk() became a macro that is defined
> in include/linux/printk.h instead of kernel/printk.c. The original
> function was renamed to _printk().
>
> Fixes: 337015573718b161 ("printk: Userspace format indexing support")
> Reported-by: Stephen Rothwell <[email protected]>
> Signed-off-by: Petr Mladek <[email protected]>
> Link: https://lore.kernel.org/r/[email protected]
> ---
> This should do the trick. I do not longer see the warning.
And I have just pushed it together with the other fixes into
printk/linux.git, branch for-5.15-printk-index.
Best Regards,
Petr
Chris Down <[email protected]> writes:
> Chris Down writes:
>>+Cc: Jonathan Corbet <[email protected]>, [email protected]
>
> Well, let's actually Cc them this time...
>
>>Stephen Rothwell writes:
>>>After merging the printk tree, today's linux-next build (htmldocs)
>>>produced this warning:
>>>
>>>kernel/printk/printk.c:1: warning: 'printk' not found
>>>
>>>Introduced by commit
>>>
>>> 337015573718 ("printk: Userspace format indexing support")
>>>
>>>I presume that "printk" is referred to elsewhere in the documentation
>>>as being in this file.
>>
>>Hmm, this is an interesting one, because I think we still generally
>>just want to refer to the API as being `printk()`. Changing it all
>>over the place seems wrong. As you'd imagine, there are quite a few
>>references to this name, so it requires a lot of noise all over the
>>docs and inline comments.
>>
>>Jonathan and other docs folks, how can one tell Sphinx that when it
>>sees printk() it's referring to a function-like macro, or otherwise
>>squelch this reasonably? :-)
The problem is that you moved printk(), but left the associated
kerneldoc comment tied to _printk(), which isn't what you really want to
document. The fix should look something like the attached.
Thanks,
jon
--------snip here----------------------
printk: Move the printk() kerneldoc comment to its new home
Commit 337015573718 ("printk: Userspace format indexing support") turned
printk() into a macro, but left the kerneldoc comment for it with the (now)
_printk() function, resulting in this docs-build warning:
kernel/printk/printk.c:1: warning: 'printk' not found
Move the kerneldoc comment back next to the (now) macro it's meant to
describe and have the docs build find it there.
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/core-api/printk-basics.rst | 5 +----
include/linux/printk.h | 24 ++++++++++++++++++++++++
kernel/printk/printk.c | 24 ------------------------
3 files changed, 25 insertions(+), 28 deletions(-)
diff --git a/Documentation/core-api/printk-basics.rst b/Documentation/core-api/printk-basics.rst
index 965e4281eddd..2dde24ca7d9f 100644
--- a/Documentation/core-api/printk-basics.rst
+++ b/Documentation/core-api/printk-basics.rst
@@ -107,9 +107,6 @@ also ``CONFIG_DYNAMIC_DEBUG`` in the case of pr_debug()) is defined.
Function reference
==================
-.. kernel-doc:: kernel/printk/printk.c
- :functions: printk
-
.. kernel-doc:: include/linux/printk.h
- :functions: pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info
+ :functions: printk pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info
pr_fmt pr_debug pr_devel pr_cont
diff --git a/include/linux/printk.h b/include/linux/printk.h
index 2651b82ed352..c1e176403967 100644
--- a/include/linux/printk.h
+++ b/include/linux/printk.h
@@ -431,6 +431,30 @@ struct pi_entry {
})
+/**
+ * printk - print a kernel message
+ * @fmt: format string
+ *
+ * This is printk(). It can be called from any context. We want it to work.
+ *
+ * If printk indexing is enabled, _printk() is called from printk_index_wrap.
+ * Otherwise, printk is simply #defined to _printk.
+ *
+ * We try to grab the console_lock. If we succeed, it's easy - we log the
+ * output and call the console drivers. If we fail to get the semaphore, we
+ * place the output into the log buffer and return. The current holder of
+ * the console_sem will notice the new output in console_unlock(); and will
+ * send it to the consoles before releasing the lock.
+ *
+ * One effect of this deferred printing is that code which calls printk() and
+ * then changes console_loglevel may break. This is because console_loglevel
+ * is inspected when the actual printing occurs.
+ *
+ * See also:
+ * printf(3)
+ *
+ * See the vsnprintf() documentation for format string extensions over C99.
+ */
#define printk(fmt, ...) printk_index_wrap(_printk, fmt, ##__VA_ARGS__)
#define printk_deferred(fmt, ...) \
printk_index_wrap(_printk_deferred, fmt, ##__VA_ARGS__)
diff --git a/kernel/printk/printk.c b/kernel/printk/printk.c
index 9b3bd6e017f1..63176be3b50c 100644
--- a/kernel/printk/printk.c
+++ b/kernel/printk/printk.c
@@ -2186,30 +2186,6 @@ int vprintk_default(const char *fmt, va_list args)
}
EXPORT_SYMBOL_GPL(vprintk_default);
-/**
- * _printk - print a kernel message
- * @fmt: format string
- *
- * This is _printk(). It can be called from any context. We want it to work.
- *
- * If printk indexing is enabled, _printk() is called from printk_index_wrap.
- * Otherwise, printk is simply #defined to _printk.
- *
- * We try to grab the console_lock. If we succeed, it's easy - we log the
- * output and call the console drivers. If we fail to get the semaphore, we
- * place the output into the log buffer and return. The current holder of
- * the console_sem will notice the new output in console_unlock(); and will
- * send it to the consoles before releasing the lock.
- *
- * One effect of this deferred printing is that code which calls printk() and
- * then changes console_loglevel may break. This is because console_loglevel
- * is inspected when the actual printing occurs.
- *
- * See also:
- * printf(3)
- *
- * See the vsnprintf() documentation for format string extensions over C99.
- */
asmlinkage __visible int _printk(const char *fmt, ...)
{
va_list args;
--
2.31.1
On Sun 2021-07-25 15:16:00, Jonathan Corbet wrote:
> Chris Down <[email protected]> writes:
>
> > Chris Down writes:
> >>+Cc: Jonathan Corbet <[email protected]>, [email protected]
> >
> > Well, let's actually Cc them this time...
> >
> >>Stephen Rothwell writes:
> >>>After merging the printk tree, today's linux-next build (htmldocs)
> >>>produced this warning:
> >>>
> >>>kernel/printk/printk.c:1: warning: 'printk' not found
> >>>
> >>>Introduced by commit
> >>>
> >>> 337015573718 ("printk: Userspace format indexing support")
> >>>
> >>>I presume that "printk" is referred to elsewhere in the documentation
> >>>as being in this file.
> >>
> >>Hmm, this is an interesting one, because I think we still generally
> >>just want to refer to the API as being `printk()`. Changing it all
> >>over the place seems wrong. As you'd imagine, there are quite a few
> >>references to this name, so it requires a lot of noise all over the
> >>docs and inline comments.
> >>
> >>Jonathan and other docs folks, how can one tell Sphinx that when it
> >>sees printk() it's referring to a function-like macro, or otherwise
> >>squelch this reasonably? :-)
>
> The problem is that you moved printk(), but left the associated
> kerneldoc comment tied to _printk(), which isn't what you really want to
> document. The fix should look something like the attached.
>
> Thanks,
>
> jon
>
> --------snip here----------------------
> printk: Move the printk() kerneldoc comment to its new home
>
> Commit 337015573718 ("printk: Userspace format indexing support") turned
> printk() into a macro, but left the kerneldoc comment for it with the (now)
> _printk() function, resulting in this docs-build warning:
>
> kernel/printk/printk.c:1: warning: 'printk' not found
>
> Move the kerneldoc comment back next to the (now) macro it's meant to
> describe and have the docs build find it there.
>
> Signed-off-by: Jonathan Corbet <[email protected]>
This looks better than my variant. I have pushed it into
printk/linux.git, branch for-5.15-printk-index.
Best Regards,
Petr
Jonathan Corbet writes:
>The problem is that you moved printk(), but left the associated
>kerneldoc comment tied to _printk(), which isn't what you really want to
>document. The fix should look something like the attached.
Ah, I see. Thank you for your help!