1 ======================= 1 =======================
2 The Frame Buffer Device 2 The Frame Buffer Device
3 ======================= 3 =======================
4 4
5 Last revised: May 10, 2001 5 Last revised: May 10, 2001
6 6
7 7
8 0. Introduction 8 0. Introduction
9 --------------- 9 ---------------
10 10
11 The frame buffer device provides an abstractio 11 The frame buffer device provides an abstraction for the graphics hardware. It
12 represents the frame buffer of some video hard 12 represents the frame buffer of some video hardware and allows application
13 software to access the graphics hardware throu 13 software to access the graphics hardware through a well-defined interface, so
14 the software doesn't need to know anything abo 14 the software doesn't need to know anything about the low-level (hardware
15 register) stuff. 15 register) stuff.
16 16
17 The device is accessed through special device 17 The device is accessed through special device nodes, usually located in the
18 /dev directory, i.e. /dev/fb*. 18 /dev directory, i.e. /dev/fb*.
19 19
20 20
21 1. User's View of /dev/fb* 21 1. User's View of /dev/fb*
22 -------------------------- 22 --------------------------
23 23
24 From the user's point of view, the frame buffe 24 From the user's point of view, the frame buffer device looks just like any
25 other device in /dev. It's a character device 25 other device in /dev. It's a character device using major 29; the minor
26 specifies the frame buffer number. 26 specifies the frame buffer number.
27 27
28 By convention, the following device nodes are 28 By convention, the following device nodes are used (numbers indicate the device
29 minor numbers):: 29 minor numbers)::
30 30
31 0 = /dev/fb0 First frame buffer 31 0 = /dev/fb0 First frame buffer
32 1 = /dev/fb1 Second frame buffer 32 1 = /dev/fb1 Second frame buffer
33 ... 33 ...
34 31 = /dev/fb31 32nd frame buffer 34 31 = /dev/fb31 32nd frame buffer
35 35
36 For backwards compatibility, you may want to c 36 For backwards compatibility, you may want to create the following symbolic
37 links:: 37 links::
38 38
39 /dev/fb0current -> fb0 39 /dev/fb0current -> fb0
40 /dev/fb1current -> fb1 40 /dev/fb1current -> fb1
41 41
42 and so on... 42 and so on...
43 43
44 The frame buffer devices are also `normal` mem 44 The frame buffer devices are also `normal` memory devices, this means, you can
45 read and write their contents. You can, for ex 45 read and write their contents. You can, for example, make a screen snapshot by::
46 46
47 cp /dev/fb0 myfile 47 cp /dev/fb0 myfile
48 48
49 There also can be more than one frame buffer a 49 There also can be more than one frame buffer at a time, e.g. if you have a
50 graphics card in addition to the built-in hard 50 graphics card in addition to the built-in hardware. The corresponding frame
51 buffer devices (/dev/fb0 and /dev/fb1 etc.) wo 51 buffer devices (/dev/fb0 and /dev/fb1 etc.) work independently.
52 52
53 Application software that uses the frame buffe 53 Application software that uses the frame buffer device (e.g. the X server) will
54 use /dev/fb0 by default (older software uses / 54 use /dev/fb0 by default (older software uses /dev/fb0current). You can specify
55 an alternative frame buffer device by setting 55 an alternative frame buffer device by setting the environment variable
56 $FRAMEBUFFER to the path name of a frame buffe 56 $FRAMEBUFFER to the path name of a frame buffer device, e.g. (for sh/bash
57 users):: 57 users)::
58 58
59 export FRAMEBUFFER=/dev/fb1 59 export FRAMEBUFFER=/dev/fb1
60 60
61 or (for csh users):: 61 or (for csh users)::
62 62
63 setenv FRAMEBUFFER /dev/fb1 63 setenv FRAMEBUFFER /dev/fb1
64 64
65 After this the X server will use the second fr 65 After this the X server will use the second frame buffer.
66 66
67 67
68 2. Programmer's View of /dev/fb* 68 2. Programmer's View of /dev/fb*
69 -------------------------------- 69 --------------------------------
70 70
71 As you already know, a frame buffer device is 71 As you already know, a frame buffer device is a memory device like /dev/mem and
72 it has the same features. You can read it, wri 72 it has the same features. You can read it, write it, seek to some location in
73 it and mmap() it (the main usage). The differe 73 it and mmap() it (the main usage). The difference is just that the memory that
74 appears in the special file is not the whole m 74 appears in the special file is not the whole memory, but the frame buffer of
75 some video hardware. 75 some video hardware.
76 76
77 /dev/fb* also allows several ioctls on it, by 77 /dev/fb* also allows several ioctls on it, by which lots of information about
78 the hardware can be queried and set. The color 78 the hardware can be queried and set. The color map handling works via ioctls,
79 too. Look into <linux/fb.h> for more informati 79 too. Look into <linux/fb.h> for more information on what ioctls exist and on
80 which data structures they work. Here's just a 80 which data structures they work. Here's just a brief overview:
81 81
82 - You can request unchangeable information a 82 - You can request unchangeable information about the hardware, like name,
83 organization of the screen memory (planes, 83 organization of the screen memory (planes, packed pixels, ...) and address
84 and length of the screen memory. 84 and length of the screen memory.
85 85
86 - You can request and change variable inform 86 - You can request and change variable information about the hardware, like
87 visible and virtual geometry, depth, color 87 visible and virtual geometry, depth, color map format, timing, and so on.
88 If you try to change that information, the 88 If you try to change that information, the driver maybe will round up some
89 values to meet the hardware's capabilities 89 values to meet the hardware's capabilities (or return EINVAL if that isn't
90 possible). 90 possible).
91 91
92 - You can get and set parts of the color map 92 - You can get and set parts of the color map. Communication is done with 16
93 bits per color part (red, green, blue, tra 93 bits per color part (red, green, blue, transparency) to support all
94 existing hardware. The driver does all the 94 existing hardware. The driver does all the computations needed to apply
95 it to the hardware (round it down to less 95 it to the hardware (round it down to less bits, maybe throw away
96 transparency). 96 transparency).
97 97
98 All this hardware abstraction makes the implem 98 All this hardware abstraction makes the implementation of application programs
99 easier and more portable. E.g. the X server wo 99 easier and more portable. E.g. the X server works completely on /dev/fb* and
100 thus doesn't need to know, for example, how th 100 thus doesn't need to know, for example, how the color registers of the concrete
101 hardware are organized. XF68_FBDev is a genera 101 hardware are organized. XF68_FBDev is a general X server for bitmapped,
102 unaccelerated video hardware. The only thing t 102 unaccelerated video hardware. The only thing that has to be built into
103 application programs is the screen organizatio 103 application programs is the screen organization (bitplanes or chunky pixels
104 etc.), because it works on the frame buffer im 104 etc.), because it works on the frame buffer image data directly.
105 105
106 For the future it is planned that frame buffer 106 For the future it is planned that frame buffer drivers for graphics cards and
107 the like can be implemented as kernel modules 107 the like can be implemented as kernel modules that are loaded at runtime. Such
108 a driver just has to call register_framebuffer 108 a driver just has to call register_framebuffer() and supply some functions.
109 Writing and distributing such drivers independ 109 Writing and distributing such drivers independently from the kernel will save
110 much trouble... 110 much trouble...
111 111
112 112
113 3. Frame Buffer Resolution Maintenance 113 3. Frame Buffer Resolution Maintenance
114 -------------------------------------- 114 --------------------------------------
115 115
116 Frame buffer resolutions are maintained using 116 Frame buffer resolutions are maintained using the utility `fbset`. It can
117 change the video mode properties of a frame bu 117 change the video mode properties of a frame buffer device. Its main usage is
118 to change the current video mode, e.g. during 118 to change the current video mode, e.g. during boot up in one of your `/etc/rc.*`
119 or `/etc/init.d/*` files. 119 or `/etc/init.d/*` files.
120 120
121 Fbset uses a video mode database stored in a c 121 Fbset uses a video mode database stored in a configuration file, so you can
122 easily add your own modes and refer to them wi 122 easily add your own modes and refer to them with a simple identifier.
123 123
124 124
125 4. The X Server 125 4. The X Server
126 --------------- 126 ---------------
127 127
128 The X server (XF68_FBDev) is the most notable 128 The X server (XF68_FBDev) is the most notable application program for the frame
129 buffer device. Starting with XFree86 release 3 129 buffer device. Starting with XFree86 release 3.2, the X server is part of
130 XFree86 and has 2 modes: 130 XFree86 and has 2 modes:
131 131
132 - If the `Display` subsection for the `fbdev 132 - If the `Display` subsection for the `fbdev` driver in the /etc/XF86Config
133 file contains a:: 133 file contains a::
134 134
135 Modes "default" 135 Modes "default"
136 136
137 line, the X server will use the scheme dis 137 line, the X server will use the scheme discussed above, i.e. it will start
138 up in the resolution determined by /dev/fb 138 up in the resolution determined by /dev/fb0 (or $FRAMEBUFFER, if set). You
139 still have to specify the color depth (usi 139 still have to specify the color depth (using the Depth keyword) and virtual
140 resolution (using the Virtual keyword) tho 140 resolution (using the Virtual keyword) though. This is the default for the
141 configuration file supplied with XFree86. 141 configuration file supplied with XFree86. It's the most simple
142 configuration, but it has some limitations 142 configuration, but it has some limitations.
143 143
144 - Therefore it's also possible to specify re 144 - Therefore it's also possible to specify resolutions in the /etc/XF86Config
145 file. This allows for on-the-fly resolutio 145 file. This allows for on-the-fly resolution switching while retaining the
146 same virtual desktop size. The frame buffe 146 same virtual desktop size. The frame buffer device that's used is still
147 /dev/fb0current (or $FRAMEBUFFER), but the 147 /dev/fb0current (or $FRAMEBUFFER), but the available resolutions are
148 defined by /etc/XF86Config now. The disadv 148 defined by /etc/XF86Config now. The disadvantage is that you have to
149 specify the timings in a different format 149 specify the timings in a different format (but `fbset -x` may help).
150 150
151 To tune a video mode, you can use fbset or xvi 151 To tune a video mode, you can use fbset or xvidtune. Note that xvidtune doesn't
152 work 100% with XF68_FBDev: the reported clock 152 work 100% with XF68_FBDev: the reported clock values are always incorrect.
153 153
154 154
155 5. Video Mode Timings 155 5. Video Mode Timings
156 --------------------- 156 ---------------------
157 157
158 A monitor draws an image on the screen by usin 158 A monitor draws an image on the screen by using an electron beam (3 electron
159 beams for color models, 1 electron beam for mo 159 beams for color models, 1 electron beam for monochrome monitors). The front of
160 the screen is covered by a pattern of colored 160 the screen is covered by a pattern of colored phosphors (pixels). If a phosphor
161 is hit by an electron, it emits a photon and t 161 is hit by an electron, it emits a photon and thus becomes visible.
162 162
163 The electron beam draws horizontal lines (scan 163 The electron beam draws horizontal lines (scanlines) from left to right, and
164 from the top to the bottom of the screen. By m 164 from the top to the bottom of the screen. By modifying the intensity of the
165 electron beam, pixels with various colors and 165 electron beam, pixels with various colors and intensities can be shown.
166 166
167 After each scanline the electron beam has to m 167 After each scanline the electron beam has to move back to the left side of the
168 screen and to the next line: this is called th 168 screen and to the next line: this is called the horizontal retrace. After the
169 whole screen (frame) was painted, the beam mov 169 whole screen (frame) was painted, the beam moves back to the upper left corner:
170 this is called the vertical retrace. During bo 170 this is called the vertical retrace. During both the horizontal and vertical
171 retrace, the electron beam is turned off (blan 171 retrace, the electron beam is turned off (blanked).
172 172
173 The speed at which the electron beam paints th 173 The speed at which the electron beam paints the pixels is determined by the
174 dotclock in the graphics board. For a dotclock 174 dotclock in the graphics board. For a dotclock of e.g. 28.37516 MHz (millions
175 of cycles per second), each pixel is 35242 ps 175 of cycles per second), each pixel is 35242 ps (picoseconds) long::
176 176
177 1/(28.37516E6 Hz) = 35.242E-9 s 177 1/(28.37516E6 Hz) = 35.242E-9 s
178 178
179 If the screen resolution is 640x480, it will t 179 If the screen resolution is 640x480, it will take::
180 180
181 640*35.242E-9 s = 22.555E-6 s 181 640*35.242E-9 s = 22.555E-6 s
182 182
183 to paint the 640 (xres) pixels on one scanline 183 to paint the 640 (xres) pixels on one scanline. But the horizontal retrace
184 also takes time (e.g. 272 `pixels`), so a full 184 also takes time (e.g. 272 `pixels`), so a full scanline takes::
185 185
186 (640+272)*35.242E-9 s = 32.141E-6 s 186 (640+272)*35.242E-9 s = 32.141E-6 s
187 187
188 We'll say that the horizontal scanrate is abou 188 We'll say that the horizontal scanrate is about 31 kHz::
189 189
190 1/(32.141E-6 s) = 31.113E3 Hz 190 1/(32.141E-6 s) = 31.113E3 Hz
191 191
192 A full screen counts 480 (yres) lines, but we 192 A full screen counts 480 (yres) lines, but we have to consider the vertical
193 retrace too (e.g. 49 `lines`). So a full scree 193 retrace too (e.g. 49 `lines`). So a full screen will take::
194 194
195 (480+49)*32.141E-6 s = 17.002E-3 s 195 (480+49)*32.141E-6 s = 17.002E-3 s
196 196
197 The vertical scanrate is about 59 Hz:: 197 The vertical scanrate is about 59 Hz::
198 198
199 1/(17.002E-3 s) = 58.815 Hz 199 1/(17.002E-3 s) = 58.815 Hz
200 200
201 This means the screen data is refreshed about 201 This means the screen data is refreshed about 59 times per second. To have a
202 stable picture without visible flicker, VESA r 202 stable picture without visible flicker, VESA recommends a vertical scanrate of
203 at least 72 Hz. But the perceived flicker is v 203 at least 72 Hz. But the perceived flicker is very human dependent: some people
204 can use 50 Hz without any trouble, while I'll 204 can use 50 Hz without any trouble, while I'll notice if it's less than 80 Hz.
205 205
206 Since the monitor doesn't know when a new scan 206 Since the monitor doesn't know when a new scanline starts, the graphics board
207 will supply a synchronization pulse (horizonta 207 will supply a synchronization pulse (horizontal sync or hsync) for each
208 scanline. Similarly it supplies a synchroniza 208 scanline. Similarly it supplies a synchronization pulse (vertical sync or
209 vsync) for each new frame. The position of the 209 vsync) for each new frame. The position of the image on the screen is
210 influenced by the moments at which the synchro 210 influenced by the moments at which the synchronization pulses occur.
211 211
212 The following picture summarizes all timings. 212 The following picture summarizes all timings. The horizontal retrace time is
213 the sum of the left margin, the right margin a 213 the sum of the left margin, the right margin and the hsync length, while the
214 vertical retrace time is the sum of the upper 214 vertical retrace time is the sum of the upper margin, the lower margin and the
215 vsync length:: 215 vsync length::
216 216
217 +----------+-------------------------------- 217 +----------+---------------------------------------------+----------+-------+
218 | | ↑ 218 | | ↑ | | |
219 | | |upper_margin 219 | | |upper_margin | | |
220 | | ↓ 220 | | ↓ | | |
221 +----------################################# 221 +----------###############################################----------+-------+
222 | # ↑ 222 | # ↑ # | |
223 | # | 223 | # | # | |
224 | # | 224 | # | # | |
225 | # | 225 | # | # | |
226 | left # | 226 | left # | # right | hsync |
227 | margin # | xres 227 | margin # | xres # margin | len |
228 |<-------->#<---------------+--------------- 228 |<-------->#<---------------+--------------------------->#<-------->|<----->|
229 | # | 229 | # | # | |
230 | # | 230 | # | # | |
231 | # | 231 | # | # | |
232 | # |yres 232 | # |yres # | |
233 | # | 233 | # | # | |
234 | # | 234 | # | # | |
235 | # | 235 | # | # | |
236 | # | 236 | # | # | |
237 | # | 237 | # | # | |
238 | # | 238 | # | # | |
239 | # | 239 | # | # | |
240 | # | 240 | # | # | |
241 | # ↓ 241 | # ↓ # | |
242 +----------################################# 242 +----------###############################################----------+-------+
243 | | ↑ 243 | | ↑ | | |
244 | | |lower_margin 244 | | |lower_margin | | |
245 | | ↓ 245 | | ↓ | | |
246 +----------+-------------------------------- 246 +----------+---------------------------------------------+----------+-------+
247 | | ↑ 247 | | ↑ | | |
248 | | |vsync_len 248 | | |vsync_len | | |
249 | | ↓ 249 | | ↓ | | |
250 +----------+-------------------------------- 250 +----------+---------------------------------------------+----------+-------+
251 251
252 The frame buffer device expects all horizontal 252 The frame buffer device expects all horizontal timings in number of dotclocks
253 (in picoseconds, 1E-12 s), and vertical timing 253 (in picoseconds, 1E-12 s), and vertical timings in number of scanlines.
254 254
255 255
256 6. Converting XFree86 timing values info frame 256 6. Converting XFree86 timing values info frame buffer device timings
257 ---------------------------------------------- 257 --------------------------------------------------------------------
258 258
259 An XFree86 mode line consists of the following 259 An XFree86 mode line consists of the following fields::
260 260
261 "800x600" 50 800 856 976 1040 6 261 "800x600" 50 800 856 976 1040 600 637 643 666
262 < name > DCF HR SH1 SH2 HFL 262 < name > DCF HR SH1 SH2 HFL VR SV1 SV2 VFL
263 263
264 The frame buffer device uses the following fie 264 The frame buffer device uses the following fields:
265 265
266 - pixclock: pixel clock in ps (pico seconds) 266 - pixclock: pixel clock in ps (pico seconds)
267 - left_margin: time from sync to picture 267 - left_margin: time from sync to picture
268 - right_margin: time from picture to sync 268 - right_margin: time from picture to sync
269 - upper_margin: time from sync to picture 269 - upper_margin: time from sync to picture
270 - lower_margin: time from picture to sync 270 - lower_margin: time from picture to sync
271 - hsync_len: length of horizontal sync 271 - hsync_len: length of horizontal sync
272 - vsync_len: length of vertical sync 272 - vsync_len: length of vertical sync
273 273
274 1) Pixelclock: 274 1) Pixelclock:
275 275
276 xfree: in MHz 276 xfree: in MHz
277 277
278 fb: in picoseconds (ps) 278 fb: in picoseconds (ps)
279 279
280 pixclock = 1000000 / DCF 280 pixclock = 1000000 / DCF
281 281
282 2) horizontal timings: 282 2) horizontal timings:
283 283
284 left_margin = HFL - SH2 284 left_margin = HFL - SH2
285 285
286 right_margin = SH1 - HR 286 right_margin = SH1 - HR
287 287
288 hsync_len = SH2 - SH1 288 hsync_len = SH2 - SH1
289 289
290 3) vertical timings: 290 3) vertical timings:
291 291
292 upper_margin = VFL - SV2 292 upper_margin = VFL - SV2
293 293
294 lower_margin = SV1 - VR 294 lower_margin = SV1 - VR
295 295
296 vsync_len = SV2 - SV1 296 vsync_len = SV2 - SV1
297 297
298 Good examples for VESA timings can be found in 298 Good examples for VESA timings can be found in the XFree86 source tree,
299 under "xc/programs/Xserver/hw/xfree86/doc/mode 299 under "xc/programs/Xserver/hw/xfree86/doc/modeDB.txt".
300 300
301 301
302 7. References 302 7. References
303 ------------- 303 -------------
304 304
305 For more specific information about the frame 305 For more specific information about the frame buffer device and its
306 applications, please refer to the Linux-fbdev 306 applications, please refer to the Linux-fbdev website:
307 307
308 http://linux-fbdev.sourceforge.net/ 308 http://linux-fbdev.sourceforge.net/
309 309
310 and to the following documentation: 310 and to the following documentation:
311 311
312 - The manual pages for fbset: fbset(8), fb.m 312 - The manual pages for fbset: fbset(8), fb.modes(5)
313 - The manual pages for XFree86: XF68_FBDev(1 313 - The manual pages for XFree86: XF68_FBDev(1), XF86Config(4/5)
314 - The mighty kernel sources: 314 - The mighty kernel sources:
315 315
316 - linux/drivers/video/ 316 - linux/drivers/video/
317 - linux/include/linux/fb.h 317 - linux/include/linux/fb.h
318 - linux/include/video/ 318 - linux/include/video/
319 319
320 320
321 321
322 8. Mailing list 322 8. Mailing list
323 --------------- 323 ---------------
324 324
325 There is a frame buffer device related mailing 325 There is a frame buffer device related mailing list at kernel.org:
326 linux-fbdev@vger.kernel.org. 326 linux-fbdev@vger.kernel.org.
327 327
328 Point your web browser to http://sourceforge.n 328 Point your web browser to http://sourceforge.net/projects/linux-fbdev/ for
329 subscription information and archive browsing. 329 subscription information and archive browsing.
330 330
331 331
332 9. Downloading 332 9. Downloading
333 -------------- 333 --------------
334 334
335 All necessary files can be found at 335 All necessary files can be found at
336 336
337 ftp://ftp.uni-erlangen.de/pub/Linux/LOCAL/ 337 ftp://ftp.uni-erlangen.de/pub/Linux/LOCAL/680x0/
338 338
339 and on its mirrors. 339 and on its mirrors.
340 340
341 The latest version of fbset can be found at 341 The latest version of fbset can be found at
342 342
343 http://www.linux-fbdev.org/ 343 http://www.linux-fbdev.org/
344 344
345 345
346 10. Credits 346 10. Credits
347 ----------- 347 -----------
348 348
349 This readme was written by Geert Uytterhoeven, 349 This readme was written by Geert Uytterhoeven, partly based on the original
350 `X-framebuffer.README` by Roman Hodek and Mart 350 `X-framebuffer.README` by Roman Hodek and Martin Schaller. Section 6 was
351 provided by Frank Neumann. 351 provided by Frank Neumann.
352 352
353 The frame buffer device abstraction was design 353 The frame buffer device abstraction was designed by Martin Schaller.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.