linux/Documentation/fb/framebuffer.txt
<<
>>
Prefs
   1                        The Frame Buffer Device
   2                        -----------------------
   3
   4Maintained by Geert Uytterhoeven <geert@linux-m68k.org>
   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 "800x600"     50      800  856  976 1040    600  637  643  666
 261 < name >     DCF       HR  SH1  SH2  HFL     VR  SV1  SV2  VFL
 262
 263The frame buffer device uses the following fields:
 264
 265  - pixclock: pixel clock in ps (pico seconds)
 266  - left_margin: time from sync to picture
 267  - right_margin: time from picture to sync
 268  - upper_margin: time from sync to picture
 269  - lower_margin: time from picture to sync
 270  - hsync_len: length of horizontal sync
 271  - vsync_len: length of vertical sync
 272
 2731) Pixelclock:
 274   xfree: in MHz
 275   fb: in picoseconds (ps)
 276
 277   pixclock = 1000000 / DCF
 278
 2792) horizontal timings:
 280   left_margin = HFL - SH2
 281   right_margin = SH1 - HR
 282   hsync_len = SH2 - SH1
 283
 2843) vertical timings:
 285   upper_margin = VFL - SV2
 286   lower_margin = SV1 - VR
 287   vsync_len = SV2 - SV1
 288
 289Good examples for VESA timings can be found in the XFree86 source tree,
 290under "xc/programs/Xserver/hw/xfree86/doc/modeDB.txt".
 291
 292
 2937. References
 294-------------
 295
 296For more specific information about the frame buffer device and its
 297applications, please refer to the Linux-fbdev website:
 298
 299    http://linux-fbdev.sourceforge.net/
 300
 301and to the following documentation:
 302
 303  - The manual pages for fbset: fbset(8), fb.modes(5)
 304  - The manual pages for XFree86: XF68_FBDev(1), XF86Config(4/5)
 305  - The mighty kernel sources:
 306      o linux/drivers/video/
 307      o linux/include/linux/fb.h
 308      o linux/include/video/
 309
 310
 311
 3128. Mailing list
 313---------------
 314
 315There is a frame buffer device related mailing list at kernel.org:
 316linux-fbdev@vger.kernel.org.
 317
 318Point your web browser to http://sourceforge.net/projects/linux-fbdev/ for
 319subscription information and archive browsing.
 320
 321
 3229. Downloading
 323--------------
 324
 325All necessary files can be found at
 326
 327    ftp://ftp.uni-erlangen.de/pub/Linux/LOCAL/680x0/
 328
 329and on its mirrors.
 330
 331The latest version of fbset can be found at
 332
 333    http://www.linux-fbdev.org/ 
 334
 335  
 33610. Credits                                                       
 337----------                                                       
 338                
 339This readme was written by Geert Uytterhoeven, partly based on the original
 340`X-framebuffer.README' by Roman Hodek and Martin Schaller. Section 6 was
 341provided by Frank Neumann.
 342
 343The frame buffer device abstraction was designed by Martin Schaller.
 344
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.