From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5340FC48BC3 for ; Tue, 20 Feb 2024 07:16:54 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id DCFC56B0085; Tue, 20 Feb 2024 02:16:53 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id D7F8C6B0087; Tue, 20 Feb 2024 02:16:53 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id C47916B008A; Tue, 20 Feb 2024 02:16:53 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0012.hostedemail.com [216.40.44.12]) by kanga.kvack.org (Postfix) with ESMTP id B1F7A6B0085 for ; Tue, 20 Feb 2024 02:16:53 -0500 (EST) Received: from smtpin04.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay09.hostedemail.com (Postfix) with ESMTP id 7F90B80554 for ; Tue, 20 Feb 2024 07:16:53 +0000 (UTC) X-FDA: 81811325106.04.7421E52 Received: from smtp-out1.suse.de (smtp-out1.suse.de [195.135.223.130]) by imf26.hostedemail.com (Postfix) with ESMTP id 4159D140007 for ; Tue, 20 Feb 2024 07:16:51 +0000 (UTC) Authentication-Results: imf26.hostedemail.com; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=2ZP2VMC6; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=yZBmTjiY; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=2ZP2VMC6; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=yZBmTjiY; dmarc=pass (policy=none) header.from=suse.de; spf=pass (imf26.hostedemail.com: domain of hare@suse.de designates 195.135.223.130 as permitted sender) smtp.mailfrom=hare@suse.de ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1708413411; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=mRahtuQSFMxt05TGxYHbI48NSmxiy73yXCx+h0UNDqg=; b=mnMYcretUltUKy7EJJePzyOxAVxdwF9t8kwNzvghYNx5ef6I8ONJZnJgmBOU9g6QMf2Ppn ubk14YxZ69WXqtaZz7dUHFgE9ZVvqqE3GIO+zRMtw6Gt+IfKFAmOv+ofjiJtHFKLCT47gy N8S0oznXoUxpXOAtx9AYOVt+MeFH2JA= ARC-Authentication-Results: i=1; imf26.hostedemail.com; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=2ZP2VMC6; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=yZBmTjiY; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=2ZP2VMC6; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=yZBmTjiY; dmarc=pass (policy=none) header.from=suse.de; spf=pass (imf26.hostedemail.com: domain of hare@suse.de designates 195.135.223.130 as permitted sender) smtp.mailfrom=hare@suse.de ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1708413411; a=rsa-sha256; cv=none; b=k1G3TPy2/wyxk9rWAqaymakf8+Lyvx8hudpaG5yD3T1Nnb21vhCy8zrYOSj0q2zDFR73Y9 dKrPCr8mzZGuw27ylOJPrtN0ysJZiYhH9CTuVWW0afj+sD67yKTpG+KXS4z11CKzLZdliA bGh9RYsQJ6vlve8FUL4yTQVt3KnuiV0= Received: from imap1.dmz-prg2.suse.org (imap1.dmz-prg2.suse.org [IPv6:2a07:de40:b281:104:10:150:64:97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by smtp-out1.suse.de (Postfix) with ESMTPS id 335122203C; Tue, 20 Feb 2024 07:16:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1708413409; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=mRahtuQSFMxt05TGxYHbI48NSmxiy73yXCx+h0UNDqg=; b=2ZP2VMC6DM1eu/RhehDHocjEQiLkCkLr4elj8T43K1MbOVsvwtXgmu4qm/wUJNXejvvR1i EMRmls/ryG0ZwiXXwcxJN8Yw5BChSCPnHHhm2zWN5bzvU0W2fOdBxfvnWR0Qp98QQbKZai R4iVacnIqXx8DLu16oTtnv8ZgLJIdLY= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1708413409; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=mRahtuQSFMxt05TGxYHbI48NSmxiy73yXCx+h0UNDqg=; b=yZBmTjiY3bD9EYX0Pm7MQzWKCke58cJGugOtYVp3LfJ2fYt+kfzoSQ97B0l0VWnQV9bZTy 8w1TBNsXbk6niEAg== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1708413409; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=mRahtuQSFMxt05TGxYHbI48NSmxiy73yXCx+h0UNDqg=; b=2ZP2VMC6DM1eu/RhehDHocjEQiLkCkLr4elj8T43K1MbOVsvwtXgmu4qm/wUJNXejvvR1i EMRmls/ryG0ZwiXXwcxJN8Yw5BChSCPnHHhm2zWN5bzvU0W2fOdBxfvnWR0Qp98QQbKZai R4iVacnIqXx8DLu16oTtnv8ZgLJIdLY= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1708413409; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=mRahtuQSFMxt05TGxYHbI48NSmxiy73yXCx+h0UNDqg=; b=yZBmTjiY3bD9EYX0Pm7MQzWKCke58cJGugOtYVp3LfJ2fYt+kfzoSQ97B0l0VWnQV9bZTy 8w1TBNsXbk6niEAg== Received: from imap1.dmz-prg2.suse.org (localhost [127.0.0.1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by imap1.dmz-prg2.suse.org (Postfix) with ESMTPS id 29582134E4; Tue, 20 Feb 2024 07:16:48 +0000 (UTC) Received: from dovecot-director2.suse.de ([10.150.64.162]) by imap1.dmz-prg2.suse.org with ESMTPSA id A8MCCOBR1GUmRAAAD6G6ig (envelope-from ); Tue, 20 Feb 2024 07:16:48 +0000 Message-ID: <427e3fdb-5be2-4ff3-9bad-a21c49d0aab4@suse.de> Date: Tue, 20 Feb 2024 08:16:46 +0100 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [LSF/MM/BPF TOPIC] Reclaiming & documenting page flags Content-Language: en-US To: Matthew Wilcox , Mike Rapoport Cc: lsf-pc@lists.linux-foundation.org, linux-fsdevel@vger.kernel.org, linux-mm@kvack.org, linux-block@vger.kernel.org, linux-ide@vger.kernel.org, linux-scsi@vger.kernel.org, linux-nvme@lists.infradead.org, bpf@vger.kernel.org References: From: Hannes Reinecke In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit X-Rspamd-Server: rspam09 X-Rspamd-Queue-Id: 4159D140007 X-Stat-Signature: wwcg81xkywggqwmswwio9arzeue7qopj X-Rspam-User: X-HE-Tag: 1708413411-38016 X-HE-Meta: U2FsdGVkX18BrnbW9LIyUdYbB1dB/ZuCQRdZOpJ0q7aSLUILhXptVaJ9w/h7HsUvFBfYU7I64ZQVmYFDFTs69/soVkf0e3NndJcm7Y1LkbjiGxIVSNYKXDoDdawtv3UcvSuZ+X2xESJ1fbgl3O21+bhpgRmY9TezcOFqPadlKiV+2kl15gJpj62NMwg99VkRC2fOtSNNuQxLdlw1vMe45uoHLCfsYtgM/oEMdT1LvboB2T+iZ0c9f+RsfkHJlR4E072mDtvA3stxSUL4Eaz9qsPHcRnGzycYMlk0wiAcrnYRkIkCayp4BSP1tH99uJUJNJOSzXWgk24XFpqUHXFOvPbqHxE19G4MxLY5cP1rjiaVA5LsrgU9RF8HgXD/LtZcsBcBn59ZQYu+vUEyo1GzM03vYoFfWMTi8iAd3STeYxnIxF/beAZCCsNIp6ZTF8/eKK52EuMfRoi4XcNfrnaovmp7xmtQJX/94CZrI25WDtJ98OnP9i9Ecp32LaYUH7IpgHPvzvMFQj7mEGU9maokOwK09IHNAQie6CPhNcBJ8t+Ej6dyUqkms6FxjL/6UOsQuuX5c9ZYANR/liQhsx5R7H6nXe92GbDb2lpSHian+4w5z/293i9/5gA6dyezc4vU2mmac6W5f+RPWT97XhrdZaZTyrUBPjoxR+Jai5qDB2mXi3sg4AMmtNzfFPlhwC+noceiJdyLzvXbeaHhu9NiA698o0BcxaHb61GB52pATXu0DKf3A5GHAoFjwx4G7Xxr46ksxTaoUwBpTqd9RCOpll2Ag2kZnvvA7JaCI2PBBygkROZs1e5m1OF4UxQh825/mkn7QEZeLxrabm86ogwnrO6EE4O0wOmIbBQoL6/8PtXFQhLLkzkTxTFOw5iBNsdXt2Hevey8OS1ZO0jWrQjXiJKaqckb2mvZl5bybmzfOpgf2srcFA0egglid9nIhowT+dxpaG2fsNAfoiI8SsU 8Lw== X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: On 2/19/24 21:13, Matthew Wilcox wrote: > On Wed, Feb 07, 2024 at 05:51:44PM +0200, Mike Rapoport wrote: >> On Sun, Feb 04, 2024 at 09:34:01PM +0000, Matthew Wilcox wrote: >>> I'm doing my best to write documentation as I go. I think we're a bit >>> better off than we were last year. Do we have scripts to tell us which >>> public functions (ie EXPORT_SYMBOL and static inline functions in header >>> files) have kernel-doc? And could we run them against kernels from, say, >>> April 2023, 2022, 2021, 2020, 2019 (and in two months against April 2024) >>> and see how we're doing in terms of percentage undocumented functions? >> >> We didn't have such script, but it was easy to compare "grep >> EXPORT_SYMBOL\|static inline" with ".. c:function" in kernel-doc. >> We do improve slowly, but we are still below 50% with kernel-doc for >> EXPORT_SYMBOL functions and slightly above 10% for static inlines. > > Thanks for doing this! Data is good ;-) > > I just came across an interesting example of a function which I believe > should NOT have kernel-doc. But it should have documentation for why it > doesn't have kernel-doc! Any thoughts about how we might accomplish that? > > The example is filemap_range_has_writeback(). It's EXPORT_SYMBOL_GPL() > and it's a helper function for filemap_range_needs_writeback(). > filemap_range_needs_writeback() has kernel-doc, but nobody should be > calling filemap_range_has_writeback() directly, so it shouldn't even > exist in the htmldocs. But we should have a comment on it saying > "Use filemap_range_needs_writeback(), don't use this", in case anyone > discovers it. And the existance of that comment should be enough to > tell our tools to not flag this as a function that needs kernel-doc. > > Or, indeed, coming up with a method of signalling "this is an internal function for a specific need, don't use otherwise". EXPORT_SYMBOL_INTERNAL? I would love to have it; it would solve _so_ many problems we're having wrt kABI... Cheers, Hannes -- Dr. Hannes Reinecke Kernel Storage Architect hare@suse.de +49 911 74053 688 SUSE Software Solutions GmbH, Frankenstr. 146, 90461 Nürnberg HRB 36809 (AG Nürnberg), GF: I. Totev, A. McDonald, W. Knoblich