]>
Commit | Line | Data |
---|---|---|
df9be302 BT |
1 | |
2 | What is udlfb? | |
3 | =============== | |
4 | ||
5 | This is a driver for DisplayLink USB 2.0 era graphics chips. | |
6 | ||
7 | DisplayLink chips provide simple hline/blit operations with some compression, | |
8 | pairing that with a hardware framebuffer (16MB) on the other end of the | |
9 | USB wire. That hardware framebuffer is able to drive the VGA, DVI, or HDMI | |
10 | monitor with no CPU involvement until a pixel has to change. | |
11 | ||
12 | The CPU or other local resource does all the rendering; optinally compares the | |
13 | result with a local shadow of the remote hardware framebuffer to identify | |
14 | the minimal set of pixels that have changed; and compresses and sends those | |
15 | pixels line-by-line via USB bulk transfers. | |
16 | ||
17 | Because of the efficiency of bulk transfers and a protocol on top that | |
18 | does not require any acks - the effect is very low latency that | |
19 | can support surprisingly high resolutions with good performance for | |
20 | non-gaming and non-video applications. | |
21 | ||
22 | Mode setting, EDID read, etc are other bulk or control transfers. Mode | |
23 | setting is very flexible - able to set nearly arbitrary modes from any timing. | |
24 | ||
25 | Advantages of USB graphics in general: | |
26 | ||
27 | * Ability to add a nearly arbitrary number of displays to any USB 2.0 | |
28 | capable system. On Linux, number of displays is limited by fbdev interface | |
29 | (FB_MAX is currently 32). Of course, all USB devices on the same | |
30 | host controller share the same 480Mbs USB 2.0 interface. | |
31 | ||
32 | Advantages of supporting DisplayLink chips with kernel framebuffer interface: | |
33 | ||
34 | * The actual hardware functionality of DisplayLink chips matches nearly | |
35 | one-to-one with the fbdev interface, making the driver quite small and | |
36 | tight relative to the functionality it provides. | |
37 | * X servers and other applications can use the standard fbdev interface | |
38 | from user mode to talk to the device, without needing to know anything | |
39 | about USB or DisplayLink's protocol at all. A "displaylink" X driver | |
40 | and a slightly modified "fbdev" X driver are among those that already do. | |
41 | ||
42 | Disadvantages: | |
43 | ||
44 | * Fbdev's mmap interface assumes a real hardware framebuffer is mapped. | |
45 | In the case of USB graphics, it is just an allocated (virtual) buffer. | |
46 | Writes need to be detected and encoded into USB bulk transfers by the CPU. | |
47 | Accurate damage/changed area notifications work around this problem. | |
48 | In the future, hopefully fbdev will be enhanced with an small standard | |
49 | interface to allow mmap clients to report damage, for the benefit | |
50 | of virtual or remote framebuffers. | |
51 | * Fbdev does not arbitrate client ownership of the framebuffer well. | |
52 | * Fbcon assumes the first framebuffer it finds should be consumed for console. | |
53 | * It's not clear what the future of fbdev is, given the rise of KMS/DRM. | |
54 | ||
55 | How to use it? | |
56 | ============== | |
57 | ||
58 | Udlfb, when loaded as a module, will match against all USB 2.0 generation | |
59 | DisplayLink chips (Alex and Ollie family). It will then attempt to read the EDID | |
60 | of the monitor, and set the best common mode between the DisplayLink device | |
61 | and the monitor's capabilities. | |
62 | ||
63 | If the DisplayLink device is successful, it will paint a "green screen" which | |
64 | means that from a hardware and fbdev software perspective, everything is good. | |
65 | ||
66 | At that point, a /dev/fb? interface will be present for user-mode applications | |
67 | to open and begin writing to the framebuffer of the DisplayLink device using | |
68 | standard fbdev calls. Note that if mmap() is used, by default the user mode | |
69 | application must send down damage notifcations to trigger repaints of the | |
70 | changed regions. Alternatively, udlfb can be recompiled with experimental | |
71 | defio support enabled, to support a page-fault based detection mechanism | |
72 | that can work without explicit notifcation. | |
73 | ||
74 | The most common client of udlfb is xf86-video-displaylink or a modified | |
75 | xf86-video-fbdev X server. These servers have no real DisplayLink specific | |
76 | code. They write to the standard framebuffer interface and rely on udlfb | |
77 | to do its thing. The one extra feature they have is the ability to report | |
78 | rectangles from the X DAMAGE protocol extension down to udlfb via udlfb's | |
79 | damage interface (which will hopefully be standardized for all virtual | |
80 | framebuffers that need damage info). These damage notifications allow | |
81 | udlfb to efficiently process the changed pixels. | |
82 | ||
83 | Module Options | |
84 | ============== | |
85 | ||
86 | Special configuration for udlfb is usually unnecessary. There are a few | |
87 | options, however. | |
88 | ||
89 | From the command line, pass options to modprobe | |
90 | modprobe udlfb defio=1 console=1 | |
91 | ||
92 | Or for permanent option, create file like /etc/modprobe.d/options with text | |
93 | options udlfb defio=1 console=1 | |
94 | ||
95 | Accepted options: | |
96 | ||
97 | fb_defio Make use of the fb_defio (CONFIG_FB_DEFERRED_IO) kernel | |
98 | module to track changed areas of the framebuffer by page faults. | |
99 | Standard fbdev applications that use mmap but that do not | |
100 | report damage, may be able to work with this enabled. | |
101 | Disabled by default because of overhead and other issues. | |
102 | ||
103 | console Allow fbcon to attach to udlfb provided framebuffers. This | |
104 | is disabled by default because fbcon will aggressively consume | |
105 | the first framebuffer it finds, which isn't usually what the | |
106 | user wants in the case of USB displays. | |
107 | ||
108 | Sysfs Attributes | |
109 | ================ | |
110 | ||
111 | Udlfb creates several files in /sys/class/graphics/fb? | |
112 | Where ? is the sequential framebuffer id of the particular DisplayLink device | |
113 | ||
114 | edid If a valid EDID blob is written to this file (typically | |
115 | by a udev rule), then udlfb will use this EDID as a | |
116 | backup in case reading the actual EDID of the monitor | |
117 | attached to the DisplayLink device fails. This is | |
118 | especially useful for fixed panels, etc. that cannot | |
119 | communicate their capabilities via EDID. Reading | |
120 | this file returns the current EDID of the attached | |
121 | monitor (or last backup value written). This is | |
122 | useful to get the EDID of the attached monitor, | |
123 | which can be passed to utilities like parse-edid. | |
124 | ||
125 | metrics_bytes_rendered 32-bit count of pixel bytes rendered | |
126 | ||
127 | metrics_bytes_identical 32-bit count of how many of those bytes were found to be | |
128 | unchanged, based on a shadow framebuffer check | |
129 | ||
130 | metrics_bytes_sent 32-bit count of how many bytes were transferred over | |
131 | USB to communicate the resulting changed pixels to the | |
132 | hardware. Includes compression and protocol overhead | |
133 | ||
134 | metrics_cpu_kcycles_used 32-bit count of CPU cycles used in processing the | |
135 | above pixels (in thousands of cycles). | |
136 | ||
137 | metrics_reset Write-only. Any write to this file resets all metrics | |
138 | above to zero. Note that the 32-bit counters above | |
139 | roll over very quickly. To get reliable results, design | |
140 | performance tests to start and finish in a very short | |
141 | period of time (one minute or less is safe). | |
142 | ||
143 | -- | |
144 | Bernie Thompson <bernie@plugable.com> |