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 8DBAAC47409 for ; Wed, 11 Dec 2019 20:57:48 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 6E0C121556 for ; Wed, 11 Dec 2019 20:57:48 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726916AbfLKU5m (ORCPT ); Wed, 11 Dec 2019 15:57:42 -0500 Received: from ms.lwn.net ([45.79.88.28]:58190 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726141AbfLKU5l (ORCPT ); Wed, 11 Dec 2019 15:57:41 -0500 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: 8bit Sender: linux-rdma-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-rdma@vger.kernel.org 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 > + > +==================================================== > +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