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 9BD50EE14A4 for ; Wed, 6 Sep 2023 15:04:27 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 33A09440170; Wed, 6 Sep 2023 11:04:27 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 2C255440151; Wed, 6 Sep 2023 11:04:27 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 16386440170; Wed, 6 Sep 2023 11:04:27 -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 007EA440151 for ; Wed, 6 Sep 2023 11:04:26 -0400 (EDT) Received: from smtpin02.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay07.hostedemail.com (Postfix) with ESMTP id AC763160BC6 for ; Wed, 6 Sep 2023 15:04:26 +0000 (UTC) X-FDA: 81206493732.02.2A8641E Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) by imf22.hostedemail.com (Postfix) with ESMTP id 0431FC002E for ; Wed, 6 Sep 2023 15:04:22 +0000 (UTC) Authentication-Results: imf22.hostedemail.com; dkim=pass header.d=infradead.org header.s=casper.20170209 header.b=vp2bRP15; dmarc=none; spf=none (imf22.hostedemail.com: domain of willy@infradead.org has no SPF policy when checking 90.155.50.34) smtp.mailfrom=willy@infradead.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1694012665; 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=groQG1OAW27aukn1St9p3F4vniNu3SS9OKbBgobN+Bs=; b=XxgDP8l16IJ/nmtzgS7xDS5BLSIPEWMuaSkFm6QVZ6Jq1kE8KCAqWCIR292t0WhJImaoKY ZUh0M+9zq71Ec1gW+3OJlY4tIGRCi3VJWPQOGjX5pRNzGZk8q9VR4xP4Nw3Rxi3F3Z4a76 Gf4XtCCvE9V3aTMPiDvMbKjkFBKhj2k= ARC-Authentication-Results: i=1; imf22.hostedemail.com; dkim=pass header.d=infradead.org header.s=casper.20170209 header.b=vp2bRP15; dmarc=none; spf=none (imf22.hostedemail.com: domain of willy@infradead.org has no SPF policy when checking 90.155.50.34) smtp.mailfrom=willy@infradead.org ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1694012665; a=rsa-sha256; cv=none; b=POPux5LCIr4kbGZhEotZhtJpKjcuuZeRFDjd1fLzi5vh5LpTM3hWqTp71vhsykk9QL47RL WMIMiHML3flxx61QUTt1lix0E3QJBP2lHMlI3SF2/BwjTY7Fq0G1oq34ubCne47yUMDkdY 8gNXb7jDS41+paC06ATPTXhmDtmJj8Y= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=casper.20170209; h=In-Reply-To:Content-Type:MIME-Version: References:Message-ID:Subject:Cc:To:From:Date:Sender:Reply-To: Content-Transfer-Encoding:Content-ID:Content-Description; bh=groQG1OAW27aukn1St9p3F4vniNu3SS9OKbBgobN+Bs=; b=vp2bRP15Vy14N+6CcyGS9jmrcP TAXO05O33h8pa0eNO9YWZGsrcXlhOK6MePNEMxsU1EhgjZ/2zsxmIU2keEKBuYR/oNx+80NIWc7Be c3UP6l4nnPxpFoEPfjCG+vw1euWLVIH0mOUH8X9+E2A7YdpgFqvvD5XQA0HYIqc7sia9RKuScx8SH X1Aejmxr14zV7z3SHdaxmlAIVijEYo1Rv89K5afqfBIT60QAYdOCZ8FWxfJF076uYR80/zKKsAAnE haRt6wD6wtSU2S8ch7VHIsx4MAvw767NMktj08KTTbQfNiFzb/qk0+sby8p6sIOZBQnDs4ZWCZr0a S/LrKL/w==; Received: from willy by casper.infradead.org with local (Exim 4.94.2 #2 (Red Hat Linux)) id 1qdu4l-003JhT-NR; Wed, 06 Sep 2023 15:04:15 +0000 Date: Wed, 6 Sep 2023 16:04:15 +0100 From: Matthew Wilcox To: Jonathan Corbet Cc: Mike Rapoport , Andrew Morton , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-mm@kvack.org Subject: Re: [PATCH] docs/mm: Physical Memory: add "Memory map" section Message-ID: References: <20230906074210.3051751-1-rppt@kernel.org> <87ledjgy93.fsf@meer.lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <87ledjgy93.fsf@meer.lwn.net> X-Rspam-User: X-Rspamd-Server: rspam12 X-Rspamd-Queue-Id: 0431FC002E X-Stat-Signature: qoom4koew7r3tru4oobeybyg9ap9bpqd X-HE-Tag: 1694012662-396050 X-HE-Meta: U2FsdGVkX1/58pFWQtCVbTwy0KquSGcFkA/dDO7XcQy9mnXE4GXw8b3zu5Dz1A3592Sbxql4i8qkNFB09pZEv9kt3Zo1SyYKAfm/UbjzaWoHitJVdlyFfjWztXbSbpRu/vk5FLHsWXkB0zOtkJnstxReX2EfS2pNOgGxidJ5/x/ZA1MegFYt9oB/kVhoaqb+POzpqNzBZY7tmk+w5MP5byv6SEN/cmcjtWyVEusSxu46C4UIeXqjEkpr3/hZvFb8xpLWLc3lw3ZLKHI598CqWZgW2fvj4vDLCF3YN0VVX26W/kMPEbHeIjxTZ8VOdIPlY+NHmewenD6zTHnJTsj+FIbeZyAXyHVn2xzwTni8/RPAOlaFKUA1EMY2ZtrLwjAbQjVeYfqTFsVZHHbk/WLvfcV5uEZe3ZKzmrj5UHYRDOntcG4zPqU09LZN5XbuRSOR7+3qDGB1uZy85AtdMh05RzppdztZlXc7+a6xYyfln3ciDP9YOKsnVLw6CTHzIU8D9ZYhmj72/6MeWKlGf9Z+z61uvYoVI1Ip9pOmMZO2uZEUuKFbgZy0sHEphrwHH6XpkUpn9qBR7JUuvjtAzpZTIpDo5O6EMjFoHZU30DnM/XwD2Q77HSqZg190T1y1JE0QSIkGIsV8UcT9Jo4yybihf8BwJedPwvuI+NBH20+XyGfIpn+VHuIYYSAW8zsBJeJJFtFqLVOAdf0/pdFALzAJq7bBCcZy8bfF6BTPrMqW5zQrI0A5NUaOYYYG/uj7A5vNPOy9XjabXWHoNyrSz2QWkE+JLESara/fCytPh+1DImk0KKP2vGmfE3TRoICT/hc+qMucmrQjDzf96/8Gq9assQkACePWKdjPlS54dvWM+bs9ekOrmBpw7Ra7ncXYKiRd1WStDKFmXPC6pyveFozqvcjS2Hm2kr/C13nvLHDNqavH6RHbXDp06rPRUhsmSj/WKKf5YmIe57uI6GS2c02 CrgzJBag S0bOulfA6nnqf8SrIb0+Sr3q2DHd3DRtxwQu4EjLL8dqzXjTgX1l33Itsa6rzkKMlUxQYzXZASWqwc0QFAxuOSTW78nAjfL8h3XLdrYbALoacShtNQfgiRUciQxxcb8R8BlldkqC0lUhJIlY= 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 Wed, Sep 06, 2023 at 08:41:28AM -0600, Jonathan Corbet wrote: > > + All flags are declared in ``include/linux/page-flags.h``. There are a > > + number of macros defined for testing, clearing and setting the flags. Page > > + flags should not be accessed directly, but only using these macros. > > It would sure be nice if we had documentation for what all the flags > mean :) When I figure them out, I'll let you know! > > +``_mapcount`` > > + If the page can be mapped to userspace, encodes the number of times this > > + page is referenced by a page table. > > + Do not use directly, call page_mapcount(). > > Have we figured out what mapcount really means yet? :) Hah! I know what this field means today! In two hours time, I might be less sure! (Does LWN want to come along to that MM meeting and write it up for an article?) > > +``virtual`` > > + Virtual address in the kernel direct map. Will be ``NULL`` for highmem > > + pages. Only defined for some architectures. > > I'd say virtual is absent more often than present anymore, right? > Perhaps it's worth being more explicit about that. And maybe say to use > page_address() rather than accessing it directly? That's something I've been thinking about for the folio kernel-doc. Just stop documenting the things that you "shouldn't use". Non-kernel-doc comments in the source about what you should use instead, but no kernel-doc comments to say "Use page_address() instead of this". > > +For pages on unevictable "LRU list" ``lru`` is overlayed with an anonymous > > +struct containing two fields: > > + > > +``__filler`` > > + A dummy field that must be always even to avoid conflict with compound > > + page encoding. > > Do we care about the constraints on this field's contents? Presumably > that is taken care of somewhere and nobody should mess with it? I also think that documenting here which things are in a union with other things is unnecessary. If someone cares for such a level of detail, they'd better be reading the source code instead of this. Nobody should be using it, better to just leave it undocumented. > > +``mapping`` > > + The file this page belongs to. Can be pagecache or swapcahe. For Oh, actually, no, it can't be swapcache. If the page is in the swapcache, you find its swapcache through swapcache_mapping(). That's because ->mapping is reused as an anon_vma pointer for anon pages. > > + anonymous memory refers to the `struct anon_vma`. > > + See also ``include/linux/page-flags.h`` for ``PAGE_MAPPING_FLAGS`` > > It seems like putting in the types for fields like this would be useful; > readers of the HTML docs can then follow the links and see what is > actually pointed to. > > > +``index`` > > + Page offset within mapping. Overlaps with ``share``. > > + > > +``share`` > > + Share count for fsdax. Overlaps with ``index``. fsdax is not pagecache, so this probably shouldn't be documented here. > I wonder if it might be better to structure it as if the splitting of > struct page were already complete, with a section for each page > descriptor type, even the ones that don't exist as separate entities > yet? Maybe that would make it easier for people to keep it current as > they hack pieces out of struct page? Yes. Although I don't think we quite know what it's all going to look like yet, which makes it challenging to document!