Received: by 2002:a05:6a10:1287:0:0:0:0 with SMTP id d7csp3037233pxv; Sun, 25 Jul 2021 14:21:10 -0700 (PDT) X-Google-Smtp-Source: ABdhPJxlTSXwu84t7SVsBSEHTvhAasXhdavayIYxy+pJVnzGXW5mSeLz7S5wHiFI+yTMbEQ578iU X-Received: by 2002:a17:907:ab8:: with SMTP id bz24mr14511990ejc.413.1627248070462; Sun, 25 Jul 2021 14:21:10 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1627248070; cv=none; d=google.com; s=arc-20160816; b=CF15oLO/THVHQ4WeTMSe8/L3nDsp+fLK7p/TZBW6vmT53C8lN6FONIVVdzUngtSnQ9 syBYIuqd5GqCCjWWrH+jRE6mYvV/Q8+bR9BozspZVptIdYehJVkQQkijRSlcgO3OxwsW OzP2JTprUVbXEiA0+IazptqfBEsGr2uipyrFv4/KmtkrJMGDtgx/hiloAwa09mw3oDWH sZMLNk2SzTjLzVkKk7nVmnITjKPkdYHJI59+lrCaDAE0J8vIQLQfgcql7G2K5V1j7PCg O+38DueNg8gcYnCz4/q/NDf27fDgCuNLviv1xhe6qQmVfNz1GU4LF1CpKwd8iARMoh4+ r2EA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:mime-version:message-id:date:references :in-reply-to:subject:cc:to:from:dkim-signature:dkim-filter; bh=ha6zQ/lQ89wnLjJN9FZzRbJvHPDXNDngMT6ZHwKPkKc=; b=oYnXnqj+2zQuw09UBjHERd+uf3G1bybyoxCNdYbyZolTDaBhauKq14h5g7pEelPTTn h0qzSCA4DIxqnwmN0dCvBjJA2uy6m+zmTouoDujGtx/ghzqVN4XGIAfpCFBa3MQDiy+9 kfUvzHI13DPKufeQ+LxCKc+95V0dYmfeN5dAdkNKLoaZk1E9wnHrppn/Frmei5j8Vnxx 8/vvq6jkCYfXQmSdHC6LmwHxgNVfCg1vkpkk8wZebaNyhxzbyVxZkRiqy6NaUXewjH7G R9MYJc7xQA2PdbLtImlnswUqZPXGJCbPPMink0OSQtkAxScUKWnadCwYvh6kZkQChyb5 QzjQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b=VX+ALNFN; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [23.128.96.18]) by mx.google.com with ESMTP id t20si37860131eds.424.2021.07.25.14.20.29; Sun, 25 Jul 2021 14:21:10 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18; Authentication-Results: mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b=VX+ALNFN; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230303AbhGYUfc (ORCPT + 99 others); Sun, 25 Jul 2021 16:35:32 -0400 Received: from ms.lwn.net ([45.79.88.28]:42250 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229829AbhGYUfb (ORCPT ); Sun, 25 Jul 2021 16:35:31 -0400 Received: from localhost (unknown [IPv6:2601:281:8300:104d::5f6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id 676C02E6; Sun, 25 Jul 2021 21:16:01 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 676C02E6 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1627247761; bh=ha6zQ/lQ89wnLjJN9FZzRbJvHPDXNDngMT6ZHwKPkKc=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=VX+ALNFNqJ8v2HjmoNofjL9fDoqpoNt457tfCRUOfcd5oO+nYWVvQrcoEVjEMS5m9 mIhaSanNmVbHBniRD88uzcWS+YgqHKFgtjpZ/wuDs+bgvBIto1r949Jue7A3uyKRVn ppTPttKmLLK206AesY60EsuFyuycBMNNXVAIzFU1eVSDdM/FqX8/tfIUhbqZFBIkj2 mUKsfCLhfC9VEOT9zQHc2VVBjvc5OQfakA8R2zXOusxMQwD1sVZb1mzPYjm1pvwmTC 4GfL/lu+dx9oedWtW6KRtKWOOhQZ8kBeCyUBoNI5dNUl7s9/iP0C8Klxv3rDd+K3ju yxZtZV/IZr3dQ== From: Jonathan Corbet To: Chris Down , Stephen Rothwell Cc: linux-doc@vger.kernel.org, Petr Mladek , Linux Kernel Mailing List , Linux Next Mailing List Subject: Re: linux-next: build warning after merge of the printk tree In-Reply-To: References: <20210720162423.75f61ce0@canb.auug.org.au> Date: Sun, 25 Jul 2021 15:16:00 -0600 Message-ID: <87o8aqt7qn.fsf@meer.lwn.net> MIME-Version: 1.0 Content-Type: text/plain Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Chris Down writes: > Chris Down writes: >>+Cc: Jonathan Corbet , 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 --- 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