Documentation: add TTY chapter

   misc-devices/index

   scheduler/index

   mhi/index

   tty/index

Architecture-agnostic documentation

-----------------------------------

.. SPDX-License-Identifier: GPL-2.0

===

TTY

===

Teletypewriter (TTY) layer takes care of all those serial devices. Including

the virtual ones like pseudoterminal (PTY).

TTY structures

==============

There are several major TTY structures. Every TTY device in a system has a

corresponding struct tty_port. These devices are maintained by a TTY driver

which is struct tty_driver. This structure describes the driver but also

contains a reference to operations which could be performed on the TTYs. It is

struct tty_operations. Then, upon open, a struct tty_struct is allocated and

lives until the final close. During this time, several callbacks from struct

tty_operations are invoked by the TTY layer.

Every character received by the kernel (both from devices and users) is passed

through a preselected :doc:`tty_ldisc` (in

short ldisc; in C, struct tty_ldisc_ops). Its task is to transform characters

as defined by a particular ldisc or by user too. The default one is n_tty,

implementing echoes, signal handling, jobs control, special characters

processing, and more. The transformed characters are passed further to

user/device, depending on the source.

In-detail description of the named TTY structures is in separate documents:

.. toctree::

   :maxdepth: 2

   tty_driver

   tty_port

   tty_struct

   tty_ldisc

   tty_buffer

   n_tty

   tty_internals

Writing TTY Driver

==================

Before one starts writing a TTY driver, they must consider

:doc:`Serial <../driver-api/serial/driver>` and :doc:`USB Serial

<../usb/usb-serial>` layers

first. Drivers for serial devices can often use one of these specific layers to

implement a serial driver. Only special devices should be handled directly by

the TTY Layer. If you are about to write such a driver, read on.

A *typical* sequence a TTY driver performs is as follows:

#. Allocate and register a TTY driver (module init)

#. Create and register TTY devices as they are probed (probe function)

#. Handle TTY operations and events like interrupts (TTY core invokes the

   former, the device the latter)

#. Remove devices as they are going away (remove function)

#. Unregister and free the TTY driver (module exit)

Steps regarding driver, i.e. 1., 3., and 5. are described in detail in

:doc:`tty_driver`. For the other two (devices handling), look into

:doc:`tty_port`.

.. SPDX-License-Identifier: GPL-2.0

=====

N_TTY

=====

.. contents:: :local:

The default (and fallback) :doc:`TTY line discipline <tty_ldisc>`. It tries to

handle characters as per POSIX.

External Functions

==================

.. kernel-doc:: drivers/tty/n_tty.c

   :export:

Internal Functions

==================

.. kernel-doc:: drivers/tty/n_tty.c

   :internal:

.. SPDX-License-Identifier: GPL-2.0

==========

TTY Buffer

==========

.. contents:: :local:

Here, we document functions for taking care of tty buffer and their flipping.

Drivers are supposed to fill the buffer by one of those functions below and

then flip the buffer, so that the data are passed to :doc:`line discipline

<tty_ldisc>` for further processing.

Flip Buffer Management

======================

.. kernel-doc:: drivers/tty/tty_buffer.c

   :identifiers: tty_prepare_flip_string tty_insert_flip_string_fixed_flag

           tty_insert_flip_string_flags __tty_insert_flip_char

           tty_flip_buffer_push tty_ldisc_receive_buf

----

Other Functions

===============

.. kernel-doc:: drivers/tty/tty_buffer.c

   :identifiers: tty_buffer_space_avail tty_buffer_set_limit

----

Buffer Locking

==============

These are used only in special circumstances. Avoid them.

.. kernel-doc:: drivers/tty/tty_buffer.c

   :identifiers: tty_buffer_lock_exclusive tty_buffer_unlock_exclusive

----

Internal Functions

==================

.. kernel-doc:: drivers/tty/tty_buffer.c

   :internal:

.. SPDX-License-Identifier: GPL-2.0

=============================

TTY Driver and TTY Operations

=============================

.. contents:: :local:

Allocation

==========

The first thing a driver needs to do is to allocate a struct tty_driver. This

