Documentation/fb/framebuffer.rst

2 The Frame Buffer Device
9 ---------------
11 The frame buffer device provides an abstraction for the graphics hardware. It
12 represents the frame buffer of some video hardware and allows application
13 software to access the graphics hardware through a well-defined interface, so
14 the software doesn't need to know anything about the low-level (hardware
22 --------------------------
24 From the user's point of view, the frame buffer device looks just like any
26 specifies the frame buffer number.
31       0 = /dev/fb0	First frame buffer
32       1 = /dev/fb1	Second frame buffer
34      31 = /dev/fb31	32nd frame buffer
39     /dev/fb0current -> fb0
40     /dev/fb1current -> fb1
44 The frame buffer devices are also `normal` memory devices, this means, you can
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 hardware. The corresponding frame
53 Application software that uses the frame buffer device (e.g. the X server) will
55 an 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
65 After this the X server will use the second frame buffer.
69 --------------------------------
71 As you already know, a frame buffer device is a memory device like /dev/mem and
74 appears in the special file is not the whole memory, but the frame buffer of
82   - You can request unchangeable information about the hardware, like name,
86   - You can request and change variable information about the hardware, like
92   - You can get and set parts of the color map. Communication is done with 16
104 etc.), because it works on the frame buffer image data directly.
106 For the future it is planned that frame buffer drivers for graphics cards and
113 3. Frame Buffer Resolution Maintenance
114 --------------------------------------
116 Frame buffer resolutions are maintained using the utility `fbset`. It can
117 change the video mode properties of a frame buffer device. Its main usage is
126 ---------------
128 The X server (XF68_FBDev) is the most notable application program for the frame
132   - If the `Display` subsection for the `fbdev` driver in the /etc/XF86Config
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
149     specify the timings in a different format (but `fbset -x` may help).
156 ---------------------
169 whole screen (frame) was painted, the beam moves back to the upper left corner:
177     1/(28.37516E6 Hz) = 35.242E-9 s
181     640*35.242E-9 s = 22.555E-6 s
184 also takes time (e.g. 272 `pixels`), so a full scanline takes::
186     (640+272)*35.242E-9 s = 32.141E-6 s
190     1/(32.141E-6 s) = 31.113E3 Hz
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 screen will take::
195     (480+49)*32.141E-6 s = 17.002E-3 s
199     1/(17.002E-3 s) = 58.815 Hz
209 vsync) for each new frame. The position of the image on the screen is
217   +----------+---------------------------------------------+----------+-------+
221   +----------###############################################----------+-------+
228   |<-------->#<---------------+--------------------------->#<-------->|<----->|
242   +----------###############################################----------+-------+
246   +----------+---------------------------------------------+----------+-------+
250   +----------+---------------------------------------------+----------+-------+
252 The frame buffer device expects all horizontal timings in number of dotclocks
253 (in picoseconds, 1E-12 s), and vertical timings in number of scanlines.
256 6. Converting XFree86 timing values info frame buffer device timings
257 --------------------------------------------------------------------
264 The frame buffer device uses the following fields:
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
284    left_margin = HFL - SH2
286    right_margin = SH1 - HR
288    hsync_len = SH2 - SH1
292    upper_margin = VFL - SV2
294    lower_margin = SV1 - VR
296    vsync_len = SV2 - SV1
303 -------------
305 For more specific information about the frame buffer device and its
306 applications, please refer to the Linux-fbdev website:
308     http://linux-fbdev.sourceforge.net/
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:
316       - linux/drivers/video/
317       - linux/include/linux/fb.h
318       - linux/include/video/
323 ---------------
325 There is a frame buffer device related mailing list at kernel.org:
326 linux-fbdev@vger.kernel.org.
328 Point your web browser to http://sourceforge.net/projects/linux-fbdev/ for
333 --------------
337     ftp://ftp.uni-erlangen.de/pub/Linux/LOCAL/680x0/
343     http://www.linux-fbdev.org/
347 -----------
350 `X-framebuffer.README` by Roman Hodek and Martin Schaller. Section 6 was
353 The frame buffer device abstraction was designed by Martin Schaller.