Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Tue, 13 Jun 2023 12:37:20 -0700
From:   Ira Weiny <ira.weiny@intel.com>
To:     "Fabio M. De Francesco" <fmdefrancesco@gmail.com>,
        Jonathan Corbet <corbet@lwn.net>,
        Andrew Morton <akpm@linux-foundation.org>,
        "Mike Rapoport (IBM)" <rppt@kernel.org>,
        Ira Weiny <ira.weiny@intel.com>,
        Deming Wang <wangdeming@inspur.com>,
        <linux-doc@vger.kernel.org>, <linux-kernel@vger.kernel.org>
CC:     Catalin Marinas <catalin.marinas@arm.com>,
        Matthew Wilcox <willy@infradead.org>,
        Mike Rapoport <rppt@linux.ibm.com>,
        "Peter Collingbourne" <pcc@google.com>,
        Peter Zijlstra <peterz@infradead.org>,
        Sebastian Andrzej Siewior <bigeasy@linutronix.de>,
        Thomas Gleixner <tglx@linutronix.de>,
        Vlastimil Babka <vbabka@suse.cz>, Will Deacon <will@kernel.org>
Subject: Re: [PATCH] Documentation/mm: Add kmap_local_folio() to Temporary
 Virt. Mappings
Message-ID: <6488c5706b99b_1ad8992949@iweiny-mobl.notmuch>
References: <20230609030908.31373-1-fmdefrancesco@gmail.com>
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
In-Reply-To: <20230609030908.31373-1-fmdefrancesco@gmail.com>
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?xFNbHszEAO03uslS8tCUbOBanvHmlLPA28i/T1Xb0MN3Iweb+iBlSd32rl1+?=
 =?us-ascii?Q?MjEUZAqn0j6+dx/ChGLnzfRIdQnmMbtkOfeHo+7OtAFUqm3M5KgUuZ3ag1/+?=
 =?us-ascii?Q?0Qh5+w2fQ9cjS9FMw3DOBN/ntyjWNOImC7otCOE3PFH9fGFZdxlmxhOnFbhI?=
 =?us-ascii?Q?rXHLzfzJp56XifcmGk5uE91CCalyy2eiR8QqGFWFp9OLYoa9UR2ELKmxd/nv?=
 =?us-ascii?Q?KcHP4XgwDrvx1jS+fWfYIkZ2FTHhcDec25lyIHNDQVLWdk95zJhFXPItmY8c?=
 =?us-ascii?Q?dHEfCo2AQixxPneSIVVtZz5pMJy/NE5OJRJj+pz4vUiWczv9p2eMgJPI6Ors?=
 =?us-ascii?Q?r/JBr7dcQgou4zuSIBaG/byMtqMZqrB2tagQLbhzSgvyRRhvETRZim5OwJfH?=
 =?us-ascii?Q?HfM+e8Ki3455I4+g6COV3w0ltW5hg4aZJn/W+0FCTO/Elo7qh57EXsuPXhzg?=
 =?us-ascii?Q?Isu9TQLQMKjIRgSyFKQMl6VETJCEqg9QN7QD1Y9An/BS+UxRj9gfw5o4zT1o?=
 =?us-ascii?Q?xwYd9erqMvWYJqD+rhZz1apr0Mvb/EtB2eK6Gy9jGRBDHHQ4nUqNcmG3IMiS?=
 =?us-ascii?Q?EUxJt8RzUyRQ0YM4s4xIrLlg+UsG/o+GVbH47F7ena/N8HC0KuePlHe+0fBu?=
 =?us-ascii?Q?Vhn53RHniTA4Z0Zs4Mjh/mg+hnS4HA+y/hPdou/Km9DV7Vi/e+6X1mTRpZQW?=
 =?us-ascii?Q?7IWZY1a9r3Kq6eJ4wdNQJwynH1fIrJvo/452mui8nXtkDlShhLY4TdTG7JkW?=
 =?us-ascii?Q?a7mzJHEfAEOPpUZXPhDyI5CcGPxH6MZaCEsa2Qd4zf1aRfQKk/2b8VDuIdBu?=
 =?us-ascii?Q?q045FAR6fp5oIqULZCC2JR2pMd3pReYJHjkJxTaw3v7mwAPqa4HyTLQkZ4cJ?=
 =?us-ascii?Q?ZS4IOY2MueW4AFTnSnwXV3jkuT8c3vRpS0fajMgm83vcW4H/KfPGm2QyZZsf?=
 =?us-ascii?Q?g8dACDOc3gdy8APpvDpdel5E0ca/7qQNhYesaqO8jZeX3CNu7MhJ2RXQqo1A?=
 =?us-ascii?Q?YxoqAyArocfxndXCUZ4NOZ8O8Bv9UTbq+Pgsnhx/4ZWwcW4EnkyISXZU2APB?=
 =?us-ascii?Q?7RCnfZFRvO6lqZuHv+jnUTxTQ8hmnWSjLvmY0evPwocTkTXsc17xvoaS5Mka?=
 =?us-ascii?Q?9h3q1AwV62A8jfMltjpCDaTHVvg1C9myFkkE4J8biCNGvpodZX8ueysXypw7?=
 =?us-ascii?Q?Sm7jEzHv2eeYfQPogurSUnIhhVX2kYZCVS7oG04tv4dnV2ufAjYZWeAT2KUX?=
 =?us-ascii?Q?9U9wzPYnyZ2BAYk/5V+LaS24UflVNANaxZ1SzCcdtxhzi/tpTwORNFCcEjSg?=
 =?us-ascii?Q?Y24ywmmvs9tUaEJIr8yQiRI9d81cnEe3LONAkVK4s1V4D6Hu24OxfogYlBFB?=
 =?us-ascii?Q?9Ze/ymEJE2PbKiRl8ik4Ryi6+lta8oE0x8bGYB66ayPWrlpFEUsgkd4F1Ipj?=
 =?us-ascii?Q?U3JwZMlTQP918AcDnxOmB8WApizjRuStqiBtXnx+OVRhQKilhV1AJ5W6FunS?=
 =?us-ascii?Q?OCx7JALLe/zXyuJaLR9ulDu2T2ojh5HmwppJM7XGua4cNVZGQdXo+Z7e8FSm?=
 =?us-ascii?Q?4//7d23E+gnnzqKjsluAdnRI5M0gM8TdsV0sVhrx?=
