0001 ==============
0002 What is udlfb?
0003 ==============
0004
0005 This is a driver for DisplayLink USB 2.0 era graphics chips.
0006
0007 DisplayLink chips provide simple hline/blit operations with some compression,
0008 pairing that with a hardware framebuffer (16MB) on the other end of the
0009 USB wire. That hardware framebuffer is able to drive the VGA, DVI, or HDMI
0010 monitor with no CPU involvement until a pixel has to change.
0011
0012 The CPU or other local resource does all the rendering; optionally compares the
0013 result with a local shadow of the remote hardware framebuffer to identify
0014 the minimal set of pixels that have changed; and compresses and sends those
0015 pixels line-by-line via USB bulk transfers.
0016
0017 Because of the efficiency of bulk transfers and a protocol on top that
0018 does not require any acks - the effect is very low latency that
0019 can support surprisingly high resolutions with good performance for
0020 non-gaming and non-video applications.
0021
0022 Mode setting, EDID read, etc are other bulk or control transfers. Mode
0023 setting is very flexible - able to set nearly arbitrary modes from any timing.
0024
0025 Advantages of USB graphics in general:
0026
0027 * Ability to add a nearly arbitrary number of displays to any USB 2.0
0028 capable system. On Linux, number of displays is limited by fbdev interface
0029 (FB_MAX is currently 32). Of course, all USB devices on the same
0030 host controller share the same 480Mbs USB 2.0 interface.
0031
0032 Advantages of supporting DisplayLink chips with kernel framebuffer interface:
0033
0034 * The actual hardware functionality of DisplayLink chips matches nearly
0035 one-to-one with the fbdev interface, making the driver quite small and
0036 tight relative to the functionality it provides.
0037 * X servers and other applications can use the standard fbdev interface
0038 from user mode to talk to the device, without needing to know anything
0039 about USB or DisplayLink's protocol at all. A "displaylink" X driver
0040 and a slightly modified "fbdev" X driver are among those that already do.
0041
0042 Disadvantages:
0043
0044 * Fbdev's mmap interface assumes a real hardware framebuffer is mapped.
0045 In the case of USB graphics, it is just an allocated (virtual) buffer.
0046 Writes need to be detected and encoded into USB bulk transfers by the CPU.
0047 Accurate damage/changed area notifications work around this problem.
0048 In the future, hopefully fbdev will be enhanced with an small standard
0049 interface to allow mmap clients to report damage, for the benefit
0050 of virtual or remote framebuffers.
0051 * Fbdev does not arbitrate client ownership of the framebuffer well.
0052 * Fbcon assumes the first framebuffer it finds should be consumed for console.
0053 * It's not clear what the future of fbdev is, given the rise of KMS/DRM.
0054
0055 How to use it?
0056 ==============
0057
0058 Udlfb, when loaded as a module, will match against all USB 2.0 generation
0059 DisplayLink chips (Alex and Ollie family). It will then attempt to read the EDID
0060 of the monitor, and set the best common mode between the DisplayLink device
0061 and the monitor's capabilities.
0062
0063 If the DisplayLink device is successful, it will paint a "green screen" which
0064 means that from a hardware and fbdev software perspective, everything is good.
0065
0066 At that point, a /dev/fb? interface will be present for user-mode applications
0067 to open and begin writing to the framebuffer of the DisplayLink device using
0068 standard fbdev calls. Note that if mmap() is used, by default the user mode
0069 application must send down damage notifications to trigger repaints of the
0070 changed regions. Alternatively, udlfb can be recompiled with experimental
0071 defio support enabled, to support a page-fault based detection mechanism
0072 that can work without explicit notification.
0073
0074 The most common client of udlfb is xf86-video-displaylink or a modified
0075 xf86-video-fbdev X server. These servers have no real DisplayLink specific
0076 code. They write to the standard framebuffer interface and rely on udlfb
0077 to do its thing. The one extra feature they have is the ability to report
0078 rectangles from the X DAMAGE protocol extension down to udlfb via udlfb's
0079 damage interface (which will hopefully be standardized for all virtual
0080 framebuffers that need damage info). These damage notifications allow
0081 udlfb to efficiently process the changed pixels.
0082
0083 Module Options
0084 ==============
0085
0086 Special configuration for udlfb is usually unnecessary. There are a few
0087 options, however.
0088
0089 From the command line, pass options to modprobe
0090 modprobe udlfb fb_defio=0 console=1 shadow=1
0091
0092 Or modify options on the fly at /sys/module/udlfb/parameters directory via
0093 sudo nano fb_defio
0094 change the parameter in place, and save the file.
0095
0096 Unplug/replug USB device to apply with new settings
0097
0098 Or for permanent option, create file like /etc/modprobe.d/udlfb.conf with text
0099 options udlfb fb_defio=0 console=1 shadow=1
0100
0101 Accepted boolean options:
0102
0103 =============== ================================================================
0104 fb_defio Make use of the fb_defio (CONFIG_FB_DEFERRED_IO) kernel
0105 module to track changed areas of the framebuffer by page faults.
0106 Standard fbdev applications that use mmap but that do not
0107 report damage, should be able to work with this enabled.
0108 Disable when running with X server that supports reporting
0109 changed regions via ioctl, as this method is simpler,
0110 more stable, and higher performance.
0111 default: fb_defio=1
0112
0113 console Allow fbcon to attach to udlfb provided framebuffers.
0114 Can be disabled if fbcon and other clients
0115 (e.g. X with --shared-vt) are in conflict.
0116 default: console=1
0117
0118 shadow Allocate a 2nd framebuffer to shadow what's currently across
0119 the USB bus in device memory. If any pixels are unchanged,
0120 do not transmit. Spends host memory to save USB transfers.
0121 Enabled by default. Only disable on very low memory systems.
0122 default: shadow=1
0123 =============== ================================================================
0124
0125 Sysfs Attributes
0126 ================
0127
0128 Udlfb creates several files in /sys/class/graphics/fb?
0129 Where ? is the sequential framebuffer id of the particular DisplayLink device
0130
0131 ======================== ========================================================
0132 edid If a valid EDID blob is written to this file (typically
0133 by a udev rule), then udlfb will use this EDID as a
0134 backup in case reading the actual EDID of the monitor
0135 attached to the DisplayLink device fails. This is
0136 especially useful for fixed panels, etc. that cannot
0137 communicate their capabilities via EDID. Reading
0138 this file returns the current EDID of the attached
0139 monitor (or last backup value written). This is
0140 useful to get the EDID of the attached monitor,
0141 which can be passed to utilities like parse-edid.
0142
0143 metrics_bytes_rendered 32-bit count of pixel bytes rendered
0144
0145 metrics_bytes_identical 32-bit count of how many of those bytes were found to be
0146 unchanged, based on a shadow framebuffer check
0147
0148 metrics_bytes_sent 32-bit count of how many bytes were transferred over
0149 USB to communicate the resulting changed pixels to the
0150 hardware. Includes compression and protocol overhead
0151
0152 metrics_cpu_kcycles_used 32-bit count of CPU cycles used in processing the
0153 above pixels (in thousands of cycles).
0154
0155 metrics_reset Write-only. Any write to this file resets all metrics
0156 above to zero. Note that the 32-bit counters above
0157 roll over very quickly. To get reliable results, design
0158 performance tests to start and finish in a very short
0159 period of time (one minute or less is safe).
0160 ======================== ========================================================
0161
0162 Bernie Thompson <bernie@plugable.com>
