Linux-mm Archive on lore.kernel.org
 help / color / Atom feed
From: Alexander Duyck <alexander.duyck@gmail.com>
To: kvm@vger.kernel.org, mst@redhat.com,
	linux-kernel@vger.kernel.org, willy@infradead.org,
	mhocko@kernel.org, linux-mm@kvack.org, akpm@linux-foundation.org,
	mgorman@techsingularity.net, vbabka@suse.cz
Cc: yang.zhang.wz@gmail.com, nitesh@redhat.com,
	konrad.wilk@oracle.com, david@redhat.com, pagupta@redhat.com,
	riel@surriel.com, lcapitulino@redhat.com, dave.hansen@intel.com,
	wei.w.wang@intel.com, aarcange@redhat.com, pbonzini@redhat.com,
	dan.j.williams@intel.com, alexander.h.duyck@linux.intel.com,
	osalvador@suse.de
Subject: [PATCH v14 4/6] mm: Add unused page reporting documentation
Date: Tue, 19 Nov 2019 13:46:40 -0800
Message-ID: <20191119214640.24996.34494.stgit@localhost.localdomain> (raw)
In-Reply-To: <20191119214454.24996.66289.stgit@localhost.localdomain>

From: Alexander Duyck <alexander.h.duyck@linux.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@linux.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
+



  parent reply index

Thread overview: 31+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-11-19 21:46 [PATCH v14 0/6] mm / virtio: Provide support for unused page reporting Alexander Duyck
2019-11-19 21:46 ` [PATCH v14 1/6] mm: Adjust shuffle code to allow for future coalescing Alexander Duyck
2019-11-27 13:52   ` Mel Gorman
2019-11-19 21:46 ` [PATCH v14 2/6] mm: Use zone and order instead of free area in free_list manipulators Alexander Duyck
2019-11-27 13:54   ` Mel Gorman
2019-11-19 21:46 ` [PATCH v14 3/6] mm: Introduce Reported pages Alexander Duyck
2019-11-27 15:24   ` Mel Gorman
2019-11-27 17:22     ` Alexander Duyck
2019-11-27 18:35       ` Mel Gorman
2019-11-27 21:55         ` Alexander Duyck
2019-11-28  9:22           ` Mel Gorman
2019-11-29 19:25             ` Alexander Duyck
2019-11-19 21:46 ` Alexander Duyck [this message]
2019-11-19 21:46 ` [PATCH v14 5/6] virtio-balloon: Pull page poisoning config out of free page hinting Alexander Duyck
2019-11-19 21:46 ` [PATCH v14 6/6] virtio-balloon: Add support for providing unused page reports to host Alexander Duyck
2019-11-28 15:25   ` David Hildenbrand
2019-11-28 17:00     ` Michael S. Tsirkin
2019-12-04 17:48       ` Alexander Duyck
2019-12-04 17:53       ` Alexander Duyck
2019-11-29 21:13     ` Alexander Duyck
2019-12-01 11:46       ` Michael S. Tsirkin
2019-12-01 18:25         ` Alexander Duyck
2019-12-02 10:43       ` David Hildenbrand
2019-11-19 21:54 ` [PATCH v14 QEMU 1/3] virtio-ballon: Implement support for page poison tracking feature Alexander Duyck
2019-11-19 21:54 ` [PATCH v14 QEMU 2/3] virtio-balloon: Add bit to notify guest of unused page reporting Alexander Duyck
2019-11-19 21:54 ` [PATCH v14 QEMU 3/3] virtio-balloon: Provide a interface for " Alexander Duyck
2019-11-26 12:20 ` [PATCH v14 0/6] mm / virtio: Provide support " David Hildenbrand
2019-11-26 16:45   ` Alexander Duyck
2019-11-27 10:01     ` David Hildenbrand
2019-11-27 17:36       ` Alexander Duyck
2019-11-27 17:37         ` David Hildenbrand

Reply instructions:

You may reply publically 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=20191119214640.24996.34494.stgit@localhost.localdomain \
    --to=alexander.duyck@gmail.com \
    --cc=aarcange@redhat.com \
    --cc=akpm@linux-foundation.org \
    --cc=alexander.h.duyck@linux.intel.com \
    --cc=dan.j.williams@intel.com \
    --cc=dave.hansen@intel.com \
    --cc=david@redhat.com \
    --cc=konrad.wilk@oracle.com \
    --cc=kvm@vger.kernel.org \
    --cc=lcapitulino@redhat.com \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-mm@kvack.org \
    --cc=mgorman@techsingularity.net \
    --cc=mhocko@kernel.org \
    --cc=mst@redhat.com \
    --cc=nitesh@redhat.com \
    --cc=osalvador@suse.de \
    --cc=pagupta@redhat.com \
    --cc=pbonzini@redhat.com \
    --cc=riel@surriel.com \
    --cc=vbabka@suse.cz \
    --cc=wei.w.wang@intel.com \
    --cc=willy@infradead.org \
    --cc=yang.zhang.wz@gmail.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

Linux-mm Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-mm/0 linux-mm/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-mm linux-mm/ https://lore.kernel.org/linux-mm \
		linux-mm@kvack.org
	public-inbox-index linux-mm

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kvack.linux-mm


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git