annotate Documentation/console/console.txt @ 0:831230e53067

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