0001 ===========
0002 Deferred IO
0003 ===========
0004
0005 Deferred IO is a way to delay and repurpose IO. It uses host memory as a
0006 buffer and the MMU pagefault as a pretrigger for when to perform the device
0007 IO. The following example may be a useful explanation of how one such setup
0008 works:
0009
0010 - userspace app like Xfbdev mmaps framebuffer
0011 - deferred IO and driver sets up fault and page_mkwrite handlers
0012 - userspace app tries to write to mmaped vaddress
0013 - we get pagefault and reach fault handler
0014 - fault handler finds and returns physical page
0015 - we get page_mkwrite where we add this page to a list
0016 - schedule a workqueue task to be run after a delay
0017 - app continues writing to that page with no additional cost. this is
0018 the key benefit.
0019 - the workqueue task comes in and mkcleans the pages on the list, then
0020 completes the work associated with updating the framebuffer. this is
0021 the real work talking to the device.
0022 - app tries to write to the address (that has now been mkcleaned)
0023 - get pagefault and the above sequence occurs again
0024
0025 As can be seen from above, one benefit is roughly to allow bursty framebuffer
0026 writes to occur at minimum cost. Then after some time when hopefully things
0027 have gone quiet, we go and really update the framebuffer which would be
0028 a relatively more expensive operation.
0029
0030 For some types of nonvolatile high latency displays, the desired image is
0031 the final image rather than the intermediate stages which is why it's okay
0032 to not update for each write that is occurring.
0033
0034 It may be the case that this is useful in other scenarios as well. Paul Mundt
0035 has mentioned a case where it is beneficial to use the page count to decide
0036 whether to coalesce and issue SG DMA or to do memory bursts.
0037
0038 Another one may be if one has a device framebuffer that is in an usual format,
0039 say diagonally shifting RGB, this may then be a mechanism for you to allow
0040 apps to pretend to have a normal framebuffer but reswizzle for the device
0041 framebuffer at vsync time based on the touched pagelist.
0042
0043 How to use it: (for applications)
0044 ---------------------------------
0045 No changes needed. mmap the framebuffer like normal and just use it.
0046
0047 How to use it: (for fbdev drivers)
0048 ----------------------------------
0049 The following example may be helpful.
0050
0051 1. Setup your structure. Eg::
0052
0053 static struct fb_deferred_io hecubafb_defio = {
0054 .delay = HZ,
0055 .deferred_io = hecubafb_dpy_deferred_io,
0056 };
0057
0058 The delay is the minimum delay between when the page_mkwrite trigger occurs
0059 and when the deferred_io callback is called. The deferred_io callback is
0060 explained below.
0061
0062 2. Setup your deferred IO callback. Eg::
0063
0064 static void hecubafb_dpy_deferred_io(struct fb_info *info,
0065 struct list_head *pagelist)
0066
0067 The deferred_io callback is where you would perform all your IO to the display
0068 device. You receive the pagelist which is the list of pages that were written
0069 to during the delay. You must not modify this list. This callback is called
0070 from a workqueue.
0071
0072 3. Call init::
0073
0074 info->fbdefio = &hecubafb_defio;
0075 fb_deferred_io_init(info);
0076
0077 4. Call cleanup::
0078
0079 fb_deferred_io_cleanup(info);
