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