Commit | Line | Data |
---|---|---|
baa293e9 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
8db8acee MCC |
2 | |
3 | =============== | |
79062a0d AD |
4 | Console Drivers |
5 | =============== | |
6 | ||
3d83d318 | 7 | The Linux kernel has 2 general types of console drivers. The first type is |
79062a0d AD |
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 | |
6b5f1465 | 18 | call do_take_over_console() will succeed in the takeover regardless of the type |
79062a0d AD |
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 | ||
8db8acee | 23 | Modular drivers, from the programmer's point of view, have to call:: |
79062a0d | 24 | |
6b5f1465 | 25 | do_take_over_console() - load and bind driver to console layer |
3d83d318 RD |
26 | give_up_console() - unload driver; it will only work if driver |
27 | is fully unbound | |
79062a0d | 28 | |
8db8acee | 29 | In newer kernels, the following are also available:: |
79062a0d | 30 | |
6b5f1465 WY |
31 | do_register_con_driver() |
32 | do_unregister_con_driver() | |
79062a0d | 33 | |
6690075d AD |
34 | If sysfs is enabled, the contents of /sys/class/vtconsole can be |
35 | examined. This shows the console backends currently registered by the | |
8db8acee MCC |
36 | system which are named vtcon<n> where <n> is an integer from 0 to 15. |
37 | Thus:: | |
79062a0d | 38 | |
6690075d AD |
39 | ls /sys/class/vtconsole |
40 | . .. vtcon0 vtcon1 | |
79062a0d | 41 | |
8db8acee | 42 | Each directory in /sys/class/vtconsole has 3 files:: |
79062a0d | 43 | |
6690075d AD |
44 | ls /sys/class/vtconsole/vtcon0 |
45 | . .. bind name uevent | |
79062a0d | 46 | |
6690075d | 47 | What do these files signify? |
79062a0d | 48 | |
6690075d AD |
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: | |
79062a0d | 52 | |
8db8acee MCC |
53 | 0 |
54 | - means the driver is not bound and if echo'ed, commands the driver | |
6690075d | 55 | to unbind |
79062a0d | 56 | |
8db8acee MCC |
57 | 1 |
58 | - means the driver is bound and if echo'ed, commands the driver to | |
6690075d | 59 | bind |
79062a0d | 60 | |
8db8acee | 61 | 2. name - read-only file. Shows the name of the driver in this format:: |
6690075d | 62 | |
8db8acee MCC |
63 | cat /sys/class/vtconsole/vtcon0/name |
64 | (S) VGA+ | |
6690075d | 65 | |
8db8acee MCC |
66 | '(S)' stands for a (S)ystem driver, i.e., it cannot be directly |
67 | commanded to bind or unbind | |
6690075d | 68 | |
8db8acee | 69 | 'VGA+' is the name of the driver |
6690075d | 70 | |
8db8acee MCC |
71 | cat /sys/class/vtconsole/vtcon1/name |
72 | (M) frame buffer device | |
6690075d | 73 | |
8db8acee MCC |
74 | In this case, '(M)' stands for a (M)odular driver, one that can be |
75 | directly commanded to bind or unbind. | |
6690075d AD |
76 | |
77 | 3. uevent - ignore this file | |
79062a0d AD |
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 | ||
8db8acee MCC |
84 | NOTE1: |
85 | Binding and unbinding must be selected in Kconfig. It's under:: | |
6690075d | 86 | |
8db8acee MCC |
87 | Device Drivers -> |
88 | Character devices -> | |
89 | Support for binding and unbinding console drivers | |
6690075d | 90 | |
8db8acee MCC |
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. | |
6690075d | 95 | |
79062a0d AD |
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 | |
3d83d318 | 102 | for more details.) |
79062a0d | 103 | |
8db8acee MCC |
104 | Notes for developers |
105 | ==================== | |
79062a0d | 106 | |
8db8acee | 107 | do_take_over_console() is now broken up into:: |
79062a0d | 108 | |
6b5f1465 WY |
109 | do_register_con_driver() |
110 | do_bind_con_driver() - private function | |
79062a0d | 111 | |
6b5f1465 | 112 | give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must |
79062a0d AD |
113 | be fully unbound for this call to succeed. con_is_bound() will check if the |
114 | driver is bound or not. | |
115 | ||
8db8acee | 116 | Guidelines for console driver writers |
79062a0d AD |
117 | ===================================== |
118 | ||
119 | In order for binding to and unbinding from the console to properly work, | |
120 | console drivers must follow these guidelines: | |
121 | ||
6b5f1465 | 122 | 1. All drivers, except system drivers, must call either do_register_con_driver() |
3d83d318 RD |
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 | |
6b5f1465 | 125 | console. do_take_over_console(), as it name implies, will also take over (or |
79062a0d AD |
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 | |
6b5f1465 | 141 | condition is satisfied, then the driver must call do_unregister_con_driver() |
79062a0d AD |
142 | or give_up_console(). |
143 | ||
6b5f1465 | 144 | 5. do_unregister_con_driver() can also be called on conditions which make it |
79062a0d AD |
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 | ||
79062a0d | 152 | Antonino Daplas <adaplas@pol.net> |