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 A0163C0015E for ; Tue, 15 Aug 2023 21:03:12 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 2B6CE940031; Tue, 15 Aug 2023 17:03:12 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 266AA8D0001; Tue, 15 Aug 2023 17:03:12 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 12E79940031; Tue, 15 Aug 2023 17:03:12 -0400 (EDT) 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 02EF98D0001 for ; Tue, 15 Aug 2023 17:03:12 -0400 (EDT) Received: from smtpin11.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay07.hostedemail.com (Postfix) with ESMTP id C7C9C160390 for ; Tue, 15 Aug 2023 21:03:11 +0000 (UTC) X-FDA: 81127564182.11.71378D5 Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) by imf09.hostedemail.com (Postfix) with ESMTP id 7F638140019 for ; Tue, 15 Aug 2023 21:03:09 +0000 (UTC) Authentication-Results: imf09.hostedemail.com; dkim=pass header.d=infradead.org header.s=casper.20170209 header.b=t7INgrVD; spf=none (imf09.hostedemail.com: domain of willy@infradead.org has no SPF policy when checking 90.155.50.34) smtp.mailfrom=willy@infradead.org; dmarc=none ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1692133390; a=rsa-sha256; cv=none; b=ziBm/GHL4EldtwaJ6skHax0hTlHns1w+qnQMRK/SJ1XszuyfKjJBuKG/KbAB88fvh0cwCd 6Zgj926jkBMNW4Sl4X/L/4WV5kerTbSWfDwBgSX/LXLvOWElphom5F607hc4iQSNjzYdwe hhbiViy8K3jdScN1bdD9WWkmHetdj1I= ARC-Authentication-Results: i=1; imf09.hostedemail.com; dkim=pass header.d=infradead.org header.s=casper.20170209 header.b=t7INgrVD; spf=none (imf09.hostedemail.com: domain of willy@infradead.org has no SPF policy when checking 90.155.50.34) smtp.mailfrom=willy@infradead.org; dmarc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1692133390; 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=LL1KvLzHhFBkD9AIgyLeOWRCgKApYsdyPiFaKvkG4Kw=; b=N03XIgHyRaAtL7jvXHevL5Tti12EwxXoR4mCjJCCjMrZLKfMCdXr/PNpEqRizE6ftVNh5A LZcVX0lrtx1WHHUnuaNPRiNslSZsutGxSWFfrFL9MyetAj1IYRO+AHORfobeJ1lMUIDw96 QdgM1vAe/dACwn9nsZBTu/Mqi005iF8= 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=LL1KvLzHhFBkD9AIgyLeOWRCgKApYsdyPiFaKvkG4Kw=; b=t7INgrVDxYvVPkKl8NvNusUivq +mjmtqF3WuGWK5tAOOlooiiXAIDjJbWuQ7yLCFc/omenuUj0QyEVTWOH9Ic8nDFDOCM1IT6jP4Etm /28k3tRPfvfELDoKX6eMxyfJKsP4Am8Cnq5SISHsUA5qPUjECYEkMqomdPk+8RdpJoG7c9QL8pEN7 T1CWO3QyP7Nh1Dw1kxjf+5yPkQPbipvz+arnhiuhS+CPX6HWc7YuGkHXZuRtCN1dosoWxUqzbvTu9 gnkv8PCBbiGrEusBOF2jEXME65osBRUw1Xd+/tBDlaArzPCs+z6lG5+8hgWCWWvzDbXLwLk3x1WRN u+rUk5JQ==; Received: from willy by casper.infradead.org with local (Exim 4.94.2 #2 (Red Hat Linux)) id 1qW1Bs-00AQJq-Th; Tue, 15 Aug 2023 21:03:00 +0000 Date: Tue, 15 Aug 2023 22:03:00 +0100 From: Matthew Wilcox To: Peter Xu Cc: linux-mm@kvack.org, linux-kernel@vger.kernel.org, Mike Kravetz , David Hildenbrand , Andrew Morton , Yu Zhao , Ryan Roberts , Yang Shi , Hugh Dickins , "Kirill A . Shutemov" Subject: Re: [PATCH RFC v2 0/3] mm: Properly document tail pages for a folio Message-ID: References: <20230814184411.330496-1-peterx@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Rspamd-Server: rspam08 X-Rspamd-Queue-Id: 7F638140019 X-Stat-Signature: skeyka5pm7jb39yh6crp8aoby8pp7b1o X-Rspam-User: X-HE-Tag: 1692133389-838029 X-HE-Meta: U2FsdGVkX18JbxDxD9WFIyWCiCBay9jNkDMqTf8O7gFwuVgp/avVyibqzxPIo5rGjHCAf5nDaQLaalLv5GC5wHUs0w+2T25RfOr3U1kOOMIxh3bOL9JDIkKD6WX8r49QEMlzJoDTfSe7wxUeXu8/uYJbPYI7KCfCbUKIOQ82pJVhID6boeeJkpqdN+DgTx3XwGpVG0Gq5gm4pGsIpOrlUbwTwrqhYQjUtDGO7AzYDuiPo54+T1CwTQ8FRXAA9Zt90YVJjvLpbQuu6yqpjhCtU3hqjwKTS6rJ7h1Mtl7M7nZr/LeChaoeQBZQSqdVgmiFSvrtN11OARf3U60YkoGNq/SFh0OCgxg0ziLUq4AZuKLISx6jTr4Rb+J/rnvbsbgt7z0pCpQPLbo198QrYOjDSfqCIKZfztk8efanpdykNcVlhvYL9M8aVHmvmxNSxgyG+gIt9RcYP2k7COWQDEPn2ZvnYjOfVwIUzOehmWaGu2ZPubUY4xsAL0J1LQTrjjBjdFvCR9s98mFvwwR1w/3jciTNesNS11lehsdhK82nBijHpK1AQpTas7qtRwYcgqK3oMAFouExj1pbXtn9BrhKGD0KLlKMTuUtdNc03FfV9EBGe7jTY7EqiZvGgnF1k+uiBvDDRZ68Wk+tjRBI7PN3OkiyYoXi33MA4jB+QMG0eBWDUUQq6WStvVzvGHbEMleDGlCq5wKEFN0JtLZcXTXyoFI8sudaceiOH8IqVeed9QP+WzVdyFL/4c9G51MaMfXbOYWTomJY1NWa6tCACDYC0rmnn5btQ67LKdKoQ2p12/73+ZMoMUrrarfYqDIPHcTyN/fLMLEmeRD2Tm6TdWhAqAUTSBFJLGxC9CtkVIX+sr6IGYDHop6X6LHdAHa/Ry4HfrkFVCYlESXnWIHovasN5enqR2w45Q7Y3LFuaQy+MLW6nhimSk1TcQMm3we0BB9sgCtp09b+0WrKp1rqi03 GUuh/aKr F7nM85UXGzNRS6Cq2h3sVtOJuKZi5zqMIaGnin+ooOE+LKupIQzocpLUnjg7QU/id+zrVkTERu8+3P3flpWhcrqnw/QHS6J2ec41eOOSrfZ7SeJ6VNxxvY6dSEayIS7eI1yOuGdELzvzfllE= 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, Aug 15, 2023 at 04:39:16PM -0400, Peter Xu wrote: > On Tue, Aug 15, 2023 at 09:16:47PM +0100, Matthew Wilcox wrote: > > No, sometimes there are things which shouldn't be documented because they > > don't matter, and when changing code sometimes we forget to change the > > documentation, and then people read the documentation which is different > > from the code, and they get confused. > > > > It matters that the various 'private' members line up. It matters > > that folio->index matches page->index. It does not matter what > > offset _entire_mapcount is at. That can be moved around freely and no > > documentation needs to be changed. > > > > I don't want you to use FOLIO_MATCH to make any unnecessary assertions. > > The only assertion missing is for _private_1 and _private_2a, and that's > > why I wrote a patch to add them. > > I didn't mean to add assertions for _entire_mapcount (I don't even know > how..), but _mapcount and _refcount to clamp the fields, then all fields > can be clear, just like head/flags clamping the start of fields. Ah! mapcount does make sense, yes. We could just put a /* no more space here */ comment in, but an assert works too. > One thing I can understand that you'd like to avoid these "offset" things > is perhaps because you keep that in mind to, one day, have mmdesc replacing > folio so folio doesn't need to match struct page at all some day, > ideally. The order of fields, size of fields, etc. none of them should > matter, when it comes, and we should go toward that. However my argument > would be that, before that day comes IMHO we need some good documentation > for us to know how the fields look like now, why they worked, and how to > reuse new fields.. when that comes, we can just safely remove these > documentations. > > It's just that these 'offset's still matter and matters a lot now, imho, > but it's very confusing when read without some help. No, that's not why I'm opposed to them. I'm opposed to over-documenting things, as I just outlined. Documentation is necessary and good for all kinds of reasons, but it should be meaningful and not prone to rot. If there's a tool that can tell you something, there's no point in documenting it; that's why I pointed you towards pahole. I also like "documentation" which is checked by the compiler, hence the existence of the FOLIO_MATCH macro which documents that the two structures line up, and the compiler checks that they do. FOLIO_MATCH even caught a bug! > Let me try one more time to see how you think about it on an rfcv3. If > that still doesn't get any form of ack from you, I'll put this aside. At least we've got to something that I like the idea of ;-)