1Console Drivers 2=============== 3 4The Linux kernel has 2 general types of console drivers. The first type is 5assigned by the kernel to all the virtual consoles during the boot process. 6This type will be called 'system driver', and only one system driver is allowed 7to exist. The system driver is persistent and it can never be unloaded, though 8it may become inactive. 9 10The second type has to be explicitly loaded and unloaded. This will be called 11'modular driver' by this document. Multiple modular drivers can coexist at 12any time with each driver sharing the console with other drivers including 13the system driver. However, modular drivers cannot take over the console 14that is currently occupied by another modular driver. (Exception: Drivers that 15call do_take_over_console() will succeed in the takeover regardless of the type 16of driver occupying the consoles.) They can only take over the console that is 17occupied by the system driver. In the same token, if the modular driver is 18released by the console, the system driver will take over. 19 20Modular drivers, from the programmer's point of view, have to call: 21 22 do_take_over_console() - load and bind driver to console layer 23 give_up_console() - unload driver; it will only work if driver 24 is fully unbound 25 26In newer kernels, the following are also available: 27 28 do_register_con_driver() 29 do_unregister_con_driver() 30 31If sysfs is enabled, the contents of /sys/class/vtconsole can be 32examined. This shows the console backends currently registered by the 33system which are named vtcon<n> where <n> is an integer from 0 to 15. Thus: 34 35 ls /sys/class/vtconsole 36 . .. vtcon0 vtcon1 37 38Each directory in /sys/class/vtconsole has 3 files: 39 40 ls /sys/class/vtconsole/vtcon0 41 . .. bind name uevent 42 43What do these files signify? 44 45 1. bind - this is a read/write file. It shows the status of the driver if 46 read, or acts to bind or unbind the driver to the virtual consoles 47 when written to. The possible values are: 48 49 0 - means the driver is not bound and if echo'ed, commands the driver 50 to unbind 51 52 1 - means the driver is bound and if echo'ed, commands the driver to 53 bind 54 55 2. name - read-only file. Shows the name of the driver in this format: 56 57 cat /sys/class/vtconsole/vtcon0/name 58 (S) VGA+ 59 60 '(S)' stands for a (S)ystem driver, i.e., it cannot be directly 61 commanded to bind or unbind 62 63 'VGA+' is the name of the driver 64 65 cat /sys/class/vtconsole/vtcon1/name 66 (M) frame buffer device 67 68 In this case, '(M)' stands for a (M)odular driver, one that can be 69 directly commanded to bind or unbind. 70 71 3. uevent - ignore this file 72 73When unbinding, the modular driver is detached first, and then the system 74driver takes over the consoles vacated by the driver. Binding, on the other 75hand, will bind the driver to the consoles that are currently occupied by a 76system driver. 77 78NOTE1: Binding and unbinding must be selected in Kconfig. It's under: 79 80Device Drivers -> Character devices -> Support for binding and unbinding 81console drivers 82 83NOTE2: If any of the virtual consoles are in KD_GRAPHICS mode, then binding or 84unbinding will not succeed. An example of an application that sets the console 85to KD_GRAPHICS is X. 86 87How useful is this feature? This is very useful for console driver 88developers. By unbinding the driver from the console layer, one can unload the 89driver, make changes, recompile, reload and rebind the driver without any need 90for rebooting the kernel. For regular users who may want to switch from 91framebuffer console to VGA console and vice versa, this feature also makes 92this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb 93for more details.) 94 95Notes for developers: 96===================== 97 98do_take_over_console() is now broken up into: 99 100 do_register_con_driver() 101 do_bind_con_driver() - private function 102 103give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must 104be fully unbound for this call to succeed. con_is_bound() will check if the 105driver is bound or not. 106 107Guidelines for console driver writers: 108===================================== 109 110In order for binding to and unbinding from the console to properly work, 111console drivers must follow these guidelines: 112 1131. All drivers, except system drivers, must call either do_register_con_driver() 114 or do_take_over_console(). do_register_con_driver() will just add the driver 115 to the console's internal list. It won't take over the 116 console. do_take_over_console(), as it name implies, will also take over (or 117 bind to) the console. 118 1192. All resources allocated during con->con_init() must be released in 120 con->con_deinit(). 121 1223. All resources allocated in con->con_startup() must be released when the 123 driver, which was previously bound, becomes unbound. The console layer 124 does not have a complementary call to con->con_startup() so it's up to the 125 driver to check when it's legal to release these resources. Calling 126 con_is_bound() in con->con_deinit() will help. If the call returned 127 false(), then it's safe to release the resources. This balance has to be 128 ensured because con->con_startup() can be called again when a request to 129 rebind the driver to the console arrives. 130 1314. Upon exit of the driver, ensure that the driver is totally unbound. If the 132 condition is satisfied, then the driver must call do_unregister_con_driver() 133 or give_up_console(). 134 1355. do_unregister_con_driver() can also be called on conditions which make it 136 impossible for the driver to service console requests. This can happen 137 with the framebuffer console that suddenly lost all of its drivers. 138 139The current crop of console drivers should still work correctly, but binding 140and unbinding them may cause problems. With minimal fixes, these drivers can 141be made to work correctly. 142 143========================== 144Antonino Daplas <adaplas@pol.net> 145 146
