1 ======================= 1 =======================
2 The Framebuffer Console 2 The Framebuffer Console
3 ======================= 3 =======================
4 4
5 The framebuffer console (fbcon), as its name i 5 The framebuffer console (fbcon), as its name implies, is a text
6 console running on top of the framebuffer devi 6 console running on top of the framebuffer device. It has the functionality of
7 any standard text console driver, such as the 7 any standard text console driver, such as the VGA console, with the added
8 features that can be attributed to the graphic 8 features that can be attributed to the graphical nature of the framebuffer.
9 9
10 In the x86 architecture, the framebuffer conso 10 In the x86 architecture, the framebuffer console is optional, and
11 some even treat it as a toy. For other archite 11 some even treat it as a toy. For other architectures, it is the only available
12 display device, text or graphical. 12 display device, text or graphical.
13 13
14 What are the features of fbcon? The framebuff 14 What are the features of fbcon? The framebuffer console supports
15 high resolutions, varying font types, display 15 high resolutions, varying font types, display rotation, primitive multihead,
16 etc. Theoretically, multi-colored fonts, blend 16 etc. Theoretically, multi-colored fonts, blending, aliasing, and any feature
17 made available by the underlying graphics card 17 made available by the underlying graphics card are also possible.
18 18
19 A. Configuration 19 A. Configuration
20 ================ 20 ================
21 21
22 The framebuffer console can be enabled by usin 22 The framebuffer console can be enabled by using your favorite kernel
23 configuration tool. It is under Device Driver 23 configuration tool. It is under Device Drivers->Graphics Support->
24 Console display driver support->Framebuffer Co 24 Console display driver support->Framebuffer Console Support.
25 Select 'y' to compile support statically or 'm 25 Select 'y' to compile support statically or 'm' for module support. The
26 module will be fbcon. 26 module will be fbcon.
27 27
28 In order for fbcon to activate, at least one f 28 In order for fbcon to activate, at least one framebuffer driver is
29 required, so choose from any of the numerous d 29 required, so choose from any of the numerous drivers available. For x86
30 systems, they almost universally have VGA card 30 systems, they almost universally have VGA cards, so vga16fb and vesafb will
31 always be available. However, using a chipset- 31 always be available. However, using a chipset-specific driver will give you
32 more speed and features, such as the ability t 32 more speed and features, such as the ability to change the video mode
33 dynamically. 33 dynamically.
34 34
35 To display the penguin logo, choose any logo a 35 To display the penguin logo, choose any logo available in Graphics
36 support->Bootup logo. 36 support->Bootup logo.
37 37
38 Also, you will need to select at least one com 38 Also, you will need to select at least one compiled-in font, but if
39 you don't do anything, the kernel configuratio 39 you don't do anything, the kernel configuration tool will select one for you,
40 usually an 8x16 font. 40 usually an 8x16 font.
41 41
42 GOTCHA: A common bug report is enabling the fr 42 GOTCHA: A common bug report is enabling the framebuffer without enabling the
43 framebuffer console. Depending on the driver, 43 framebuffer console. Depending on the driver, you may get a blanked or
44 garbled display, but the system still boots to 44 garbled display, but the system still boots to completion. If you are
45 fortunate to have a driver that does not alter 45 fortunate to have a driver that does not alter the graphics chip, then you
46 will still get a VGA console. 46 will still get a VGA console.
47 47
48 B. Loading 48 B. Loading
49 ========== 49 ==========
50 50
51 Possible scenarios: 51 Possible scenarios:
52 52
53 1. Driver and fbcon are compiled statically 53 1. Driver and fbcon are compiled statically
54 54
55 Usually, fbcon will automatically tak 55 Usually, fbcon will automatically take over your console. The notable
56 exception is vesafb. It needs to be 56 exception is vesafb. It needs to be explicitly activated with the
57 vga= boot option parameter. 57 vga= boot option parameter.
58 58
59 2. Driver is compiled statically, fbcon is com 59 2. Driver is compiled statically, fbcon is compiled as a module
60 60
61 Depending on the driver, you either g 61 Depending on the driver, you either get a standard console, or a
62 garbled display, as mentioned above. 62 garbled display, as mentioned above. To get a framebuffer console,
63 do a 'modprobe fbcon'. 63 do a 'modprobe fbcon'.
64 64
65 3. Driver is compiled as a module, fbcon is co 65 3. Driver is compiled as a module, fbcon is compiled statically
66 66
67 You get your standard console. Once 67 You get your standard console. Once the driver is loaded with
68 'modprobe xxxfb', fbcon automatically 68 'modprobe xxxfb', fbcon automatically takes over the console with
69 the possible exception of using the f 69 the possible exception of using the fbcon=map:n option. See below.
70 70
71 4. Driver and fbcon are compiled as a module. 71 4. Driver and fbcon are compiled as a module.
72 72
73 You can load them in any order. Once 73 You can load them in any order. Once both are loaded, fbcon will take
74 over the console. 74 over the console.
75 75
76 C. Boot options 76 C. Boot options
77 77
78 The framebuffer console has several, 78 The framebuffer console has several, largely unknown, boot options
79 that can change its behavior. 79 that can change its behavior.
80 80
81 1. fbcon=font:<name> 81 1. fbcon=font:<name>
82 82
83 Select the initial font to use. The va 83 Select the initial font to use. The value 'name' can be any of the
84 compiled-in fonts: 10x18, 6x10, 6x8, 7 84 compiled-in fonts: 10x18, 6x10, 6x8, 7x14, Acorn8x8, MINI4x6,
85 PEARL8x8, ProFont6x11, SUN12x22, SUN8x 85 PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, TER16x32, VGA8x16, VGA8x8.
86 86
87 Note, not all drivers can handle font 87 Note, not all drivers can handle font with widths not divisible by 8,
88 such as vga16fb. 88 such as vga16fb.
89 89
90 90
91 2. fbcon=map:<0123> 91 2. fbcon=map:<0123>
92 92
93 This is an interesting option. It tell 93 This is an interesting option. It tells which driver gets mapped to
94 which console. The value '0123' is a s 94 which console. The value '0123' is a sequence that gets repeated until
95 the total length is 64 which is the nu 95 the total length is 64 which is the number of consoles available. In
96 the above example, it is expanded to 0 96 the above example, it is expanded to 012301230123... and the mapping
97 will be:: 97 will be::
98 98
99 tty | 1 2 3 4 5 6 7 8 9 ... 99 tty | 1 2 3 4 5 6 7 8 9 ...
100 fb | 0 1 2 3 0 1 2 3 0 ... 100 fb | 0 1 2 3 0 1 2 3 0 ...
101 101
102 ('cat /proc/fb' should tell yo 102 ('cat /proc/fb' should tell you what the fb numbers are)
103 103
104 One side effect that may be useful is 104 One side effect that may be useful is using a map value that exceeds
105 the number of loaded fb drivers. For e 105 the number of loaded fb drivers. For example, if only one driver is
106 available, fb0, adding fbcon=map:1 tel 106 available, fb0, adding fbcon=map:1 tells fbcon not to take over the
107 console. 107 console.
108 108
109 Later on, when you want to map the con 109 Later on, when you want to map the console the to the framebuffer
110 device, you can use the con2fbmap util 110 device, you can use the con2fbmap utility.
111 111
112 3. fbcon=vc:<n1>-<n2> 112 3. fbcon=vc:<n1>-<n2>
113 113
114 This option tells fbcon to take over o 114 This option tells fbcon to take over only a range of consoles as
115 specified by the values 'n1' and 'n2'. 115 specified by the values 'n1' and 'n2'. The rest of the consoles
116 outside the given range will still be 116 outside the given range will still be controlled by the standard
117 console driver. 117 console driver.
118 118
119 NOTE: For x86 machines, the standard c 119 NOTE: For x86 machines, the standard console is the VGA console which
120 is typically located on the same video 120 is typically located on the same video card. Thus, the consoles that
121 are controlled by the VGA console will 121 are controlled by the VGA console will be garbled.
122 122
123 4. fbcon=rotate:<n> 123 4. fbcon=rotate:<n>
124 124
125 This option changes the orientation an 125 This option changes the orientation angle of the console display. The
126 value 'n' accepts the following: 126 value 'n' accepts the following:
127 127
128 - 0 - normal orientation (0 degree 128 - 0 - normal orientation (0 degree)
129 - 1 - clockwise orientation (90 de 129 - 1 - clockwise orientation (90 degrees)
130 - 2 - upside down orientation (180 130 - 2 - upside down orientation (180 degrees)
131 - 3 - counterclockwise orientation 131 - 3 - counterclockwise orientation (270 degrees)
132 132
133 The angle can be changed anytime after 133 The angle can be changed anytime afterwards by 'echoing' the same
134 numbers to any one of the 2 attributes 134 numbers to any one of the 2 attributes found in
135 /sys/class/graphics/fbcon: 135 /sys/class/graphics/fbcon:
136 136
137 - rotate - rotate the disp 137 - rotate - rotate the display of the active console
138 - rotate_all - rotate the disp 138 - rotate_all - rotate the display of all consoles
139 139
140 Console rotation will only become avai 140 Console rotation will only become available if Framebuffer Console
141 Rotation support is compiled in your k 141 Rotation support is compiled in your kernel.
142 142
143 NOTE: This is purely console rotation. 143 NOTE: This is purely console rotation. Any other applications that
144 use the framebuffer will remain at the 144 use the framebuffer will remain at their 'normal' orientation.
145 Actually, the underlying fb driver is 145 Actually, the underlying fb driver is totally ignorant of console
146 rotation. 146 rotation.
147 147
148 5. fbcon=margin:<color> 148 5. fbcon=margin:<color>
149 149
150 This option specifies the color of the 150 This option specifies the color of the margins. The margins are the
151 leftover area at the right and the bot 151 leftover area at the right and the bottom of the screen that are not
152 used by text. By default, this area wi 152 used by text. By default, this area will be black. The 'color' value
153 is an integer number that depends on t 153 is an integer number that depends on the framebuffer driver being used.
154 154
155 6. fbcon=nodefer 155 6. fbcon=nodefer
156 156
157 If the kernel is compiled with deferre 157 If the kernel is compiled with deferred fbcon takeover support, normally
158 the framebuffer contents, left in plac 158 the framebuffer contents, left in place by the firmware/bootloader, will
159 be preserved until there actually is s 159 be preserved until there actually is some text is output to the console.
160 This option causes fbcon to bind immed 160 This option causes fbcon to bind immediately to the fbdev device.
161 161
162 7. fbcon=logo-pos:<location> 162 7. fbcon=logo-pos:<location>
163 163
164 The only possible 'location' is 'cente 164 The only possible 'location' is 'center' (without quotes), and when
165 given, the bootup logo is moved from t 165 given, the bootup logo is moved from the default top-left corner
166 location to the center of the framebuf 166 location to the center of the framebuffer. If more than one logo is
167 displayed due to multiple CPUs, the co 167 displayed due to multiple CPUs, the collected line of logos is moved
168 as a whole. 168 as a whole.
169 169
170 8. fbcon=logo-count:<n> 170 8. fbcon=logo-count:<n>
171 171
172 The value 'n' overrides the number of 172 The value 'n' overrides the number of bootup logos. 0 disables the
173 logo, and -1 gives the default which i 173 logo, and -1 gives the default which is the number of online CPUs.
174 174
175 C. Attaching, Detaching and Unloading 175 C. Attaching, Detaching and Unloading
176 176
177 Before going on to how to attach, detach and u 177 Before going on to how to attach, detach and unload the framebuffer console, an
178 illustration of the dependencies may help. 178 illustration of the dependencies may help.
179 179
180 The console layer, as with most subsystems, ne 180 The console layer, as with most subsystems, needs a driver that interfaces with
181 the hardware. Thus, in a VGA console:: 181 the hardware. Thus, in a VGA console::
182 182
183 console ---> VGA driver ---> hardware. 183 console ---> VGA driver ---> hardware.
184 184
185 Assuming the VGA driver can be unloaded, one m 185 Assuming the VGA driver can be unloaded, one must first unbind the VGA driver
186 from the console layer before unloading the dr 186 from the console layer before unloading the driver. The VGA driver cannot be
187 unloaded if it is still bound to the console l 187 unloaded if it is still bound to the console layer. (See
188 Documentation/driver-api/console.rst for more 188 Documentation/driver-api/console.rst for more information).
189 189
190 This is more complicated in the case of the fr 190 This is more complicated in the case of the framebuffer console (fbcon),
191 because fbcon is an intermediate layer between 191 because fbcon is an intermediate layer between the console and the drivers::
192 192
193 console ---> fbcon ---> fbdev drivers 193 console ---> fbcon ---> fbdev drivers ---> hardware
194 194
195 The fbdev drivers cannot be unloaded if bound 195 The fbdev drivers cannot be unloaded if bound to fbcon, and fbcon cannot
196 be unloaded if it's bound to the console layer 196 be unloaded if it's bound to the console layer.
197 197
198 So to unload the fbdev drivers, one must first 198 So to unload the fbdev drivers, one must first unbind fbcon from the console,
199 then unbind the fbdev drivers from fbcon. For 199 then unbind the fbdev drivers from fbcon. Fortunately, unbinding fbcon from
200 the console layer will automatically unbind fr 200 the console layer will automatically unbind framebuffer drivers from
201 fbcon. Thus, there is no need to explicitly un 201 fbcon. Thus, there is no need to explicitly unbind the fbdev drivers from
202 fbcon. 202 fbcon.
203 203
204 So, how do we unbind fbcon from the console? P 204 So, how do we unbind fbcon from the console? Part of the answer is in
205 Documentation/driver-api/console.rst. To summa 205 Documentation/driver-api/console.rst. To summarize:
206 206
207 Echo a value to the bind file that represents 207 Echo a value to the bind file that represents the framebuffer console
208 driver. So assuming vtcon1 represents fbcon, t 208 driver. So assuming vtcon1 represents fbcon, then::
209 209
210 echo 1 > /sys/class/vtconsole/vtcon1/bind - !! 210 echo 1 > sys/class/vtconsole/vtcon1/bind - attach framebuffer console to
211 c 211 console layer
212 echo 0 > /sys/class/vtconsole/vtcon1/bind - !! 212 echo 0 > sys/class/vtconsole/vtcon1/bind - detach framebuffer console from
213 c 213 console layer
214 214
215 If fbcon is detached from the console layer, y 215 If fbcon is detached from the console layer, your boot console driver (which is
216 usually VGA text mode) will take over. A few 216 usually VGA text mode) will take over. A few drivers (rivafb and i810fb) will
217 restore VGA text mode for you. With the rest, 217 restore VGA text mode for you. With the rest, before detaching fbcon, you
218 must take a few additional steps to make sure 218 must take a few additional steps to make sure that your VGA text mode is
219 restored properly. The following is one of the 219 restored properly. The following is one of the several methods that you can do:
220 220
221 1. Download or install vbetool. This utility 221 1. Download or install vbetool. This utility is included with most
222 distributions nowadays, and is usually part 222 distributions nowadays, and is usually part of the suspend/resume tool.
223 223
224 2. In your kernel configuration, ensure that C 224 2. In your kernel configuration, ensure that CONFIG_FRAMEBUFFER_CONSOLE is set
225 to 'y' or 'm'. Enable one or more of your f 225 to 'y' or 'm'. Enable one or more of your favorite framebuffer drivers.
226 226
227 3. Boot into text mode and as root run:: 227 3. Boot into text mode and as root run::
228 228
229 vbetool vbestate save > <vga state fil 229 vbetool vbestate save > <vga state file>
230 230
231 The above command saves the register conten 231 The above command saves the register contents of your graphics
232 hardware to <vga state file>. You need to 232 hardware to <vga state file>. You need to do this step only once as
233 the state file can be reused. 233 the state file can be reused.
234 234
235 4. If fbcon is compiled as a module, load fbco 235 4. If fbcon is compiled as a module, load fbcon by doing::
236 236
237 modprobe fbcon 237 modprobe fbcon
238 238
239 5. Now to detach fbcon:: 239 5. Now to detach fbcon::
240 240
241 vbetool vbestate restore < <vga state f 241 vbetool vbestate restore < <vga state file> && \
242 echo 0 > /sys/class/vtconsole/vtcon1/bi 242 echo 0 > /sys/class/vtconsole/vtcon1/bind
243 243
244 6. That's it, you're back to VGA mode. And if 244 6. That's it, you're back to VGA mode. And if you compiled fbcon as a module,
245 you can unload it by 'rmmod fbcon'. 245 you can unload it by 'rmmod fbcon'.
246 246
247 7. To reattach fbcon:: 247 7. To reattach fbcon::
248 248
249 echo 1 > /sys/class/vtconsole/vtcon1/bi 249 echo 1 > /sys/class/vtconsole/vtcon1/bind
250 250
251 8. Once fbcon is unbound, all drivers register 251 8. Once fbcon is unbound, all drivers registered to the system will also
252 become unbound. This means that fbcon and ind 252 become unbound. This means that fbcon and individual framebuffer drivers
253 can be unloaded or reloaded at will. Reloading 253 can be unloaded or reloaded at will. Reloading the drivers or fbcon will
254 automatically bind the console, fbcon and the 254 automatically bind the console, fbcon and the drivers together. Unloading
255 all the drivers without unloading fbcon will m 255 all the drivers without unloading fbcon will make it impossible for the
256 console to bind fbcon. 256 console to bind fbcon.
257 257
258 Notes for vesafb users: 258 Notes for vesafb users:
259 ======================= 259 =======================
260 260
261 Unfortunately, if your bootline includes a vga 261 Unfortunately, if your bootline includes a vga=xxx parameter that sets the
262 hardware in graphics mode, such as when loadin 262 hardware in graphics mode, such as when loading vesafb, vgacon will not load.
263 Instead, vgacon will replace the default boot 263 Instead, vgacon will replace the default boot console with dummycon, and you
264 won't get any display after detaching fbcon. Y 264 won't get any display after detaching fbcon. Your machine is still alive, so
265 you can reattach vesafb. However, to reattach 265 you can reattach vesafb. However, to reattach vesafb, you need to do one of
266 the following: 266 the following:
267 267
268 Variation 1: 268 Variation 1:
269 269
270 a. Before detaching fbcon, do:: 270 a. Before detaching fbcon, do::
271 271
272 vbetool vbemode save > <vesa state fil 272 vbetool vbemode save > <vesa state file> # do once for each vesafb mode,
273 273 # the file can be reused
274 274
275 b. Detach fbcon as in step 5. 275 b. Detach fbcon as in step 5.
276 276
277 c. Attach fbcon:: 277 c. Attach fbcon::
278 278
279 vbetool vbestate restore < <vesa state 279 vbetool vbestate restore < <vesa state file> && \
280 echo 1 > /sys/class/vtconsole/vtcon1/b 280 echo 1 > /sys/class/vtconsole/vtcon1/bind
281 281
282 Variation 2: 282 Variation 2:
283 283
284 a. Before detaching fbcon, do:: 284 a. Before detaching fbcon, do::
285 285
286 echo <ID> > /sys/class/tty/console/bin 286 echo <ID> > /sys/class/tty/console/bind
287 287
288 vbetool vbemode get 288 vbetool vbemode get
289 289
290 b. Take note of the mode number 290 b. Take note of the mode number
291 291
292 b. Detach fbcon as in step 5. 292 b. Detach fbcon as in step 5.
293 293
294 c. Attach fbcon:: 294 c. Attach fbcon::
295 295
296 vbetool vbemode set <mode number> && \ 296 vbetool vbemode set <mode number> && \
297 echo 1 > /sys/class/vtconsole/vtcon1/b 297 echo 1 > /sys/class/vtconsole/vtcon1/bind
298 298
299 Samples: 299 Samples:
300 ======== 300 ========
301 301
302 Here are 2 sample bash scripts that you can us 302 Here are 2 sample bash scripts that you can use to bind or unbind the
303 framebuffer console driver if you are on an X8 303 framebuffer console driver if you are on an X86 box::
304 304
305 #!/bin/bash 305 #!/bin/bash
306 # Unbind fbcon 306 # Unbind fbcon
307 307
308 # Change this to where your actual vgastate 308 # Change this to where your actual vgastate file is located
309 # Or Use VGASTATE=$1 to indicate the state f 309 # Or Use VGASTATE=$1 to indicate the state file at runtime
310 VGASTATE=/tmp/vgastate 310 VGASTATE=/tmp/vgastate
311 311
312 # path to vbetool 312 # path to vbetool
313 VBETOOL=/usr/local/bin 313 VBETOOL=/usr/local/bin
314 314
315 315
316 for (( i = 0; i < 16; i++)) 316 for (( i = 0; i < 16; i++))
317 do 317 do
318 if test -x /sys/class/vtconsole/vtcon$i; t 318 if test -x /sys/class/vtconsole/vtcon$i; then
319 if [ `cat /sys/class/vtconsole/vtcon$i 319 if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \
320 = 1 ]; then 320 = 1 ]; then
321 if test -x $VBETOOL/vbetool; then 321 if test -x $VBETOOL/vbetool; then
322 echo Unbinding vtcon$i 322 echo Unbinding vtcon$i
323 $VBETOOL/vbetool vbestate resto 323 $VBETOOL/vbetool vbestate restore < $VGASTATE
324 echo 0 > /sys/class/vtconsole/v 324 echo 0 > /sys/class/vtconsole/vtcon$i/bind
325 fi 325 fi
326 fi 326 fi
327 fi 327 fi
328 done 328 done
329 329
330 ---------------------------------------------- 330 ---------------------------------------------------------------------------
331 331
332 :: 332 ::
333 333
334 #!/bin/bash 334 #!/bin/bash
335 # Bind fbcon 335 # Bind fbcon
336 336
337 for (( i = 0; i < 16; i++)) 337 for (( i = 0; i < 16; i++))
338 do 338 do
339 if test -x /sys/class/vtconsole/vtcon$i; t 339 if test -x /sys/class/vtconsole/vtcon$i; then
340 if [ `cat /sys/class/vtconsole/vtcon$i 340 if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \
341 = 1 ]; then 341 = 1 ]; then
342 echo Unbinding vtcon$i 342 echo Unbinding vtcon$i
343 echo 1 > /sys/class/vtconsole/vtcon$ 343 echo 1 > /sys/class/vtconsole/vtcon$i/bind
344 fi 344 fi
345 fi 345 fi
346 done 346 done
347 347
348 Antonino Daplas <adaplas@pol.net> 348 Antonino Daplas <adaplas@pol.net>
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.