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