The following changes:
Docs: console.txt: A complete overhaul
since commit 9e79e3e9dd9672b37ac9412e9a926714306551fe:
Merge git://git.kernel.org/pub/scm/linux/kernel/git/davem/sparc
(2011-08-30 11:28:18 -0700)
are available in the git repository at:
git://github.com/mfwitten/linux.git docs/console
For various reasons, I didn't produce a fine-grained patch series;
there is just this blob of new text, which renders the diff somewhat
useless.
Consequently, I present in the following the full text of the
refurbished Documentation/console/console.txt (fortunately, it's not
terribly long):
Console Drivers
===============
The linux kernel has 2 general types of console driver.
System driver
-------------
The driver of this type is bound to all virtual consoles during the boot
process. Only one system driver is allowed to be registered; the system
driver is persistent and it may never be unregistered, though it may become
unbound from any virtual console.
Modular driver
--------------
A driver of this type must be explicitly registered, bound, unbound, and
unregistered.
NOTE: The ability to bind and unbind a modular driver must be enabled
when configuring the kernel:
Device Drivers
|
+-> Character devices
|
+-> Support for binding and unbinding console drivers
Binding and Unbinding
=====================
Multiple drivers may be simultaneously registered with the virtual terminal
layer. However, only one driver may be bound to a particular virtual console
at a given time, as described by the following rules:
* When no driver is bound to a particular virtual console, then the system
driver is automatically bound to it.
* When the system driver is bound to a particular virtual console, then
binding a modular driver to that virtual console automatically unbinds
the system driver first, thereby allowing the modular driver to be bound
to it.
* Usually, it is necessary to unbind one modular driver before binding
another modular driver to the same virtual console.
* If a driver is bound to any virtual console that is in KD_GRAPHICS mode,
then binding and unbinding that driver will not succeed; the X Window
System is an example of an application that sets the console to
KD_GRAPHICS mode.
The ability to register, bind, unbind, and unregister a console driver is
mainly useful to developers; a driver in development could be unbound from
the virtual console(s), unregistered, rebuilt from source, reregistered,
and rebound to the virtual console(s) without any need for rebooting the
kernel. Of course, end users may use this feature e.g. to switch between a
framebuffer console driver and a VGA console driver (please read fbcon.txt
under Documentation/fb for more details).
The sysfs Interface
===================
It is intended that modern drivers may only be bound to the virtual console(s)
and unbound through a sysfs interface.
When sysfs is enabled, the directory /sys/class/vtconsole/ contains one
subdirectory for each registered console driver; these subdirectories are
named vtcon<n>, where <n> is an integer from 0 to 15. Thus:
$ ls /sys/class/vtconsole
. .. vtcon0 vtcon1
Each such subdirectory has at least 3 noteworthy files:
$ ls /sys/class/vtconsole/vtcon0
. .. bind name uevent
Specifically:
bind (read/write)
-----------------
It shows the status of the driver when read, or acts to bind or unbind the
driver to the virtual console(s) when written to. The possible values are:
0: When read, it means the driver is unbound from all virtual consoles.
When written, it commands the virtual terminal layer to unbind the
driver from all virtual consoles to which it is bound.
1: When read, it means the driver is bound to at least one virtual
console. When written, it commands the virtual terminal layer
to attempt to bind the driver to some predetermined range of virtual
consoles; ultimately, the driver is only bound to those virtual
consoles for which binding is allowed, as per the aformentioned rules.
name (read-only)
----------------
It shows the name of the driver, using this format:
(<type>) <name>
where <type> may be 'S' for 'system driver' or 'M' for 'modular driver',
and <name> may be some arbitrary string. For example:
$ cat /sys/class/vtconsole/vtcon0/name
(S) VGA+
$ cat /sys/class/vtconsole/vtcon1/name
(M) frame buffer device
uevent
------
Ignore this file.
Notes for Developers
====================
Traditionally, a modular driver is set up and torn down with the following
functions:
* take_over_console() /* Register and forcibly bind the driver. */
* give_up_console() /* Unregister the driver. */
For backwards compatibility, a call to the function take_over_console() first
automatically unbinds any (possibly modular) driver that is currently bound to
the conflicting virtual console(s), and then binds the provided console driver
to the virtual console(s) in question; this is the only public interface
outside of sysfs for controlling the binding and unbinding of drivers.
In order for give_up_console() to succeed, the provided driver must be unbound
from all virtual consoles; con_is_bound() may be used to determine whether
the provided driver is bound to any virtual console.
With newer kernels, a driver should only be registered and unregistered with
the following (leaving binding and unbinding to the sysfs interface):
* register_con_driver() /* Register the driver. */
* unregister_con_driver() /* Unregister the driver. */
In fact, give_up_console() is an alias for unregister_con_driver(), and
take_over_console() is now implemented with calls to:
* register_con_driver()
* bind_con_driver() /* This is a private function. */
In order for binding and unbinding to work properly, console drivers must
follow these guidelines:
* All modular drivers must call either register_con_driver() or
take_over_console().
* All resources allocated by con->con_init() must be release by
con->con_deinit().
* All resources allocated by con->con_startup() must be released
when the driver is unbound from all virtual consoles after having
been previously bound to at least one virtual console.
This balance must be ensured because con->con_startup() might be
called again when another request arrives to bind the driver to a
virtual console once more.
Unlike con->con_init(), there is no complement to con->con_startup()
for the explicit purpose of such releasing; consequently, it's up
to the driver to check when it may do so safely. For instance, a
driver may call con_is_bound() in con->con_deinit(), releasing the
resources if the result is false.
* Before exiting, a driver must ensure that it is unregistered
via a call to either unregister_con_driver() or give_up_console();
note that these calls to these functions only succeed if the driver
is already unbound from all virtual consoles.
* unregister_con_driver() may also be called under any condition
that makes it impossible for the driver to service console requests.
Older console drivers should still work correctly, but binding and unbinding
them may cause problems. With minimal fixes, these drivers could be made to
work correctly.
==========================
Originally written by Antonino Daplas <adaplas@xxxxxxx>
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
