| Alexander Duyck | 1edca85 | 2020-04-06 20:05:18 -0700 | [diff] [blame] | 1 | .. _free_page_reporting: |
| 2 | |
| 3 | ===================== |
| 4 | Free Page Reporting |
| 5 | ===================== |
| 6 | |
| 7 | Free page reporting is an API by which a device can register to receive |
| 8 | lists of pages that are currently unused by the system. This is useful in |
| 9 | the case of virtualization where a guest is then able to use this data to |
| 10 | notify the hypervisor that it is no longer using certain pages in memory. |
| 11 | |
| 12 | For the driver, typically a balloon driver, to use of this functionality |
| 13 | it will allocate and initialize a page_reporting_dev_info structure. The |
| 14 | field within the structure it will populate is the "report" function |
| 15 | pointer used to process the scatterlist. It must also guarantee that it can |
| 16 | handle at least PAGE_REPORTING_CAPACITY worth of scatterlist entries per |
| 17 | call to the function. A call to page_reporting_register will register the |
| 18 | page reporting interface with the reporting framework assuming no other |
| 19 | page reporting devices are already registered. |
| 20 | |
| 21 | Once registered the page reporting API will begin reporting batches of |
| 22 | pages to the driver. The API will start reporting pages 2 seconds after |
| 23 | the interface is registered and will continue to do so 2 seconds after any |
| 24 | page of a sufficiently high order is freed. |
| 25 | |
| 26 | Pages reported will be stored in the scatterlist passed to the reporting |
| 27 | function with the final entry having the end bit set in entry nent - 1. |
| 28 | While pages are being processed by the report function they will not be |
| 29 | accessible to the allocator. Once the report function has been completed |
| 30 | the pages will be returned to the free area from which they were obtained. |
| 31 | |
| 32 | Prior to removing a driver that is making use of free page reporting it |
| 33 | is necessary to call page_reporting_unregister to have the |
| 34 | page_reporting_dev_info structure that is currently in use by free page |
| 35 | reporting removed. Doing this will prevent further reports from being |
| 36 | issued via the interface. If another driver or the same driver is |
| 37 | registered it is possible for it to resume where the previous driver had |
| 38 | left off in terms of reporting free pages. |
| 39 | |
| 40 | Alexander Duyck, Dec 04, 2019 |