Commit 1edca85e authored by Alexander Duyck's avatar Alexander Duyck Committed by Linus Torvalds
Browse files

mm/page_reporting: add free page reporting documentation 



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: default avatarAlexander Duyck <alexander.h.duyck@linux.intel.com>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
Cc: Andrea Arcangeli <aarcange@redhat.com>
Cc: Dan Williams <dan.j.williams@intel.com>
Cc: Dave Hansen <dave.hansen@intel.com>
Cc: David Hildenbrand <david@redhat.com>
Cc: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
Cc: Luiz Capitulino <lcapitulino@redhat.com>
Cc: Matthew Wilcox <willy@infradead.org>
Cc: Mel Gorman <mgorman@techsingularity.net>
Cc: Michael S. Tsirkin <mst@redhat.com>
Cc: Michal Hocko <mhocko@kernel.org>
Cc: Nitesh Narayan Lal <nitesh@redhat.com>
Cc: Oscar Salvador <osalvador@suse.de>
Cc: Pankaj Gupta <pagupta@redhat.com>
Cc: Paolo Bonzini <pbonzini@redhat.com>
Cc: Rik van Riel <riel@surriel.com>
Cc: Vlastimil Babka <vbabka@suse.cz>
Cc: Wei Wang <wei.w.wang@intel.com>
Cc: Yang Zhang <yang.zhang.wz@gmail.com>
Cc: wei qi <weiqi4@huawei.com>
Link: http://lkml.kernel.org/r/20200211224730.29318.43815.stgit@localhost.localdomain


Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 43b76f29

Documentation/vm/free_page_reporting.rst

0 → 100644
+40 −0
Original line number Original line Diff line number Diff line 
.. _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

CRA Git | Maintained and supported by SUSTech CRA and CCSE