linux-kernel - [PATCH] mm/gup: update pin_user_pages.rst for "case 3" (mmu notifiers)

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [day] [month] [year] [list]

Message-ID: <20200527194953.11130-1-jhubbard@nvidia.com>
Date:   Wed, 27 May 2020 12:49:53 -0700
From:   John Hubbard <jhubbard@...dia.com>
To:     Andrew Morton <akpm@...ux-foundation.org>
CC:     Souptick Joarder <jrdr.linux@...il.com>,
        LKML <linux-kernel@...r.kernel.org>, <linux-mm@...ck.org>,
        John Hubbard <jhubbard@...dia.com>,
        Daniel Vetter <daniel@...ll.ch>,
        Jérôme Glisse <jglisse@...hat.com>,
        Vlastimil Babka <vbabka@...e.cz>, Jan Kara <jack@...e.cz>,
        Dave Chinner <david@...morbit.com>,
        Jonathan Corbet <corbet@....net>, <linux-doc@...r.kernel.org>,
        <linux-fsdevel@...r.kernel.org>
Subject: [PATCH] mm/gup: update pin_user_pages.rst for "case 3" (mmu notifiers)

Update case 3 so that it covers the use of mmu notifiers, for
hardware that does, or does not have replayable page faults.

Also, elaborate case 4 slightly, as it was quite cryptic.

Cc: Daniel Vetter <daniel@...ll.ch>
Cc: Jérôme Glisse <jglisse@...hat.com>
Cc: Vlastimil Babka <vbabka@...e.cz>
Cc: Jan Kara <jack@...e.cz>
Cc: Dave Chinner <david@...morbit.com>
Cc: Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org
Cc: linux-fsdevel@...r.kernel.org
Signed-off-by: John Hubbard <jhubbard@...dia.com>
---
 Documentation/core-api/pin_user_pages.rst | 33 +++++++++++++----------
 1 file changed, 19 insertions(+), 14 deletions(-)

diff --git a/Documentation/core-api/pin_user_pages.rst b/Documentation/core-api/pin_user_pages.rst
index 2e939ff10b86..4675b04e8829 100644
--- a/Documentation/core-api/pin_user_pages.rst
+++ b/Documentation/core-api/pin_user_pages.rst
@@ -148,23 +148,28 @@ NOTE: Some pages, such as DAX pages, cannot be pinned with longterm pins. That's
 because DAX pages do not have a separate page cache, and so "pinning" implies
 locking down file system blocks, which is not (yet) supported in that way.
 
-CASE 3: Hardware with page faulting support
--------------------------------------------
-Here, a well-written driver doesn't normally need to pin pages at all. However,
-if the driver does choose to do so, it can register MMU notifiers for the range,
-and will be called back upon invalidation. Either way (avoiding page pinning, or
-using MMU notifiers to unpin upon request), there is proper synchronization with
-both filesystem and mm (page_mkclean(), munmap(), etc).
-
-Therefore, neither flag needs to be set.
-
-In this case, ideally, neither get_user_pages() nor pin_user_pages() should be
-called. Instead, the software should be written so that it does not pin pages.
-This allows mm and filesystems to operate more efficiently and reliably.
+CASE 3: MMU notifier registration, with or without page faulting hardware
+-------------------------------------------------------------------------
+Device drivers can pin pages via get_user_pages*(), and register for mmu
+notifier callbacks for the memory range. Then, upon receiving a notifier
+"invalidate range" callback , stop the device from using the range, and unpin
+the pages. There may be other possible schemes, such as for example explicitly
+synchronizing against pending IO, that accomplish approximately the same thing.
+
+Or, if the hardware supports replayable page faults, then the device driver can
+avoid pinning entirely (this is ideal), as follows: register for mmu notifier
+callbacks as above, but instead of stopping the device and unpinning in the
+callback, simply remove the range from the device's page tables.
+
+Either way, as long as the driver unpins the pages upon mmu notifier callback,
+then there is proper synchronization with both filesystem and mm
+(page_mkclean(), munmap(), etc). Therefore, neither flag needs to be set.
 
 CASE 4: Pinning for struct page manipulation only
 -------------------------------------------------
-Here, normal GUP calls are sufficient, so neither flag needs to be set.
+If only struct page data (as opposed to the actual memory contents that a page
+is tracking) is affected, then normal GUP calls are sufficient, and neither flag
+needs to be set.
 
 page_maybe_dma_pinned(): the whole point of pinning
 ===================================================
-- 
2.26.2