Message-ID: <20191119214640.24996.34494.stgit@localhost.localdomain>
Date:   Tue, 19 Nov 2019 13:46:40 -0800
From:   Alexander Duyck <alexander.duyck@...il.com>
To:     kvm@...r.kernel.org, mst@...hat.com, linux-kernel@...r.kernel.org,
        willy@...radead.org, mhocko@...nel.org, linux-mm@...ck.org,
        akpm@...ux-foundation.org, mgorman@...hsingularity.net,
        vbabka@...e.cz
Cc:     yang.zhang.wz@...il.com, nitesh@...hat.com, konrad.wilk@...cle.com,
        david@...hat.com, pagupta@...hat.com, riel@...riel.com,
        lcapitulino@...hat.com, dave.hansen@...el.com,
        wei.w.wang@...el.com, aarcange@...hat.com, pbonzini@...hat.com,
        dan.j.williams@...el.com, alexander.h.duyck@...ux.intel.com,
        osalvador@...e.de
Subject: [PATCH v14 4/6] mm: Add unused page reporting documentation

From: Alexander Duyck <alexander.h.duyck@...ux.intel.com>

Add documentation for unused page reporting. Currently the only consumer is
virtio-balloon, however it is possible that other drivers might make use of
this so it is best to add a bit of documetation explaining at a high level
how to use the API.

Signed-off-by: Alexander Duyck <alexander.h.duyck@...ux.intel.com>
---
 Documentation/vm/unused_page_reporting.rst |   44 ++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 Documentation/vm/unused_page_reporting.rst

diff --git a/Documentation/vm/unused_page_reporting.rst b/Documentation/vm/unused_page_reporting.rst
new file mode 100644
index 000000000000..932406f48842
--- /dev/null
+++ b/Documentation/vm/unused_page_reporting.rst
@@ -0,0 +1,44 @@
+.. _unused_page_reporting:
+
+=====================
+Unused Page Reporting
+=====================
+
+Unused page reporting is an API by which a device can register to receive
+lists of pages that are currently unused by the system. This is useful in
+the case of virtualization where a guest is then able to use this data to
+notify the hypervisor that it is no longer using certain pages in memory.
+
+For the driver, typically a balloon driver, to use of this functionality
+it will allocate and initialize a page_reporting_dev_info structure. The
+fields within the structure it will populate are the "report" function
+pointer used to process the scatterlist and "capacity" representing the
+number of entries that the device can support in a single request. Once
+those are populated a call to page_reporting_register will allocate the
+scatterlist and register the device with the reporting framework assuming
+no other page reporting devices are already registered.
+
+Once registered the page reporting API will begin reporting batches of
+pages to the driver. The API determines that it needs to start reporting by
+measuring the number of pages in a given free area versus the number of
+reported pages for that free area. If the value meets or exceeds the value
+defined by PAGE_REPORTING_HWM then the zone is flagged as requesting
+reporting and a worker is scheduled to process zone requesting reporting.
+
+Pages reported will be stored in the scatterlist pointed to in the
+page_reporting_dev_info with the final entry having the end bit set in
+entry nent - 1. While pages are being processed by the report function they
+will not be accessible to the allocator. Once the report function has been
+completed the pages will be returned to the free area from which they were
+obtained.
+
+Prior to removing a driver that is making use of unused page reporting it
+is necessary to call page_reporting_unregister to have the
+page_reporting_dev_info structure that is currently in use by unused page
+reporting removed. Doing this will prevent further reports from being
+issued via the interface. If another driver or the same driver is
+registered it is possible for it to resume where the previous driver had
+left off in terms of reporting unused pages.
+
+Alexander Duyck, Nov 15, 2019
+

Powered by blists - more mailing lists