Documentation/driver-api/tty/tty_driver.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =============================
   4 TTY Driver and TTY Operations
   5 =============================
   6
   7 .. contents:: :local:
   8
   9 Allocation
  10 ==========
  11
  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_driver()). Next, the newly
  14 allocated structure is filled with information. See `TTY Driver Reference`_ at
  15 the end of this document on what actually shall be filled in.
  16
  17 The allocation routines expect a number of devices the driver can handle at
  18 most and flags. Flags are those starting ``TTY_DRIVER_`` listed and described
  19 in `TTY Driver Flags`_ below.
  20
  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 it reaches zero, the driver is
  23 freed.
  24
  25 For reference, both allocation and deallocation functions are explained here in
  26 detail:
  27
  28 .. kernel-doc:: drivers/tty/tty_io.c
  29    :identifiers: __tty_alloc_driver tty_driver_kref_put
  30
  31 TTY Driver Flags
  32 ----------------
  33
  34 Here 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
  42 Registration
  43 ============
  44
  45 When a struct tty_driver is allocated and filled in, it can be registered using
  46 tty_register_driver(). It is recommended to pass ``TTY_DRIVER_DYNAMIC_DEV`` in
  47 flags of tty_alloc_driver(). If it is not passed, *all* devices are also
  48 registered during tty_register_driver() and the following paragraph of
  49 registering devices can be skipped for such drivers. However, the struct
  50 tty_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
  55 Registering Devices
  56 -------------------
  57
  58 Every TTY device shall be backed by a struct tty_port. Usually, TTY drivers
  59 embed tty_port into device's private structures. Further details about handling
  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() and tty_port_put(). The final
  62 put is supposed to free the tty_port including the device's private struct.
  63
  64 Unless ``TTY_DRIVER_DYNAMIC_DEV`` was passed as flags to tty_alloc_driver(),
  65 TTY 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
  67 tty_register_device_attr() if the driver wants to expose some information
  68 through struct attribute_group. Both of them register ``index``'th device and
  69 upon return, the device can be opened. There are also preferred tty_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. The TTY layer only refuses to
  72 register more devices than passed to tty_alloc_driver().
  73
  74 When the device is opened, the TTY layer allocates struct tty_struct and starts
  75 calling operations from :c:member:`tty_driver.ops`, see `TTY Operations
  76 Reference`_.
  77
  78 The 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
  86 Linking Devices to Ports
  87 ------------------------
  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:member:`tty_driver.ops.install()`
  90 at latest.  There are few helpers to *link* the two. Ideally, the driver uses
  91 tty_port_register_device() or tty_port_register_device_attr() instead of
  92 tty_register_device() and tty_register_device_attr() at the registration time.
  93 This way, the driver needs not care about linking later on.
  94
  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_port_link_device(). If it still
  97 does 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
  99 dedicated mostly for in-memory devices like PTY where tty_ports are allocated
 100 on demand.
 101
 102 The 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
 110 TTY Driver Reference
 111 ====================
 112
 113 All members of struct tty_driver are documented here. The required members are
 114 noted 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
 121 TTY Operations Reference
 122 ========================
 123
 124 When 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