Documentation/core-api/pin_user_pages.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 pin_user_pages() and related calls
35 In other words, use pin_user_pages*() for DMA-pinned pages, and
54 flags the caller provides. The caller is required to pass in a non-null struct
72  --------
79 but the caller passed in a non-null struct pages* array, then the function
84  --------
89 Tracking dma-pinned pages
92 Some of the key design constraints, and solutions, for tracking dma-pinned
98 * False positives (reporting that a page is dma-pinned, when in fact it is not)
104 * Given the above, we can overload the page->_refcount field by using, sort of,
105   the upper bits in that field for a dma-pinned count. "Sort of", means that,
106   rather than dividing page->_refcount into bit fields, we simple add a medium-
108   page->_refcount. This provides fuzzy behavior: if a page has get_page() called
109   on it 1024 times, then it will appear to have a single dma-pinned count.
112 This also leads to limitations: there are only 31-10==21 bits available for a
116   when using FOLL_PIN.  We only pretend to pin a zero page - we don't alter its
121 * Callers must specifically request "dma-pinned tracking of pages". In other
123   pin_user_page() and related, must be used.
128 Thanks to Jan Kara, Vlastimil Babka and several other -mm people, for describing
132 -----------------------
144 ------------
145 There are GUP references to pages that are serving as DMA
156 .. _mmu-notifier-registration-case:
159 -------------------------------------------------------------------------
176 -------------------------------------------------
182 -------------------------------------------------------------
183 Even though neither DMA nor Direct IO is involved, just a simple case of "pin,
202 The whole point of marking folios as "DMA-pinned" or "gup-pinned" is to be able
203 to query, "is this folio DMA-pinned?" That allows code such as folio_mkclean()
207 What to do in those cases is the subject of a years-long series of discussions
214 ...is a prerequisite to solving the long-running gup+DMA problem.
235 * PIN_FAST_BENCHMARK (./gup_test -a)
236 * PIN_BASIC_TEST (./gup_test -b)
238 You can monitor how many total dma-pinned pages have been acquired and released
245 long-term [R]DMA pins in place, or during pin/unpin transitions.
268 (...unless it was already out of balance due to a long-term RDMA pin being in
282 * `DMA and get_user_pages() (LPC: Dec 12, 2018) <https://lwn.net/Articles/774411/>`_
284 * `LWN kernel index: get_user_pages() <https://lwn.net/Kernel/Index/#Memory_management-get_user_pag…