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