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 A3AF1E7716E for ; Sat, 7 Dec 2024 04:24:12 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id E5A298D0013; Fri, 6 Dec 2024 23:24:11 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id E08718D0011; Fri, 6 Dec 2024 23:24:11 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id CD0B16B0106; Fri, 6 Dec 2024 23:24:11 -0500 (EST) 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 B05636B0101 for ; Fri, 6 Dec 2024 23:24:11 -0500 (EST) Received: from smtpin19.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay07.hostedemail.com (Postfix) with ESMTP id 35A6C160FAC for ; Sat, 7 Dec 2024 04:24:11 +0000 (UTC) X-FDA: 82866869862.19.A3B0A59 Received: from mail-pl1-f173.google.com (mail-pl1-f173.google.com [209.85.214.173]) by imf20.hostedemail.com (Postfix) with ESMTP id 59CB91C0003 for ; Sat, 7 Dec 2024 04:23:50 +0000 (UTC) Authentication-Results: imf20.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=ZugqmCTT; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (imf20.hostedemail.com: domain of akiyks@gmail.com designates 209.85.214.173 as permitted sender) smtp.mailfrom=akiyks@gmail.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1733545432; a=rsa-sha256; cv=none; b=gUkt2yWPRVJqx0m+5AKQGU24uA5akHhhLnKUVi+YEejVZFuj82GGWb4GJ7hEoBhKB5tIGM O++RMEqqG4a2SNKR7YzpBCSL8NpoJUoJ+GwERhFWy7v+s7nr9QBJ+ut28Z2J00O3SAFZNQ X+p4geXhLoMdSFmLiuPDfXqFeDBSr3A= ARC-Authentication-Results: i=1; imf20.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=ZugqmCTT; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (imf20.hostedemail.com: domain of akiyks@gmail.com designates 209.85.214.173 as permitted sender) smtp.mailfrom=akiyks@gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1733545432; 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:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=IYUGdhq/mGb5oiUNzEBADFNnjpGP75R+ldAacHlJ15U=; b=qgcQtyMarq7yqsMq+V9bBCpitZNT55SBvw35Mx2B4yaXlK3xc/R/5DhUQdLpOhdTd+Nc4D A1zcFXBnxD8/qN1NzNB0co+5sq5+YO+TswoXRVUbVGy5AWGWBzceqMMsIWaQE9s4aQysUH cmGMZK3to9o+rwcAWB4dmlo9uHY7RJg= Received: by mail-pl1-f173.google.com with SMTP id d9443c01a7336-215bebfba73so26608885ad.1 for ; Fri, 06 Dec 2024 20:24:09 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1733545448; x=1734150248; darn=kvack.org; h=content-transfer-encoding:in-reply-to:from:content-language:subject :references:cc:to:user-agent:mime-version:date:message-id:from:to:cc :subject:date:message-id:reply-to; bh=IYUGdhq/mGb5oiUNzEBADFNnjpGP75R+ldAacHlJ15U=; b=ZugqmCTTgxGV3ehILG3YQaUM9cPC3wJ2Ap3ke6EdE/EQE+wPd3rCkaDvY1eQFH4YK7 VxtTRcc+2bA+8CEI7imoREzlyyBVGrBQ5aa9dMBO++0R2zZ9hSG7ZlqhIiCsQfb5e7vO DLUfF5jL6MJBPHIwm/q2U9jiL+x+qwlWbi/UgoNbomG+I4aXkLWlOvzrdtSUuUebel+b XsumOPWZtOy+YrIE3j7/XTU+ge9Ckjpe0LoEmTbq7/32gZYEv8nO0sdPSRWOu7H6s6Iq WR6osAj5+BJJLiOxNURGqX5R4y3NyqCFHj4Ube8+97u22ZSAQDQJafwjqCoQl7fqKugC bhIA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1733545448; x=1734150248; h=content-transfer-encoding:in-reply-to:from:content-language:subject :references:cc:to:user-agent:mime-version:date:message-id :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=IYUGdhq/mGb5oiUNzEBADFNnjpGP75R+ldAacHlJ15U=; b=FF0D+H4xwsRuiWegEFSudACrUEyByXm5jklUrNrjA6Im7OYSKhCBLNnTz5XeZ4sHUK uM1lMo98gHtcOV4uzPYbpouYE2HIZNCxXnFmdTyFqeK8UTIUzoryDaa5q/1DMut3DmTp U56mzB6eVi2I/ZdaGt7ewYRPTbHBvCKVg0F+D+PbNszupUpedCwZGUySY5ZOatDOIfiu h6a8r58ZIJrM+H9WoIo9kXJEP1SUvnySaG9wmaLRYbSlGDrfQDcnR9ZeONV6qqGj4XLS SMjI2C1E0TAFT4PHcb/b1a2Nt4NO34jXBdQe3oBHCFLvG4acT437UFxWQOTUOWunUu3S 6ISA== X-Forwarded-Encrypted: i=1; AJvYcCUgcflUgloZOMe1Y6B5FTjPCPPKzBo8LAyHI0y9AXIASqIBq+UpuZWbysF+yfaUrQl/GJwVtQP5KQ==@kvack.org X-Gm-Message-State: AOJu0YwyahiDQOdlJ2vJdpat/960IUbNB1uvFo0za18Y2LvjGDPWEzrd KYRsG5q34sr6HkTV3Y6fatq2znwR8EfEXtltpAZGTEvMDhzYostP X-Gm-Gg: ASbGncveUICpg8mBLxiOASiA3+95BqDlJeCx/VxEjDY3x+YRsngvYpcNuusPr4Ayr6Y qC3ccifAM0sWUsv77jcLcKO9kUwWkY8Q5cpJmcVxs2i9q5Q+8kSyudxcKeUNkDOJIXQjLxzjUlw AkcWiTpxa2njgVSMq2hSCJBU2+byqE2DhDXhWRUPBtIDz5TQ8TgM04agkWFP+UbEDSWYlWVz5xN L7zl5gmerBPLPLAhxTyrhga+MGXNUQ9AzeUAOawlnt+UQcXGZme3X3FdFJY6DOptiNB4I7N9XwQ 3I4AyNYj9nPodJVx X-Google-Smtp-Source: AGHT+IGMGpaA90GHEQ6E0t84HtFzEX9s6mfNRK1/lHN0kH62/PnZ68jZEVHeyllrAP8z4UXqOgvqdg== X-Received: by 2002:a17:902:ccc4:b0:215:6c9a:15 with SMTP id d9443c01a7336-21614dc52b5mr77649245ad.42.1733545447904; Fri, 06 Dec 2024 20:24:07 -0800 (PST) Received: from [10.0.2.15] (KD106167137155.ppp-bb.dion.ne.jp. [106.167.137.155]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-215f8e5f24esm36224995ad.83.2024.12.06.20.24.01 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Fri, 06 Dec 2024 20:24:07 -0800 (PST) Message-ID: Date: Sat, 7 Dec 2024 13:24:00 +0900 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird To: rdunlap@infradead.org, surenb@google.com Cc: akpm@linux-foundation.org, brauner@kernel.org, corbet@lwn.net, dave@stgolabs.net, david@redhat.com, dhowells@redhat.com, hannes@cmpxchg.org, hdanton@sina.com, hughd@google.com, jannh@google.com, kernel-team@android.com, liam.howlett@oracle.com, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-mm@kvack.org, lorenzo.stoakes@oracle.com, mgorman@techsingularity.net, mhocko@suse.com, minchan@google.com, mjguzik@gmail.com, oleg@redhat.com, oliver.sang@intel.com, pasha.tatashin@soleen.com, paulmck@kernel.org, peterx@redhat.com, shakeel.butt@linux.dev, souravpanda@google.com, vbabka@suse.cz, willy@infradead.org References: <9baeaab7-61d8-4121-8aa5-cf1c129daa40@infradead.org> Subject: Re: [PATCH v5 6/6] docs/mm: document latest changes to vm_lock Content-Language: en-US From: Akira Yokosawa In-Reply-To: <9baeaab7-61d8-4121-8aa5-cf1c129daa40@infradead.org> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Rspamd-Server: rspam04 X-Rspamd-Queue-Id: 59CB91C0003 X-Stat-Signature: j5148knzsn88a3bm6oc6qz5pt7b7zjxw X-Rspam-User: X-HE-Tag: 1733545430-825708 X-HE-Meta: U2FsdGVkX19+UrRRzVjTY2kNKP6mcA3/9QgxveqH8FThBbx3k5GEr3uJbH0u3LRzD3Ptfk9m0d1Iba/CAPvM+HqU738BRQcPayofzK5b0p/dy3NOpCTXveO+Nw6x4WadtOMFm9Z/VbSwy//aXuRF19hesmXR6B9C/d3itkk0eLbdt2RaS2lPaTJRMQI0ZRwHCsX/7eqsuncrjc/lgWbQBxi4K/yYew0o52pHeoZTH8CqVZ3H/VI2fxUyIJ9B/h6R8rk9bMtznJkvYJ1Oq1Oii1e9MZ4F2ZTIEWXl74uI7TtpJCmAFuM0Uy7VbKQcSsqBcioLG7Jf6D+6BOuB9v2Ezt19bON8tIE+QzSdPDua1veReblUmG8RaMXy7cEAOPUWR2Sy30oNikraBYNjyHN+0YyMN6vZQhB6DUHA6GZlzI3rJHYINQztdlGybI5EMyxOvYjvmPAcn6X4jobV63dDPVJHs3BYW/yaDPhXG8c9O7F4G3Tei/kkOkzzW/zQIE8GiNVM3gWteLE/NXmN+od3WdIL6NW3O9yiGRlDCtFiZIBTVFWmFWM7hibPb7IPC1z466cIRVYiuJOGn3IpvjqEuqd2pEyv22F6/piAc4uq5mu8560t4/gUjcn19hiMK0CaDnzu4gkIIIHNT2NjF2gNign5hzVGRHPUWjfy80MYiEE+O8DPAFPFPQCRK1xbXYxc1AdfhSU2/QEnxQqmpPQFc7M+4UslJfMa+Mw6GF7Lyu5Gr+35Ej+5aT2O7ZCuJPaHjy2UsQc7lOcdevV+qH2r7PFixLRXcYv5G5wWvp/b+vnIImBRuB5GawJqCtmt1jSMjC/Yvi5LLKAq2gEPt0HRroVzwQO3kwkmOoVpHWcZz/Nmw2NcZb0UU7JVszpLU8zxJnIhcBCohCYZe0V9tkVBeM4SnkmVoqA+hyCtUYumxfrTDI23LSNgHAGT/1Sgq+/b6EiTJzTg/RmjCgfINTL oZyGBk2r iur/9nRsPV9EJktoP/66oVH1DR21DofX0sGV7EdlAXQ/N6mn9kyxaQZh7zTqt2l5T3qe5GtmHzD0ptTnIT3+nahw/ELR2b9mriXRpHjksF+bXyzjnGz5U6l3XEp99ah6JRkl3Vfg1YN/Eu/z4fyQ3QiwKmRNouCeHF4x1HMM8wJgFkKc0LAYGNy7aLAeTzvT7x+HOpQxD5L1OZACY2xfRmaVxGgVPRhOW+B3o7MUfZamWsacCzV/bIw3FH/MYqdsfD7NRyFZCXV7EKv//w4y7iTGeMwS4veik/I18bZZ6eU0TKjtV/+FV186V6sLhR3Qnj5BKvlm1VamqdKMy7192QXcmE7HSEnccJv1q9yMATIRtMDaCPtEEwkJf8D/gXByuAXS9ImKBlMs5+HaIJB89RbU/NvM7SeguDWxuwUcmQ12X1MWhB4GjcTiSmLymJlJvxSt6DPINNXY5mF1kSMli4O0CBmUVqZdSks5rW7jC2sm5iHIH1MOGaP+dXxaYYRLp+yT85hzRyLBnQf5wqP6cmG3+siTnp0+OviDaTHCzlL1Q5e1KeGclCPPqLK8LxF9DwXcwAzPSj0gObKI= X-Bogosity: Ham, tests=bogofilter, spamicity=0.007010, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: On Fri, 6 Dec 2024 19:23:59 -0800, Randy Dunlap wrote: > Hi, > > Can someone explain what the (consistent) usage of '!' does in this file? > This is the only file in Documentation/ that uses this syntax. > > > E.g.: > >> diff --git a/Documentation/mm/process_addrs.rst b/Documentation/mm/process_addrs.rst >> index 81417fa2ed20..92cf497a9e3c 100644 >> --- a/Documentation/mm/process_addrs.rst >> +++ b/Documentation/mm/process_addrs.rst >> @@ -716,7 +716,11 @@ calls :c:func:`!rcu_read_lock` to ensure that the VMA is looked up in an RCU >> critical section, then attempts to VMA lock it via :c:func:`!vma_start_read`, >> before releasing the RCU lock via :c:func:`!rcu_read_unlock`. >> >> -VMA read locks hold the read lock on the :c:member:`!vma->vm_lock` semaphore for >> +In cases when the user already holds mmap read lock, :c:func:`!vma_start_read_locked` >> +and :c:func:`!vma_start_read_locked_nested` can be used. These functions always >> +succeed in acquiring VMA read lock. > Quoting from https://www.sphinx-doc.org/en/master/usage/referencing.html#syntax * Suppressed link: Prefixing with an exclamation mark (!) prevents the creation of a link but otherwise keeps the visual output of the role. For example, writing :py:func:`!target` displays target(), with no link generated. This is helpful for cases in which the link target does not exist; e.g. changelog entries that describe removed functionality, or third-party libraries that don’t support intersphinx. Suppressing the link prevents warnings in nitpicky mode. But in kernel documentation, there is a preferred alternative. Referencing by function names is the way to go. For example: calls rcu_read_lock() to ensure that the VMA is looked up in an RCU critical section, then attempts to VMA lock it via vma_start_read(), before releasing the RCU lock via rcu_read_unlock(). In cases when the user already holds mmap read lock, vma_start_read_locked() and vma_start_read_locked_nested() can be used. These functions always succeed in acquiring VMA read lock. They work regardless of link target's existence. Kernel-specific Sphinx extension named "automarkup" does conversions for you. HTH, Akira > thanks. > -- > ~Randy