X-MS-Exchange-CrossTenant-Network-Message-Id: 2fd2b733-85c8-44dc-f761-08db6c459ff1
X-MS-Exchange-CrossTenant-AuthSource: SA1PR11MB6733.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 13 Jun 2023 19:37:29.9007
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: 4fxAm7WTOkoowPmoA3pOlqE+Uaz6ONovH7filmhdfOolX8XwJ4pMUBWoT8CsNTWhGqfm7TPuCS5EFd3SlxMq2g==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: CH0PR11MB5539
X-OriginatorOrg: intel.com
X-Spam-Status: No, score=-4.4 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,
        DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_MED,
        SPF_HELO_NONE,SPF_NONE,T_SCC_BODY_TEXT_LINE,URIBL_BLOCKED
        autolearn=ham autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

Fabio M. De Francesco wrote:
> The differences between kmap_local_page() and kmap_local_folio() consist
> only in the first taking a pointer to a page and the second taking two
> arguments, a pointer to a folio and the byte offset within the folio which
> identifies the page.
> 
> The two API's can be explained at the same time in the "Temporary Virtual
> Mappings" section of the Highmem's documentation.
> 
> Add information about kmap_local_folio() in the same subsection that
> explains kmap_local_page().
> 
> Cc: Catalin Marinas <catalin.marinas@arm.com>
> Cc: Ira Weiny <ira.weiny@intel.com>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Matthew Wilcox (Oracle) <willy@infradead.org>
> Cc: Mike Rapoport <rppt@linux.ibm.com>
> Cc: Peter Collingbourne <pcc@google.com>
> Cc: Peter Zijlstra <peterz@infradead.org>
> Cc: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> Cc: Thomas Gleixner <tglx@linutronix.de>
> Cc: Vlastimil Babka <vbabka@suse.cz>
> Cc: Will Deacon <will@kernel.org>
> Signed-off-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>
>

