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