Documentation: move tty to driver-api

Based on discussion starting as 87mthw2o93.fsf@meer.lwn.net, let's move
the tty documentation to driver-api. It's more appropriate there.

Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20220411110143.10019-2-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

8 files changed, 0 insertions, 526 deletions

diff --git a/Documentation/tty/index.rst b/Documentation/tty/index.rst
deleted file mode 100644
index 21ea0cb21e55..000000000000
--- a/Documentation/tty/index.rst
+++ /dev/null
@@ -1,63 +0,0 @@
-.. 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`.
diff --git a/Documentation/tty/n_tty.rst b/Documentation/tty/n_tty.rst
deleted file mode 100644
index 15b70faee72d..000000000000
--- a/Documentation/tty/n_tty.rst
+++ /dev/null
@@ -1,22 +0,0 @@
-.. 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:
diff --git a/Documentation/tty/tty_buffer.rst b/Documentation/tty/tty_buffer.rst
deleted file mode 100644
index a39d4781e0d2..000000000000
--- a/Documentation/tty/tty_buffer.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-.. 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:
diff --git a/Documentation/tty/tty_driver.rst b/Documentation/tty/tty_driver.rst
deleted file mode 100644
index cc529f863406..000000000000
--- a/Documentation/tty/tty_driver.rst
+++ /dev/null
@@ -1,128 +0,0 @@
-.. 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
-
diff --git a/Documentation/tty/tty_internals.rst b/Documentation/tty/tty_internals.rst
deleted file mode 100644
index d0d415820300..000000000000
--- a/Documentation/tty/tty_internals.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-=============
-TTY Internals
-=============
-
-.. contents:: :local:
-
-Kopen
-=====
-
-These functions serve for opening a TTY from the kernelspace:
-
-.. kernel-doc:: drivers/tty/tty_io.c
-      :identifiers: tty_kopen_exclusive tty_kopen_shared tty_kclose
-
-----
-
-Exported Internal Functions
-===========================
-
-.. kernel-doc:: drivers/tty/tty_io.c
-   :identifiers: tty_release_struct tty_dev_name_to_number tty_get_icount
-
-----
-
-Internal Functions
-==================
-
-.. kernel-doc:: drivers/tty/tty_io.c
-   :internal:
diff --git a/Documentation/tty/tty_ldisc.rst b/Documentation/tty/tty_ldisc.rst
deleted file mode 100644
index 5144751be804..000000000000
--- a/Documentation/tty/tty_ldisc.rst
+++ /dev/null
@@ -1,85 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-===================
-TTY Line Discipline
-===================
-
-.. contents:: :local:
-
-TTY line discipline process all incoming and outgoing character from/to a tty
-device. The default line discipline is :doc:`N_TTY <n_tty>`. It is also a
-fallback if establishing any other discipline for a tty fails. If even N_TTY
-fails, N_NULL takes over. That never fails, but also does not process any
-characters -- it throws them away.
-
-Registration
-============
-
-Line disciplines are registered with tty_register_ldisc() passing the ldisc
-structure. At the point of registration the discipline must be ready to use and
-it is possible it will get used before the call returns success. If the call
-returns an error then it won’t get called. Do not re-use ldisc numbers as they
-are part of the userspace ABI and writing over an existing ldisc will cause
-demons to eat your computer. You must not re-register over the top of the line
-discipline even with the same data or your computer again will be eaten by
-demons. In order to remove a line discipline call tty_unregister_ldisc().
-
-Heed this warning: the reference count field of the registered copies of the
-tty_ldisc structure in the ldisc table counts the number of lines using this
-discipline. The reference count of the tty_ldisc structure within a tty counts
-the number of active users of the ldisc at this instant. In effect it counts
-the number of threads of execution within an ldisc method (plus those about to
-enter and exit although this detail matters not).
-
-.. kernel-doc:: drivers/tty/tty_ldisc.c
-   :identifiers: tty_register_ldisc tty_unregister_ldisc
-
-Other Functions
-===============
-
-.. kernel-doc:: drivers/tty/tty_ldisc.c
-   :identifiers: tty_set_ldisc tty_ldisc_flush
-
-Line Discipline Operations Reference
-====================================
-
-.. kernel-doc:: include/linux/tty_ldisc.h
-   :identifiers: tty_ldisc_ops
-
-Driver Access
-=============
-
-Line discipline methods can call the methods of the underlying hardware driver.
-These are documented as a part of struct tty_operations.
-
-TTY Flags
-=========
-
-Line discipline methods have access to :c:member:`tty_struct.flags` field. See
-:doc:`tty_struct`.
-
-Locking
-=======
-
-Callers to the line discipline functions from the tty layer are required to
-take line discipline locks. The same is true of calls from the driver side
-but not yet enforced.
-
-.. kernel-doc:: drivers/tty/tty_ldisc.c
-   :identifiers: tty_ldisc_ref_wait tty_ldisc_ref tty_ldisc_deref
-
-While these functions are slightly slower than the old code they should have
-minimal impact as most receive logic uses the flip buffers and they only
-need to take a reference when they push bits up through the driver.
-
-A caution: The :c:member:`tty_ldisc_ops.open()`,
-:c:member:`tty_ldisc_ops.close()` and :c:member:`tty_driver.set_ldisc()`
-functions are called with the ldisc unavailable. Thus tty_ldisc_ref() will fail
-in this situation if used within these functions.  Ldisc and driver code
-calling its own functions must be careful in this case.
-
-Internal Functions
-==================
-
-.. kernel-doc:: drivers/tty/tty_ldisc.c
-   :internal:
diff --git a/Documentation/tty/tty_port.rst b/Documentation/tty/tty_port.rst
deleted file mode 100644
index 5cb90e954fcf..000000000000
--- a/Documentation/tty/tty_port.rst
+++ /dev/null
@@ -1,70 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-========
-TTY Port
-========
-
-.. contents:: :local:
-
-The TTY drivers are advised to use struct tty_port helpers as much as possible.
-If the drivers implement :c:member:`tty_port.ops.activate()` and
-:c:member:`tty_port.ops.shutdown()`, they can use tty_port_open(),
-tty_port_close(), and tty_port_hangup() in respective
-:c:member:`tty_struct.ops` hooks.
-
-The reference and details are contained in the `TTY Port Reference`_ and `TTY
-Port Operations Reference`_ sections at the bottom.
-
-TTY Port Functions
-==================
-
-Init & Destroy
---------------
-
-.. kernel-doc::  drivers/tty/tty_port.c
-   :identifiers: tty_port_init tty_port_destroy
-        tty_port_get tty_port_put
-
-Open/Close/Hangup Helpers
--------------------------
-
-.. kernel-doc::  drivers/tty/tty_port.c
-   :identifiers: tty_port_install tty_port_open tty_port_block_til_ready
-        tty_port_close tty_port_close_start tty_port_close_end tty_port_hangup
-        tty_port_shutdown
-
-TTY Refcounting
----------------
-
-.. kernel-doc::  drivers/tty/tty_port.c
-   :identifiers: tty_port_tty_get tty_port_tty_set
-
-TTY Helpers
------------
-
-.. kernel-doc::  drivers/tty/tty_port.c
-   :identifiers: tty_port_tty_hangup tty_port_tty_wakeup
-
-
-Modem Signals
--------------
-
-.. kernel-doc::  drivers/tty/tty_port.c
-   :identifiers: tty_port_carrier_raised tty_port_raise_dtr_rts
-        tty_port_lower_dtr_rts
-
-----
-
-TTY Port Reference
-==================
-
-.. kernel-doc:: include/linux/tty_port.h
-   :identifiers: tty_port
-
-----
-
-TTY Port Operations Reference
-=============================
-
-.. kernel-doc:: include/linux/tty_port.h
-   :identifiers: tty_port_operations
diff --git a/Documentation/tty/tty_struct.rst b/Documentation/tty/tty_struct.rst
deleted file mode 100644
index c72f5a4293b2..000000000000
--- a/Documentation/tty/tty_struct.rst
+++ /dev/null
@@ -1,81 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-==========
-TTY Struct
-==========
-
-.. contents:: :local:
-
-struct tty_struct is allocated by the TTY layer upon the first open of the TTY
-device and released after the last close. The TTY layer passes this structure
-to most of struct tty_operation's hooks. Members of tty_struct are documented
-in `TTY Struct Reference`_ at the bottom.
-
-Initialization
-==============
-
-.. kernel-doc:: drivers/tty/tty_io.c
-   :identifiers: tty_init_termios
-
-Name
-====
-
-.. kernel-doc:: drivers/tty/tty_io.c
-   :identifiers: tty_name
-
-Reference counting
-==================
-
-.. kernel-doc:: include/linux/tty.h
-   :identifiers: tty_kref_get
-
-.. kernel-doc:: drivers/tty/tty_io.c
-   :identifiers: tty_kref_put
-
-Install
-=======
-
-.. kernel-doc:: drivers/tty/tty_io.c
-   :identifiers: tty_standard_install
-
-Read & Write
-============
-
-.. kernel-doc:: drivers/tty/tty_io.c
-   :identifiers: tty_put_char
-
-Start & Stop
-============
-
-.. kernel-doc:: drivers/tty/tty_io.c
-   :identifiers: start_tty stop_tty
-
-Wakeup
-======
-
-.. kernel-doc:: drivers/tty/tty_io.c
-   :identifiers: tty_wakeup
-
-Hangup
-======
-
-.. kernel-doc:: drivers/tty/tty_io.c
-   :identifiers: tty_hangup tty_vhangup tty_hung_up_p
-
-Misc
-====
-
-.. kernel-doc:: drivers/tty/tty_io.c
-   :identifiers: tty_do_resize
-
-TTY Struct Flags
-================
-
-.. kernel-doc:: include/linux/tty.h
-   :doc: TTY Struct Flags
-
-TTY Struct Reference
-====================
-
-.. kernel-doc:: include/linux/tty.h
-   :identifiers: tty_struct