• John Hubbard's avatar
    mm/gup: introduce pin_user_pages*() and FOLL_PIN · eddb1c22
    John Hubbard authored
    Introduce pin_user_pages*() variations of get_user_pages*() calls, and
    also pin_longterm_pages*() variations.
    
    For now, these are placeholder calls, until the various call sites are
    converted to use the correct get_user_pages*() or pin_user_pages*() API.
    
    These variants will eventually all set FOLL_PIN, which is also
    introduced, and thoroughly documented.
    
        pin_user_pages()
        pin_user_pages_remote()
        pin_user_pages_fast()
    
    All pages that are pinned via the above calls, must be unpinned via
    put_user_page().
    
    The underlying rules are:
    
    * FOLL_PIN is a gup-internal flag, so the call sites should not directly
      set it.  That behavior is enforced with assertions.
    
    * Call sites that want to indicate that they are going to do DirectIO
      ("DIO") or something with similar characteristics, should call a
      get_user_pages()-like wrapper call that sets FOLL_PIN.  These wrappers
      will:
    
        * Start with "pin_user_pages" instead of "get_user_pages".  That
          makes it easy to find and audit the call sites.
    
        * Set FOLL_PIN
    
    * For pages that are received via FOLL_PIN, those pages must be returned
      via put_user_page().
    
    Thanks to Jan Kara and Vlastimil Babka for explaining the 4 cases in
    this documentation.  (I've reworded it and expanded upon it.)
    
    Link: http://lkml.kernel.org/r/20200107224558.2362728-12-jhubbard@nvidia.com
    
    Signed-off-by: default avatarJohn Hubbard <jhubbard@nvidia.com>
    Reviewed-by: default avatarJan Kara <jack@suse.cz>
    Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>		[Documentation]
    Reviewed-by: default avatarJérôme Glisse <jglisse@redhat.com>
    Cc: Jonathan Corbet <corbet@lwn.net>
    Cc: Ira Weiny <ira.weiny@intel.com>
    Cc: Alex Williamson <alex.williamson@redhat.com>
    Cc: Aneesh Kumar K.V <aneesh.kumar@linux.ibm.com>
    Cc: Björn Töpel <bjorn.topel@intel.com>
    Cc: Christoph Hellwig <hch@lst.de>
    Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
    Cc: Dan Williams <dan.j.williams@intel.com>
    Cc: Hans Verkuil <hverkuil-cisco@xs4all.nl>
    Cc: Jason Gunthorpe <jgg@mellanox.com>
    Cc: Jason Gunthorpe <jgg@ziepe.ca>
    Cc: Jens Axboe <axboe@kernel.dk>
    Cc: Kirill A. Shutemov <kirill@shutemov.name>
    Cc: Leon Romanovsky <leonro@mellanox.com>
    Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
    Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
    Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
    eddb1c22
gup.c 70.9 KB