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 vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E457FC433EF for ; Tue, 10 May 2022 19:23:10 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233859AbiEJTXJ (ORCPT ); Tue, 10 May 2022 15:23:09 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:46532 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S243015AbiEJTWm (ORCPT ); Tue, 10 May 2022 15:22:42 -0400 Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B71D51BDADD for ; Tue, 10 May 2022 12:22:36 -0700 (PDT) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id 4C60A6131D for ; Tue, 10 May 2022 19:22:36 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8FC6DC385CE; Tue, 10 May 2022 19:22:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=linux-foundation.org; s=korg; t=1652210555; bh=2VvK4d5qTqWX6aUY2pwmNZEEb1mMddGRIyHCDSHg8Q4=; h=Date:To:From:Subject:From; b=y5lKt5ZRlha5nLG27HuApIZpEeLP0gZzIb7+VqLYGhIt3NcDujfpMd9baGW1wc8Ta ywVwcew528TZYNZEcnX/jikwbdzJdYAq9v6xM9MTo9KJFqanOUmg34SFy+MwJXp72g 8IDTCP1n37c19NCn1URlDZ1xQTgf+6dMNP08+rCw= Date: Tue, 10 May 2022 12:22:34 -0700 To: mm-commits@vger.kernel.org, willy@infradead.org, will@kernel.org, vbabka@suse.cz, tglx@linutronix.de, rppt@linux.ibm.com, peterz@infradead.org, pcc@google.com, ira.weiny@intel.com, corbet@lwn.net, catalin.marinas@arm.com, bigeasy@linutronix.de, fmdefrancesco@gmail.com, akpm@linux-foundation.org From: Andrew Morton Subject: + documentation-vm-move-using-kmap-atomic-to-highmemh.patch added to mm-unstable branch Message-Id: <20220510192235.8FC6DC385CE@smtp.kernel.org> Precedence: bulk Reply-To: linux-kernel@vger.kernel.org List-ID: X-Mailing-List: mm-commits@vger.kernel.org The patch titled Subject: Documentation/vm: move "Using kmap-atomic" to highmem.h has been added to the -mm mm-unstable branch. Its filename is documentation-vm-move-using-kmap-atomic-to-highmemh.patch This patch will shortly appear at https://git.kernel.org/pub/scm/linux/kernel/git/akpm/25-new.git/tree/patches/documentation-vm-move-using-kmap-atomic-to-highmemh.patch This patch will later appear in the mm-unstable branch at git://git.kernel.org/pub/scm/linux/kernel/git/akpm/mm Before you just go and hit "reply", please: a) Consider who else should be cc'ed b) Prefer to cc a suitable mailing list as well c) Ideally: find the original patch on the mailing list and do a reply-to-all to that, adding suitable additional cc's *** Remember to use Documentation/process/submit-checklist.rst when testing your code *** The -mm tree is included into linux-next via the mm-everything branch at git://git.kernel.org/pub/scm/linux/kernel/git/akpm/mm and is updated there every 2-3 working days ------------------------------------------------------ From: "Fabio M. De Francesco" Subject: Documentation/vm: move "Using kmap-atomic" to highmem.h 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. Link: https://lkml.kernel.org/r/20220428212455.892-4-fmdefrancesco@gmail.com Signed-off-by: Fabio M. De Francesco Suggested-by: Ira Weiny Reviewed-by: Sebastian Andrzej Siewior Reviewed-by: Ira Weiny Cc: Jonathan Corbet Cc: Matthew Wilcox Cc: Peter Zijlstra Cc: Thomas Gleixner Cc: Catalin Marinas Cc: Mike Rapoport Cc: Peter Collingbourne Cc: Vlastimil Babka Cc: Will Deacon Cc: Jonathan Corbet Signed-off-by: Andrew Morton --- Documentation/vm/highmem.rst | 35 --------------------------------- include/linux/highmem.h | 31 +++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+), 35 deletions(-) --- a/Documentation/vm/highmem.rst~documentation-vm-move-using-kmap-atomic-to-highmemh +++ a/Documentation/vm/highmem.rst @@ -72,41 +72,6 @@ The kernel contains several ways of crea 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 ========================== --- a/include/linux/highmem.h~documentation-vm-move-using-kmap-atomic-to-highmemh +++ a/include/linux/highmem.h @@ -145,6 +145,37 @@ static inline void *kmap_local_folio(str * Mappings should always be released by kunmap_atomic(). * * 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); _ Patches currently in -mm which might be from fmdefrancesco@gmail.com are mm-highmem-fix-kernel-doc-warnings-in-highmemh.patch documentation-vm-include-kdocs-from-highmemh-into-highmemrst.patch documentation-vm-move-using-kmap-atomic-to-highmemh.patch documentation-vm-rework-temporary-virtual-mappings-section.patch