About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / fb / framebuffer.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1				The Frame Buffer Device
2				-----------------------
3	
4	Maintained by Geert Uytterhoeven <geert@linux-m68k.org>
5	Last revised: May 10, 2001
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	      1 = /dev/fb1	Second frame buffer
33		  ...
34	     31 = /dev/fb31	32nd 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 `lines'). 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 Linux-fbdev website:
298	
299	    http://linux-fbdev.sourceforge.net/
300	
301	and 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	
312	8. Mailing list
313	---------------
314	
315	There is a frame buffer device related mailing list at kernel.org:
316	linux-fbdev@vger.kernel.org.
317	
318	Point your web browser to http://sourceforge.net/projects/linux-fbdev/ for
319	subscription information and archive browsing.
320	
321	
322	9. Downloading
323	--------------
324	
325	All necessary files can be found at
326	
327	    ftp://ftp.uni-erlangen.de/pub/Linux/LOCAL/680x0/
328	
329	and on its mirrors.
330	
331	The latest version of fbset can be found at
332	
333	    http://www.linux-fbdev.org/ 
334	
335	  
336	10. Credits                                                       
337	----------                                                       
338	                
339	This readme was written by Geert Uytterhoeven, partly based on the original
340	`X-framebuffer.README' by Roman Hodek and Martin Schaller. Section 6 was
341	provided by Frank Neumann.
342	
343	The frame buffer device abstraction was designed by Martin Schaller.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog