mirros/rockchip-kernel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Pull tty and serial driver updates from Greg KH:
 "Here is the big set of tty and serial driver updates for 5.19-rc1.

  Lots of tiny cleanups in here, the major stuff is:

   - termbit cleanups and unification by Ilpo. A much needed change that
     goes a long way to making things simpler for all of the different
     arches

   - tty documentation cleanups and movements to their own place in the
     documentation tree

   - old tty driver cleanups and fixes from Jiri to bring some existing
     drivers into the modern world

   - RS485 cleanups and unifications to make it easier for individual
     drivers to support this mode instead of having to duplicate logic
     in each driver

   - Lots of 8250 driver updates and additions

   - new device id additions

   - n_gsm continued fixes and cleanups

   - other minor serial driver updates and cleanups

  All of these have been in linux-next for weeks with no reported issues"

* tag 'tty-5.19-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty: (166 commits)
  tty: Rework receive flow control char logic
  pcmcia: synclink_cs: Don't allow CS5-6
  serial: stm32-usart: Correct CSIZE, bits, and parity
  serial: st-asc: Sanitize CSIZE and correct PARENB for CS7
  serial: sifive: Sanitize CSIZE and c_iflag
  serial: sh-sci: Don't allow CS5-6
  serial: txx9: Don't allow CS5-6
  serial: rda-uart: Don't allow CS5-6
  serial: digicolor-usart: Don't allow CS5-6
  serial: uartlite: Fix BRKINT clearing
  serial: cpm_uart: Fix build error without CONFIG_SERIAL_CPM_CONSOLE
  serial: core: Do stop_rx in suspend path for console if console_suspend is disabled
  tty: serial: qcom-geni-serial: Remove uart frequency table. Instead, find suitable frequency with call to clk_round_rate.
  dt-bindings: serial: renesas,em-uart: Add RZ/V2M clock to access the registers
  serial: 8250_fintek: Check SER_RS485_RTS_* only with RS485
  Revert "serial: 8250_mtk: Make sure to select the right FEATURE_SEL"
  serial: msm_serial: disable interrupts in __msm_console_write()
  serial: meson: acquire port->lock in startup()
  serial: 8250_dw: Use dev_err_probe()
  serial: 8250_dw: Use devm_add_action_or_reset()
  ...
This commit is contained in:
Linus Torvalds
2022-06-03 11:08:40 -07:00
parent 4ad680f083 25e02ba60f
commit 932c2989b5
114 changed files with 3166 additions and 2453 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
Documentation/driver-api/index.rst
View File

@@ -101,6 +101,7 @@ available subsections can be seen below.
surface_aggregator/index
switchtec
sync_file
tty/index
vfio-mediated-device
vfio
vfio-pci-device-specific-driver-acceptance

2
Documentation/driver-api/serial/driver.rst
View File

@@ -311,7 +311,7 @@ hardware.
This call must not sleep
set_ldisc(port,termios)
Notifier for discipline change. See Documentation/tty/tty_ldisc.rst.
Notifier for discipline change. See ../tty/tty_ldisc.rst.
Locking: caller holds tty_port->mutex

2
Documentation/driver-api/serial/index.rst
View File

@@ -16,8 +16,6 @@ Serial drivers
.. toctree::
:maxdepth: 1
moxa-smartio
n_gsm
serial-iso7816
serial-rs485

159
Documentation/driver-api/serial/n_gsm.rst
View File

