1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ============================= 3 =============================
4 TTY Driver and TTY Operations 4 TTY Driver and TTY Operations
5 ============================= 5 =============================
6 6
7 .. contents:: :local: 7 .. contents:: :local:
8 8
9 Allocation 9 Allocation
10 ========== 10 ==========
11 11
12 The first thing a driver needs to do is to all 12 The first thing a driver needs to do is to allocate a struct tty_driver. This
13 is done by tty_alloc_driver() (or __tty_alloc_ 13 is done by tty_alloc_driver() (or __tty_alloc_driver()). Next, the newly
14 allocated structure is filled with information 14 allocated structure is filled with information. See `TTY Driver Reference`_ at
15 the end of this document on what actually shal 15 the end of this document on what actually shall be filled in.
16 16
17 The allocation routines expect a number of dev 17 The allocation routines expect a number of devices the driver can handle at
18 most and flags. Flags are those starting ``TTY 18 most and flags. Flags are those starting ``TTY_DRIVER_`` listed and described
19 in `TTY Driver Flags`_ below. 19 in `TTY Driver Flags`_ below.
20 20
21 When the driver is about to be freed, tty_driv 21 When the driver is about to be freed, tty_driver_kref_put() is called on that.
22 It will decrements the reference count and if 22 It will decrements the reference count and if it reaches zero, the driver is
23 freed. 23 freed.
24 24
25 For reference, both allocation and deallocatio 25 For reference, both allocation and deallocation functions are explained here in
26 detail: 26 detail:
27 27
28 .. kernel-doc:: drivers/tty/tty_io.c 28 .. kernel-doc:: drivers/tty/tty_io.c
29 :identifiers: __tty_alloc_driver tty_driver 29 :identifiers: __tty_alloc_driver tty_driver_kref_put
30 30
31 TTY Driver Flags 31 TTY Driver Flags
32 ---------------- 32 ----------------
33 33
34 Here comes the documentation of flags accepted 34 Here comes the documentation of flags accepted by tty_alloc_driver() (or
35 __tty_alloc_driver()): 35 __tty_alloc_driver()):
36 36
37 .. kernel-doc:: include/linux/tty_driver.h 37 .. kernel-doc:: include/linux/tty_driver.h
38 :doc: TTY Driver Flags 38 :doc: TTY Driver Flags
39 39
40 ---- 40 ----
41 41
42 Registration 42 Registration
43 ============ 43 ============
44 44
45 When a struct tty_driver is allocated and fill 45 When a struct tty_driver is allocated and filled in, it can be registered using
46 tty_register_driver(). It is recommended to pa 46 tty_register_driver(). It is recommended to pass ``TTY_DRIVER_DYNAMIC_DEV`` in
47 flags of tty_alloc_driver(). If it is not pass 47 flags of tty_alloc_driver(). If it is not passed, *all* devices are also
48 registered during tty_register_driver() and th 48 registered during tty_register_driver() and the following paragraph of
49 registering devices can be skipped for such dr 49 registering devices can be skipped for such drivers. However, the struct
50 tty_port part in `Registering Devices`_ is sti 50 tty_port part in `Registering Devices`_ is still relevant there.
51 51
52 .. kernel-doc:: drivers/tty/tty_io.c 52 .. kernel-doc:: drivers/tty/tty_io.c
53 :identifiers: tty_register_driver tty_unreg 53 :identifiers: tty_register_driver tty_unregister_driver
54 54
55 Registering Devices 55 Registering Devices
56 ------------------- 56 -------------------
57 57
58 Every TTY device shall be backed by a struct t 58 Every TTY device shall be backed by a struct tty_port. Usually, TTY drivers
59 embed tty_port into device's private structure 59 embed tty_port into device's private structures. Further details about handling
60 tty_port can be found in :doc:`tty_port`. The 60 tty_port can be found in :doc:`tty_port`. The driver is also recommended to use
61 tty_port's reference counting by tty_port_get( 61 tty_port's reference counting by tty_port_get() and tty_port_put(). The final
62 put is supposed to free the tty_port including 62 put is supposed to free the tty_port including the device's private struct.
63 63
64 Unless ``TTY_DRIVER_DYNAMIC_DEV`` was passed a 64 Unless ``TTY_DRIVER_DYNAMIC_DEV`` was passed as flags to tty_alloc_driver(),
65 TTY driver is supposed to register every devic 65 TTY driver is supposed to register every device discovered in the system
66 (the latter is preferred). This is performed b 66 (the latter is preferred). This is performed by tty_register_device(). Or by
67 tty_register_device_attr() if the driver wants 67 tty_register_device_attr() if the driver wants to expose some information
68 through struct attribute_group. Both of them r 68 through struct attribute_group. Both of them register ``index``'th device and
69 upon return, the device can be opened. There a 69 upon return, the device can be opened. There are also preferred tty_port
70 variants described in `Linking Devices to Port 70 variants described in `Linking Devices to Ports`_ later. It is up to driver to
71 manage free indices and choosing the right one 71 manage free indices and choosing the right one. The TTY layer only refuses to
72 register more devices than passed to tty_alloc 72 register more devices than passed to tty_alloc_driver().
73 73
74 When the device is opened, the TTY layer alloc 74 When the device is opened, the TTY layer allocates struct tty_struct and starts
75 calling operations from :c:member:`tty_driver. 75 calling operations from :c:member:`tty_driver.ops`, see `TTY Operations
76 Reference`_. 76 Reference`_.
77 77
78 The registration routines are documented as fo 78 The registration routines are documented as follows:
79 79
80 .. kernel-doc:: drivers/tty/tty_io.c 80 .. kernel-doc:: drivers/tty/tty_io.c
81 :identifiers: tty_register_device tty_regis 81 :identifiers: tty_register_device tty_register_device_attr
82 tty_unregister_device 82 tty_unregister_device
83 83
84 ---- 84 ----
85 85
86 Linking Devices to Ports 86 Linking Devices to Ports
87 ------------------------ 87 ------------------------
88 As stated earlier, every TTY device shall have 88 As stated earlier, every TTY device shall have a struct tty_port assigned to
89 it. It must be known to the TTY layer at :c:me 89 it. It must be known to the TTY layer at :c:member:`tty_driver.ops.install()`
90 at latest. There are few helpers to *link* th 90 at latest. There are few helpers to *link* the two. Ideally, the driver uses
91 tty_port_register_device() or tty_port_registe 91 tty_port_register_device() or tty_port_register_device_attr() instead of
92 tty_register_device() and tty_register_device_ 92 tty_register_device() and tty_register_device_attr() at the registration time.
93 This way, the driver needs not care about link 93 This way, the driver needs not care about linking later on.
94 94
95 If that is not possible, the driver still can 95 If that is not possible, the driver still can link the tty_port to a specific
96 index *before* the actual registration by tty_ 96 index *before* the actual registration by tty_port_link_device(). If it still
97 does not fit, tty_port_install() can be used f 97 does not fit, tty_port_install() can be used from the
98 :c:member:`tty_driver.ops.install` hook as a l 98 :c:member:`tty_driver.ops.install` hook as a last resort. The last one is
99 dedicated mostly for in-memory devices like PT 99 dedicated mostly for in-memory devices like PTY where tty_ports are allocated
100 on demand. 100 on demand.
101 101
102 The linking routines are documented here: 102 The linking routines are documented here:
103 103
104 .. kernel-doc:: drivers/tty/tty_port.c 104 .. kernel-doc:: drivers/tty/tty_port.c
105 :identifiers: tty_port_link_device tty_port 105 :identifiers: tty_port_link_device tty_port_register_device
106 tty_port_register_device_attr 106 tty_port_register_device_attr
107 107
108 ---- 108 ----
109 109
110 TTY Driver Reference 110 TTY Driver Reference
111 ==================== 111 ====================
112 112
113 All members of struct tty_driver are documente 113 All members of struct tty_driver are documented here. The required members are
114 noted at the end. struct tty_operations are do 114 noted at the end. struct tty_operations are documented next.
115 115
116 .. kernel-doc:: include/linux/tty_driver.h 116 .. kernel-doc:: include/linux/tty_driver.h
117 :identifiers: tty_driver 117 :identifiers: tty_driver
118 118
119 ---- 119 ----
120 120
121 TTY Operations Reference 121 TTY Operations Reference
122 ======================== 122 ========================
123 123
124 When a TTY is registered, these driver hooks c 124 When a TTY is registered, these driver hooks can be invoked by the TTY layer:
125 125
126 .. kernel-doc:: include/linux/tty_driver.h 126 .. kernel-doc:: include/linux/tty_driver.h
127 :identifiers: tty_operations 127 :identifiers: tty_operations
128 128
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.