1*4882a593Smuzhiyun============== 2*4882a593SmuzhiyunWhat is udlfb? 3*4882a593Smuzhiyun============== 4*4882a593Smuzhiyun 5*4882a593SmuzhiyunThis is a driver for DisplayLink USB 2.0 era graphics chips. 6*4882a593Smuzhiyun 7*4882a593SmuzhiyunDisplayLink chips provide simple hline/blit operations with some compression, 8*4882a593Smuzhiyunpairing that with a hardware framebuffer (16MB) on the other end of the 9*4882a593SmuzhiyunUSB wire. That hardware framebuffer is able to drive the VGA, DVI, or HDMI 10*4882a593Smuzhiyunmonitor with no CPU involvement until a pixel has to change. 11*4882a593Smuzhiyun 12*4882a593SmuzhiyunThe CPU or other local resource does all the rendering; optionally compares the 13*4882a593Smuzhiyunresult with a local shadow of the remote hardware framebuffer to identify 14*4882a593Smuzhiyunthe minimal set of pixels that have changed; and compresses and sends those 15*4882a593Smuzhiyunpixels line-by-line via USB bulk transfers. 16*4882a593Smuzhiyun 17*4882a593SmuzhiyunBecause of the efficiency of bulk transfers and a protocol on top that 18*4882a593Smuzhiyundoes not require any acks - the effect is very low latency that 19*4882a593Smuzhiyuncan support surprisingly high resolutions with good performance for 20*4882a593Smuzhiyunnon-gaming and non-video applications. 21*4882a593Smuzhiyun 22*4882a593SmuzhiyunMode setting, EDID read, etc are other bulk or control transfers. Mode 23*4882a593Smuzhiyunsetting is very flexible - able to set nearly arbitrary modes from any timing. 24*4882a593Smuzhiyun 25*4882a593SmuzhiyunAdvantages of USB graphics in general: 26*4882a593Smuzhiyun 27*4882a593Smuzhiyun * Ability to add a nearly arbitrary number of displays to any USB 2.0 28*4882a593Smuzhiyun capable system. On Linux, number of displays is limited by fbdev interface 29*4882a593Smuzhiyun (FB_MAX is currently 32). Of course, all USB devices on the same 30*4882a593Smuzhiyun host controller share the same 480Mbs USB 2.0 interface. 31*4882a593Smuzhiyun 32*4882a593SmuzhiyunAdvantages of supporting DisplayLink chips with kernel framebuffer interface: 33*4882a593Smuzhiyun 34*4882a593Smuzhiyun * The actual hardware functionality of DisplayLink chips matches nearly 35*4882a593Smuzhiyun one-to-one with the fbdev interface, making the driver quite small and 36*4882a593Smuzhiyun tight relative to the functionality it provides. 37*4882a593Smuzhiyun * X servers and other applications can use the standard fbdev interface 38*4882a593Smuzhiyun from user mode to talk to the device, without needing to know anything 39*4882a593Smuzhiyun about USB or DisplayLink's protocol at all. A "displaylink" X driver 40*4882a593Smuzhiyun and a slightly modified "fbdev" X driver are among those that already do. 41*4882a593Smuzhiyun 42*4882a593SmuzhiyunDisadvantages: 43*4882a593Smuzhiyun 44*4882a593Smuzhiyun * Fbdev's mmap interface assumes a real hardware framebuffer is mapped. 45*4882a593Smuzhiyun In the case of USB graphics, it is just an allocated (virtual) buffer. 46*4882a593Smuzhiyun Writes need to be detected and encoded into USB bulk transfers by the CPU. 47*4882a593Smuzhiyun Accurate damage/changed area notifications work around this problem. 48*4882a593Smuzhiyun In the future, hopefully fbdev will be enhanced with an small standard 49*4882a593Smuzhiyun interface to allow mmap clients to report damage, for the benefit 50*4882a593Smuzhiyun of virtual or remote framebuffers. 51*4882a593Smuzhiyun * Fbdev does not arbitrate client ownership of the framebuffer well. 52*4882a593Smuzhiyun * Fbcon assumes the first framebuffer it finds should be consumed for console. 53*4882a593Smuzhiyun * It's not clear what the future of fbdev is, given the rise of KMS/DRM. 54*4882a593Smuzhiyun 55*4882a593SmuzhiyunHow to use it? 56*4882a593Smuzhiyun============== 57*4882a593Smuzhiyun 58*4882a593SmuzhiyunUdlfb, when loaded as a module, will match against all USB 2.0 generation 59*4882a593SmuzhiyunDisplayLink chips (Alex and Ollie family). It will then attempt to read the EDID 60*4882a593Smuzhiyunof the monitor, and set the best common mode between the DisplayLink device 61*4882a593Smuzhiyunand the monitor's capabilities. 62*4882a593Smuzhiyun 63*4882a593SmuzhiyunIf the DisplayLink device is successful, it will paint a "green screen" which 64*4882a593Smuzhiyunmeans that from a hardware and fbdev software perspective, everything is good. 65*4882a593Smuzhiyun 66*4882a593SmuzhiyunAt that point, a /dev/fb? interface will be present for user-mode applications 67*4882a593Smuzhiyunto open and begin writing to the framebuffer of the DisplayLink device using 68*4882a593Smuzhiyunstandard fbdev calls. Note that if mmap() is used, by default the user mode 69*4882a593Smuzhiyunapplication must send down damage notifications to trigger repaints of the 70*4882a593Smuzhiyunchanged regions. Alternatively, udlfb can be recompiled with experimental 71*4882a593Smuzhiyundefio support enabled, to support a page-fault based detection mechanism 72*4882a593Smuzhiyunthat can work without explicit notification. 73*4882a593Smuzhiyun 74*4882a593SmuzhiyunThe most common client of udlfb is xf86-video-displaylink or a modified 75*4882a593Smuzhiyunxf86-video-fbdev X server. These servers have no real DisplayLink specific 76*4882a593Smuzhiyuncode. They write to the standard framebuffer interface and rely on udlfb 77*4882a593Smuzhiyunto do its thing. The one extra feature they have is the ability to report 78*4882a593Smuzhiyunrectangles from the X DAMAGE protocol extension down to udlfb via udlfb's 79*4882a593Smuzhiyundamage interface (which will hopefully be standardized for all virtual 80*4882a593Smuzhiyunframebuffers that need damage info). These damage notifications allow 81*4882a593Smuzhiyunudlfb to efficiently process the changed pixels. 82*4882a593Smuzhiyun 83*4882a593SmuzhiyunModule Options 84*4882a593Smuzhiyun============== 85*4882a593Smuzhiyun 86*4882a593SmuzhiyunSpecial configuration for udlfb is usually unnecessary. There are a few 87*4882a593Smuzhiyunoptions, however. 88*4882a593Smuzhiyun 89*4882a593SmuzhiyunFrom the command line, pass options to modprobe 90*4882a593Smuzhiyunmodprobe udlfb fb_defio=0 console=1 shadow=1 91*4882a593Smuzhiyun 92*4882a593SmuzhiyunOr modify options on the fly at /sys/module/udlfb/parameters directory via 93*4882a593Smuzhiyunsudo nano fb_defio 94*4882a593Smuzhiyunchange the parameter in place, and save the file. 95*4882a593Smuzhiyun 96*4882a593SmuzhiyunUnplug/replug USB device to apply with new settings 97*4882a593Smuzhiyun 98*4882a593SmuzhiyunOr for permanent option, create file like /etc/modprobe.d/udlfb.conf with text 99*4882a593Smuzhiyunoptions udlfb fb_defio=0 console=1 shadow=1 100*4882a593Smuzhiyun 101*4882a593SmuzhiyunAccepted boolean options: 102*4882a593Smuzhiyun 103*4882a593Smuzhiyun=============== ================================================================ 104*4882a593Smuzhiyunfb_defio Make use of the fb_defio (CONFIG_FB_DEFERRED_IO) kernel 105*4882a593Smuzhiyun module to track changed areas of the framebuffer by page faults. 106*4882a593Smuzhiyun Standard fbdev applications that use mmap but that do not 107*4882a593Smuzhiyun report damage, should be able to work with this enabled. 108*4882a593Smuzhiyun Disable when running with X server that supports reporting 109*4882a593Smuzhiyun changed regions via ioctl, as this method is simpler, 110*4882a593Smuzhiyun more stable, and higher performance. 111*4882a593Smuzhiyun default: fb_defio=1 112*4882a593Smuzhiyun 113*4882a593Smuzhiyunconsole Allow fbcon to attach to udlfb provided framebuffers. 114*4882a593Smuzhiyun Can be disabled if fbcon and other clients 115*4882a593Smuzhiyun (e.g. X with --shared-vt) are in conflict. 116*4882a593Smuzhiyun default: console=1 117*4882a593Smuzhiyun 118*4882a593Smuzhiyunshadow Allocate a 2nd framebuffer to shadow what's currently across 119*4882a593Smuzhiyun the USB bus in device memory. If any pixels are unchanged, 120*4882a593Smuzhiyun do not transmit. Spends host memory to save USB transfers. 121*4882a593Smuzhiyun Enabled by default. Only disable on very low memory systems. 122*4882a593Smuzhiyun default: shadow=1 123*4882a593Smuzhiyun=============== ================================================================ 124*4882a593Smuzhiyun 125*4882a593SmuzhiyunSysfs Attributes 126*4882a593Smuzhiyun================ 127*4882a593Smuzhiyun 128*4882a593SmuzhiyunUdlfb creates several files in /sys/class/graphics/fb? 129*4882a593SmuzhiyunWhere ? is the sequential framebuffer id of the particular DisplayLink device 130*4882a593Smuzhiyun 131*4882a593Smuzhiyun======================== ======================================================== 132*4882a593Smuzhiyunedid If a valid EDID blob is written to this file (typically 133*4882a593Smuzhiyun by a udev rule), then udlfb will use this EDID as a 134*4882a593Smuzhiyun backup in case reading the actual EDID of the monitor 135*4882a593Smuzhiyun attached to the DisplayLink device fails. This is 136*4882a593Smuzhiyun especially useful for fixed panels, etc. that cannot 137*4882a593Smuzhiyun communicate their capabilities via EDID. Reading 138*4882a593Smuzhiyun this file returns the current EDID of the attached 139*4882a593Smuzhiyun monitor (or last backup value written). This is 140*4882a593Smuzhiyun useful to get the EDID of the attached monitor, 141*4882a593Smuzhiyun which can be passed to utilities like parse-edid. 142*4882a593Smuzhiyun 143*4882a593Smuzhiyunmetrics_bytes_rendered 32-bit count of pixel bytes rendered 144*4882a593Smuzhiyun 145*4882a593Smuzhiyunmetrics_bytes_identical 32-bit count of how many of those bytes were found to be 146*4882a593Smuzhiyun unchanged, based on a shadow framebuffer check 147*4882a593Smuzhiyun 148*4882a593Smuzhiyunmetrics_bytes_sent 32-bit count of how many bytes were transferred over 149*4882a593Smuzhiyun USB to communicate the resulting changed pixels to the 150*4882a593Smuzhiyun hardware. Includes compression and protocol overhead 151*4882a593Smuzhiyun 152*4882a593Smuzhiyunmetrics_cpu_kcycles_used 32-bit count of CPU cycles used in processing the 153*4882a593Smuzhiyun above pixels (in thousands of cycles). 154*4882a593Smuzhiyun 155*4882a593Smuzhiyunmetrics_reset Write-only. Any write to this file resets all metrics 156*4882a593Smuzhiyun above to zero. Note that the 32-bit counters above 157*4882a593Smuzhiyun roll over very quickly. To get reliable results, design 158*4882a593Smuzhiyun performance tests to start and finish in a very short 159*4882a593Smuzhiyun period of time (one minute or less is safe). 160*4882a593Smuzhiyun======================== ======================================================== 161*4882a593Smuzhiyun 162*4882a593SmuzhiyunBernie Thompson <bernie@plugable.com> 163