« back to all changes in this revision
Viewing changes to kernel-doc/framebuffer.txt
- browse files at revision 2
- compare with another revision
- download diff
- download tarball
- view history from revision 2
- Committer: Bazaar Package Importer
- Author(s): André Dahlqvist
- Date: 2001-07-25 14:35:29 UTC
- Revision ID: james.westby@ubuntu.com-20010725143529-we6osd4v21j4s0ff
Tags: 2.1-6.1
* NMU with permission of maintainer.
* Use debhelper v3.
* Ask user if we should create framebuffer devices. (Closes: #106232)
+ Add dependency on debconf as a result of this question.
+ Do not ask this question if devfs is used.
* Kevin Kreamer contributed a manpage for modeline2fb. (Closes: #87145)
* Use /sbin/MAKEDEV, not /dev/MAKEDEV, in postinst. (Closes: #55667)
* Depend on makedev >= 2.3.1-24 as recommended in #55667.
* Describe -a and -accel in the manpage for fbset. (Closes: #105619)
* Changed two places in fb.modes manpage to refer to section 5, not 8.
* Bumped Standards-Version to 3.5.5.0
* Use debhelper v3.
* Ask user if we should create framebuffer devices. (Closes: #106232)
+ Add dependency on debconf as a result of this question.
+ Do not ask this question if devfs is used.
* Kevin Kreamer contributed a manpage for modeline2fb. (Closes: #87145)
* Use /sbin/MAKEDEV, not /dev/MAKEDEV, in postinst. (Closes: #55667)
* Depend on makedev >= 2.3.1-24 as recommended in #55667.
* Describe -a and -accel in the manpage for fbset. (Closes: #105619)
* Changed two places in fb.modes manpage to refer to section 5, not 8.
* Bumped Standards-Version to 3.5.5.0
added
removed
kernel-doc/framebuffer.txt
1
The Frame Buffer Device
2
-----------------------
3
4
Maintained by Geert Uytterhoeven (Geert.Uytterhoeven@cs.kuleuven.ac.be)
5
Last revised: November 7, 1998
6
7
8
0. Introduction
9
---------------
10
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
15
register) stuff.
16
17
The device is accessed through special device nodes, usually located in the
18
/dev directory, i.e. /dev/fb*.
19
20
21
1. User's View of /dev/fb*
22
--------------------------
23
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 using major 29; the minor
26
specifies the frame buffer number.
27
28
By convention, the following device nodes are used (numbers indicate the device
29
minor numbers):
30
31
0 = /dev/fb0 First frame buffer
32
32 = /dev/fb1 Second frame buffer
33
...
34
224 = /dev/fb7 8th frame buffer
35
36
For backwards compatibility, you may want to create the following symbolic
37
links:
38
39
/dev/fb0current -> fb0
40
/dev/fb1current -> fb1
41
42
and so on...
43
44
The frame buffer devices are also `normal' memory devices, this means, you can
45
read and write their contents. You can, for example, make a screen snapshot by
46
47
cp /dev/fb0 myfile
48
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
51
buffer devices (/dev/fb0 and /dev/fb1 etc.) work independently.
52
53
Application software that uses the frame buffer device (e.g. the X server) will
54
use /dev/fb0 by default (older software uses /dev/fb0current). You can specify
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
57
users):
58
59
export FRAMEBUFFER=/dev/fb1
60
61
or (for csh users):
62
63
setenv FRAMEBUFFER /dev/fb1
64
65
After this the X server will use the second frame buffer.
66
67
68
2. Programmer's View of /dev/fb*
69
--------------------------------
70
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, write it, seek to some location in
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 memory, but the frame buffer of
75
some video hardware.
76
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 map handling works via ioctls,
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 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
98
All this hardware abstraction makes the implementation of application programs
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 the color registers of the concrete
101
hardware are organized. XF68_FBDev is a general X server for bitmapped,
102
unaccelerated video hardware. The only thing that has to be built into
103
application programs is the screen organization (bitplanes or chunky pixels
104
etc.), because it works on the frame buffer image data directly.
105
106
For the future it is planned that frame buffer drivers for graphics cards and
107
the like can be implemented as kernel modules that are loaded at runtime. Such
108
a driver just has to call register_framebuffer() and supply some functions.
109
Writing and distributing such drivers independently from the kernel will save
110
much trouble...
111
112
113
3. Frame Buffer Resolution Maintenance
114
--------------------------------------
115
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
118
to change the current video mode, e.g. during boot up in one of your /etc/rc.*
119
or /etc/init.d/* files.
120
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 with a simple identifier.
123
124
125
4. The X Server
126
---------------
127
128
The X server (XF68_FBDev) is the most notable application program for the frame
129
buffer device. Starting with XFree86 release 3.2, the X server is part of
130
XFree86 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
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 values are always incorrect.
153
154
155
5. Video Mode Timings
156
---------------------
157
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 monochrome monitors). The front of
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 thus becomes visible.
162
163
The electron beam draws horizontal lines (scanlines) from left to right, and
164
from the top to the bottom of the screen. By modifying the intensity of the
165
electron beam, pixels with various colors and intensities can be shown.
166
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 the horizontal retrace. After the
169
whole screen (frame) was painted, the beam moves back to the upper left corner:
170
this is called the vertical retrace. During both the horizontal and vertical
171
retrace, the electron beam is turned off (blanked).
172
173
The speed at which the electron beam paints the pixels is determined by the
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 (picoseconds) long:
176
177
1/(28.37516E6 Hz) = 35.242E-9 s
178
179
If the screen resolution is 640x480, it will take
180
181
640*35.242E-9 s = 22.555E-6 s
182
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 scanline takes
185
186
(640+272)*35.242E-9 s = 32.141E-6 s
187
188
We'll say that the horizontal scanrate is about 31 kHz:
189
190
1/(32.141E-6 s) = 31.113E3 Hz
191
192
A full screen counts 480 (yres) lines, but we have to consider the vertical
193
retrace too (e.g. 49 `pixels'). So a full screen will take
194
195
(480+49)*32.141E-6 s = 17.002E-3 s
196
197
The vertical scanrate is about 59 Hz:
198
199
1/(17.002E-3 s) = 58.815 Hz
200
201
This means the screen data is refreshed about 59 times per second. To have a
202
stable picture without visible flicker, VESA recommends a vertical scanrate of
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 notice if it's less than 80 Hz.
205
206
Since the monitor doesn't know when a new scanline starts, the graphics board
207
will supply a synchronization pulse (horizontal sync or hsync) for each
208
scanline. Similarly it supplies a synchronization pulse (vertical sync or
209
vsync) for each new frame. The position of the image on the screen is
210
influenced by the moments at which the synchronization pulses occur.
211
212
The following picture summarizes all timings. The horizontal retrace time is
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 margin, the lower margin and the
215
vsync 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
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.
254
255
256
6. Converting XFree86 timing values info frame buffer device timings
257
--------------------------------------------------------------------
258
259
An 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
263
The 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
273
1) Pixelclock:
274
xfree: in MHz
275
fb: in picoseconds (ps)
276
277
pixclock = 1000000 / DCF
278
279
2) horizontal timings:
280
left_margin = HFL - SH2
281
right_margin = SH1 - HR
282
hsync_len = SH2 - SH1
283
284
3) vertical timings:
285
upper_margin = VFL - SV2
286
lower_margin = SV1 - VR
287
vsync_len = SV2 - SV1
288
289
Good examples for VESA timings can be found in the XFree86 source tree,
290
under "xc/programs/Xserver/hw/xfree86/doc/modeDB.txt".
291
292
293
7. References
294
-------------
295
296
For more specific information about the frame buffer device and its
297
applications, please refer to the following documentation:
298
299
- The manual pages for fbset: fbset(8), fb.modes(5)
300
- The manual pages for XFree86: XF68_FBDev(1), XF86Config(4/5)
301
- The mighty kernel sources:
302
o linux/drivers/video/
303
o linux/include/linux/fb.h
304
o linux/include/video/
305
306
307
8. Downloading
308
--------------
309
310
All necessary files can be found at
311
312
ftp://ftp.uni-erlangen.de/pub/Linux/LOCAL/680x0/
313
314
and on its mirrors.
315
316
317
9. Credits
318
----------
319
320
This readme was written by Geert Uytterhoeven, partly based on the original
321
`X-framebuffer.README' by Roman Hodek and Martin Schaller. Section 6 was
322
provided by Frank Neumann.
323
324
The frame buffer device abstraction was designed by Martin Schaller.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1