1*4882a593Smuzhiyun.. _free_page_reporting: 2*4882a593Smuzhiyun 3*4882a593Smuzhiyun===================== 4*4882a593SmuzhiyunFree Page Reporting 5*4882a593Smuzhiyun===================== 6*4882a593Smuzhiyun 7*4882a593SmuzhiyunFree page reporting is an API by which a device can register to receive 8*4882a593Smuzhiyunlists of pages that are currently unused by the system. This is useful in 9*4882a593Smuzhiyunthe case of virtualization where a guest is then able to use this data to 10*4882a593Smuzhiyunnotify the hypervisor that it is no longer using certain pages in memory. 11*4882a593Smuzhiyun 12*4882a593SmuzhiyunFor the driver, typically a balloon driver, to use of this functionality 13*4882a593Smuzhiyunit will allocate and initialize a page_reporting_dev_info structure. The 14*4882a593Smuzhiyunfield within the structure it will populate is the "report" function 15*4882a593Smuzhiyunpointer used to process the scatterlist. It must also guarantee that it can 16*4882a593Smuzhiyunhandle at least PAGE_REPORTING_CAPACITY worth of scatterlist entries per 17*4882a593Smuzhiyuncall to the function. A call to page_reporting_register will register the 18*4882a593Smuzhiyunpage reporting interface with the reporting framework assuming no other 19*4882a593Smuzhiyunpage reporting devices are already registered. 20*4882a593Smuzhiyun 21*4882a593SmuzhiyunOnce registered the page reporting API will begin reporting batches of 22*4882a593Smuzhiyunpages to the driver. The API will start reporting pages 2 seconds after 23*4882a593Smuzhiyunthe interface is registered and will continue to do so 2 seconds after any 24*4882a593Smuzhiyunpage of a sufficiently high order is freed. 25*4882a593Smuzhiyun 26*4882a593SmuzhiyunPages reported will be stored in the scatterlist passed to the reporting 27*4882a593Smuzhiyunfunction with the final entry having the end bit set in entry nent - 1. 28*4882a593SmuzhiyunWhile pages are being processed by the report function they will not be 29*4882a593Smuzhiyunaccessible to the allocator. Once the report function has been completed 30*4882a593Smuzhiyunthe pages will be returned to the free area from which they were obtained. 31*4882a593Smuzhiyun 32*4882a593SmuzhiyunPrior to removing a driver that is making use of free page reporting it 33*4882a593Smuzhiyunis necessary to call page_reporting_unregister to have the 34*4882a593Smuzhiyunpage_reporting_dev_info structure that is currently in use by free page 35*4882a593Smuzhiyunreporting removed. Doing this will prevent further reports from being 36*4882a593Smuzhiyunissued via the interface. If another driver or the same driver is 37*4882a593Smuzhiyunregistered it is possible for it to resume where the previous driver had 38*4882a593Smuzhiyunleft off in terms of reporting free pages. 39*4882a593Smuzhiyun 40*4882a593SmuzhiyunAlexander Duyck, Dec 04, 2019 41