0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===================
0004 TTY Line Discipline
0005 ===================
0006
0007 .. contents:: :local:
0008
0009 TTY line discipline process all incoming and outgoing character from/to a tty
0010 device. The default line discipline is :doc:`N_TTY <n_tty>`. It is also a
0011 fallback if establishing any other discipline for a tty fails. If even N_TTY
0012 fails, N_NULL takes over. That never fails, but also does not process any
0013 characters -- it throws them away.
0014
0015 Registration
0016 ============
0017
0018 Line disciplines are registered with tty_register_ldisc() passing the ldisc
0019 structure. At the point of registration the discipline must be ready to use and
0020 it is possible it will get used before the call returns success. If the call
0021 returns an error then it won’t get called. Do not re-use ldisc numbers as they
0022 are part of the userspace ABI and writing over an existing ldisc will cause
0023 demons to eat your computer. You must not re-register over the top of the line
0024 discipline even with the same data or your computer again will be eaten by
0025 demons. In order to remove a line discipline call tty_unregister_ldisc().
0026
0027 Heed this warning: the reference count field of the registered copies of the
0028 tty_ldisc structure in the ldisc table counts the number of lines using this
0029 discipline. The reference count of the tty_ldisc structure within a tty counts
0030 the number of active users of the ldisc at this instant. In effect it counts
0031 the number of threads of execution within an ldisc method (plus those about to
0032 enter and exit although this detail matters not).
0033
0034 .. kernel-doc:: drivers/tty/tty_ldisc.c
0035 :identifiers: tty_register_ldisc tty_unregister_ldisc
0036
0037 Other Functions
0038 ===============
0039
0040 .. kernel-doc:: drivers/tty/tty_ldisc.c
0041 :identifiers: tty_set_ldisc tty_ldisc_flush
0042
0043 Line Discipline Operations Reference
0044 ====================================
0045
0046 .. kernel-doc:: include/linux/tty_ldisc.h
0047 :identifiers: tty_ldisc_ops
0048
0049 Driver Access
0050 =============
0051
0052 Line discipline methods can call the methods of the underlying hardware driver.
0053 These are documented as a part of struct tty_operations.
0054
0055 TTY Flags
0056 =========
0057
0058 Line discipline methods have access to :c:member:`tty_struct.flags` field. See
0059 :doc:`tty_struct`.
0060
0061 Locking
0062 =======
0063
0064 Callers to the line discipline functions from the tty layer are required to
0065 take line discipline locks. The same is true of calls from the driver side
0066 but not yet enforced.
0067
0068 .. kernel-doc:: drivers/tty/tty_ldisc.c
0069 :identifiers: tty_ldisc_ref_wait tty_ldisc_ref tty_ldisc_deref
0070
0071 While these functions are slightly slower than the old code they should have
0072 minimal impact as most receive logic uses the flip buffers and they only
0073 need to take a reference when they push bits up through the driver.
0074
0075 A caution: The :c:member:`tty_ldisc_ops.open()`,
0076 :c:member:`tty_ldisc_ops.close()` and :c:member:`tty_driver.set_ldisc()`
0077 functions are called with the ldisc unavailable. Thus tty_ldisc_ref() will fail
0078 in this situation if used within these functions. Ldisc and driver code
0079 calling its own functions must be careful in this case.
0080
0081 Internal Functions
0082 ==================
0083
0084 .. kernel-doc:: drivers/tty/tty_ldisc.c
0085 :internal:
