Root/
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> |
145 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9