diff options
Diffstat (limited to 'Documentation/driver-api/tty')
| -rw-r--r-- | Documentation/driver-api/tty/index.rst | 73 | ||||
| -rw-r--r-- | Documentation/driver-api/tty/moxa-smartio.rst | 197 | ||||
| -rw-r--r-- | Documentation/driver-api/tty/n_gsm.rst | 153 | ||||
| -rw-r--r-- | Documentation/driver-api/tty/n_tty.rst | 22 | ||||
| -rw-r--r-- | Documentation/driver-api/tty/tty_buffer.rst | 46 | ||||
| -rw-r--r-- | Documentation/driver-api/tty/tty_driver.rst | 128 | ||||
| -rw-r--r-- | Documentation/driver-api/tty/tty_internals.rst | 31 | ||||
| -rw-r--r-- | Documentation/driver-api/tty/tty_ldisc.rst | 85 | ||||
| -rw-r--r-- | Documentation/driver-api/tty/tty_port.rst | 70 | ||||
| -rw-r--r-- | Documentation/driver-api/tty/tty_struct.rst | 81 |
10 files changed, 886 insertions, 0 deletions
diff --git a/Documentation/driver-api/tty/index.rst b/Documentation/driver-api/tty/index.rst new file mode 100644 index 000000000..2d32606a4 --- /dev/null +++ b/Documentation/driver-api/tty/index.rst @@ -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 diff --git a/Documentation/driver-api/tty/moxa-smartio.rst b/Documentation/driver-api/tty/moxa-smartio.rst new file mode 100644 index 000000000..af25bc5cc --- /dev/null +++ b/Documentation/driver-api/tty/moxa-smartio.rst @@ -0,0 +1,197 @@ +============================================================= +MOXA Smartio/Industio Family Device Driver Installation Guide +============================================================= + +Copyright (C) 2008, Moxa Inc. +Copyright (C) 2021, Jiri Slaby + +.. Content + + 1. Introduction + 2. System Requirement + 3. Installation + 3.1 Hardware installation + 3.2 Device naming convention + 4. Utilities + 5. Setserial + 6. Troubleshooting + +1. Introduction +^^^^^^^^^^^^^^^ + + The Smartio/Industio/UPCI family Linux driver supports following multiport + boards: + + - 2 ports multiport board + CP-102U, CP-102UL, CP-102UF + CP-132U-I, CP-132UL, + CP-132, CP-132I, CP132S, CP-132IS, + (CP-102, CP-102S) + + - 4 ports multiport board + CP-104EL, + CP-104UL, CP-104JU, + CP-134U, CP-134U-I, + C104H/PCI, C104HS/PCI, + CP-114, CP-114I, CP-114S, CP-114IS, CP-114UL, + (C114HI, CT-114I), + POS-104UL, + CB-114, + CB-134I + + - 8 ports multiport board + CP-118EL, CP-168EL, + CP-118U, CP-168U, + C168H/PCI, + CB-108 + + If a compatibility problem occurs, please contact Moxa at + support@moxa.com.tw. + + In addition to device driver, useful utilities are also provided in this + version. They are: + + - msdiag + Diagnostic program for displaying installed Moxa + Smartio/Industio boards. + - msmon + Monitor program to observe data count and line status signals. + - msterm A simple terminal program which is useful in testing serial + ports. + + All the drivers and utilities are published in form of source code under + GNU General Public License in this version. Please refer to GNU General + Public License announcement in each source code file for more detail. + + In Moxa's Web sites, you may always find the latest driver at + https://www.moxa.com/. + + This version of driver can be installed as a Loadable Module (Module driver) + or built-in into kernel (Static driver). Before you install the driver, + please refer to hardware installation procedure in the User's Manual. + + We assume the user should be familiar with following documents: + + - Serial-HOWTO + - Kernel-HOWTO + +2. System Requirement +^^^^^^^^^^^^^^^^^^^^^ + + - Maximum 4 boards can be installed in combination + +3. Installation +^^^^^^^^^^^^^^^ + +3.1 Hardware installation +========================= + +PCI/UPCI board +-------------- + + You may need to adjust IRQ usage in BIOS to avoid IRQ conflict with other + ISA devices. Please refer to hardware installation procedure in User's + Manual in advance. + +PCI IRQ Sharing +--------------- + + Each port within the same multiport board shares the same IRQ. Up to + 4 Moxa Smartio/Industio PCI Family multiport boards can be installed + together on one system and they can share the same IRQ. + + + +3.2 Device naming convention +============================ + + The device node is named "ttyMxx". + +Device naming when more than 2 boards installed +----------------------------------------------- + + Naming convention for each Smartio/Industio multiport board is + pre-defined as below. + + ============ =============== + Board Num. Device node + 1st board ttyM0 - ttyM7 + 2nd board ttyM8 - ttyM15 + 3rd board ttyM16 - ttyM23 + 4th board ttyM24 - ttyM31 + ============ =============== + +4. Utilities +^^^^^^^^^^^^ + + There are 3 utilities contained in this driver. They are msdiag, msmon and + msterm. These 3 utilities are released in form of source code. They should + be compiled into executable file and copied into /usr/bin. + +msdiag - Diagnostic +=================== + + This utility provides the function to display what Moxa Smartio/Industio + board was found by the driver in the system. + +msmon - Port Monitoring +======================= + + This utility gives the user a quick view about all the MOXA ports' + activities. One can easily learn each port's total received/transmitted + (Rx/Tx) character count since the time when the monitoring is started. + + Rx/Tx throughputs per second are also reported in interval basis (e.g. + the last 5 seconds) and in average basis (since the time the monitoring + is started). You can reset all ports' count by <HOME> key. <+> <-> + (plus/minus) keys to change the displaying time interval. Press <ENTER> + on the port, that cursor stay, to view the port's communication + parameters, signal status, and input/output queue. + +msterm - Terminal Emulation +=========================== + + This utility provides data sending and receiving ability of all tty ports, + especially for MOXA ports. It is quite useful for testing simple + application, for example, sending AT command to a modem connected to the + port or used as a terminal for login purpose. Note that this is only a + dumb terminal emulation without handling full screen operation. + +5. Setserial +^^^^^^^^^^^^ + + Supported Setserial parameters are listed as below. + + ============== ============================================================= + uart set UART type(16450 --> disable FIFO, 16550A --> enable FIFO) + close_delay set the amount of time (in 1/100 of a second) that DTR + should be kept low while being closed. + closing_wait set the amount of time (in 1/100 of a second) that the + serial port should wait for data to be drained while + being closed, before the receiver is disabled. + spd_hi Use 57.6kb when the application requests 38.4kb. + spd_vhi Use 115.2kb when the application requests 38.4kb. + spd_shi Use 230.4kb when the application requests 38.4kb. + spd_warp Use 460.8kb when the application requests 38.4kb. + spd_normal Use 38.4kb when the application requests 38.4kb. + spd_cust Use the custom divisor to set the speed when the + application requests 38.4kb. + divisor This option sets the custom division. + baud_base This option sets the base baud rate. + ============== ============================================================= + +6. Troubleshooting +^^^^^^^^^^^^^^^^^^ + + The boot time error messages and solutions are stated as clearly as + possible. If all the possible solutions fail, please contact our technical + support team to get more help. + + + Error msg: + More than 4 Moxa Smartio/Industio family boards found. Fifth board + and after are ignored. + + Solution: + To avoid this problem, please unplug fifth and after board, because Moxa + driver supports up to 4 boards. diff --git a/Documentation/driver-api/tty/n_gsm.rst b/Documentation/driver-api/tty/n_gsm.rst new file mode 100644 index 000000000..35d738151 --- /dev/null +++ b/Documentation/driver-api/tty/n_gsm.rst @@ -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> diff --git a/Documentation/driver-api/tty/n_tty.rst b/Documentation/driver-api/tty/n_tty.rst new file mode 100644 index 000000000..15b70faee --- /dev/null +++ b/Documentation/driver-api/tty/n_tty.rst @@ -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: diff --git a/Documentation/driver-api/tty/tty_buffer.rst b/Documentation/driver-api/tty/tty_buffer.rst new file mode 100644 index 000000000..a39d4781e --- /dev/null +++ b/Documentation/driver-api/tty/tty_buffer.rst @@ -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: diff --git a/Documentation/driver-api/tty/tty_driver.rst b/Documentation/driver-api/tty/tty_driver.rst new file mode 100644 index 000000000..cc529f863 --- /dev/null +++ b/Documentation/driver-api/tty/tty_driver.rst @@ -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 + diff --git a/Documentation/driver-api/tty/tty_internals.rst b/Documentation/driver-api/tty/tty_internals.rst new file mode 100644 index 000000000..d0d415820 --- /dev/null +++ b/Documentation/driver-api/tty/tty_internals.rst @@ -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: diff --git a/Documentation/driver-api/tty/tty_ldisc.rst b/Documentation/driver-api/tty/tty_ldisc.rst new file mode 100644 index 000000000..5144751be --- /dev/null +++ b/Documentation/driver-api/tty/tty_ldisc.rst @@ -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: diff --git a/Documentation/driver-api/tty/tty_port.rst b/Documentation/driver-api/tty/tty_port.rst new file mode 100644 index 000000000..5cb90e954 --- /dev/null +++ b/Documentation/driver-api/tty/tty_port.rst @@ -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 diff --git a/Documentation/driver-api/tty/tty_struct.rst b/Documentation/driver-api/tty/tty_struct.rst new file mode 100644 index 000000000..c72f5a429 --- /dev/null +++ b/Documentation/driver-api/tty/tty_struct.rst @@ -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 |