From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-ej1-f53.google.com (mail-ej1-f53.google.com [209.85.218.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 7BB297F5 for ; Wed, 27 Apr 2022 18:38:35 +0000 (UTC) Received: by mail-ej1-f53.google.com with SMTP id i27so5113927ejd.9 for ; Wed, 27 Apr 2022 11:38:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Og01PFU5EZe5B0bBCu0F7erpiwis4vadvQ4RVspA5Fo=; b=SntM5HDOwIGePMHzM/EfZTAhbrz7ckZ4p9NyGG4x3OSE/dbxyn70Q3EhHR3ygKzW5I kcW88k/EYG4S4Y3mmysxcGIpqI71WboengmOm95wO05I0S2E4E/FEx1JP5+l0E9x9wUv vcXil4U7biijyBk1Jm85LLyjEdhgroQlCphFFLda5167dYmB/EDh7ghlCmlnieJY8xg0 fvN2hmw458gg5trRdsn3dFe8ytLIWo3Tr+0LrQdoqgOleP/j5bO2/+P5kV3pG5BtBL/B uEJXUEEUxJiE22KQNChwj7jyiGkWZqygQlDWDBeluT0PjfPSt04Ie3jfBhN7N1UHoehq Byjg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Og01PFU5EZe5B0bBCu0F7erpiwis4vadvQ4RVspA5Fo=; b=QfPQPjF2XHujYUDMa2S9w6BiHszR1gMwDRzAYBgZjVV9wgI6naCrVhh70BI1VEPlkL jzKfcV/X/G1x9B6Fb7v2LZcQXbXqPiV0VXdLxK5jPUdpiHYt0UkVVyuGFwaR3J9FjFa+ jCav6bDVWZIlMpAMPEq9vgTW6AAc14nciaadoJ6LEY+RFDc0SjCNVvq/9upVvJu+7gGb oYNkWbZ2JAA7v76PZ4Uit7KRT9vC7CirSwSCDu92hwTKA2pGDLTkzy4a6noP3DBBK1Oj +OktkV+ZoqDi78QLTBL5LKsMg7sMlWPdGLpvfgKQscZeymY2vw/oghvXPjBibz07xQ7Q 2RZQ== X-Gm-Message-State: AOAM530QrWm56AcA3xPSWpNEGLH+h+NuzhYjvrt3FSBXjuDRk/E9+3I1 SBjtdSGfQ+/UQlck8OSrj0Y= X-Google-Smtp-Source: ABdhPJxSqgxF0sunXBvQPcd7EMxD0GNBqflpYY2ga2IkDu1yXDb35IfTimGHpeVMmtZs0AC1cq/pgA== X-Received: by 2002:a17:907:7745:b0:6f3:674a:339 with SMTP id kx5-20020a170907774500b006f3674a0339mr24302043ejc.207.1651084713819; Wed, 27 Apr 2022 11:38:33 -0700 (PDT) Received: from localhost.localdomain (host-79-50-86-254.retail.telecomitalia.it. [79.50.86.254]) by smtp.gmail.com with ESMTPSA id ig8-20020a1709072e0800b006f38f2e9ebesm4691667ejc.64.2022.04.27.11.38.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 Apr 2022 11:38:32 -0700 (PDT) From: "Fabio M. De Francesco" To: Ira Weiny , Andrew Morton , Catalin Marinas , "Matthew Wilcox (Oracle)" , Will Deacon , Peter Collingbourne , Vlastimil Babka , Sebastian Andrzej Siewior , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, outreachy@lists.linux.dev Cc: "Fabio M. De Francesco" , Jonathan Corbet , Thomas Gleixner , Peter Zijlstra Subject: [PATCH v3 3/4] Documentation/vm: Move "Using kmap-atomic" to highmem.h Date: Wed, 27 Apr 2022 20:38:20 +0200 Message-Id: <20220427183821.1979-4-fmdefrancesco@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20220427183821.1979-1-fmdefrancesco@gmail.com> References: <20220427183821.1979-1-fmdefrancesco@gmail.com> Precedence: bulk X-Mailing-List: outreachy@lists.linux.dev List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit The use of kmap_atomic() is new code is being deprecated in favor of kmap_local_page(). For this reason the "Using kmap_atomic" section in highmem.rst is obsolete and unnecessary, but it can still help developers if it were moved to kdocs in highmem.h. Therefore, move the relevant parts of this section from highmem.rst and merge them with the kdocs in highmem.h. Cc: Jonathan Corbet Cc: Thomas Gleixner Cc: Matthew Wilcox Cc: Peter Zijlstra Suggested-by: Ira Weiny Signed-off-by: Fabio M. De Francesco --- Documentation/vm/highmem.rst | 35 ----------------------------------- include/linux/highmem.h | 31 +++++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+), 35 deletions(-) diff --git a/Documentation/vm/highmem.rst b/Documentation/vm/highmem.rst index ccff08a8211d..e05bf5524174 100644 --- a/Documentation/vm/highmem.rst +++ b/Documentation/vm/highmem.rst @@ -72,41 +72,6 @@ The kernel contains several ways of creating temporary mappings: It may be assumed that k[un]map_atomic() won't fail. -Using kmap_atomic -================= - -When and where to use kmap_atomic() is straightforward. It is used when code -wants to access the contents of a page that might be allocated from high memory -(see __GFP_HIGHMEM), for example a page in the pagecache. The API has two -functions, and they can be used in a manner similar to the following:: - - /* Find the page of interest. */ - struct page *page = find_get_page(mapping, offset); - - /* Gain access to the contents of that page. */ - void *vaddr = kmap_atomic(page); - - /* Do something to the contents of that page. */ - memset(vaddr, 0, PAGE_SIZE); - - /* Unmap that page. */ - kunmap_atomic(vaddr); - -Note that the kunmap_atomic() call takes the result of the kmap_atomic() call -not the argument. - -If you need to map two pages because you want to copy from one page to -another you need to keep the kmap_atomic calls strictly nested, like:: - - vaddr1 = kmap_atomic(page1); - vaddr2 = kmap_atomic(page2); - - memcpy(vaddr1, vaddr2, PAGE_SIZE); - - kunmap_atomic(vaddr2); - kunmap_atomic(vaddr1); - - Cost of Temporary Mappings ========================== diff --git a/include/linux/highmem.h b/include/linux/highmem.h index 3623319a659d..d1f9b298415e 100644 --- a/include/linux/highmem.h +++ b/include/linux/highmem.h @@ -143,6 +143,37 @@ static inline void *kmap_local_folio(struct folio *folio, size_t offset); * configurations). * * Do not use in new code. Use kmap_local_page() instead. + * + * It is used in atomic context when code wants to access the contents of a + * page that might be allocated from high memory (see __GFP_HIGHMEM), for + * example a page in the pagecache. The API has two functions, and they + * can be used in a manner similar to the following: + * + * -- Find the page of interest. -- + * struct page *page = find_get_page(mapping, offset); + * + * -- Gain access to the contents of that page. -- + * void *vaddr = kmap_atomic(page); + * + * -- Do something to the contents of that page. -- + * memset(vaddr, 0, PAGE_SIZE); + * + * -- Unmap that page. -- + * kunmap_atomic(vaddr); + * + * Note that the kunmap_atomic() call takes the result of the kmap_atomic() + * call, not the argument. + * + * If you need to map two pages because you want to copy from one page to + * another you need to keep the kmap_atomic calls strictly nested, like: + * + * vaddr1 = kmap_atomic(page1); + * vaddr2 = kmap_atomic(page2); + * + * memcpy(vaddr1, vaddr2, PAGE_SIZE); + * + * kunmap_atomic(vaddr2); + * kunmap_atomic(vaddr1); */ static inline void *kmap_atomic(struct page *page); -- 2.34.1