linux-next: build warning after merge of the printk tree
Subsystems (3)
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.
Signature · 2 lines
Cheers, Stephen Rothwell
+Cc: Jonathan Corbet <[email protected]>, [email protected]
Quoted 11 lines · Stephen Rothwell
After merging the printk tree, today's linux-next build (htmldocs) produced this warning:
kernel/printk/printk.c:1: warning: 'printk' not foundIntroduced 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? :-)
Quoted 1 line · Chris Down
+Cc: Jonathan Corbet <[email protected]>, [email protected]
Well, let's actually Cc them this time...
Quoted 16 lines
Quoted 11 lines · Stephen Rothwell
After merging the printk tree, today's linux-next build (htmldocs) produced this warning:
kernel/printk/printk.c:1: warning: 'printk' not foundIntroduced 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? :-)
Petr Mladek
maintainerPATCH 1/1 printk/documentation: Update printk()/_printk() documentation
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().
---
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(-)
Documentation/core-api/printk-basics.rst +3 -3
@@ -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
include/linux/printk.h +12 -0
@@ -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__)
kernel/printk/printk.c +2 -1
@@ -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.
Signature · 1 line
2.26.2
Petr Mladek
maintainerRe: [PATCH] printk/documentation: Update printk()/_printk() documentation
Quoted 9 lines · Petr Mladek
The commit
337015573718b161("printk: Userspace format indexing support") caused the following warning when building htmldocs:
kernel/printk/printk.c:1: warning: 'printk' not foundThe problem is that
printk()became a macro that is defined ininclude/linux/printk.hinstead ofkernel/printk.c. The original function was renamed to_printk().
Quoted 6 lines
Fixes 337015573718b161 ("printk: Userspace format indexing support")Reported-by Stephen Rothwell <[email protected]>Signed-off-by Petr Mladek <[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
Jonathan Corbet
maintainerQuoted 27 lines · Chris Down
Quoted 1 line · Chris Down
+Cc: Jonathan Corbet <[email protected]>, [email protected]
Well, let's actually Cc them this time...
Quoted 22 lines
Quoted 11 lines · Stephen Rothwell
After merging the printk tree, today's linux-next build (htmldocs) produced this warning:
kernel/printk/printk.c:1: warning: 'printk' not foundIntroduced 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.
--- Documentation/core-api/printk-basics.rst | 5 +---- include/linux/printk.h | 24 ++++++++++++++++++++++++ kernel/printk/printk.c | 24 ------------------------ 3 files changed, 25 insertions(+), 28 deletions(-)
Documentation/core-api/printk-basics.rst +1 -4
@@ -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
include/linux/printk.h +24 -0
@@ -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__)
kernel/printk/printk.c +0 -24
@@ -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;
Signature · 1 line
2.31.1
Petr Mladek
maintainerQuoted 45 lines · Jonathan Corbet
Quoted 27 lines · Chris Down
Quoted 1 line · Chris Down
+Cc: Jonathan Corbet <[email protected]>, [email protected]
Well, let's actually Cc them this time...
Quoted 22 lines
Quoted 11 lines · Stephen Rothwell
After merging the printk tree, today's linux-next build (htmldocs) produced this warning:
kernel/printk/printk.c:1: warning: 'printk' not foundIntroduced 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 theprintk()kerneldoc comment to its new homeCommit 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:
Quoted 6 lines
kernel/printk/printk.c:1: warning: 'printk' not foundMove 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
Quoted 3 lines · Jonathan Corbet
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!