From patchwork Sat Jul 1 14:19:31 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Fabio M. De Francesco" X-Patchwork-Id: 13299105 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 CD8C4C001B0 for ; Sat, 1 Jul 2023 14:20:50 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id CD8038E006C; Sat, 1 Jul 2023 10:20:49 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id C882A8E0059; Sat, 1 Jul 2023 10:20:49 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id B4FB98E006C; Sat, 1 Jul 2023 10:20:49 -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 A66C48E0059 for ; Sat, 1 Jul 2023 10:20:49 -0400 (EDT) Received: from smtpin05.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay07.hostedemail.com (Postfix) with ESMTP id 73A201605DC for ; Sat, 1 Jul 2023 14:20:49 +0000 (UTC) X-FDA: 80963254218.05.3D40FE4 Received: from mail-wr1-f41.google.com (mail-wr1-f41.google.com [209.85.221.41]) by imf22.hostedemail.com (Postfix) with ESMTP id AA39EC0009 for ; Sat, 1 Jul 2023 14:20:47 +0000 (UTC) Authentication-Results: imf22.hostedemail.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=VMDWbuxc; spf=pass (imf22.hostedemail.com: domain of fmdefrancesco@gmail.com designates 209.85.221.41 as permitted sender) smtp.mailfrom=fmdefrancesco@gmail.com; dmarc=pass (policy=none) header.from=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1688221247; 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-transfer-encoding:content-transfer-encoding: in-reply-to:references:dkim-signature; bh=4xzwfPjRQFT6QKTWY2W7B8J20zCNe8ZcBZy6OXaEZiE=; b=NbPAWYJaEbv004BhHK7JgXJ4KQzaIHH8P+X5rVSWNrOhvX/gxOme86Y95khOSA2xAt5jal ULBEjkUpkE3KvbyJm3Soge+sg8WPTFqwjQzqPbNjI94PykEdiwYVNUcy6Kv/yp54proWAM 8OaBXWYEolw/Q5FQaDmmMSbp9Cgctr8= ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1688221247; a=rsa-sha256; cv=none; b=NxHZ0J1NVXvB0RKxfezYH5QxrCa4ZZjvgxqgG0oFuoFEPzem5naLzg1yP88WybhaDeNkIs 9xO2BXj3VQZJnYvKJoBY1ea8+9NPk6n7mEfOcWaCc5jeFrZ4f5COuXqQGnFppWLI6Aky5a e4X8s0Xw2wtZH3ybrkNNOF0sAwLGkeQ= ARC-Authentication-Results: i=1; imf22.hostedemail.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=VMDWbuxc; spf=pass (imf22.hostedemail.com: domain of fmdefrancesco@gmail.com designates 209.85.221.41 as permitted sender) smtp.mailfrom=fmdefrancesco@gmail.com; dmarc=pass (policy=none) header.from=gmail.com Received: by mail-wr1-f41.google.com with SMTP id ffacd0b85a97d-3142a9ff6d8so786849f8f.3 for ; Sat, 01 Jul 2023 07:20:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1688221246; x=1690813246; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=4xzwfPjRQFT6QKTWY2W7B8J20zCNe8ZcBZy6OXaEZiE=; b=VMDWbuxc1Y6vsnHVtQXRkXyvapLiLnw6gcnHcjZLt2lDpg8vDqciqBzOkHDZgGgCJJ +QwCuRAk8LsSSfXQOXg7wO1/dG+fYDAmMT/+mEf/uMJ/DDIr29gwEKvPARdlvxRnUplI u3brKHyBqYEOAby5GHwvguXFV5okajoyD/gpdVUy2qgMAT/EOBRO9OVzk4uOIShNc0DM 65CMYHkesyGwMuesK+Aqzo6cnCKO7q1glqj6an3sIU+GtW1GKwkW3M4jLVYQCnVT3Nr5 qn4j820pxQOdVxkMyUFSePMrzKu1DdtNubgwbhuUuMwF4HhiiZ7Oi9Vn1xgGKHJtsQJw k/zw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1688221246; x=1690813246; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=4xzwfPjRQFT6QKTWY2W7B8J20zCNe8ZcBZy6OXaEZiE=; b=jVT8TrxOESnBvfWfThflG8S5ldq9BycdFE/omsi+3x6ITzdBl7BSZmi2ZYGWa0syRe s/dJbHNZZi43Azg9tqg/Jn9R184JSMFqC5SjkfC/ppUfQRm+l4vk4IHMVwvmlg/Mxa3X DJxNEW0TmIVNm/RKPgZYwPNy28zPWgE+TTL0o99eJHfJ7Tp/ShiXIZliNicGCMiioN9U 49jitoiNH6d1fOfAhCJLa4oOG5Dfhy21E4pieCwm7Hid/hHtGRNUiPtqpWYYf0H4wg4f L7ufdVzn1A0TLintDbqJ8O44BxJNeOdlNyW7PgWZg3q1ZyDebbY48GQp5fH4mfEo1z/9 TndQ== X-Gm-Message-State: ABy/qLbMS/mqH4pnijXTzgNo28J00nwtJMiCn4F7w5YGabK4AeOoC/hG og6komE0urSd/mnWEV+ob+4= X-Google-Smtp-Source: APBJJlH8c1U2WWQW1POCEW5HO6qA6qoyqkRKvCgSWNquBLbN/NooBhoLGygUtVIZX4azLQMGdUrtKQ== X-Received: by 2002:a5d:49d1:0:b0:314:15b7:1fb5 with SMTP id t17-20020a5d49d1000000b0031415b71fb5mr4238962wrs.34.1688221246067; Sat, 01 Jul 2023 07:20:46 -0700 (PDT) Received: from localhost.localdomain (host-82-49-237-33.retail.telecomitalia.it. [82.49.237.33]) by smtp.gmail.com with ESMTPSA id t5-20020a05600001c500b00313f7b077fesm14307741wrx.59.2023.07.01.07.20.43 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 01 Jul 2023 07:20:45 -0700 (PDT) From: "Fabio M. De Francesco" To: Jonathan Corbet , Andrew Morton , "Fabio M. De Francesco" , "Mike Rapoport (IBM)" , Deming Wang , Ira Weiny , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-mm@kvack.org Cc: Catalin Marinas , Matthew Wilcox , Mike Rapoport , Peter Collingbourne , Peter Zijlstra , Sebastian Andrzej Siewior , Thomas Gleixner , Vlastimil Babka , Will Deacon Subject: [PATCH v2] Documentation/mm: Add information about kmap_local_folio() Date: Sat, 1 Jul 2023 16:19:31 +0200 Message-ID: <20230701142041.9992-1-fmdefrancesco@gmail.com> X-Mailer: git-send-email 2.41.0 MIME-Version: 1.0 X-Rspamd-Queue-Id: AA39EC0009 X-Rspam-User: X-Stat-Signature: h4brmywf7ek1ni84h9tiryf6sxf8ccbs X-Rspamd-Server: rspam03 X-HE-Tag: 1688221247-975048 X-HE-Meta: U2FsdGVkX18KuKU6I5W09S8xGR2y+OafjZMIju7CxqyWc70Q3GlHUy/S/R9IUzt7bt91JEK9tbErTfF9y+kd5xmW5VuOmRhm9TAjNXsJUd2qKrdQI2oSqV7n9VOJ5wG4YU0/Ss+lPnLhbht/udLDgJp8F8YmuyljF9NwSFh+AHZQ+dbTF7MzU0u2dzUydegGxwVI5/XAH8dhpDVskwfwJLUE+27eOpFPtj3Jc75QSuYLko0EBSdKVRP+ys8cS61kPvaKGpFyMaY2K68/tlWnSSbJuo0BPHEZrFQnqCpBDycOH5tpvgsgky/zwR7XX0Sh9hCC2+hHNl5huC5+Yomo+aNEo/Ps5GWbOST+HogEM0m271MBvA3QN1+D6koGriH7MGZAZyHA0rAWMCRKaTOV6jc5DB2yGLnJhRz/+4IiAwTY9oHtfDsvn7nhjjo3wY4HlGC+eZaOYsHePY23tAVUVUSXSddqMJLW2x08+vAQA2jqh3Jykfy53kmgZEaLwYtKnjXBQLUrJL4w75kO7bHIOA7tl6khXEZ49kjVyFAQyyAMxcFnIg/pdohJO2KhSRjxkFMW15MMm4xI9RESmLcy4RpD3zyqTZEQX1peBr+phuU5UpocgoaGcWr0oZ4svGcwwNk3ELa3U7wk31qNlaXIQF88TTdVQNEvXe5xe6ldtBPMu0yJ10wQXQ4F44EttcL1A48bIeVIs5fJHCtBxguSSHc97T9pTNCJNht/YybupWv+WYFSDw+EmxuFWOpAV0V5G1Z/m1RvdJvtnO6f3HNKSZa9fR5+UFXDUh55Hn2PNhcdNcOH1TwoTRrHU7LLWCL8OEDFuLeT2a39zJ8GZFe00KKd+5CLCjCV0rva3Gt1rikmEN33UElkmK9+EOGd3r4F+vPe2GMNax17mMj+X+d66wJAPvIIDiJumlBosU14eovLDZOEnOdehXMXinBzvQaBSE+bVuz+Z1ldGuAMRyG IlbkE39W askxh9dlKvq2yYZJ441cVpHlZsDEKNP2fbOidZjIWqJAinVWTysPLN8pasSGIyogjJoOLKDQwWT/rYYiYklSQeKr6L+VTDlCbXKFQprcV3OtJ2quiyynXnFfv946ShqCRpUg4vSeoEWpIkA0k14eC4/wv6j6Dihx5UUGfDEfDTswY+317eXUHzqT3y3AHSxmc+zTVb30okmCTwZ2IQ5qiblUPYpEHvbn4DqV8e+Lal7fQvL9h8exenM9ZF3CRcOtqy4qn/gmrPSIRVijkTxql7KnAYN1G7p2bnV013CsqRr8dcbSQ96wEcoCkYenHjcm1s3iQG76rFe9ocqlZDv+FlDbezW+4/NZfk0293/YF2rnnnheFB6LcVIFVDe1gDrZSRqs9o4ug1NH0JezcCcVoy5lFplVgK9qiaDE3XcA+mKZ8StEv8I+S6U8yNo9i2vXYZP00mwNRl7mOXX+38gFy2YWJmyLNfgKlHC3Rq8qaP/5HXpB2+Oy/GRMlXBw0PfxDoZl2KAbjH4xzquIGhu7QHquLzhNfMdFB/ntLOrCc8BdzlHxvjhjeq/FBpzcuM/Gtijp3FJp3mcNeS2OfoKQB/J8lYkeVNMJcK3LqvZB4QCjvp9KpQq9M0V24Ca4L9dOk9OUNGSKwnUqfp7GP0ZL4WNO2zn9pC2zm7MNvFmyl6/2+bJw688TvNq+PsVqdhcAv+8EHDZkbbbYjIqsJO4Q7pGjoxXhh/vLdsucN7bXxF50DQsWWIl4dTQohWO6dSClskAOno3V4Bluxarymvu9wZwZGetEpI0dXHFkHr+px2gVLWqfLE1QnNQZ+g6o3TDnxMF7KnzrP9261buLbj4yLDfErx6SjMErSZM3d67vVeuFK5FU= 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: 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: Andrew Morton Cc: Catalin Marinas Cc: Ira Weiny Cc: Jonathan Corbet Cc: Matthew Wilcox (Oracle) Cc: Mike Rapoport Cc: Peter Collingbourne Cc: Peter Zijlstra Cc: Sebastian Andrzej Siewior Cc: Thomas Gleixner Cc: Vlastimil Babka Cc: Will Deacon Reviewed-by: Ira Weiny Reviewed-by: Mike Rapoport (IBM) Signed-off-by: Fabio M. De Francesco --- v1->v2: I thought to Cc everybody but Andrew :-( Sorry, fixed. Andrew, can you please take this patch through your tree? 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