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