0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =============================
0004 TTY Driver and TTY Operations
0005 =============================
0006
0007 .. contents:: :local:
0008
0009 Allocation
0010 ==========
0011
0012 The first thing a driver needs to do is to allocate a struct tty_driver. This
0013 is done by tty_alloc_driver() (or __tty_alloc_driver()). Next, the newly
0014 allocated structure is filled with information. See `TTY Driver Reference`_ at
0015 the end of this document on what actually shall be filled in.
0016
0017 The allocation routines expect a number of devices the driver can handle at
0018 most and flags. Flags are those starting ``TTY_DRIVER_`` listed and described
0019 in `TTY Driver Flags`_ below.
0020
0021 When the driver is about to be freed, tty_driver_kref_put() is called on that.
0022 It will decrements the reference count and if it reaches zero, the driver is
0023 freed.
0024
0025 For reference, both allocation and deallocation functions are explained here in
0026 detail:
0027
0028 .. kernel-doc:: drivers/tty/tty_io.c
0029 :identifiers: __tty_alloc_driver tty_driver_kref_put
0030
0031 TTY Driver Flags
0032 ----------------
0033
0034 Here comes the documentation of flags accepted by tty_alloc_driver() (or
0035 __tty_alloc_driver()):
0036
0037 .. kernel-doc:: include/linux/tty_driver.h
0038 :doc: TTY Driver Flags
0039
0040 ----
0041
0042 Registration
0043 ============
0044
0045 When a struct tty_driver is allocated and filled in, it can be registered using
0046 tty_register_driver(). It is recommended to pass ``TTY_DRIVER_DYNAMIC_DEV`` in
0047 flags of tty_alloc_driver(). If it is not passed, *all* devices are also
0048 registered during tty_register_driver() and the following paragraph of
0049 registering devices can be skipped for such drivers. However, the struct
0050 tty_port part in `Registering Devices`_ is still relevant there.
0051
0052 .. kernel-doc:: drivers/tty/tty_io.c
0053 :identifiers: tty_register_driver tty_unregister_driver
0054
0055 Registering Devices
0056 -------------------
0057
0058 Every TTY device shall be backed by a struct tty_port. Usually, TTY drivers
0059 embed tty_port into device's private structures. Further details about handling
0060 tty_port can be found in :doc:`tty_port`. The driver is also recommended to use
0061 tty_port's reference counting by tty_port_get() and tty_port_put(). The final
0062 put is supposed to free the tty_port including the device's private struct.
0063
0064 Unless ``TTY_DRIVER_DYNAMIC_DEV`` was passed as flags to tty_alloc_driver(),
0065 TTY driver is supposed to register every device discovered in the system
0066 (the latter is preferred). This is performed by tty_register_device(). Or by
0067 tty_register_device_attr() if the driver wants to expose some information
0068 through struct attribute_group. Both of them register ``index``'th device and
0069 upon return, the device can be opened. There are also preferred tty_port
0070 variants described in `Linking Devices to Ports`_ later. It is up to driver to
0071 manage free indices and choosing the right one. The TTY layer only refuses to
0072 register more devices than passed to tty_alloc_driver().
0073
0074 When the device is opened, the TTY layer allocates struct tty_struct and starts
0075 calling operations from :c:member:`tty_driver.ops`, see `TTY Operations
0076 Reference`_.
0077
0078 The registration routines are documented as follows:
0079
0080 .. kernel-doc:: drivers/tty/tty_io.c
0081 :identifiers: tty_register_device tty_register_device_attr
0082 tty_unregister_device
0083
0084 ----
0085
0086 Linking Devices to Ports
0087 ------------------------
0088 As stated earlier, every TTY device shall have a struct tty_port assigned to
0089 it. It must be known to the TTY layer at :c:member:`tty_driver.ops.install()`
0090 at latest. There are few helpers to *link* the two. Ideally, the driver uses
0091 tty_port_register_device() or tty_port_register_device_attr() instead of
0092 tty_register_device() and tty_register_device_attr() at the registration time.
0093 This way, the driver needs not care about linking later on.
0094
0095 If that is not possible, the driver still can link the tty_port to a specific
0096 index *before* the actual registration by tty_port_link_device(). If it still
0097 does not fit, tty_port_install() can be used from the
0098 :c:member:`tty_driver.ops.install` hook as a last resort. The last one is
0099 dedicated mostly for in-memory devices like PTY where tty_ports are allocated
0100 on demand.
0101
0102 The linking routines are documented here:
0103
0104 .. kernel-doc:: drivers/tty/tty_port.c
0105 :identifiers: tty_port_link_device tty_port_register_device
0106 tty_port_register_device_attr
0107
0108 ----
0109
0110 TTY Driver Reference
0111 ====================
0112
0113 All members of struct tty_driver are documented here. The required members are
0114 noted at the end. struct tty_operations are documented next.
0115
0116 .. kernel-doc:: include/linux/tty_driver.h
0117 :identifiers: tty_driver
0118
0119 ----
0120
0121 TTY Operations Reference
0122 ========================
0123
0124 When a TTY is registered, these driver hooks can be invoked by the TTY layer:
0125
0126 .. kernel-doc:: include/linux/tty_driver.h
0127 :identifiers: tty_operations
0128
