1 ==============
2 What is udlfb?
3 ==============
4
5 This is a driver for DisplayLink USB 2.0 era g
6
7 DisplayLink chips provide simple hline/blit op
8 pairing that with a hardware framebuffer (16MB
9 USB wire. That hardware framebuffer is able t
10 monitor with no CPU involvement until a pixel
11
12 The CPU or other local resource does all the r
13 result with a local shadow of the remote hardw
14 the minimal set of pixels that have changed; a
15 pixels line-by-line via USB bulk transfers.
16
17 Because of the efficiency of bulk transfers an
18 does not require any acks - the effect is very
19 can support surprisingly high resolutions with
20 non-gaming and non-video applications.
21
22 Mode setting, EDID read, etc are other bulk or
23 setting is very flexible - able to set nearly
24
25 Advantages of USB graphics in general:
26
27 * Ability to add a nearly arbitrary number of
28 capable system. On Linux, number of display
29 (FB_MAX is currently 32). Of course, all US
30 host controller share the same 480Mbs USB 2
31
32 Advantages of supporting DisplayLink chips wit
33
34 * The actual hardware functionality of Displa
35 one-to-one with the fbdev interface, making
36 tight relative to the functionality it prov
37 * X servers and other applications can use th
38 from user mode to talk to the device, witho
39 about USB or DisplayLink's protocol at all.
40 and a slightly modified "fbdev" X driver ar
41
42 Disadvantages:
43
44 * Fbdev's mmap interface assumes a real hardw
45 In the case of USB graphics, it is just an
46 Writes need to be detected and encoded into
47 Accurate damage/changed area notifications
48 In the future, hopefully fbdev will be enha
49 interface to allow mmap clients to report d
50 of virtual or remote framebuffers.
51 * Fbdev does not arbitrate client ownership o
52 * Fbcon assumes the first framebuffer it find
53 * It's not clear what the future of fbdev is,
54
55 How to use it?
56 ==============
57
58 Udlfb, when loaded as a module, will match aga
59 DisplayLink chips (Alex and Ollie family). It
60 of the monitor, and set the best common mode b
61 and the monitor's capabilities.
62
63 If the DisplayLink device is successful, it wi
64 means that from a hardware and fbdev software
65
66 At that point, a /dev/fb? interface will be pr
67 to open and begin writing to the framebuffer o
68 standard fbdev calls. Note that if mmap() is
69 application must send down damage notification
70 changed regions. Alternatively, udlfb can be
71 defio support enabled, to support a page-fault
72 that can work without explicit notification.
73
74 The most common client of udlfb is xf86-video-
75 xf86-video-fbdev X server. These servers have
76 code. They write to the standard framebuffer i
77 to do its thing. The one extra feature they h
78 rectangles from the X DAMAGE protocol extensio
79 damage interface (which will hopefully be stan
80 framebuffers that need damage info). These dam
81 udlfb to efficiently process the changed pixel
82
83 Module Options
84 ==============
85
86 Special configuration for udlfb is usually unn
87 options, however.
88
89 From the command line, pass options to modprob
90
91 modprobe udlfb fb_defio=0 console=1 shadow=1
92
93 Or change options on the fly by editing
94 /sys/module/udlfb/parameters/PARAMETER_NAME ::
95
96 cd /sys/module/udlfb/parameters
97 ls # to see a list of parameter names
98 sudo nano PARAMETER_NAME
99 # change the parameter in place, and save th
100
101 Unplug/replug USB device to apply with new set
102
103 Or to apply options permanently, create a modp
104 like /etc/modprobe.d/udlfb.conf with text::
105
106 options udlfb fb_defio=0 console=1 shadow=1
107
108 Accepted boolean options:
109
110 =============== ==============================
111 fb_defio Make use of the fb_defio (CONF
112 module to track changed areas
113 Standard fbdev applications th
114 report damage, should be able
115 Disable when running with X se
116 changed regions via ioctl, as
117 more stable, and higher perfor
118 default: fb_defio=1
119
120 console Allow fbcon to attach to udlfb
121 Can be disabled if fbcon and o
122 (e.g. X with --shared-vt) are
123 default: console=1
124
125 shadow Allocate a 2nd framebuffer to
126 the USB bus in device memory.
127 do not transmit. Spends host m
128 Enabled by default. Only disab
129 default: shadow=1
130 =============== ==============================
131
132 Sysfs Attributes
133 ================
134
135 Udlfb creates several files in /sys/class/grap
136 Where ? is the sequential framebuffer id of th
137
138 ======================== =====================
139 edid If a valid EDID blob
140 by a udev rule), then
141 backup in case readin
142 attached to the Displ
143 especially useful for
144 communicate their cap
145 this file returns the
146 monitor (or last back
147 useful to get the EDI
148 which can be passed t
149
150 metrics_bytes_rendered 32-bit count of pixel
151
152 metrics_bytes_identical 32-bit count of how m
153 unchanged, based on a
154
155 metrics_bytes_sent 32-bit count of how m
156 USB to communicate th
157 hardware. Includes co
158
159 metrics_cpu_kcycles_used 32-bit count of CPU c
160 above pixels (in thou
161
162 metrics_reset Write-only. Any write
163 above to zero. Note
164 roll over very quickl
165 performance tests to
166 period of time (one m
167 ======================== =====================
168
169 Bernie Thompson <bernie@plugable.com>
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.