Commit | Line | Data |
---|---|---|
1edca85e AD |
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 |