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