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 A8C6EC4828D for ; Wed, 7 Feb 2024 15:52:13 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 0E7E56B007D; Wed, 7 Feb 2024 10:52:13 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 0982E6B007E; Wed, 7 Feb 2024 10:52:13 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id EA25D6B0083; Wed, 7 Feb 2024 10:52:12 -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 D9D766B007D for ; Wed, 7 Feb 2024 10:52:12 -0500 (EST) Received: from smtpin29.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay01.hostedemail.com (Postfix) with ESMTP id A47671C0978 for ; Wed, 7 Feb 2024 15:52:12 +0000 (UTC) X-FDA: 81765449304.29.7742299 Received: from sin.source.kernel.org (sin.source.kernel.org [145.40.73.55]) by imf23.hostedemail.com (Postfix) with ESMTP id 2D815140015 for ; Wed, 7 Feb 2024 15:52:09 +0000 (UTC) Authentication-Results: imf23.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=S4roDxo8; dmarc=pass (policy=none) header.from=kernel.org; spf=pass (imf23.hostedemail.com: domain of rppt@kernel.org designates 145.40.73.55 as permitted sender) smtp.mailfrom=rppt@kernel.org ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1707321131; a=rsa-sha256; cv=none; b=lYuMMTkCLdffkI0REwrIIwyTQgpTorEXCKyVH8NEO/vE+G9PAkJC1DpI+0xv1oT4WL8S2F bhPmhChTAI9yqMKHIHdRawWROqNgD+JO+fZIMm86ooiogwH5BS1wk1l3D83TxjKr2CTgME WaHpiEl2TikInFCpFhQ1XN0ucPHF274= ARC-Authentication-Results: i=1; imf23.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=S4roDxo8; dmarc=pass (policy=none) header.from=kernel.org; spf=pass (imf23.hostedemail.com: domain of rppt@kernel.org designates 145.40.73.55 as permitted sender) smtp.mailfrom=rppt@kernel.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1707321131; 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: in-reply-to:in-reply-to:references:references:dkim-signature; bh=ZbGDeRJmDQjqTCeYEI4ULf6ULadhlIT0/4yy3wdLoGM=; b=pQX3GygU15pfXHsVOg+WdSjkUJWqBhLZxUgjT6wg/F+YiMqqGf8g5WjSQQarUzGaq3/8Dg urBPxt2cpE1BNwfWCD0V5X0am9HFjV6Kj8bsid+FtKP4M66Toyb0pnlQJuWPgXQhKUW9hO 1zjugopVnsQoHgSUaHWjcWZ0RDFbyxc= Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by sin.source.kernel.org (Postfix) with ESMTP id B11B6CE13C7; Wed, 7 Feb 2024 15:52:04 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9D9B4C43394; Wed, 7 Feb 2024 15:52:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1707321123; bh=/1x7h2DpHjWcd/k76A8g5THiTurxMbwv+SYlEW+93sc=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=S4roDxo8tVqC2GezTlb3cfXFcp6weQcwLaiGZmdf1pdhhuOhtMsuGhDXsDCMV8GbO RLxAo3vtpqHJdWUBeO1ZdBUc+YJEiBqPKnzeW10gKgdzx5yAj262qNEjatFr2oewA5 U96gkG8+cuJWYr/hLXC31VNHfddrz7/y70HWgLAxw3ppS44aI4YAdO6JffVBmwOlG8 XU9HW6HuV+8zPXv4xQ3gBEg6Ps5noXk7cufMK2v4qV4yePWova47vaD8FNN7s7EdTb NB9oCYbsmwivsZGgDOIpD/iQoZTqpkGenaDhqgpVnREaQgX0b1oUD9pyX7pTlppedD uLYLbPbnYYeQg== Date: Wed, 7 Feb 2024 17:51:44 +0200 From: Mike Rapoport To: Matthew Wilcox 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 Subject: Re: [LSF/MM/BPF TOPIC] Reclaiming & documenting page flags Message-ID: References: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Rspam-User: X-Rspamd-Server: rspam06 X-Rspamd-Queue-Id: 2D815140015 X-Stat-Signature: u6oqx1mmaswpq36qobq3dhjaw1zz8cuk X-HE-Tag: 1707321129-965416 X-HE-Meta: U2FsdGVkX1+Wgz9Q2DvxYVW2te1jm3Guir7Dyrrr6Ea1hI2Toe+2GGDJewo9p2j6bMfVU3aFkhRAlKjSdiZj+JmiLPu4ayYOEih4SHE7KPxoHm4tysT9VgU34ruT/h4gsLUuL2ch2eCYfj+4MyG1ro7Pd/3VHufz7HMh/MsGP0d5QCWEu//tWSVqyMjp0pZrLPPZF03Tuk8fPnpROhraqZHZF7il5AFoorpC6PECJ8x9cD3/OdmjHmLiESVXHApiNdVfjObJzBueQSswh+oVtsU/tQ+K1aBHmkMmMs46YThz12zRCUlFfmw5Ocv001q3cx7uVP2aNVVUIbneyywdJriNAFJH7YU/4vGijn7y6OhMxCADvmuonzpi6uDvuG3S7VIUcfmEV8DAcyFn0UrUo+BATdWBkQzHIk9CxU/SRvbiiI5n0SmN1uB4KA8x5w9z9lfGrf0/peSk4pZ/3mREY4Xrw9I2cIhAcIktE8nNxdN2prcacd7RZz8j4JOXT5Tn9hhZYVWbf/Iiresc3g4OhI7EOLDctW+7cxWHpDbLsyE97lVB10XDG7DS1PSPpqrd14xKLCxcvAPjsdMYvx9HKam666TU9D/OS62qY6gnnHst+BaQbM0Vg/1A21q9Jk11t8R3nZa6c9dmta2P6vQWRIzriIZyHJT1jzJN2lqYLXequVLur60mLbcY6FRYKZosOaTi8t67R7KD+px87zGb1QytCJmrPd7pwbtYkqDErslYvq8eaaWbN6Toy9ielbuC6HzrYuXGDV65cg/5B27/2VBsPwtVD44a8BUizl9YLmXlxq3dGixkSjVIHeH6I+k4NgezAPyicGZQfgFafkVPKGG84X4E2incTsjZIZmjiZU7EZrs00VOlZUI/6h92BirbbHxzYTsJbvCQMMvL4vK2Fhm/V3vZZsPyyu2NZ7RzCBDaEBd0UVQ1oD9mwjRV12a94BTaSDmMImAYTnQRlS Wo30cY1u w7LCA7OQTQMI70tCbJw2zSwV1rmwvPqx5DRsJVSjll8CEWMFK+NqG39zahrx/+sdmp35QOpX9Em8B6fkASsk1zYoE+8GKnyXJCDAVRHEznFdWgzvzLB4wfPH3XtwTL3/iRUSsrarToUlX6UnldpivGb0g1WUEpAtaHyCRhm36/nQC4KJdx0QWoTUfgApQjIIU02W3 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 Sun, Feb 04, 2024 at 09:34:01PM +0000, Matthew Wilcox wrote: > On Sun, Feb 04, 2024 at 11:39:33AM +0100, Mike Rapoport wrote: > > On Mon, Jan 29, 2024 at 04:32:03AM +0000, Matthew Wilcox wrote: > > > Our documentation of the current page flags is ... not great. I think > > > I can improve it for the page cache side of things; I understand the > > > meanings of locked, writeback, uptodate, dirty, head, waiters, slab, > > > mlocked, mappedtodisk, error, hwpoison, readahead, anon_exclusive, > > > has_hwpoisoned, hugetlb and large_remappable. > > > > > > Where I'm a lot more shaky is the meaning of the more "real MM" flags, > > > like active, referenced, lru, workingset, reserved, reclaim, swapbacked, > > > unevictable, young, idle, swapcache, isolated, and reported. > > > > > > Perhaps we could have an MM session where we try to explain slowly and > > > carefully to each other what all these flags actually mean, talk about > > > what combinations of them make sense, how we might eliminate some of > > > them to make more space in the flags word, and what all this looks like > > > in a memdesc world. > > > > > > And maybe we can get some documentation written about it! Not trying > > > to nerd snipe Jon into attending this session, but if he did ... > > > > I suspect Jon will be there anyway, but not sure he'd be willing to do the > > writing :) > > > > I was going to propose the "mm docs" session again, but this one seems more > > useful than talking yet again about how hard it is to get MM documentation > > done. > > 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. Although with static inlines it's quite possible that the percentage of actual public API documentation is higher because some of the functions in inlcude/linux/ are only used inside mm. There are also APIs that are not EXPORT_SYMBOL, but I didn't find an easy way to check how well there are documented. EXPORT_SYMBOL version funcs docs percent v5.0 514 177 34 v5.6 538 208 38 v5.12 550 209 38 v5.17 580 228 39 v6.3 580 235 40 v6.8-rc1 565 238 42 static inline version funcs docs percent v5.0 581 33 5 v5.6 596 41 6 v5.12 629 42 6 v5.17 746 74 9 v6.3 867 95 10 v6.8-rc1 944 116 12 > There's also the problem of getting long-form documentation done. > But I think that's a different problem from getting kernel-doc written. > Looking at the 55 commits in the last year to Documentation/mm, we seems > to be doing a pretty good job of keeping the documentation we have up > to date. Just not a great job of adding new documentation. I agree that long-form documentation is a different problem from getting kernel-doc written and we are not doing a great job in writing new documentation. -- Sincerely yours, Mike.