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 9C977C5AE59 for ; Tue, 3 Jun 2025 14:08:27 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 3ADB06B0477; Tue, 3 Jun 2025 10:08:27 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 35ED96B0478; Tue, 3 Jun 2025 10:08:27 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 275DA6B0479; Tue, 3 Jun 2025 10:08:27 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0011.hostedemail.com [216.40.44.11]) by kanga.kvack.org (Postfix) with ESMTP id 063656B0477 for ; Tue, 3 Jun 2025 10:08:27 -0400 (EDT) Received: from smtpin11.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay09.hostedemail.com (Postfix) with ESMTP id B6BC580B1C for ; Tue, 3 Jun 2025 14:08:26 +0000 (UTC) X-FDA: 83514269412.11.02248BA Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by imf24.hostedemail.com (Postfix) with ESMTP id F2F17180025 for ; Tue, 3 Jun 2025 14:08:24 +0000 (UTC) Authentication-Results: imf24.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b=AuUCoHVF; spf=pass (imf24.hostedemail.com: domain of corbet@lwn.net designates 45.79.88.28 as permitted sender) smtp.mailfrom=corbet@lwn.net; dmarc=pass (policy=none) header.from=lwn.net ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1748959705; 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=kPV8PzmODhGoCbC5F8Uzo9NG4JabbIz25OZ6D+Zy0Y0=; b=utpCN4wdvTXifeVyCbxjjDkzl/3IVi3aiAsQcbNzkuT9LSrERJSz3fNKWB5oVmogUkIKBH O/s0HjPKUZVWiV7VW6ybFg1/ysfHPFneecx97t+mCtmlQhDONcdG5Ax8EEiZhN4hHla+rK TwPRc3ss7fFEVQE7/6u+fQ04C2lfN88= ARC-Authentication-Results: i=1; imf24.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b=AuUCoHVF; spf=pass (imf24.hostedemail.com: domain of corbet@lwn.net designates 45.79.88.28 as permitted sender) smtp.mailfrom=corbet@lwn.net; dmarc=pass (policy=none) header.from=lwn.net ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1748959705; a=rsa-sha256; cv=none; b=DXtMQkI0PBE32NBwbHvTUobZVToADFBTUtpBjEHVr/fFsAmoLguwwHges6yoU6NUQxMNp8 se4ugf3JUcpcLdF6pDQxy5p/tSH02xLhIrnY6gq09/NaBvlMbQyAx1CJLp2e+lWzEWMzaJ GkRUvvZXmHcbcqoMr7oJ12vBXBK14c8= DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 00F8241ED0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1748959703; bh=kPV8PzmODhGoCbC5F8Uzo9NG4JabbIz25OZ6D+Zy0Y0=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=AuUCoHVFyP/+6UWarP9xJqL7C2WXKUBUpyIAN0K4+AG0tawllQExHgh2sRNEpcEuR 6s4Ttz3NjxVz42xza4rj5t/zXrJIUqVOyRGhRBzKZE7OPMyQMaMqwAp7aQNZ67azwX 9SqQj/7Z80bRxCRiX8xwXhtQYKBA0zaDvOkn7F/bA73Hre/11vG5oGssvzxui9xXlQ 5zQB2rgfcezVs+0CLAHJ4jUVooRvD/FrIPpjkcGwwUDpkUPwkQG0d8p5WiH05MwhP+ M565Ol68KibHzRpc1nXPqpjWFvsr+b9tBjWPHOexXBdAYTpTboiEMNzBtNwUHcFA8b 9ir1HmuW1S2IA== Received: from localhost (unknown [IPv6:2601:280:4600:2da9::1fe]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id 00F8241ED0; Tue, 3 Jun 2025 14:08:22 +0000 (UTC) From: Jonathan Corbet To: Lorenzo Stoakes Cc: Andrew Morton , Suren Baghdasaryan , "Liam R . Howlett" , Vlastimil Babka , Shakeel Butt , Jann Horn , Qi Zheng , linux-mm@kvack.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH] docs/mm: expand vma doc to highlight pte freeing, non-vma traversal In-Reply-To: <9fc9ac50-abce-48bd-979f-2e00b26917b5@lucifer.local> References: <20250602210710.106159-1-lorenzo.stoakes@oracle.com> <87bjr59634.fsf@trenco.lwn.net> <9fc9ac50-abce-48bd-979f-2e00b26917b5@lucifer.local> Date: Tue, 03 Jun 2025 08:08:22 -0600 Message-ID: <8734cg9auh.fsf@trenco.lwn.net> MIME-Version: 1.0 Content-Type: text/plain X-Rspamd-Queue-Id: F2F17180025 X-Stat-Signature: 7h3trdhxieozc49s3w3pdbnb93guecsi X-Rspam-User: X-Rspamd-Server: rspam04 X-HE-Tag: 1748959704-109344 X-HE-Meta: U2FsdGVkX1/7POPgZpk6M+x2UqxOsMv0qXgt6sLI8kX2RgNoAbbJgwUgc23pkPQNYDoGl4KY/YTlvdHfu1CCaHvhXQwEwtrqNQa0i/WWpovG6HYBnEVuqhoRmAbWBpS0a6mFDta1khjaaUEANKwEGR45KFWx3tgwtu1/a+S1CNo7QelPxnAmQxKaFhEkRn3P2OiaYrysRE2saKzip9WsgsOJNr1CnIc8RjCnhvVA3lp6AwUjxe6FAtLIRv5OHBPK4C7uGJY5Uw7bl/mA0/i5WraGl/g45ADov34VNmtL413UsysJY+Y7t38o5wMNfLWlaRTIpS25pierXjVzmbicNSY8b3GfzUo2I5slI9Qww5jnwhPqiy2nGDwopurYFBJqGy7Bb7Qc1ruXrCPGEPCDxgofu5JXLZjcLUZK3SscyaWUayBeTl0LAYSb3oAaqgxmsEUMB+tanXMuw7GSIH47pF8lW9il+9Ed+BaH5VeazX4Vg/2qpSyfX38syijLxWVQuRjHA6eKo7sPEwwtUnr5Dq6dK4gG9fyE7Yc7AkYn4vWw4Hm3R495F2U8bSHee0HGONiCBv8a2v1Z3RG6cLsRsVXe2qLutOUaUdtw7SV+9zvIq0p6+mxxaPv674vrup3UWt3AZ2PweYNu0/7aNS+9LMl/+24VoC3B757yFEZRjbzT0hiUjaYXHsnWuEB00rrJ35kpn9B1mdEQ1uapqa/CtI8warva1tVncWiFED2raeGIAPgZBojaK2/6KEwD1iwa+abaAaw6xSjH1jweYV0VLXXMWA2BHFLVegTRVoeqXieN7eZ7ABMfdoTIsVH30/LjnfzLzeONuWDA9pqOoO1mpqnQpEddbm6B7pi3YGgCiGoe+N19z9Td7cthot0NgzON0o+KmZX3xTkNDtaB959zmG3tENRzZWXIe26tnKBQ4Auqp/AiaiNuettGKaBS1f44LgxDBkXqibfkdbOpZiv rWht1JxS wVJFJsMXjQJCvOF+3OfMU932+EGim+h5ey0Orh/x+lrB5JatSD8mQ1mwcltTfxBHBAmLX6Ass6iuKw/8UzQXX+R8nT1FkADxF2COneRSCjTayolmB00S/2ioj62ePW70/6KlMOu5PqZbiTH2AuxiqMbWyIO4fuIOPSbM9e/sfvko8v3VJzjWVbwXQj7ts58iYB9Yp7c+zmeyBRDN5GBt7Sf8zqc/amxeuu2xkXDCF3+T4buJKpG3iDZVJz2534hg33ziVS0bliGidU3bzuEyugWAJsupZOF/z8JKfTDfKRtv1nhjvTAAXrKX+mA== 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: List-Subscribe: List-Unsubscribe: Lorenzo Stoakes writes: > On Mon, Jun 02, 2025 at 03:38:55PM -0600, Jonathan Corbet wrote: >> Lorenzo Stoakes writes: >> >> > --- a/Documentation/mm/process_addrs.rst >> > +++ b/Documentation/mm/process_addrs.rst >> > @@ -303,7 +303,9 @@ There are four key operations typically performed on page tables: >> > 1. **Traversing** page tables - Simply reading page tables in order to traverse >> > them. This only requires that the VMA is kept stable, so a lock which >> > establishes this suffices for traversal (there are also lockless variants >> > - which eliminate even this requirement, such as :c:func:`!gup_fast`). >> > + which eliminate even this requirement, such as :c:func:`!gup_fast`). There is >> > + also a special case of page table traversal for non-VMA regions which we >> >> The "!gup_fast" caught my attention - I was unaware that Sphinx had such >> a thing. Its purpose would be to appear to suppress the generation of the >> link that turns the cross reference into a cross reference. >> >> The MM docs are full of these, do we know why? > > Removing it from the struct vm_area_struct struct immediately give: > > /home/lorenzo/kerndev/kernels/mm/Documentation/mm/process_addrs.rst:11: WARNING: Unparseable C cross-reference: 'struct vm_area_struct' > Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6] > struct vm_area_struct > > And given C's weirdness with typing I really prefer to be explicit in > referencing a struct vs. e.g. a typedef. That's because the :c:struct: markup doesn't want the word "struct" in there. In this case, the "!" is being used, essentially, to hide the fact that the Sphinx markup is being entirely misused here. You would be far better off just saying: **struct vm_area_struct** and avoiding the uglier markup in this case. Once again, taking out the markup entirely will cause the automarkup code to do the right thing, with the proviso that undocumented structures (which, tragically, includes struct vm_area_struct) won't be marked up in the current implementation. By far the best solution here is to remove all of the markup and add a kerneldoc comment for this rather important structure. > At any rate I'm not sure it's all that useful to cross-reference these? Why would you *not* want to cross-reference something and make life easier for your reader? Thanks, jon