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 E075BC43603 for ; Wed, 11 Dec 2019 20:57:42 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id C069D2173E for ; Wed, 11 Dec 2019 20:57:42 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org C069D2173E Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=lwn.net Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=dri-devel-bounces@lists.freedesktop.org Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id DBB2A6E0B8; Wed, 11 Dec 2019 20:57:41 +0000 (UTC) Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by gabe.freedesktop.org (Postfix) with ESMTPS id A83E96E0B8 for ; Wed, 11 Dec 2019 20:57:40 +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 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 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Michal Hocko , Jan Kara , kvm@vger.kernel.org, linux-doc@vger.kernel.org, David Airlie , Dave Chinner , dri-devel@lists.freedesktop.org, LKML , linux-mm@kvack.org, Paul Mackerras , linux-kselftest@vger.kernel.org, Ira Weiny , linux-rdma@vger.kernel.org, Michael Ellerman , Mike Rapoport , Christoph Hellwig , Jason Gunthorpe , Vlastimil Babka , =?UTF-8?B?QmrDtnJuIFQ=?= =?UTF-8?B?w7ZwZWw=?= , linux-media@vger.kernel.org, Shuah Khan , linux-block@vger.kernel.org, =?UTF-8?B?SsOpcsO0bWU=?= Glisse , Al Viro , Dan Williams , Mauro Carvalho Chehab , bpf@vger.kernel.org, Magnus Karlsson , Jens Axboe , netdev@vger.kernel.org, Alex Williamson , linux-fsdevel@vger.kernel.org, Andrew Morton , linuxppc-dev@lists.ozlabs.org, "David S . Miller" , Mike Kravetz Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" 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 _______________________________________________ dri-devel mailing list dri-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/dri-devel