@@ -1,159 +0,0 @@
==============================
GSM 0710 tty multiplexor HOWTO
==============================
This line discipline implements the GSM 07.10 multiplexing protocol
detailed in the following 3GPP document:
https://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip
This document give some hints on how to use this driver with GPRS and 3G
modems connected to a physical serial port.
How to use it
-------------
1. config initiator
^^^^^^^^^^^^^^^^^^^^^
1.1 initialize the modem in 0710 mux mode (usually AT+CMUX= command) through
its serial port. Depending on the modem used, you can pass more or less
parameters to this command.
1.2 switch the serial line to using the n_gsm line discipline by using
TIOCSETD ioctl.
1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
1.4 obtain base gsmtty number for the used serial port.
Major parts of the initialization program :
(a good starting point is util-linux-ng/sys-utils/ldattach.c)::
#include <stdio.h>
#include <stdint.h>
#include <linux/gsmmux.h>
#include <linux/tty.h>
#define DEFAULT_SPEED B115200
#define SERIAL_PORT /dev/ttyS0
int ldisc = N_GSM0710;
struct gsm_config c;
struct termios configuration;
uint32_t first;
/* open the serial port connected to the modem */
fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
/* configure the serial port : speed, flow control ... */
/* send the AT commands to switch the modem to CMUX mode
and check that it's successful (should return OK) */
write(fd, "AT+CMUX=0\r", 10);
/* experience showed that some modems need some time before
being able to answer to the first MUX packet so a delay
may be needed here in some case */
sleep(3);
/* use n_gsm line discipline */
ioctl(fd, TIOCSETD, &ldisc);
/* get n_gsm configuration */
ioctl(fd, GSMIOC_GETCONF, &c);
/* we are initiator and need encoding 0 (basic) */
c.initiator = 1;
c.encapsulation = 0;
/* our modem defaults to a maximum size of 127 bytes */
c.mru = 127;
c.mtu = 127;
/* set the new configuration */
ioctl(fd, GSMIOC_SETCONF, &c);
/* get first gsmtty device node */
ioctl(fd, GSMIOC_GETFIRST, &first);
printf("first muxed line: /dev/gsmtty%i\n", first);
/* and wait for ever to keep the line discipline enabled */
daemon(0,0);
pause();
1.5 use these devices as plain serial ports.
for example, it's possible:
- and to use gnokii to send / receive SMS on ttygsm1
- to use ppp to establish a datalink on ttygsm2
1.6 first close all virtual ports before closing the physical port.
Note that after closing the physical port the modem is still in multiplexing
mode. This may prevent a successful re-opening of the port later. To avoid
this situation either reset the modem if your hardware allows that or send
a disconnect command frame manually before initializing the multiplexing mode
for the second time. The byte sequence for the disconnect command frame is::
0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9.
2. config requester
^^^^^^^^^^^^^^^^^^^^^
2.1 receive string "AT+CMUX= command" through its serial port,initialize
mux mode config
2.2 switch the serial line to using the n_gsm line discipline by using
TIOCSETD ioctl.
2.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
2.4 obtain base gsmtty number for the used serial port::
#include <stdio.h>
#include <stdint.h>
#include <linux/gsmmux.h>
#include <linux/tty.h>
#define DEFAULT_SPEED B115200
#define SERIAL_PORT /dev/ttyS0
int ldisc = N_GSM0710;
struct gsm_config c;
struct termios configuration;
uint32_t first;
/* open the serial port */
fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
/* configure the serial port : speed, flow control ... */
/* get serial data and check "AT+CMUX=command" parameter ... */
/* use n_gsm line discipline */
ioctl(fd, TIOCSETD, &ldisc);
/* get n_gsm configuration */
ioctl(fd, GSMIOC_GETCONF, &c);
/* we are requester and need encoding 0 (basic) */
c.initiator = 0;
c.encapsulation = 0;
/* our modem defaults to a maximum size of 127 bytes */
c.mru = 127;
c.mtu = 127;
/* set the new configuration */
ioctl(fd, GSMIOC_SETCONF, &c);
/* get first gsmtty device node */
ioctl(fd, GSMIOC_GETFIRST, &first);
printf("first muxed line: /dev/gsmtty%i\n", first);
/* and wait for ever to keep the line discipline enabled */
daemon(0,0);
pause();
Additional Documentation
------------------------
More practical details on the protocol and how it's supported by industrial
modems can be found in the following documents :
- http://www.telit.com/module/infopool/download.php?id=616
- http://www.u-blox.com/images/downloads/Product_Docs/LEON-G100-G200-MuxImplementation_ApplicationNote_%28GSM%20G1-CS-10002%29.pdf
- http://www.sierrawireless.com/Support/Downloads/AirPrime/WMP_Series/~/media/Support_Downloads/AirPrime/Application_notes/CMUX_Feature_Application_Note-Rev004.ashx
- http://wm.sim.com/sim/News/photo/2010721161442.pdf
11-03-08 - Eric Bénard - <eric@eukrea.com>

73
Documentation/driver-api/tty/index.rst Normal file
View File

@@ -0,0 +1,73 @@
.. 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
tty_internals
Writing TTY Driver
==================
Before one starts writing a TTY driver, they must consider
:doc:`Serial <../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`.
Other Documentation
===================
Miscellaneous documentation can be further found in these documents:
.. toctree::
:maxdepth: 2
moxa-smartio
n_gsm
n_tty

0
Documentation/driver-api/serial/moxa-smartio.rst → Documentation/driver-api/tty/moxa-smartio.rst
View File

153
Documentation/driver-api/tty/n_gsm.rst Normal file
View File

