0001 .. _free_page_reporting:
0002
0003 =====================
0004 Free Page Reporting
0005 =====================
0006
0007 Free page reporting is an API by which a device can register to receive
0008 lists of pages that are currently unused by the system. This is useful in
0009 the case of virtualization where a guest is then able to use this data to
0010 notify the hypervisor that it is no longer using certain pages in memory.
0011
0012 For the driver, typically a balloon driver, to use of this functionality
0013 it will allocate and initialize a page_reporting_dev_info structure. The
0014 field within the structure it will populate is the "report" function
0015 pointer used to process the scatterlist. It must also guarantee that it can
0016 handle at least PAGE_REPORTING_CAPACITY worth of scatterlist entries per
0017 call to the function. A call to page_reporting_register will register the
0018 page reporting interface with the reporting framework assuming no other
0019 page reporting devices are already registered.
0020
0021 Once registered the page reporting API will begin reporting batches of
0022 pages to the driver. The API will start reporting pages 2 seconds after
0023 the interface is registered and will continue to do so 2 seconds after any
0024 page of a sufficiently high order is freed.
0025
0026 Pages reported will be stored in the scatterlist passed to the reporting
0027 function with the final entry having the end bit set in entry nent - 1.
0028 While pages are being processed by the report function they will not be
0029 accessible to the allocator. Once the report function has been completed
0030 the pages will be returned to the free area from which they were obtained.
0031
0032 Prior to removing a driver that is making use of free page reporting it
0033 is necessary to call page_reporting_unregister to have the
0034 page_reporting_dev_info structure that is currently in use by free page
0035 reporting removed. Doing this will prevent further reports from being
0036 issued via the interface. If another driver or the same driver is
0037 registered it is possible for it to resume where the previous driver had
0038 left off in terms of reporting free pages.
0039
0040 Alexander Duyck, Dec 04, 2019
