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=-6.4 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,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 D00B9C433ED for ; Fri, 21 May 2021 08:36:20 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id 65EC461363 for ; Fri, 21 May 2021 08:36:20 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 65EC461363 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id E9CB68E0026; Fri, 21 May 2021 04:36:19 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id E254C8E0022; Fri, 21 May 2021 04:36:19 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id CC64D8E0026; Fri, 21 May 2021 04:36:19 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0182.hostedemail.com [216.40.44.182]) by kanga.kvack.org (Postfix) with ESMTP id 981A18E0022 for ; Fri, 21 May 2021 04:36:19 -0400 (EDT) Received: from smtpin20.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay02.hostedemail.com (Postfix) with ESMTP id 3056AC5A0 for ; Fri, 21 May 2021 08:36:19 +0000 (UTC) X-FDA: 78164581278.20.BF6FF6E Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by imf03.hostedemail.com (Postfix) with ESMTP id 7529EC0042E7 for ; Fri, 21 May 2021 08:36:16 +0000 (UTC) Received: by mail.kernel.org (Postfix) with ESMTPSA id B539061057; Fri, 21 May 2021 08:36:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1621586177; bh=WnbmDngFmIVGygLdgmAhgYLnaYcGhEuI/ubqB73Fn/Y=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=UklVLRejCZgJPSIPVE+1kclw/R8OoY2OEIk4PR2Ya9wjuMBNdwjnzoONYc0opWIur AQlnDeyjzf3uVYKgquiqsa6FRUyp6hWGAEiBl1sBVHhMk155YLbzY9tuVtbNIHfe8c sSbNfHdJuPrj95bML+4gmbPaDmGpg0BKssyX2yuTrUmWLfBJNUJ+WBhXsmdVMYdvDP GtehouExfyP9110bpYYkUs8Ld/Bc9hEuut5OP1hP1Dzsz90eJ87TnclxMwjFtZE3Sa y//fOe61QgAyPizsBvZn48FFdN1TASvA5fU11oDB7n0qnzPMjdbnl8ULGxzXNcF6uf mhiVnimVTvEHg== Date: Fri, 21 May 2021 11:36:11 +0300 From: Mike Rapoport To: Matthew Wilcox Cc: lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org Subject: Re: [LSF/MM TOPIC] mm documentation Message-ID: References: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: Authentication-Results: imf03.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=UklVLRej; dmarc=pass (policy=none) header.from=kernel.org; spf=pass (imf03.hostedemail.com: domain of rppt@kernel.org designates 198.145.29.99 as permitted sender) smtp.mailfrom=rppt@kernel.org X-Stat-Signature: dkpa69kszsgex3u999uzwmh1gri41det X-Rspamd-Queue-Id: 7529EC0042E7 X-Rspamd-Server: rspam02 X-HE-Tag: 1621586176-268285 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 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). > - 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. -- Sincerely yours, Mike.