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