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 EBCBEC48BF8 for ; Tue, 20 Feb 2024 00:21:46 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 402F66B0072; Mon, 19 Feb 2024 19:21:46 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 38B536B0078; Mon, 19 Feb 2024 19:21:46 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 2050E6B007B; Mon, 19 Feb 2024 19:21:46 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0010.hostedemail.com [216.40.44.10]) by kanga.kvack.org (Postfix) with ESMTP id 0A3986B0072 for ; Mon, 19 Feb 2024 19:21:46 -0500 (EST) Received: from smtpin10.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay01.hostedemail.com (Postfix) with ESMTP id D30A01C03CD for ; Tue, 20 Feb 2024 00:21:45 +0000 (UTC) X-FDA: 81810278970.10.310BDE2 Received: from smtp-out1.suse.de (smtp-out1.suse.de [195.135.223.130]) by imf04.hostedemail.com (Postfix) with ESMTP id 82F424000F for ; Tue, 20 Feb 2024 00:21:43 +0000 (UTC) Authentication-Results: imf04.hostedemail.com; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=eHEgPEMA; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=AqAbl95u; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=eHEgPEMA; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=AqAbl95u; dmarc=pass (policy=none) header.from=suse.de; spf=pass (imf04.hostedemail.com: domain of neilb@suse.de designates 195.135.223.130 as permitted sender) smtp.mailfrom=neilb@suse.de ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1708388504; 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=aCStDtcRffeU4jURBHp/euC2Vn/pS2u4zscwEUzLt+k=; b=pifZMKW9Mqm5KFWwG1QoV9KSsYmHXxT6pI29ja0DgZrXO6rCzxB/2TijeMzJcfFZ7AJ9w1 OwDFZ4ut/eWpNmXly7va7H2xDqNya+bJFUSqK8ONJWHX0OjQuB4MO0fbxN+HzY6sEnrV5O OwGBfYNJkzOSNcsYDirSrvEJdrDvvlk= ARC-Authentication-Results: i=1; imf04.hostedemail.com; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=eHEgPEMA; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=AqAbl95u; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=eHEgPEMA; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=AqAbl95u; dmarc=pass (policy=none) header.from=suse.de; spf=pass (imf04.hostedemail.com: domain of neilb@suse.de designates 195.135.223.130 as permitted sender) smtp.mailfrom=neilb@suse.de ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1708388504; a=rsa-sha256; cv=none; b=608TC0ErLUmZsJo2p5jkJ4lgFa1DtlvSknDdY93mKsDHL0yVZU9KsiiTc5cXRBjnz004R5 spVWcIkLD/0VuouRQpQESLXVRM04diiosIc2CxXG7iZ/NYIssz+M6oZobgUVE4dLMW/mb9 8k7/9ywzeJfE86mCseJ3STQLyr+pO3g= 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 A9F2121EAD; Tue, 20 Feb 2024 00:21:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1708388501; 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=aCStDtcRffeU4jURBHp/euC2Vn/pS2u4zscwEUzLt+k=; b=eHEgPEMAEvAjhowMWVtD1L45v2+oTmGs40a7GZOJ1Ov9Jb9s5RNEuhdI/LqkTAnSckTKAJ xfUbQrIRGupq65EmcwwUqT+dl/wp3Vn/I5B1feDMhJv4MQfRlAcEH77ONSSW6Ocsj9HK2+ lGA0/CFkumnx/sZEaFmPNPhFZu0ydRY= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1708388501; 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=aCStDtcRffeU4jURBHp/euC2Vn/pS2u4zscwEUzLt+k=; b=AqAbl95uLUKL7GTueZQ3qWuww7EqxAm3/78Jlrz4vkGAoFUdNbY3/TvYsv215SIX5ySpk0 4UPPxuSKOkij04Dw== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1708388501; 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=aCStDtcRffeU4jURBHp/euC2Vn/pS2u4zscwEUzLt+k=; b=eHEgPEMAEvAjhowMWVtD1L45v2+oTmGs40a7GZOJ1Ov9Jb9s5RNEuhdI/LqkTAnSckTKAJ xfUbQrIRGupq65EmcwwUqT+dl/wp3Vn/I5B1feDMhJv4MQfRlAcEH77ONSSW6Ocsj9HK2+ lGA0/CFkumnx/sZEaFmPNPhFZu0ydRY= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1708388501; 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=aCStDtcRffeU4jURBHp/euC2Vn/pS2u4zscwEUzLt+k=; b=AqAbl95uLUKL7GTueZQ3qWuww7EqxAm3/78Jlrz4vkGAoFUdNbY3/TvYsv215SIX5ySpk0 4UPPxuSKOkij04Dw== 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 657EF139D0; Tue, 20 Feb 2024 00:21:38 +0000 (UTC) Received: from dovecot-director2.suse.de ([10.150.64.162]) by imap1.dmz-prg2.suse.org with ESMTPSA id KtjvBpLw02UVagAAD6G6ig (envelope-from ); Tue, 20 Feb 2024 00:21:38 +0000 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit MIME-Version: 1.0 From: "NeilBrown" To: "Matthew Wilcox" Cc: "Mike Rapoport" , 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 Subject: Re: [LSF/MM/BPF TOPIC] Reclaiming & documenting page flags In-reply-to: References: , , , , , <170838273655.1530.946393725104206593@noble.neil.brown.name>, Date: Tue, 20 Feb 2024 11:21:35 +1100 Message-id: <170838849545.1530.13553329646368488958@noble.neil.brown.name> X-Rspam-User: X-Rspamd-Server: rspam12 X-Rspamd-Queue-Id: 82F424000F X-Stat-Signature: 8ufwthkambdj463h556m3bgsbje41g9j X-HE-Tag: 1708388503-815807 X-HE-Meta: U2FsdGVkX18tWMTtcxQN4g04gCGd+mW9eQpHhpDnGj5skSeXDcNahfnbRAKchIyKZ+vKNN8n5lWHj2dVkCy74SZuIzeshqYVdF5lkfic2nQUjKYlfufI1rIHXTvIxzrOu+2XLuT2gVp4YZqk9nCikqt/IUt3qCIm7wk8qtoW/DIfolp71KFKIEMxeU93rXjy7lxBWHVagMp/tX09WaU4lRvMoAglz80mMRqCwagD3JkK9fmdlXostYiekrM3tBben65m3YSRej1llqorxIwRyrTLF0pDZUFo54lHaEEZFcynnNnVxaGCN3E3S4AeOzd8fR3cp2uPz/1cdZP7+bAoSE99itIIW3T5x/T5ikqlXngWM3+Dd7luBcC6VmhRmr9mQQ72ZZhHIIQg9tlEL2Q0rb9kJxlx7llK5leeLyqIvXwfY5jm9b7EcN2HvUJx2Z69wYCVpMi5UnK1hh2C7EbAThqIdnG9713nWqKbHo7Q0rLRv0+V8ZFM21rSNnzlJ0x6j0G38D9iWdqhPtj1XAeR2vO8vItVi4DdTZEoqB2AubUeUu4SuXUHrlQ8wiFWlm6QISwYj/mvL5/Yya2BWkAyupSH4vOc9RhytpcQQs9LmV0eSPRhHvHtMA5uBDFbdGVs93usq7rmzBY+vofPSMzHklPlBgc2zbMG/nAgBx+vjYLAf3d+zJP4/kexp5JnqXXkqHxzoKg63vWk57FYWxeI2FSwicLJx2PvXZk+Zef1OsodLOvOh1mkblB43vEpJ2CPUS81fn1496g8g4ETeUENmxtFdLkkJi3hogDuauYwDWdB6xY7Hc+6NjdvU2Z5xmzd3iJ+ntAxS73xXb7218uegs9z7ZwGAtZG5a1Q2NZNQRyPQm0RdEVdL2fiIvcQOBylh54RTKXDH1v1/Z+Erw7HBShnE/rM6rmnwyLc7Pfcp7mSo2xOlPkAaN3Q6UWhDSwNcIPZ3mzfjH9rWZkxXmX OAWDxR/X UNwfgnH40mTxf6ni4ZHmb3qcjnkl50BpRCr1xp+TSgWkS/Hn7RZGK/MTPAH4WAJ4yw1EkP0sM6mw24WNwA9EnNpWfXkM8VMZqRhD86tejxZ4x82hjhZG2sdqqwibCCpifY44dWTCKX2AySlU2yvXwbKIKfYfjXM4cITWi0EjykgydDsgjYpI8OJBJZtUPLbHRsd45htQ4RLu7swTu1ms3/seBhyp31XJ9X+5h X-Bogosity: Ham, tests=bogofilter, spamicity=0.000003, 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 Tue, 20 Feb 2024, Matthew Wilcox wrote: > On Tue, Feb 20, 2024 at 09:45:36AM +1100, NeilBrown wrote: > > On Tue, 20 Feb 2024, Matthew Wilcox wrote: > > > 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. > > > > > > > Don't we use a __prefix for internal stuff that shouldn't be used? > > No? Or if we do, we are inconsistent with that convention. Let's > consider some examples. > > __SetPageReferenced -- non-atomic version of SetPageReferenced. > Akin to __set_bit. > > __filemap_fdatawrite_range() -- like filemap_fdatawrite_range but > allows the specification of sync_mode > > __page_cache_alloc() -- like page_cache_alloc() but takes the gfp mask > directly instead of inferring it from mapping_gfp_mask() > > __folio_lock() -- This does fit the "don't call this pattern"! > > __set_page_dirty() -- Like set_page_dirty() but allows warn to be > specified. > > __filemap_remove_folio() -- Like filemap_remove_folio() but allows it > to be replaced with a shadow entry. > > __readahead_folio() -- Another internal one > > I mostly confined myself to pagemap.h for this survey, but if you've > conducted a different survey that shows your assertion is generally true > and I've hit on the exceptions to the rule ... ? > Yes, __ is used for other things too. It would be nice to have some consistency with naming, but probably impossible. And with 1074 functions named __foo having kernel doc already, it is too late to close that gate. :-( Thanks, NeilBrown