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 C7411C77B7F for ; Fri, 12 May 2023 01:40:05 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 214746B0071; Thu, 11 May 2023 21:40:05 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 1C4EB6B0074; Thu, 11 May 2023 21:40:05 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 0B3FE6B0075; Thu, 11 May 2023 21:40:05 -0400 (EDT) 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 F0E066B0071 for ; Thu, 11 May 2023 21:40:04 -0400 (EDT) Received: from smtpin30.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay09.hostedemail.com (Postfix) with ESMTP id B07B68045E for ; Fri, 12 May 2023 01:40:04 +0000 (UTC) X-FDA: 80779897128.30.65E4FFF Received: from mail-pf1-f178.google.com (mail-pf1-f178.google.com [209.85.210.178]) by imf20.hostedemail.com (Postfix) with ESMTP id EA3A31C000A for ; Fri, 12 May 2023 01:40:02 +0000 (UTC) Authentication-Results: imf20.hostedemail.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=CQIw18NE; spf=pass (imf20.hostedemail.com: domain of lstoakes@gmail.com designates 209.85.210.178 as permitted sender) smtp.mailfrom=lstoakes@gmail.com; dmarc=pass (policy=none) header.from=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1683855603; 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=eU0/Ov62QZDbftqYsDW0sSHUzm/BcVFKf00taUoOR0A=; b=dIveuUU4TQYFiGkTwGth97OozUABYfMeJEeh0UrTE0BcQKxe7pQLHeXtaPlSreiLr3Ti9f d2uRyX5B7Wmi9W36A1ZjrpGXtfrFv3FrnXZNmQsG7m8jCV7ObQsqe00NXcp3P/dyaWJRSC SjlDiw/pZ7LZjOQtARPpHYPwSvQNw6A= ARC-Authentication-Results: i=1; imf20.hostedemail.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=CQIw18NE; spf=pass (imf20.hostedemail.com: domain of lstoakes@gmail.com designates 209.85.210.178 as permitted sender) smtp.mailfrom=lstoakes@gmail.com; dmarc=pass (policy=none) header.from=gmail.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1683855603; a=rsa-sha256; cv=none; b=4gdBctUwtFcSHD7kaWQe6VOW6eqSpybET6epznqSDD0zG/3gptBXAaT4F4/c6VKA32yIvC V2UgZABTZT8LVEt5MkH+JjgCsbIhSpxxSqo2ZplM27+hKpBe7vigyvb0X4NcOgWiZ7IGCC cS48b3i+UZODfdYnWehAuxsduVs+DOI= Received: by mail-pf1-f178.google.com with SMTP id d2e1a72fcca58-643912bca6fso7476577b3a.0 for ; Thu, 11 May 2023 18:40:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1683855602; x=1686447602; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=eU0/Ov62QZDbftqYsDW0sSHUzm/BcVFKf00taUoOR0A=; b=CQIw18NEFjFcrep4j15RupFs0eMQ1m8xaL51PAqtjUfJT7Mu5EtYmSCg5xERNWCt6T H2beXwBu1MqQIVZkwEGmSnkDDATYkb6Hn5K0kne1YVZ81udbiOMJPMzO3EUns4UGuUqj jG7+QsLpGtvNqWgNiAdZDnjdcBmDx+pY4bo1lSLZpOWkz3Siq5ghdyDAlAUBJCTG29R1 qFNuXL7QGYYEncNM1jLvT9cBaE2LoP2q6dVdBNXrnhlXBQSc/+Yq0HiGCen2Ky07Fo+G eB9hKUmhprj80/SyVHz+xlXUH+TIonT6Mkgha3cY2+TCOLCQ4VN85lzqIvQ/nDMg2flg 8jJQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1683855602; x=1686447602; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=eU0/Ov62QZDbftqYsDW0sSHUzm/BcVFKf00taUoOR0A=; b=jfMXQ6yi6wOEbeyx+w9+MzlNGUISrJqvW0MzyBH8ZBYFPk1iahmBcLUaya5guXipe7 hdjgtllR0ZU8NwntaLOXSoWl5ptvZ3SOCDtJZ+eZoEcSZjuts50Rzy2QFRn5D+fg7c4a oKi2P72lmv9dqE6IqMY4pIsURtcV1x3ZfEkQWd3vdTu+gPqlb63vEpkz97jVHTh1cl59 38MatzdfOHut/728HD2NtV93iK4rj1Wrd6/wgSOCJ6WsDdiIgRR30tl57h9Nmx3gLmTO P7ytBAr6JaxKkv1Q+YESufKov/9dDMK4ZI8vVJTo/lvo5t692o0kiNCaZb+4TuqTt+sD dx3g== X-Gm-Message-State: AC+VfDyP4NT+Ks5pQblsc/3gd+eMyj3fNXzRiswYb2UDMQo0+R4FJcGc Uz7F5poEOmPlnlN3E3Z/oTtoUreoGZtxlATEZ8k= X-Google-Smtp-Source: ACHHUZ5sJSyhApHiCqrTglX33t3qyJ6fvPIQRmiHCf8WKaPk99y+SVVPaqt4AVtaSJ7dSjn9w9j7LvsmIbr+iSPPycM= X-Received: by 2002:a05:6a00:234c:b0:646:3c2:4d30 with SMTP id j12-20020a056a00234c00b0064603c24d30mr21220127pfj.30.1683855601582; Thu, 11 May 2023 18:40:01 -0700 (PDT) MIME-Version: 1.0 References: In-Reply-To: From: Lorenzo Stoakes Date: Thu, 11 May 2023 18:39:50 -0700 Message-ID: Subject: Re: [LSF/MM/BPF TOPIC] mm documentation To: Mike Rapoport Cc: linux-mm@kvack.org, Matthew Wilcox , Jonathan Corbet Content-Type: text/plain; charset="UTF-8" X-Rspam-User: X-Rspamd-Server: rspam01 X-Rspamd-Queue-Id: EA3A31C000A X-Stat-Signature: m6z79bihdxm7kbca17sdapnb5dbz8s7o X-HE-Tag: 1683855602-117424 X-HE-Meta: U2FsdGVkX19U3c9uMdxvGjy8No+PvNls2JDDEDDeqKp/kOPBx9+GecPjh4//75DaQe0QDzIpE5W8AjYtHSFl+39sUeHM8l55LFzBG/x+Ehn/fiLzTnTK15yvAdAS2ZugqDGKW91UnB1YbTrNusoOpdBZ/YC3H7pNvpi3146KVeH+CcU0yH6Nf30rBWurZ5K0KmQGL+BVA+NSBOmSCvM8eDNDDK6sui3tpqMZt/5OXKK/Y8Vq+fwWAZd/oyMFtDjnBTUsIaqRVkqoXqMx4y1IsXDvfsBQ/K6QxJ2xRbrB0iFZ+8/rarI6mjz3+j7X/55VxiNin8oZJQ/54OMrvgztnXf5hmeDPOFXOMzR06NQ4PEZAOSDoRQ7NgxzsGIWJflGXGw5okV87Hgm8r7vOXPde3BQkw3C503OsoATicxJhZ+XMpTFUECeu4sp4uw55xCmrSztDtb0PeH3PMhbnzyYa8OPDxVxQVQLOwujK9sUTq5mEcQgAN/YMAEYXZCT1PC9aSUSnaJESSu7GlKsBCuJyf1y3EZAdKrbRfHBeBqGGzTTRaKxeL1ksZceqd8lfq2M5n3MVWfrVqKVsXcrcxuEBZ7gNZsgBtxWXVv4HLwGqflVKlyTR9Wtvs+qKCuVs3CL0KIxnnaBt1YmNauqcH73mR5CdtMV8G3Ad6FZI1T0uaGbz/BovjRGymTea1jqNaJwOpLaC69rXiTeeRkjKBqoyrPQ5IKD4H1Ys6XWQOJgFfQwzhhq3hKBpH10EDanRTlNDxdVlVX6h+WYZU+k6yy5EJVno9vZ69gscW3Y/9KctzYFrrqQiSfFtyjucTTn2NL8rIyPl1VyjMv+1JEbyI8PDupDopKqtFE+vR/ACREUh7Q0ypSgmeHjpohxCf1LpCIXIG5dyXzoxZDXVvXvlJd5Sp51Wp1cA6p2zDcutHDfSJwicZfdemUr8JVuJ9WMCU3WchfgDHqO9DRO0b0gMpZ CSbv24qN Hw7kZM35wP8OIGuMF51HwoJQpWcqHakLaW1vbn0NS/i/TJKjnD1NiOFbhL55uDFHCFZ5x5LBQiFuuBUOZahqZfymlyZbC0FYkdn7zSE/uyrG9gR82g95atzbyRWpG+NxTE52694jPK3s8fvbUS06h9Nt+ghVRePuhpg8NDVHyUD3hEshoWQJiMojCNoVJhLv85cCAVEnIsbUXxlKiYW2Oa/K5OWWxCOcM+hzxiuiKnaRTCI0ma0bsXKVt1eCId6Si6R3wHcwWTA+XGGye/aucEPb2jD1VOj3LbtCrDg4Hy+n12a8hgTdOUfGwAYC1dglpucXDb8Rx3X6yHClOVwRdyx2JN3aoUJtY0aYzyURvqbuo/Q/DUwcWk3+nP3qtKG6XPEdHOktq2An8viyZMicg9z7vTrY++V3GKPo4RAJXgwd+xamSNB4sU19UBM7AOSRiYjGdK7T+iPU7eHDukSyFzt6iPA== 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: On Tue, 1 Feb 2022 at 11:03, Mike Rapoport wrote: > > Hi all, > > I'm suggesting this topic for a while now, maybe if we finally get to talk > about it in person something will improve :) > > The mm documentation is, well, not entirely up to date. We can opt for > dropping the outdated parts, which would generate a nice negative > diffstat, but identifying the outdated documentation requires nearly > as much effort as updating it, so I think that making and keeping > the docs up to date would be a better option. > > I'd like to discuss what can be done process-wise to improve the > situation. > > Some points I had in mind: > > * Pay more attention to docs during review > * Set an expectation level for docs accompanying a changeset > * Spend some cycles to review and update the existing docs > * Spend some more cycles to add new documentation > * Participate in programs like Google Season of Docs > > I'd appreciate a discussion about how we can improve the existing memory > management documentation so that a reader can get a coherent view of it, > what are the gaps (although they are too many), and what would be the best > way to close these gaps. > I've been thinking about this since the lsf/mm discussion and wonder whether there might be some way I can contribute portions of the book that _do_ overlap the aims of the mm documentation? Specifically those parts which are descriptive, rather than the parts that are code commentary (which I still consider to be inappropriate for, and orthogonal to, the docs). An example, as Mike pointed out on the relevant thread, is the diagram I made for the vma merge cases [1]. I feel this is quite handy for looking at this code and have used it a lot for my work in this area. There are a number of parts of the book that seem relevant like this. HOWEVER, there are some issues here:- 1. The book is pure LaTeX. Not sure how easy it would be to port any part of it to the mm codebase. 2. I explicitly target v6 out of necessity. Therefore some explanations are simply incorrect for $curr kernel, and others which are accurate right now will be inaccurate as soon as Willy decides to change them :) 3. I don't have the time to put in the effort to port changes to $curr kernel, nor can I stand too much nitpicky review because that'll just hold up the remaining book work. So I wonder whether it would be helpful to provide parts of this work 'as is'? I am sure there are some diagrams at the very least I can provide. I am happy to do so (and accept a GPL/whatever license for those bits). Also, as always, I am happy to send the current WIP book to anybody in MAINTAINERS if they would like to take a look! Relatedly, I am shortly going to be working on the page cache chapter, Willy - I wondered if you would like to take a look when I am done with that? Cheers, Lorenzo [1]:https://ljs.io/merge_cases.png > -- > Sincerely yours, > Mike. >