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