Add the explanation of the added ioctl on pagemap file. It can be used
to get, clear or both soft-dirty PTE bit of the specified range.
or both at the same time.
Signed-off-by: Muhammad Usama Anjum <usama.anjum@xxxxxxxxxxxxx>
---
Changes in v2:
- Update documentation to mention ioctl instead of the syscall
---
Documentation/admin-guide/mm/soft-dirty.rst | 42 ++++++++++++++++++++-
1 file changed, 41 insertions(+), 1 deletion(-)
diff --git a/Documentation/admin-guide/mm/soft-dirty.rst b/Documentation/admin-guide/mm/soft-dirty.rst
index cb0cfd6672fa..d3d33e63a965 100644
--- a/Documentation/admin-guide/mm/soft-dirty.rst
+++ b/Documentation/admin-guide/mm/soft-dirty.rst
@@ -5,7 +5,12 @@ Soft-Dirty PTEs
===============
The soft-dirty is a bit on a PTE which helps to track which pages a task
-writes to. In order to do this tracking one should
+writes to.
+
+Using Proc FS
+-------------
+
+In order to do this tracking one should
1. Clear soft-dirty bits from the task's PTEs.
@@ -20,6 +25,41 @@ writes to. In order to do this tracking one should
64-bit qword is the soft-dirty one. If set, the respective PTE was
written to since step 1.
+Using IOCTL
+-----------
+
+The IOCTL on the ``/proc/PID/pagemap`` can be can be used to find the dirty pages
+atomically. The following commands are supported::
+
+ MEMWATCH_SD_GET
+ Get the page offsets which are soft dirty.
+
+ MEMWATCH_SD_CLEAR
+ Clear the pages which are soft dirty.
+
+ MEMWATCH_SD_GET_AND_CLEAR
+ Get and clear the pages which are soft dirty.
+
+The struct :c:type:`pagemap_sd_args` is used as the argument. In this struct:
+
+ 1. The range is specified through start and len. The len argument need not be
+ the multiple of the page size, but since the information is returned for the
+ whole pages, len is effectively rounded up to the next multiple of the page
+ size.
+
+ 2. The output buffer and size is specified in vec and vec_len. The offsets of
+ the dirty pages from start are returned in vec. The ioctl returns when the
+ whole range has been searched or vec is completely filled. The whole range
+ isn't cleared if vec fills up completely.
+
+ 3. The flags can be specified in flags field. Currently only one flag,
+ PAGEMAP_SD_NO_REUSED_REGIONS is supported which can be specified to ignore
+ the VMA dirty flags for better performance. This flag shows only those pages
+ dirty which have been written to by the user. All new allocations aren't returned
+ to be dirty.
+
+Explanation
+-----------
Internally, to do this tracking, the writable bit is cleared from PTEs
when the soft-dirty bit is cleared. So, after this, when the task tries to
--
2.30.2
