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 X-Spam-Level: X-Spam-Status: No, score=-2.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 696F8C2B9F8 for ; Tue, 25 May 2021 07:04:22 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id E597C6138C for ; Tue, 25 May 2021 07:04:21 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org E597C6138C Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id 901706B006C; Tue, 25 May 2021 03:04:20 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 8D0C26B006E; Tue, 25 May 2021 03:04:20 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 440296B0070; Tue, 25 May 2021 03:04:20 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0153.hostedemail.com [216.40.44.153]) by kanga.kvack.org (Postfix) with ESMTP id 00F436B006C for ; Tue, 25 May 2021 03:04:19 -0400 (EDT) Received: from smtpin18.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay02.hostedemail.com (Postfix) with ESMTP id 74A946135 for ; Tue, 25 May 2021 07:04:19 +0000 (UTC) X-FDA: 78178864638.18.BD0CA37 Received: from mail-vs1-f53.google.com (mail-vs1-f53.google.com [209.85.217.53]) by imf10.hostedemail.com (Postfix) with ESMTP id 8839440002FF for ; Tue, 25 May 2021 07:04:13 +0000 (UTC) Received: by mail-vs1-f53.google.com with SMTP id f11so15549333vst.0 for ; Tue, 25 May 2021 00:04:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=R5qSYI3H+0hKhtur4WubbZFIAqp8tvqJ+a69rLE2/4c=; b=WQXhVd5gnXzCoc3weXSpAu24OZHy68JLoNxpB5SQKazPhOmji1Bo6tceB2begnrEg7 yaKjP4Zk82rmO74yXO0dObcMUvgF83eNzWLR5eOZOO4GkzCMBr1JEMqZf2AqqLQIT9Rd M4Ii/CKo6pE+Nyp6ML3UgyguHvMcHiD9imOitKs2yjkMpLYRIckqRHYipPwIrgopDqFZ Bv+Du75r4rBpIMmSRpmwNsHPEYLp3q+GDettVjehiVeTnDwwMyD/AAC9jyrLlZQ/MGQE dv42BlJwljANRACo27G73zpGSKJPWuIBQZi4fJVA1tn32bHuIMlhOEdnpcePZZZPfqaQ 67xw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=R5qSYI3H+0hKhtur4WubbZFIAqp8tvqJ+a69rLE2/4c=; b=eDAE+wbHMWXianVPxoRnDCHTLnZd8QhU10jTdarKuIKiVj2l0/rKQFOOeD7bEqD8Rj zzVb4c6gfGmtIQNBreWK2Hccmlmi6LtfVIflZzXmMZki1xCbayO3XQxjvXrE5A4P5T67 x2Yow2O06EimYMdWAlX1QwCYQGSAs1QdRKj3KSzyI45DmqcIayBiJoB9CyztA/Z6rs64 WdvigjXnny6ug4XMH3cKesf15mFxd5S/Gd7DpgySB55VBB/5eljx8pAX0OUHNDNhYgEo rz96ksbMgE0V/3ckyPcgkNE7KmpOtMge9hE+QAnXFhq28UKsIzT5uDb/L5c48hVsdvhk oNYw== X-Gm-Message-State: AOAM530CrHOeNG9Q+fvFQrQb6rSwE1NRFSbDndCZPxA+c1+DOKmj2h6G ovRlp/pQh7eYN9uKa9CIi4kXO0TTiWuOvOaBqYA= X-Google-Smtp-Source: ABdhPJxmLCWS+KeqwHpEBEz+DpfNQsoageeB769AOSzYB1qjSvKBtvqwo57xCIPJW5357VwJkaG0297DdNPV4OMkfKM= X-Received: by 2002:a67:7cc7:: with SMTP id x190mr21200522vsc.30.1621926258425; Tue, 25 May 2021 00:04:18 -0700 (PDT) MIME-Version: 1.0 References: In-Reply-To: From: Souptick Joarder Date: Tue, 25 May 2021 12:34:06 +0530 Message-ID: Subject: Re: [LSF/MM TOPIC] mm documentation To: Mike Rapoport Cc: Matthew Wilcox , lsf-pc@lists.linux-foundation.org, Linux-MM Content-Type: text/plain; charset="UTF-8" Authentication-Results: imf10.hostedemail.com; dkim=pass header.d=gmail.com header.s=20161025 header.b=WQXhVd5g; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (imf10.hostedemail.com: domain of jrdrlinux@gmail.com designates 209.85.217.53 as permitted sender) smtp.mailfrom=jrdrlinux@gmail.com X-Stat-Signature: e7exj56mcykywe7hgizbftuodzu71oyb X-Rspamd-Queue-Id: 8839440002FF X-Rspamd-Server: rspam02 X-HE-Tag: 1621926253-228942 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 Fri, May 21, 2021 at 2:06 PM Mike Rapoport wrote: > > On Thu, May 20, 2021 at 03:19:08PM +0100, Matthew Wilcox wrote: > > On Thu, May 20, 2021 at 11:56:09AM +0300, Mike Rapoport wrote: > > > 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 prorams 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 think we have four target audiences for mm documentation, > > > > - Sysadmins/user space programmers who are trying to make their system > > perform well. They need documentation of the > > proc/sys/cmdline/... parameters that the MM pays attention to. > > I'd say this part needs some love. Just a few weeks ago we've discussed how > /proc/meminfo description is outdated and there are more examples. > Besides, this is probably the most important part to keep up to date. > > > - Kernel programmers who are not (and do not wish to be) MM developers. > > Filesystem developers, device driver developers, networking > > developers. They need kernel-doc for our exported functions and > > advice for when to use and not use particular functions/flags. > > - Programmers who want to "get started" in the MM area. They may or > > may not be familiar with Linux internals (perhaps they're moving from > > another kernel, perhaps their experience is with some other part > > of Linux; perhaps they have no experience at all). I think these > > people are probably well served by Mel's book, even if it is a few > > years old now. > > Mel's book is definitely an excellent starting point, but I afraid its age > is starting to show. As it was written mostly about 2.4 with some bits > about 2.6, there are lot of details that are missing in the book. Some are > probably less important because the concept didn't change much (e.g. page > table management), but others have considerable effect on our code (e.g > migration, compaction, THP). IMO, updating Mel's book will be helpful. I thought about it but realized that without guidance I can't make good progress. > > > - Each other. The MM is huge these days, and I certainly don't > > understand how it all interacts with itself. I think we actually do > > a pretty good job of talking to each other and writing commit messages. > > IMHO, there is a fifth group: arch developers. I think it is important to > have documentation of what core mm expects from an architecture and what is > the expected semantics of various low level functions architectures supply. > > > I think it's really the second group where we do the worst job of > > documentation, but I may be biased. It's certainly where I'm focusing > > my documentation efforts. > > I'm not sure it's the worst, but certainly along with the first group it's > the most important part. I am interested to contribute to this if agree to take it forward.