ia64/linux-2.6.18-xen.hg

diff 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)
parents
children
line diff
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/Documentation/console/console.txt	Wed Apr 11 14:15:44 2007 +0100
     1.3 @@ -0,0 +1,144 @@
     1.4 +Console Drivers
     1.5 +===============
     1.6 +
     1.7 +The linux kernel has 2 general types of console drivers.  The first type is
     1.8 +assigned by the kernel to all the virtual consoles during the boot process.
     1.9 +This type will be called 'system driver', and only one system driver is allowed
    1.10 +to exist. The system driver is persistent and it can never be unloaded, though
    1.11 +it may become inactive.
    1.12 +
    1.13 +The second type has to be explicitly loaded and unloaded. This will be called
    1.14 +'modular driver' by this document. Multiple modular drivers can coexist at
    1.15 +any time with each driver sharing the console with other drivers including
    1.16 +the system driver. However, modular drivers cannot take over the console
    1.17 +that is currently occupied by another modular driver. (Exception: Drivers that
    1.18 +call take_over_console() will succeed in the takeover regardless of the type
    1.19 +of driver occupying the consoles.) They can only take over the console that is
    1.20 +occupied by the system driver. In the same token, if the modular driver is
    1.21 +released by the console, the system driver will take over.
    1.22 +
    1.23 +Modular drivers, from the programmer's point of view, has to call:
    1.24 +
    1.25 +	 take_over_console() - load and bind driver to console layer
    1.26 +	 give_up_console() - unbind and unload driver
    1.27 +
    1.28 +In newer kernels, the following are also available:
    1.29 +
    1.30 +	 register_con_driver()
    1.31 +	 unregister_con_driver()
    1.32 +
    1.33 +If sysfs is enabled, the contents of /sys/class/vtconsole can be
    1.34 +examined. This shows the console backends currently registered by the
    1.35 +system which are named vtcon<n> where <n> is an integer fro 0 to 15. Thus:
    1.36 +
    1.37 +       ls /sys/class/vtconsole
    1.38 +       .  ..  vtcon0  vtcon1
    1.39 +
    1.40 +Each directory in /sys/class/vtconsole has 3 files:
    1.41 +
    1.42 +     ls /sys/class/vtconsole/vtcon0
    1.43 +     .  ..  bind  name  uevent
    1.44 +
    1.45 +What do these files signify?
    1.46 +
    1.47 +     1. bind - this is a read/write file. It shows the status of the driver if
    1.48 +        read, or acts to bind or unbind the driver to the virtual consoles
    1.49 +        when written to. The possible values are:
    1.50 +
    1.51 +	0 - means the driver is not bound and if echo'ed, commands the driver
    1.52 +	    to unbind
    1.53 +
    1.54 +        1 - means the driver is bound and if echo'ed, commands the driver to
    1.55 +	    bind
    1.56 +
    1.57 +     2. name - read-only file. Shows the name of the driver in this format:
    1.58 +
    1.59 +	cat /sys/class/vtconsole/vtcon0/name
    1.60 +	(S) VGA+
    1.61 +
    1.62 +	    '(S)' stands for a (S)ystem driver, ie, it cannot be directly
    1.63 +	    commanded to bind or unbind
    1.64 +
    1.65 +	    'VGA+' is the name of the driver
    1.66 +
    1.67 +	cat /sys/class/vtconsole/vtcon1/name
    1.68 +	(M) frame buffer device
    1.69 +
    1.70 +	    In this case, '(M)' stands for a (M)odular driver, one that can be
    1.71 +	    directly commanded to bind or unbind.
    1.72 +
    1.73 +     3. uevent - ignore this file
    1.74 +
    1.75 +When unbinding, the modular driver is detached first, and then the system
    1.76 +driver takes over the consoles vacated by the driver. Binding, on the other
    1.77 +hand, will bind the driver to the consoles that are currently occupied by a
    1.78 +system driver.
    1.79 +
    1.80 +NOTE1: Binding and binding must be selected in Kconfig. It's under:
    1.81 +
    1.82 +Device Drivers -> Character devices -> Support for binding and unbinding
    1.83 +console drivers
    1.84 +
    1.85 +NOTE2: If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
    1.86 +unbinding will not succeed. An example of an application that sets the console
    1.87 +to KD_GRAPHICS is X.
    1.88 +
    1.89 +How useful is this feature? This is very useful for console driver
    1.90 +developers. By unbinding the driver from the console layer, one can unload the
    1.91 +driver, make changes, recompile, reload and rebind the driver without any need
    1.92 +for rebooting the kernel. For regular users who may want to switch from
    1.93 +framebuffer console to VGA console and vice versa, this feature also makes
    1.94 +this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb
    1.95 +for more details).
    1.96 +
    1.97 +Notes for developers:
    1.98 +=====================
    1.99 +
   1.100 +take_over_console() is now broken up into:
   1.101 +
   1.102 +     register_con_driver()
   1.103 +     bind_con_driver() - private function
   1.104 +
   1.105 +give_up_console() is a wrapper to unregister_con_driver(), and a driver must
   1.106 +be fully unbound for this call to succeed. con_is_bound() will check if the
   1.107 +driver is bound or not.
   1.108 +
   1.109 +Guidelines for console driver writers:
   1.110 +=====================================
   1.111 +
   1.112 +In order for binding to and unbinding from the console to properly work,
   1.113 +console drivers must follow these guidelines:
   1.114 +
   1.115 +1. All drivers, except system drivers, must call either register_con_driver()
   1.116 +   or take_over_console(). register_con_driver() will just add the driver to
   1.117 +   the console's internal list. It won't take over the
   1.118 +   console. take_over_console(), as it name implies, will also take over (or
   1.119 +   bind to) the console.
   1.120 +
   1.121 +2. All resources allocated during con->con_init() must be released in
   1.122 +   con->con_deinit().
   1.123 +
   1.124 +3. All resources allocated in con->con_startup() must be released when the
   1.125 +   driver, which was previously bound, becomes unbound.  The console layer
   1.126 +   does not have a complementary call to con->con_startup() so it's up to the
   1.127 +   driver to check when it's legal to release these resources. Calling
   1.128 +   con_is_bound() in con->con_deinit() will help.  If the call returned
   1.129 +   false(), then it's safe to release the resources.  This balance has to be
   1.130 +   ensured because con->con_startup() can be called again when a request to
   1.131 +   rebind the driver to the console arrives.
   1.132 +
   1.133 +4. Upon exit of the driver, ensure that the driver is totally unbound. If the
   1.134 +   condition is satisfied, then the driver must call unregister_con_driver()
   1.135 +   or give_up_console().
   1.136 +
   1.137 +5. unregister_con_driver() can also be called on conditions which make it
   1.138 +   impossible for the driver to service console requests.  This can happen
   1.139 +   with the framebuffer console that suddenly lost all of its drivers.
   1.140 +
   1.141 +The current crop of console drivers should still work correctly, but binding
   1.142 +and unbinding them may cause problems. With minimal fixes, these drivers can
   1.143 +be made to work correctly.
   1.144 +
   1.145 +==========================
   1.146 +Antonino Daplas <adaplas@pol.net>
   1.147 +