From: Alexander Duyck <firstname.lastname@example.org> To: email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com Cc: firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com Subject: [PATCH v15 7/7] mm: Add free page reporting documentation Date: Thu, 05 Dec 2019 08:23:04 -0800 [thread overview] Message-ID: <firstname.lastname@example.org> (raw) In-Reply-To: <email@example.com> From: Alexander Duyck <firstname.lastname@example.org> Add documentation for free 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 <email@example.com> --- Documentation/vm/free_page_reporting.rst | 41 ++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 Documentation/vm/free_page_reporting.rst diff --git a/Documentation/vm/free_page_reporting.rst b/Documentation/vm/free_page_reporting.rst new file mode 100644 index 000000000000..33f54a450a4a --- /dev/null +++ b/Documentation/vm/free_page_reporting.rst @@ -0,0 +1,41 @@ +.. _free_page_reporting: + +===================== +Free Page Reporting +===================== + +Free 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 +field within the structure it will populate is the "report" function +pointer used to process the scatterlist. It must also guarantee that it can +handle at least PAGE_REPORTING_CAPACITY worth of scatterlist entries per +call to the function. A call to page_reporting_register will register the +page reporting interface 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 will start reporting pages 2 seconds after +the interface is registered and will continue to do so 2 seconds after any +page of a sufficiently high order is freed. + +Pages reported will be stored in the scatterlist passed to the reporting +function 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 free page reporting it +is necessary to call page_reporting_unregister to have the +page_reporting_dev_info structure that is currently in use by free 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 free pages. + +Alexander Duyck, Dec 04, 2019 +
next prev parent reply other threads:[~2019-12-05 16:23 UTC|newest] Thread overview: 39+ messages / expand[flat|nested] mbox.gz Atom feed top 2019-12-05 16:22 [PATCH v15 0/7] mm / virtio: Provide support for free page reporting Alexander Duyck 2019-12-05 16:22 ` [PATCH v15 1/7] mm: Adjust shuffle code to allow for future coalescing Alexander Duyck 2019-12-05 16:22 ` [PATCH v15 2/7] mm: Use zone and order instead of free area in free_list manipulators Alexander Duyck 2019-12-05 16:22 ` [PATCH v15 3/7] mm: Add function __putback_isolated_page Alexander Duyck 2019-12-16 11:36 ` David Hildenbrand 2019-12-16 16:22 ` Alexander Duyck 2019-12-17 10:58 ` David Hildenbrand 2019-12-17 16:26 ` Alexander Duyck 2019-12-17 17:24 ` David Hildenbrand 2019-12-17 18:24 ` Alexander Duyck 2019-12-17 18:46 ` David Hildenbrand 2019-12-17 21:50 ` Alexander Duyck 2019-12-05 16:22 ` [PATCH v15 4/7] mm: Introduce Reported pages Alexander Duyck 2019-12-16 10:17 ` Nitesh Narayan Lal 2019-12-16 16:28 ` Alexander Duyck 2019-12-17 8:55 ` Nitesh Narayan Lal 2019-12-17 16:31 ` Alexander Duyck 2019-12-18 7:31 ` Mel Gorman 2019-12-16 11:44 ` Nitesh Narayan Lal 2019-12-16 16:10 ` Alexander Duyck 2019-12-05 16:22 ` [PATCH v15 5/7] virtio-balloon: Pull page poisoning config out of free page hinting Alexander Duyck 2019-12-13 7:03 ` Michael S. Tsirkin 2019-12-05 16:22 ` [PATCH v15 6/7] virtio-balloon: Add support for providing free page reports to host Alexander Duyck 2019-12-13 7:08 ` Michael S. Tsirkin 2019-12-13 16:35 ` Alexander Duyck 2019-12-15 9:29 ` Michael S. Tsirkin 2019-12-13 10:15 ` David Hildenbrand 2019-12-13 16:37 ` Alexander Duyck 2019-12-05 16:23 ` Alexander Duyck [this message] 2019-12-05 16:24 ` [PATCH v15 QEMU 1/3] virtio-ballon: Implement support for page poison tracking feature Alexander Duyck 2019-12-05 16:24 ` [PATCH v15 QEMU 2/3] virtio-balloon: Add bit to notify guest of unused page reporting Alexander Duyck 2019-12-05 16:24 ` [PATCH v15 QEMU 3/3] virtio-balloon: Provide a interface for " Alexander Duyck 2019-12-05 16:26 ` [PATCH v15 QEMU 4/3 RFC] memory: Add support for MADV_FREE as mechanism to lazy discard pages Alexander Duyck 2019-12-12 23:47 ` [PATCH v15 0/7] mm / virtio: Provide support for free page reporting Alexander Duyck 2019-12-13 10:00 ` David Hildenbrand 2019-12-13 11:08 ` Mel Gorman 2019-12-13 16:59 ` Alexander Duyck 2019-12-13 16:46 ` Alexander Duyck 2019-12-16 12:21 ` David Hildenbrand
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 \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --subject='Re: [PATCH v15 7/7] mm: Add free page reporting documentation' \ /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
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).