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