From: Jiri Slaby Date: Mon, 11 Apr 2022 11:01:38 +0000 (+0200) Subject: Documentation: move tty to driver-api X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=b96cd8b05ead8939b972192c4f4ac2fc2dffceb7;p=linux.git 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 Signed-off-by: Jiri Slaby Link: https://lore.kernel.org/r/20220411110143.10019-2-jslaby@suse.cz Signed-off-by: Greg Kroah-Hartman --- diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index a7b0223e2886a..bbbbcf20b7ce4 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -101,6 +101,7 @@ available subsections can be seen below. surface_aggregator/index switchtec sync_file + tty vfio-mediated-device vfio vfio-pci-device-specific-driver-acceptance diff --git a/Documentation/driver-api/serial/driver.rst b/Documentation/driver-api/serial/driver.rst index 06ec04ba086fd..7ef83fd3917b2 100644 --- a/Documentation/driver-api/serial/driver.rst +++ b/Documentation/driver-api/serial/driver.rst @@ -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 diff --git a/Documentation/driver-api/tty/index.rst b/Documentation/driver-api/tty/index.rst new file mode 100644 index 0000000000000..2240e52203d6a --- /dev/null +++ b/Documentation/driver-api/tty/index.rst @@ -0,0 +1,62 @@ +.. 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 <../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/driver-api/tty/n_tty.rst b/Documentation/driver-api/tty/n_tty.rst new file mode 100644 index 0000000000000..15b70faee72da --- /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 `. 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 0000000000000..a39d4781e0d24 --- /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 +` 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 0000000000000..cc529f8634060 --- /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 0000000000000..d0d415820300e --- /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 0000000000000..5144751be804a --- /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 `. 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 0000000000000..5cb90e954fcf7 --- /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 0000000000000..c72f5a4293b2c --- /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 diff --git a/Documentation/index.rst b/Documentation/index.rst index 1988c19d9daf4..5a5acac985f3e 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -137,7 +137,6 @@ needed). misc-devices/index scheduler/index mhi/index - tty/index peci/index Architecture-agnostic documentation diff --git a/Documentation/tty/index.rst b/Documentation/tty/index.rst deleted file mode 100644 index 21ea0cb21e558..0000000000000 --- 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 15b70faee72da..0000000000000 --- 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 `. 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 a39d4781e0d24..0000000000000 --- 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 -` 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 cc529f8634060..0000000000000 --- 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 d0d415820300e..0000000000000 --- 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 5144751be804a..0000000000000 --- 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 `. 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 5cb90e954fcf7..0000000000000 --- 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 c72f5a4293b2c..0000000000000 --- 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