Merge tag 'tty-5.17-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty

Pull tty/serial driver updates from Greg KH:
 "Here is the big set of tty/serial driver updates for 5.17-rc1.

  Nothing major in here, just lots of good updates and fixes, including:

   - more tty core cleanups from Jiri as well as mxser driver cleanups.
     This is the majority of the core diffstat

   - tty documentation updates from Jiri

   - platform_get_irq() updates

   - various serial driver updates for new features and hardware

   - fifo usage for 8250 console, reducing cpu load a lot

   - LED fix for keyboards, long-time bugfix that went through many
     revisions

   - minor cleanups

  All have been in linux-next for a while with no reported problems"

* tag 'tty-5.17-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty: (119 commits)
  serial: core: Keep mctrl register state and cached copy in sync
  serial: stm32: correct loop for dma error handling
  serial: stm32: fix flow control transfer in DMA mode
  serial: stm32: rework TX DMA state condition
  serial: stm32: move tx dma terminate DMA to shutdown
  serial: pl011: Drop redundant DTR/RTS preservation on close/open
  serial: pl011: Drop CR register reset on set_termios
  serial: pl010: Drop CR register reset on set_termios
  serial: liteuart: fix MODULE_ALIAS
  serial: 8250_bcm7271: Fix return error code in case of dma_alloc_coherent() failure
  Revert "serdev: BREAK/FRAME/PARITY/OVERRUN notification prototype V2"
  tty: goldfish: Use platform_get_irq() to get the interrupt
  serdev: BREAK/FRAME/PARITY/OVERRUN notification prototype V2
  tty: serial: meson: Drop the legacy compatible strings and clock code
  serial: pmac_zilog: Use platform_get_irq() to get the interrupt
  serial: bcm63xx: Use platform_get_irq() to get the interrupt
  serial: ar933x: Use platform_get_irq() to get the interrupt
  serial: vt8500: Use platform_get_irq() to get the interrupt
  serial: altera_jtaguart: Use platform_get_irq_optional() to get the interrupt
  serial: pxa: Use platform_get_irq() to get the interrupt
  ...

1 files changed, 63 insertions, 0 deletions

diff --git a/Documentation/tty/index.rst b/Documentation/tty/index.rst
new file mode 100644
index 000000000000..21ea0cb21e55
--- /dev/null
+++ b/Documentation/tty/index.rst
@@ -0,0 +1,63 @@
+.. 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`.