Documentation/driver-api/tty/index.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===
   4 TTY
   5 ===
   6
   7 Teletypewriter (TTY) layer takes care of all those serial devices. Including
   8 the virtual ones like pseudoterminal (PTY).
   9
  10 TTY structures
  11 ==============
  12
  13 There are several major TTY structures. Every TTY device in a system has a
  14 corresponding struct tty_port. These devices are maintained by a TTY driver
  15 which is struct tty_driver. This structure describes the driver but also
  16 contains a reference to operations which could be performed on the TTYs. It is
  17 struct tty_operations. Then, upon open, a struct tty_struct is allocated and
  18 lives until the final close. During this time, several callbacks from struct
  19 tty_operations are invoked by the TTY layer.
  20
  21 Every character received by the kernel (both from devices and users) is passed
  22 through a preselected :doc:`tty_ldisc` (in
  23 short ldisc; in C, struct tty_ldisc_ops). Its task is to transform characters
  24 as defined by a particular ldisc or by user too. The default one is n_tty,
  25 implementing echoes, signal handling, jobs control, special characters
  26 processing, and more. The transformed characters are passed further to
  27 user/device, depending on the source.
  28
  29 In-detail description of the named TTY structures is in separate documents:
  30
  31 .. toctree::
  32    :maxdepth: 2
  33
  34    tty_driver
  35    tty_port
  36    tty_struct
  37    tty_ldisc
  38    tty_buffer
  39    tty_ioctl
  40    tty_internals
  41
  42 Writing TTY Driver
  43 ==================
  44
  45 Before one starts writing a TTY driver, they must consider
  46 :doc:`Serial <../serial/driver>` and :doc:`USB Serial <../../usb/usb-serial>`
  47 layers first. Drivers for serial devices can often use one of these specific
  48 layers to implement a serial driver. Only special devices should be handled
  49 directly by the TTY Layer. If you are about to write such a driver, read on.
  50
  51 A *typical* sequence a TTY driver performs is as follows:
  52
  53 #. Allocate and register a TTY driver (module init)
  54 #. Create and register TTY devices as they are probed (probe function)
  55 #. Handle TTY operations and events like interrupts (TTY core invokes the
  56    former, the device the latter)
  57 #. Remove devices as they are going away (remove function)
  58 #. Unregister and free the TTY driver (module exit)
  59
  60 Steps regarding driver, i.e. 1., 3., and 5. are described in detail in
  61 :doc:`tty_driver`. For the other two (devices handling), look into
  62 :doc:`tty_port`.
  63
  64 Other Documentation
  65 ===================
  66
  67 Miscellaneous documentation can be further found in these documents:
  68
  69 .. toctree::
  70    :maxdepth: 2
  71
  72    moxa-smartio
  73    n_gsm
  74    n_tty