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