On Wed, Nov 21, 2018 at 04:19:11AM -0700, William Kucharski wrote:

Could you add a line to the description explicitly stating that a failure
to insert any page in the range will fail the entire routine, something
like:

quoted

* This allows drivers to insert range of kernel pages they've allocated
* into a user vma. This is a generic function which drivers can use
* rather than using their own way of mapping range of kernel pages into
* user vma.
*
* A failure to insert any page in the range will fail the call as a whole.

It's obvious when reading the code, but it would be self-documenting to
state it outright.

It's probably better to be more explicit and answer Randy's question:

 * If we fail to insert any page into the vma, the function will return
 * immediately leaving any previously-inserted pages present.  Callers
 * from the mmap handler may immediately return the error as their
 * caller will destroy the vma, removing any successfully-inserted pages.
 * Other callers should make their own arrangements for calling unmap_region().

Although unmap_region() is static so there clearly isn't any code in the
kernel today other than in mmap handlers (or fault handlers) that needs to
insert pages into a VMA.