Skip to contentSkip to conversation

linux-next: build warning after merge of the printk tree

PATCH In review Stephen Rothwell 4 participants 8 messages Jul 20, 2021 – Jul 26, 2021

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

+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 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? :-)

#2 lore raw
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 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? :-)

maintainer
#3 lore raw

PATCH 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().

Fixes 337015573718b161 ("printk: Userspace format indexing support")

---
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
index 965e4281eddd..3160a73c27b1 100644
@@ -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
index 2651b82ed352..e0e3411db67b 100644
@@ -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
index 765f7af6ce56..2e5559175214 100644
@@ -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
maintainer
#4 lore raw

Re: [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 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().

Quoted 6 lines
Fixes 337015573718b161 ("printk: Userspace format indexing support")

---
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

maintainer
#5 lore raw
In reply to Chris Down
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 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.

---
 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
index 965e4281eddd..2dde24ca7d9f 100644
@@ -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
index 2651b82ed352..c1e176403967 100644
@@ -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
index 9b3bd6e017f1..63176be3b50c 100644
@@ -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
maintainer
#6 lore raw
Quoted 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 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:

Quoted 6 lines

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.

This looks better than my variant. I have pushed it into printk/linux.git, branch for-5.15-printk-index.

Best Regards,
Petr

#7 lore raw
In reply to Jonathan Corbet
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!