free_page_reporting.rst 2.0 KB

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