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 X-Spam-Level: X-Spam-Status: No, score=-0.7 required=3.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 67A29C00454 for ; Wed, 11 Dec 2019 20:57:43 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id 351352173E for ; Wed, 11 Dec 2019 20:57:43 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 351352173E Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=lwn.net Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id BB2F66B33E4; Wed, 11 Dec 2019 15:57:42 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id B3C086B33E5; Wed, 11 Dec 2019 15:57:42 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id A2AA76B33E6; Wed, 11 Dec 2019 15:57:42 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0113.hostedemail.com [216.40.44.113]) by kanga.kvack.org (Postfix) with ESMTP id 85FFE6B33E4 for ; Wed, 11 Dec 2019 15:57:42 -0500 (EST) Received: from smtpin22.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay04.hostedemail.com (Postfix) with SMTP id 54F1645C1 for ; Wed, 11 Dec 2019 20:57:42 +0000 (UTC) X-FDA: 76254071964.22.look97_7d63378f0e91e X-HE-Tag: look97_7d63378f0e91e X-Filterd-Recvd-Size: 5279 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by imf33.hostedemail.com (Postfix) with ESMTP for ; Wed, 11 Dec 2019 20:57:41 +0000 (UTC) Received: from lwn.net (localhost [127.0.0.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id 7D799739; Wed, 11 Dec 2019 20:57:38 +0000 (UTC) Date: Wed, 11 Dec 2019 13:57:37 -0700 From: Jonathan Corbet To: John Hubbard Cc: Andrew Morton , Al Viro , Alex Williamson , Benjamin Herrenschmidt , =?UTF-8?B?QmrDtnJuIFQ=?= =?UTF-8?B?w7ZwZWw=?= , Christoph Hellwig , Dan Williams , Daniel Vetter , Dave Chinner , David Airlie , "David S . Miller" , Ira Weiny , Jan Kara , Jason Gunthorpe , Jens Axboe , =?UTF-8?B?SsOpcsO0bWU=?= Glisse , Magnus Karlsson , Mauro Carvalho Chehab , Michael Ellerman , Michal Hocko , Mike Kravetz , Paul Mackerras , Shuah Khan , Vlastimil Babka , , , , , , , , , , , , , LKML , Mike Rapoport Subject: Re: [PATCH v9 10/25] mm/gup: introduce pin_user_pages*() and FOLL_PIN Message-ID: <20191211135737.581add2f@lwn.net> In-Reply-To: <20191211025318.457113-11-jhubbard@nvidia.com> References: <20191211025318.457113-1-jhubbard@nvidia.com> <20191211025318.457113-11-jhubbard@nvidia.com> Organization: LWN.net MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: On Tue, 10 Dec 2019 18:53:03 -0800 John Hubbard 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 > + > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D > +pin_user_pages() and related calls > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D > + > +.. contents:: :local: > + > +Overview > +=3D=3D=3D=3D=3D=3D=3D=3D > + > +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()." Bu= t that's a matter of personal taste, I guess. Using the function() notatio= n will cause the docs system to automatically link to the kerneldoc info, though. =20 > +Basic description of FOLL_PIN > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D > + > +FOLL_PIN and FOLL_LONGTERM are flags that can be passed to the get_use= r_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 fo= r problems > +as well. > + > +FOLL_LONGTERM, on the other hand, *is* allowed to be set at the gup ca= ll 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 wrap= per calls. > +In other words, use pin_user_pages*() for DMA-pinned pages, and > +get_user_pages*() for other cases. There are four cases described late= r on in > +this document, to further clarify that concept. > + > +FOLL_PIN and FOLL_GET are mutually exclusive for a given gup call. How= ever, > +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 on= e or the > +other, not the struct page(s). > + > +The FOLL_PIN implementation is nearly the same as FOLL_GET, except tha= t FOLL_PIN > +uses a different reference counting technique. > + > +FOLL_PIN is a prerequisite to FOLL_LONGTGERM. Another way of saying th= at is, FOLL_LONGTERM typoed there. Thanks, jon