[PATCH 19/19] Documentation/vm: add pin_user_pages.rst

[John Hubbard]

On 10/30/19 3:49 PM, John Hubbard wrote:
...
> +* struct page may not be increased in size for this, and all fields are already
> +  used.
> +
> +* Given the above, we can overload the page->_refcount field by using, sort of,
> +  the upper bits in that field for a dma-pinned count. "Sort of", means that,
> +  rather than dividing page->_refcount into bit fields, we simple add a medium-
> +  large value (GUP_PIN_COUNTING_BIAS, initially chosen to be 1024: 10 bits) to
> +  page->_refcount. This provides fuzzy behavior: if a page has get_page() called
> +  on it 1024 times, then it will appear to have a single dma-pinned count.
> +  And again, that's acceptable.
> +
> +This also leads to limitations: there are only 32-10==22 bits available for a
> +counter that increments 10 bits at a time.
> +

The above claim is just a "bit" too optimistic, by one bit: page->_refcount, being 
an atomic_t which uses a signed int (and we use the sign bit to check for overflow),
only has 31 total bits available for actual counting, not 32.

I'll adjust the documentation in v2, to account for this.

thanks,

John Hubbard
NVIDIA