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