diff mbox series

[v10,2/6] userfaultfd: update documentation to describe UFFD_FEATURE_WP_ASYNC

Message ID 20230202112915.867409-3-usama.anjum@collabora.com
State New
Headers show
Series Implement IOCTL to get and/or the clear info about PTEs | expand

Commit Message

Muhammad Usama Anjum Feb. 2, 2023, 11:29 a.m. UTC
Explain the difference created by UFFD_FEATURE_WP_ASYNC to the write
protection (UFFDIO_WRITEPROTECT_MODE_WP) mode.

Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
---
 Documentation/admin-guide/mm/userfaultfd.rst | 7 +++++++
 1 file changed, 7 insertions(+)

Comments

Peter Xu Feb. 8, 2023, 9:31 p.m. UTC | #1
On Thu, Feb 02, 2023 at 04:29:11PM +0500, Muhammad Usama Anjum wrote:
> Explain the difference created by UFFD_FEATURE_WP_ASYNC to the write
> protection (UFFDIO_WRITEPROTECT_MODE_WP) mode.
> 
> Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
> ---
>  Documentation/admin-guide/mm/userfaultfd.rst | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/Documentation/admin-guide/mm/userfaultfd.rst b/Documentation/admin-guide/mm/userfaultfd.rst
> index 83f31919ebb3..4747e7bd5b26 100644
> --- a/Documentation/admin-guide/mm/userfaultfd.rst
> +++ b/Documentation/admin-guide/mm/userfaultfd.rst
> @@ -221,6 +221,13 @@ former will have ``UFFD_PAGEFAULT_FLAG_WP`` set, the latter
>  you still need to supply a page when ``UFFDIO_REGISTER_MODE_MISSING`` was
>  used.
>  
> +If ``UFFD_FEATURE_WP_ASYNC`` is set while calling ``UFFDIO_API`` ioctl, the
> +behaviour of ``UFFDIO_WRITEPROTECT_MODE_WP`` changes such that faults for

UFFDIO_WRITEPROTECT_MODE_WP is only a flag in UFFDIO_WRITEPROTECT, while
it's forbidden only when not specified.

> +anon and shmem are resolved automatically by the kernel instead of sending
> +the message to the userfaultfd. The hugetlb isn't supported. The ``pagemap``
> +file can be read to find which pages have ``PM_UFFD_WP`` flag set which
> +means they are write-protected.

Here's my version. Please feel free to do modifications on top.

  If the userfaultfd context (that has ``UFFDIO_REGISTER_MODE_WP``
  registered against) has ``UFFD_FEATURE_WP_ASYNC`` feature enabled, it
  will work in async write protection mode.  It can be seen as a more
  accurate version of soft-dirty tracking, meanwhile the results will not
  be easily affected by other operations like vma merging.

  Comparing to the generic mode, the async mode will not generate any
  userfaultfd message when the protected memory range is written.  Instead,
  the kernel will automatically resolve the page fault immediately by
  dropping the uffd-wp bit in the pgtables.  The user app can collect the
  "written/dirty" status by looking up the uffd-wp bit for the pages being
  interested in /proc/pagemap.

  The page will be under track of uffd-wp async mode until the page is
  explicitly write-protected by ``UFFDIO_WRITEPROTECT`` ioctl with the mode
  flag ``UFFDIO_WRITEPROTECT_MODE_WP`` set.  Trying to resolve a page fault
  that was tracked by async mode userfaultfd-wp is invalid.

  Currently ``UFFD_FEATURE_WP_ASYNC`` only support anonymous and shmem.
  Hugetlb is not yet supported.