is done by tty_alloc_driver() (or __tty_alloc_driver()). Next, the newly

allocated structure is filled with information. See `TTY Driver Reference`_ at

the end of this document on what actually shall be filled in.

The allocation routines expect a number of devices the driver can handle at

most and flags. Flags are those starting ``TTY_DRIVER_`` listed and described

in `TTY Driver Flags`_ below.

When the driver is about to be freed, tty_driver_kref_put() is called on that.

It will decrements the reference count and if it reaches zero, the driver is

freed.

For reference, both allocation and deallocation functions are explained here in

detail:

.. kernel-doc:: drivers/tty/tty_io.c

   :identifiers: __tty_alloc_driver tty_driver_kref_put

TTY Driver Flags

----------------

Here comes the documentation of flags accepted by tty_alloc_driver() (or

__tty_alloc_driver()):

.. kernel-doc:: include/linux/tty_driver.h

   :doc: TTY Driver Flags

----

Registration

============

When a struct tty_driver is allocated and filled in, it can be registered using

tty_register_driver(). It is recommended to pass ``TTY_DRIVER_DYNAMIC_DEV`` in

flags of tty_alloc_driver(). If it is not passed, *all* devices are also

registered during tty_register_driver() and the following paragraph of

registering devices can be skipped for such drivers. However, the struct

tty_port part in `Registering Devices`_ is still relevant there.

.. kernel-doc:: drivers/tty/tty_io.c

   :identifiers: tty_register_driver tty_unregister_driver

Registering Devices

-------------------

Every TTY device shall be backed by a struct tty_port. Usually, TTY drivers

embed tty_port into device's private structures. Further details about handling

tty_port can be found in :doc:`tty_port`. The driver is also recommended to use

tty_port's reference counting by tty_port_get() and tty_port_put(). The final

put is supposed to free the tty_port including the device's private struct.

Unless ``TTY_DRIVER_DYNAMIC_DEV`` was passed as flags to tty_alloc_driver(),

TTY driver is supposed to register every device discovered in the system

(the latter is preferred). This is performed by tty_register_device(). Or by

tty_register_device_attr() if the driver wants to expose some information

through struct attribute_group. Both of them register ``index``'th device and

upon return, the device can be opened. There are also preferred tty_port

variants described in `Linking Devices to Ports`_ later. It is up to driver to

manage free indices and choosing the right one. The TTY layer only refuses to

register more devices than passed to tty_alloc_driver().

When the device is opened, the TTY layer allocates struct tty_struct and starts

calling operations from :c:member:`tty_driver.ops`, see `TTY Operations

Reference`_.

The registration routines are documented as follows:

.. kernel-doc:: drivers/tty/tty_io.c

   :identifiers: tty_register_device tty_register_device_attr

        tty_unregister_device

----

Linking Devices to Ports

------------------------

As stated earlier, every TTY device shall have a struct tty_port assigned to

it. It must be known to the TTY layer at :c:member:`tty_driver.ops.install()`

at latest.  There are few helpers to *link* the two. Ideally, the driver uses

tty_port_register_device() or tty_port_register_device_attr() instead of

tty_register_device() and tty_register_device_attr() at the registration time.

This way, the driver needs not care about linking later on.

If that is not possible, the driver still can link the tty_port to a specific

index *before* the actual registration by tty_port_link_device(). If it still

does not fit, tty_port_install() can be used from the

:c:member:`tty_driver.ops.install` hook as a last resort. The last one is

dedicated mostly for in-memory devices like PTY where tty_ports are allocated

on demand.

The linking routines are documented here:

.. kernel-doc::  drivers/tty/tty_port.c

   :identifiers: tty_port_link_device tty_port_register_device

        tty_port_register_device_attr

----

TTY Driver Reference

====================

All members of struct tty_driver are documented here. The required members are

noted at the end. struct tty_operations are documented next.

.. kernel-doc:: include/linux/tty_driver.h

   :identifiers: tty_driver

----

TTY Operations Reference

========================

When a TTY is registered, these driver hooks can be invoked by the TTY layer:

.. kernel-doc:: include/linux/tty_driver.h

   :identifiers: tty_operations