Good to keep the doc up to date with reality.

Reviewed-by: Ira Weiny <ira.weiny@intel.com>

> ---
>  Documentation/mm/highmem.rst | 27 +++++++++++++++------------
>  1 file changed, 15 insertions(+), 12 deletions(-)
> 
> diff --git a/Documentation/mm/highmem.rst b/Documentation/mm/highmem.rst
> index c964e0848702..bb9584f167a6 100644
> --- a/Documentation/mm/highmem.rst
> +++ b/Documentation/mm/highmem.rst
> @@ -51,11 +51,14 @@ Temporary Virtual Mappings
>  The kernel contains several ways of creating temporary mappings. The following
>  list shows them in order of preference of use.
>  
> -* kmap_local_page().  This function is used to require short term mappings.
> -  It can be invoked from any context (including interrupts) but the mappings
> -  can only be used in the context which acquired them.
> -
> -  This function should always be used, whereas kmap_atomic() and kmap() have
> +* kmap_local_page(), kmap_local_folio() - These functions are used to require
> +  short term mappings. They can be invoked from any context (including
> +  interrupts) but the mappings can only be used in the context which acquired
> +  them. The only differences between them consist in the first taking a pointer
> +  to a struct page and the second taking a pointer to struct folio and the byte
> +  offset within the folio which identifies the page.
> +
> +  These functions should always be used, whereas kmap_atomic() and kmap() have
>    been deprecated.
>  
>    These mappings are thread-local and CPU-local, meaning that the mapping
> @@ -72,17 +75,17 @@ list shows them in order of preference of use.
>    maps of the outgoing task are saved and those of the incoming one are
>    restored.
>  
> -  kmap_local_page() always returns a valid virtual address and it is assumed
> -  that kunmap_local() will never fail.
> +  kmap_local_page(), as well as kmap_local_folio() always returns valid virtual
> +  kernel addresses and it is assumed that kunmap_local() will never fail.
>  
> -  On CONFIG_HIGHMEM=n kernels and for low memory pages this returns the
> +  On CONFIG_HIGHMEM=n kernels and for low memory pages they return the
>    virtual address of the direct mapping. Only real highmem pages are
>    temporarily mapped. Therefore, users may call a plain page_address()
>    for pages which are known to not come from ZONE_HIGHMEM. However, it is
> -  always safe to use kmap_local_page() / kunmap_local().
> +  always safe to use kmap_local_{page,folio}() / kunmap_local().
>  
> -  While it is significantly faster than kmap(), for the highmem case it
> -  comes with restrictions about the pointers validity. Contrary to kmap()
> +  While they are significantly faster than kmap(), for the highmem case they
> +  come with restrictions about the pointers validity. Contrary to kmap()
>    mappings, the local mappings are only valid in the context of the caller
>    and cannot be handed to other contexts. This implies that users must
>    be absolutely sure to keep the use of the return address local to the
> @@ -91,7 +94,7 @@ list shows them in order of preference of use.
>    Most code can be designed to use thread local mappings. User should
>    therefore try to design their code to avoid the use of kmap() by mapping
>    pages in the same thread the address will be used and prefer
> -  kmap_local_page().
> +  kmap_local_page() or kmap_local_folio().
>  
>    Nesting kmap_local_page() and kmap_atomic() mappings is allowed to a certain
>    extent (up to KMAP_TYPE_NR) but their invocations have to be strictly ordered
> -- 
> 2.40.1
>