* linux-next: build warning after merge of the printk tree @ 2021-07-20 6:24 Stephen Rothwell 2021-07-20 12:18 ` Chris Down 0 siblings, 1 reply; 8+ messages in thread From: Stephen Rothwell @ 2021-07-20 6:24 UTC (permalink / raw) To: Petr Mladek Cc: Chris Down, Linux Kernel Mailing List, Linux Next Mailing List [-- Attachment #1: Type: text/plain, Size: 379 bytes --] 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 [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 488 bytes --] ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: linux-next: build warning after merge of the printk tree 2021-07-20 6:24 linux-next: build warning after merge of the printk tree Stephen Rothwell @ 2021-07-20 12:18 ` Chris Down 2021-07-20 12:22 ` Chris Down 0 siblings, 1 reply; 8+ messages in thread From: Chris Down @ 2021-07-20 12:18 UTC (permalink / raw) To: Stephen Rothwell Cc: Petr Mladek, Linux Kernel Mailing List, Linux Next Mailing List [-- Attachment #1: Type: text/plain, Size: 917 bytes --] +Cc: Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org 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? :-) [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 963 bytes --] ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: linux-next: build warning after merge of the printk tree 2021-07-20 12:18 ` Chris Down @ 2021-07-20 12:22 ` Chris Down 2021-07-23 11:09 ` [PATCH] printk/documentation: Update printk()/_printk() documentation Petr Mladek 2021-07-25 21:16 ` linux-next: build warning after merge of the printk tree Jonathan Corbet 0 siblings, 2 replies; 8+ messages in thread From: Chris Down @ 2021-07-20 12:22 UTC (permalink / raw) To: Stephen Rothwell Cc: Jonathan Corbet, linux-doc, Petr Mladek, Linux Kernel Mailing List, Linux Next Mailing List [-- Attachment #1: Type: text/plain, Size: 1010 bytes --] Chris Down writes: >+Cc: Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org 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? :-) [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 963 bytes --] ^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH] printk/documentation: Update printk()/_printk() documentation 2021-07-20 12:22 ` Chris Down @ 2021-07-23 11:09 ` Petr Mladek 2021-07-23 11:24 ` Petr Mladek 2021-07-25 21:16 ` linux-next: build warning after merge of the printk tree Jonathan Corbet 1 sibling, 1 reply; 8+ messages in thread From: Petr Mladek @ 2021-07-23 11:09 UTC (permalink / raw) To: Chris Down Cc: Stephen Rothwell, Jonathan Corbet, linux-doc, Linux Kernel Mailing List, Linux Next Mailing List 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 <sfr@canb.auug.org.au> Signed-off-by: Petr Mladek <pmladek@suse.com> Link: https://lore.kernel.org/r/YPbBfdz9srIpI+bb@chrisdown.name --- 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 ^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH] printk/documentation: Update printk()/_printk() documentation 2021-07-23 11:09 ` [PATCH] printk/documentation: Update printk()/_printk() documentation Petr Mladek @ 2021-07-23 11:24 ` Petr Mladek 0 siblings, 0 replies; 8+ messages in thread From: Petr Mladek @ 2021-07-23 11:24 UTC (permalink / raw) To: Chris Down Cc: Stephen Rothwell, Jonathan Corbet, linux-doc, Linux Kernel Mailing List, Linux Next Mailing List 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 <sfr@canb.auug.org.au> > Signed-off-by: Petr Mladek <pmladek@suse.com> > Link: https://lore.kernel.org/r/YPbBfdz9srIpI+bb@chrisdown.name > --- > 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: linux-next: build warning after merge of the printk tree 2021-07-20 12:22 ` Chris Down 2021-07-23 11:09 ` [PATCH] printk/documentation: Update printk()/_printk() documentation Petr Mladek @ 2021-07-25 21:16 ` Jonathan Corbet 2021-07-26 12:28 ` Petr Mladek 2021-07-26 13:07 ` Chris Down 1 sibling, 2 replies; 8+ messages in thread From: Jonathan Corbet @ 2021-07-25 21:16 UTC (permalink / raw) To: Chris Down, Stephen Rothwell Cc: linux-doc, Petr Mladek, Linux Kernel Mailing List, Linux Next Mailing List Chris Down <chris@chrisdown.name> writes: > Chris Down writes: >>+Cc: Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org > > 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 <corbet@lwn.net> --- 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 ^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: linux-next: build warning after merge of the printk tree 2021-07-25 21:16 ` linux-next: build warning after merge of the printk tree Jonathan Corbet @ 2021-07-26 12:28 ` Petr Mladek 2021-07-26 13:07 ` Chris Down 1 sibling, 0 replies; 8+ messages in thread From: Petr Mladek @ 2021-07-26 12:28 UTC (permalink / raw) To: Jonathan Corbet Cc: Chris Down, Stephen Rothwell, linux-doc, Linux Kernel Mailing List, Linux Next Mailing List On Sun 2021-07-25 15:16:00, Jonathan Corbet wrote: > Chris Down <chris@chrisdown.name> writes: > > > Chris Down writes: > >>+Cc: Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org > > > > 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 <corbet@lwn.net> This looks better than my variant. I have pushed it into printk/linux.git, branch for-5.15-printk-index. Best Regards, Petr ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: linux-next: build warning after merge of the printk tree 2021-07-25 21:16 ` linux-next: build warning after merge of the printk tree Jonathan Corbet 2021-07-26 12:28 ` Petr Mladek @ 2021-07-26 13:07 ` Chris Down 1 sibling, 0 replies; 8+ messages in thread From: Chris Down @ 2021-07-26 13:07 UTC (permalink / raw) To: Jonathan Corbet Cc: Stephen Rothwell, linux-doc, Petr Mladek, Linux Kernel Mailing List, Linux Next Mailing List 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! ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2021-07-26 13:07 UTC | newest] Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2021-07-20 6:24 linux-next: build warning after merge of the printk tree Stephen Rothwell 2021-07-20 12:18 ` Chris Down 2021-07-20 12:22 ` Chris Down 2021-07-23 11:09 ` [PATCH] printk/documentation: Update printk()/_printk() documentation Petr Mladek 2021-07-23 11:24 ` Petr Mladek 2021-07-25 21:16 ` linux-next: build warning after merge of the printk tree Jonathan Corbet 2021-07-26 12:28 ` Petr Mladek 2021-07-26 13:07 ` Chris Down
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.