@@ -0,0 +1,153 @@
==============================
GSM 0710 tty multiplexor HOWTO
==============================
.. contents:: :local:
This line discipline implements the GSM 07.10 multiplexing protocol
detailed in the following 3GPP document:
https://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip
This document give some hints on how to use this driver with GPRS and 3G
modems connected to a physical serial port.
How to use it
=============
Config Initiator
----------------
#. Initialize the modem in 0710 mux mode (usually ``AT+CMUX=`` command) through
its serial port. Depending on the modem used, you can pass more or less
parameters to this command.
#. Switch the serial line to using the n_gsm line discipline by using
``TIOCSETD`` ioctl.
#. Configure the mux using ``GSMIOC_GETCONF``/``GSMIOC_SETCONF`` ioctl.
#. Obtain base gsmtty number for the used serial port.
Major parts of the initialization program
(a good starting point is util-linux-ng/sys-utils/ldattach.c)::
#include <stdio.h>
#include <stdint.h>
#include <linux/gsmmux.h>
#include <linux/tty.h>
#define DEFAULT_SPEED B115200
#define SERIAL_PORT /dev/ttyS0
int ldisc = N_GSM0710;
struct gsm_config c;
struct termios configuration;
uint32_t first;
/* open the serial port connected to the modem */
fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
/* configure the serial port : speed, flow control ... */
/* send the AT commands to switch the modem to CMUX mode
and check that it's successful (should return OK) */
write(fd, "AT+CMUX=0\r", 10);
/* experience showed that some modems need some time before
being able to answer to the first MUX packet so a delay
may be needed here in some case */
sleep(3);
/* use n_gsm line discipline */
ioctl(fd, TIOCSETD, &ldisc);
/* get n_gsm configuration */
ioctl(fd, GSMIOC_GETCONF, &c);
/* we are initiator and need encoding 0 (basic) */
c.initiator = 1;
c.encapsulation = 0;
/* our modem defaults to a maximum size of 127 bytes */
c.mru = 127;
c.mtu = 127;
/* set the new configuration */
ioctl(fd, GSMIOC_SETCONF, &c);
/* get first gsmtty device node */
ioctl(fd, GSMIOC_GETFIRST, &first);
printf("first muxed line: /dev/gsmtty%i\n", first);
/* and wait for ever to keep the line discipline enabled */
daemon(0,0);
pause();
#. Use these devices as plain serial ports.
For example, it's possible:
- to use *gnokii* to send / receive SMS on ``ttygsm1``
- to use *ppp* to establish a datalink on ``ttygsm2``
#. First close all virtual ports before closing the physical port.
Note that after closing the physical port the modem is still in multiplexing
mode. This may prevent a successful re-opening of the port later. To avoid
this situation either reset the modem if your hardware allows that or send
a disconnect command frame manually before initializing the multiplexing mode
for the second time. The byte sequence for the disconnect command frame is::
0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9
Config Requester
----------------
#. Receive ``AT+CMUX=`` command through its serial port, initialize mux mode
config.
#. Switch the serial line to using the *n_gsm* line discipline by using
``TIOCSETD`` ioctl.
#. Configure the mux using ``GSMIOC_GETCONF``/``GSMIOC_SETCONF`` ioctl.
#. Obtain base gsmtty number for the used serial port::
#include <stdio.h>
#include <stdint.h>
#include <linux/gsmmux.h>
#include <linux/tty.h>
#define DEFAULT_SPEED B115200
#define SERIAL_PORT /dev/ttyS0
int ldisc = N_GSM0710;
struct gsm_config c;
struct termios configuration;
uint32_t first;
/* open the serial port */
fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
/* configure the serial port : speed, flow control ... */
/* get serial data and check "AT+CMUX=command" parameter ... */
/* use n_gsm line discipline */
ioctl(fd, TIOCSETD, &ldisc);
/* get n_gsm configuration */
ioctl(fd, GSMIOC_GETCONF, &c);
/* we are requester and need encoding 0 (basic) */
c.initiator = 0;
c.encapsulation = 0;
/* our modem defaults to a maximum size of 127 bytes */
c.mru = 127;
c.mtu = 127;
/* set the new configuration */
ioctl(fd, GSMIOC_SETCONF, &c);
/* get first gsmtty device node */
ioctl(fd, GSMIOC_GETFIRST, &first);
printf("first muxed line: /dev/gsmtty%i\n", first);
/* and wait for ever to keep the line discipline enabled */
daemon(0,0);
pause();
11-03-08 - Eric Bénard - <eric@eukrea.com>

22
Documentation/driver-api/tty/n_tty.rst Normal file
View File

@@ -0,0 +1,22 @@
.. 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:

46
Documentation/driver-api/tty/tty_buffer.rst Normal file
View File

@@ -0,0 +1,46 @@
.. 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:

128
Documentation/driver-api/tty/tty_driver.rst Normal file
View File

@@ -0,0 +1,128 @@
.. 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

31
Documentation/driver-api/tty/tty_internals.rst Normal file
View File

@@ -0,0 +1,31 @@
.. 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:

85
Documentation/driver-api/tty/tty_ldisc.rst Normal file
View File

@@ -0,0 +1,85 @@
.. 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:

70
Documentation/driver-api/tty/tty_port.rst Normal file
View File

@@ -0,0 +1,70 @@
.. 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

81
Documentation/driver-api/tty/tty_struct.rst Normal file
View File

@@ -0,0 +1,81 @@
.. 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