Muhammad Usama Anjum Feb. 9, 2023, 3:47 p.m. UTC | #2
On 2/9/23 2:31 AM, Peter Xu wrote:
> On Thu, Feb 02, 2023 at 04:29:11PM +0500, Muhammad Usama Anjum wrote:
>> Explain the difference created by UFFD_FEATURE_WP_ASYNC to the write
>> protection (UFFDIO_WRITEPROTECT_MODE_WP) mode.
>>
>> Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
>> ---
>>  Documentation/admin-guide/mm/userfaultfd.rst | 7 +++++++
>>  1 file changed, 7 insertions(+)
>>
>> diff --git a/Documentation/admin-guide/mm/userfaultfd.rst b/Documentation/admin-guide/mm/userfaultfd.rst
>> index 83f31919ebb3..4747e7bd5b26 100644
>> --- a/Documentation/admin-guide/mm/userfaultfd.rst
>> +++ b/Documentation/admin-guide/mm/userfaultfd.rst
>> @@ -221,6 +221,13 @@ former will have ``UFFD_PAGEFAULT_FLAG_WP`` set, the latter
>>  you still need to supply a page when ``UFFDIO_REGISTER_MODE_MISSING`` was
>>  used.
>>  
>> +If ``UFFD_FEATURE_WP_ASYNC`` is set while calling ``UFFDIO_API`` ioctl, the
>> +behaviour of ``UFFDIO_WRITEPROTECT_MODE_WP`` changes such that faults for
> 
> UFFDIO_WRITEPROTECT_MODE_WP is only a flag in UFFDIO_WRITEPROTECT, while
> it's forbidden only when not specified.
> 
>> +anon and shmem are resolved automatically by the kernel instead of sending
>> +the message to the userfaultfd. The hugetlb isn't supported. The ``pagemap``
>> +file can be read to find which pages have ``PM_UFFD_WP`` flag set which
>> +means they are write-protected.
> 
> Here's my version. Please feel free to do modifications on top.
> 
>   If the userfaultfd context (that has ``UFFDIO_REGISTER_MODE_WP``
>   registered against) has ``UFFD_FEATURE_WP_ASYNC`` feature enabled, it
>   will work in async write protection mode.  It can be seen as a more
>   accurate version of soft-dirty tracking, meanwhile the results will not
>   be easily affected by other operations like vma merging.
> 
>   Comparing to the generic mode, the async mode will not generate any
>   userfaultfd message when the protected memory range is written.  Instead,
>   the kernel will automatically resolve the page fault immediately by
>   dropping the uffd-wp bit in the pgtables.  The user app can collect the
>   "written/dirty" status by looking up the uffd-wp bit for the pages being
>   interested in /proc/pagemap.
> 
>   The page will be under track of uffd-wp async mode until the page is
>   explicitly write-protected by ``UFFDIO_WRITEPROTECT`` ioctl with the mode
>   flag ``UFFDIO_WRITEPROTECT_MODE_WP`` set.  Trying to resolve a page fault
>   that was tracked by async mode userfaultfd-wp is invalid.
> 
>   Currently ``UFFD_FEATURE_WP_ASYNC`` only support anonymous and shmem.
>   Hugetlb is not yet supported.
> 
It'll get replaced the documentation. I'll add a suggested by tag as well.
Thanks.
diff mbox series

Patch

diff --git a/Documentation/admin-guide/mm/userfaultfd.rst b/Documentation/admin-guide/mm/userfaultfd.rst
index 83f31919ebb3..4747e7bd5b26 100644
--- a/Documentation/admin-guide/mm/userfaultfd.rst
+++ b/Documentation/admin-guide/mm/userfaultfd.rst
@@ -221,6 +221,13 @@  former will have ``UFFD_PAGEFAULT_FLAG_WP`` set, the latter
 you still need to supply a page when ``UFFDIO_REGISTER_MODE_MISSING`` was
 used.
 
+If ``UFFD_FEATURE_WP_ASYNC`` is set while calling ``UFFDIO_API`` ioctl, the
+behaviour of ``UFFDIO_WRITEPROTECT_MODE_WP`` changes such that faults for
+anon and shmem are resolved automatically by the kernel instead of sending
+the message to the userfaultfd. The hugetlb isn't supported. The ``pagemap``
+file can be read to find which pages have ``PM_UFFD_WP`` flag set which
+means they are write-protected.
+
 QEMU/KVM
 ========