On Tue, 10 Dec 2019 18:53:03 -0800 John Hubbard jhubbard@nvidia.com wrote:
Introduce pin_user_pages*() variations of get_user_pages*() calls, and also pin_longterm_pages*() variations.
Just a couple of nits on the documentation patch
+++ b/Documentation/core-api/pin_user_pages.rst @@ -0,0 +1,232 @@ +.. SPDX-License-Identifier: GPL-2.0
+==================================================== +pin_user_pages() and related calls +====================================================
+.. contents:: :local:
+Overview +========
+This document describes the following functions: ::
- pin_user_pages
- pin_user_pages_fast
- pin_user_pages_remote
You could just say "the following functions::" and get the result you're after with a slightly less alien plain-text reading experience.
Of course, you could also just say "This document describes pin_user_pages(), pin_user_pages_fast(), and pin_user_pages_remote()." But that's a matter of personal taste, I guess. Using the function() notation will cause the docs system to automatically link to the kerneldoc info, though.
+Basic description of FOLL_PIN +=============================
+FOLL_PIN and FOLL_LONGTERM are flags that can be passed to the get_user_pages*() +("gup") family of functions. FOLL_PIN has significant interactions and +interdependencies with FOLL_LONGTERM, so both are covered here.
+FOLL_PIN is internal to gup, meaning that it should not appear at the gup call +sites. This allows the associated wrapper functions (pin_user_pages*() and +others) to set the correct combination of these flags, and to check for problems +as well.
+FOLL_LONGTERM, on the other hand, *is* allowed to be set at the gup call sites. +This is in order to avoid creating a large number of wrapper functions to cover +all combinations of get*(), pin*(), FOLL_LONGTERM, and more. Also, the +pin_user_pages*() APIs are clearly distinct from the get_user_pages*() APIs, so +that's a natural dividing line, and a good point to make separate wrapper calls. +In other words, use pin_user_pages*() for DMA-pinned pages, and +get_user_pages*() for other cases. There are four cases described later on in +this document, to further clarify that concept.
+FOLL_PIN and FOLL_GET are mutually exclusive for a given gup call. However, +multiple threads and call sites are free to pin the same struct pages, via both +FOLL_PIN and FOLL_GET. It's just the call site that needs to choose one or the +other, not the struct page(s).
+The FOLL_PIN implementation is nearly the same as FOLL_GET, except that FOLL_PIN +uses a different reference counting technique.
+FOLL_PIN is a prerequisite to FOLL_LONGTGERM. Another way of saying that is,
FOLL_LONGTERM typoed there.
Thanks,
jon