From: Muhammad Usama Anjum <usama.anjum@collabora.com>
To: "Peter Xu" <peterx@redhat.com>,
"David Hildenbrand" <david@redhat.com>,
"Andrew Morton" <akpm@linux-foundation.org>,
"Michał Mirosław" <emmir@google.com>,
"Andrei Vagin" <avagin@gmail.com>,
"Danylo Mocherniuk" <mdanylo@google.com>,
"Paul Gofman" <pgofman@codeweavers.com>,
"Cyrill Gorcunov" <gorcunov@gmail.com>,
"Mike Rapoport" <rppt@kernel.org>,
"Nadav Amit" <namit@vmware.com>
Cc: Alexander Viro <viro@zeniv.linux.org.uk>,
Shuah Khan <shuah@kernel.org>,
Christian Brauner <brauner@kernel.org>,
Yang Shi <shy828301@gmail.com>, Vlastimil Babka <vbabka@suse.cz>,
"Liam R . Howlett" <Liam.Howlett@Oracle.com>,
Yun Zhou <yun.zhou@windriver.com>,
Suren Baghdasaryan <surenb@google.com>,
Alex Sierra <alex.sierra@amd.com>,
Muhammad Usama Anjum <usama.anjum@collabora.com>,
Matthew Wilcox <willy@infradead.org>,
Pasha Tatashin <pasha.tatashin@soleen.com>,
Axel Rasmussen <axelrasmussen@google.com>,
"Gustavo A . R . Silva" <gustavoars@kernel.org>,
Dan Williams <dan.j.williams@intel.com>,
linux-kernel@vger.kernel.org, linux-fsdevel@vger.kernel.org,
linux-mm@kvack.org, linux-kselftest@vger.kernel.org,
Greg KH <gregkh@linuxfoundation.org>,
kernel@collabora.com
Subject: [PATCH v25 4/5] mm/pagemap: add documentation of PAGEMAP_SCAN IOCTL
Date: Thu, 13 Jul 2023 15:14:14 +0500 [thread overview]
Message-ID: <20230713101415.108875-5-usama.anjum@collabora.com> (raw)
In-Reply-To: <20230713101415.108875-1-usama.anjum@collabora.com>
Add some explanation and method to use write-protection and written-to
on memory range.
Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
---
Changes in v21:
- Update according to changed interface
Changes in v20:
- Add new flag in documentation
Changes in v19:
- Improved documentatiom with punctuation marks
Changes in v16:
- Update the documentation
Changes in v11:
- Add more documentation
rst
---
Documentation/admin-guide/mm/pagemap.rst | 58 ++++++++++++++++++++++++
1 file changed, 58 insertions(+)
diff --git a/Documentation/admin-guide/mm/pagemap.rst b/Documentation/admin-guide/mm/pagemap.rst
index c8f380271cad..4bdad8eff009 100644
--- a/Documentation/admin-guide/mm/pagemap.rst
+++ b/Documentation/admin-guide/mm/pagemap.rst
@@ -227,3 +227,61 @@ Before Linux 3.11 pagemap bits 55-60 were used for "page-shift" (which is
always 12 at most architectures). Since Linux 3.11 their meaning changes
after first clear of soft-dirty bits. Since Linux 4.2 they are used for
flags unconditionally.
+
+Pagemap Scan IOCTL
+==================
+
+The ``PAGEMAP_SCAN`` IOCTL on the pagemap file can be used to get or optionally
+clear the info about page table entries. The following operations are supported
+in this IOCTL:
+- Get the information if the pages have been written to (``PAGE_IS_WRITTEN``),
+ file mapped (``PAGE_IS_FILE``), present (``PAGE_IS_PRESENT``), swapped
+ (``PAGE_IS_SWAPPED``) or page has pfn zero (``PAGE_IS_PFNZERO``).
+- Find pages which have been written to and/or write protect the pages atomically
+ (atomic ``PM_SCAN_OP_GET + PM_SCAN_OP_WP``)
+
+The ``struct pm_scan_arg`` is used as the argument of the IOCTL.
+ 1. The size of the ``struct pm_scan_arg`` must be specified in the ``size``
+ field. This field will be helpful in recognizing the structure if extensions
+ are done later.
+ 2. The flags can be specified in the ``flags`` field. The ``PM_SCAN_OP_GET``
+ and ``PM_SCAN_OP_WP`` are the only added flags at this time.
+ 3. The range is specified through ``start`` and ``end``.
+ 4. The output buffer of ``struct page_region`` array and size is specified in
+ ``vec`` and ``vec_len``.
+ 5. The optional maximum requested pages are specified in the ``max_pages``.
+ 6. The masks are specified in ``required_mask``, ``anyof_mask``,
+ ``excluded_ mask`` and ``return_mask``.
+ 1. To find if ``PAGE_IS_WRITTEN`` flag is set for pages which have
+ ``PAGE_IS_FILE`` set and ``PAGE_IS_SWAPPED`` unset, ``required_mask``
+ is set to ``PAGE_IS_FILE``, ``exclude_mask`` is set to
+ ``PAGE_IS_SWAPPED`` and ``return_mask`` is set to ``PAGE_IS_WRITTEN``.
+ The output buffer in ``vec`` and length must be specified in ``vec_len``.
+ 2. To find pages which have either ``PAGE_IS_FILE`` or ``PAGE_IS_SWAPPED``
+ set, ``anyof_masks`` is set to ``PAGE_IS_FILE | PAGE_IS_SWAPPED``.
+ 3. To find written pages and engage write protect, ``PAGE_IS_WRITTEN`` is
+ specified in ``required_mask`` and ``return_mask``. In addition to
+ specifying the output buffer in ``vec`` and length in ``vec_len``, the
+ ``PM_SCAN_OP_WP`` is specified in ``flags`` to perform write protect
+ on the range as well.
+
+The ``PAGE_IS_WRITTEN`` flag can be considered as the better and correct
+alternative of soft-dirty flag. It doesn't get affected by housekeeping chores
+(VMA merging) of the kernel and hence the user can find the true soft-dirty pages
+only. This IOCTL adds the atomic way to find which pages have been written and
+write protect those pages again. This kind of operation is needed to efficiently
+find out which pages have changed in the memory.
+
+To get information about which pages have been written to or optionally write
+protect the pages, following must be performed first in order:
+ 1. The userfaultfd file descriptor is created with ``userfaultfd`` syscall.
+ 2. The ``UFFD_FEATURE_WP_UNPOPULATED`` and ``UFFD_FEATURE_WP_ASYNC`` features
+ are set by ``UFFDIO_API`` IOCTL.
+ 3. The memory range is registered with ``UFFDIO_REGISTER_MODE_WP`` mode
+ through ``UFFDIO_REGISTER`` IOCTL.
+ 4. Then any part of the registered memory or the whole memory region must
+ be write protected using ``PAGEMAP_SCAN`` IOCTL with flag ``PM_SCAN_OP_WP``
+ or the ``UFFDIO_WRITEPROTECT`` IOCTL can be used. Both of these perform the
+ same operation. The former is better in terms of performance.
+ 5. Now the ``PAGEMAP_SCAN`` IOCTL can be used to either just find pages which
+ have been written to and/or optionally write protect the pages as well.
--
2.39.2
next prev parent reply other threads:[~2023-07-13 10:15 UTC|newest]
Thread overview: 45+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-07-13 10:14 [PATCH v25 0/5] Implement IOCTL to get and optionally clear info about PTEs Muhammad Usama Anjum
2023-07-13 10:14 ` [PATCH v25 1/5] userfaultfd: UFFD_FEATURE_WP_ASYNC Muhammad Usama Anjum
2023-07-13 10:14 ` [PATCH v25 2/5] fs/proc/task_mmu: Implement IOCTL to get and optionally clear info about PTEs Muhammad Usama Anjum
2023-07-17 17:26 ` Andrei Vagin
2023-07-18 8:18 ` Muhammad Usama Anjum
2023-07-18 16:08 ` Andrei Vagin
2023-07-18 16:27 ` Muhammad Usama Anjum
2023-07-13 10:14 ` [PATCH v25 3/5] tools headers UAPI: Update linux/fs.h with the kernel sources Muhammad Usama Anjum
2023-07-13 10:14 ` Muhammad Usama Anjum [this message]
2023-07-13 10:14 ` [PATCH v25 5/5] selftests: mm: add pagemap ioctl tests Muhammad Usama Anjum
[not found] ` <a0b5c6776b2ed91f78a7575649f8b100e58bd3a9.1689881078.git.mirq-linux@rere.qmqm.pl>
2023-07-20 19:50 ` fs/proc/task_mmu: Implement IOCTL for efficient page table scanning Michał Mirosław
2023-07-20 21:12 ` kernel test robot
2023-07-21 2:56 ` kernel test robot
2023-07-21 4:27 ` Muhammad Usama Anjum
2023-07-21 14:49 ` Andrei Vagin
2023-07-21 5:43 ` kernel test robot
2023-07-21 7:18 ` kernel test robot
2023-07-21 10:48 ` Muhammad Usama Anjum
2023-07-21 11:23 ` Michał Mirosław
2023-07-21 17:50 ` Muhammad Usama Anjum
2023-07-22 0:22 ` Michał Mirosław
2023-07-22 0:24 ` [v2] " Michał Mirosław
2023-07-22 13:55 ` kernel test robot
2023-07-22 14:05 ` kernel test robot
2023-07-24 14:04 ` Muhammad Usama Anjum
2023-07-24 14:38 ` Michał Mirosław
2023-07-24 15:21 ` Muhammad Usama Anjum
2023-07-24 16:10 ` Michał Mirosław
2023-07-25 7:23 ` Muhammad Usama Anjum
2023-07-25 9:09 ` Muhammad Usama Anjum
2023-07-25 9:11 ` [v3] " Muhammad Usama Anjum
2023-07-25 18:05 ` Michał Mirosław
2023-07-26 8:34 ` Muhammad Usama Anjum
2023-07-26 21:10 ` Michał Mirosław
2023-07-26 23:06 ` Paul Gofman
2023-07-27 11:18 ` Michał Mirosław
2023-07-27 11:21 ` Michał Mirosław
2023-07-27 17:15 ` Paul Gofman
2023-07-27 8:03 ` Muhammad Usama Anjum
2023-07-27 11:26 ` Michał Mirosław
2023-07-27 11:31 ` Muhammad Usama Anjum
2023-07-21 11:29 ` Michał Mirosław
2023-07-21 17:51 ` Muhammad Usama Anjum
2023-08-26 13:07 ` kernel test robot
2023-07-18 16:05 ` [PATCH v25 0/5] Implement IOCTL to get and optionally clear info about PTEs Rogerio Alves
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230713101415.108875-5-usama.anjum@collabora.com \
--to=usama.anjum@collabora.com \
--cc=Liam.Howlett@Oracle.com \
--cc=akpm@linux-foundation.org \
--cc=alex.sierra@amd.com \
--cc=avagin@gmail.com \
--cc=axelrasmussen@google.com \
--cc=brauner@kernel.org \
--cc=dan.j.williams@intel.com \
--cc=david@redhat.com \
--cc=emmir@google.com \
--cc=gorcunov@gmail.com \
--cc=gregkh@linuxfoundation.org \
--cc=gustavoars@kernel.org \
--cc=kernel@collabora.com \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-kselftest@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=mdanylo@google.com \
--cc=namit@vmware.com \
--cc=pasha.tatashin@soleen.com \
--cc=peterx@redhat.com \
--cc=pgofman@codeweavers.com \
--cc=rppt@kernel.org \
--cc=shuah@kernel.org \
--cc=shy828301@gmail.com \
--cc=surenb@google.com \
--cc=vbabka@suse.cz \
--cc=viro@zeniv.linux.org.uk \
--cc=willy@infradead.org \
--cc=yun.zhou@windriver.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).