surface_aggregator/index
switchtec
sync_file
+ tty
vfio-mediated-device
vfio
vfio-pci-device-specific-driver-acceptance
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
--- /dev/null
+.. 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`.
--- /dev/null
+.. 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:
--- /dev/null
+.. 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:
--- /dev/null
+.. 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
+
--- /dev/null
+.. 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:
--- /dev/null
+.. 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:
--- /dev/null
+.. 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
--- /dev/null
+.. 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
misc-devices/index
scheduler/index
mhi/index
- tty/index
peci/index
Architecture-agnostic documentation
+++ /dev/null
-.. 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`.
+++ /dev/null
-.. 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:
+++ /dev/null
-.. 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:
+++ /dev/null
-.. 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
-
+++ /dev/null
-.. 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:
+++ /dev/null
-.. 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:
+++ /dev/null
-.. 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
+++ /dev/null
-.. 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
projects / linux.git / commitdiff