1.. SPDX-License-Identifier: GPL-2.0 2 3=================== 4TTY Line Discipline 5=================== 6 7.. contents:: :local: 8 9TTY line discipline process all incoming and outgoing character from/to a tty 10device. The default line discipline is :doc:`N_TTY <n_tty>`. It is also a 11fallback if establishing any other discipline for a tty fails. If even N_TTY 12fails, N_NULL takes over. That never fails, but also does not process any 13characters -- it throws them away. 14 15Registration 16============ 17 18Line disciplines are registered with tty_register_ldisc() passing the ldisc 19structure. At the point of registration the discipline must be ready to use and 20it is possible it will get used before the call returns success. If the call 21returns an error then it won’t get called. Do not re-use ldisc numbers as they 22are part of the userspace ABI and writing over an existing ldisc will cause 23demons to eat your computer. You must not re-register over the top of the line 24discipline even with the same data or your computer again will be eaten by 25demons. In order to remove a line discipline call tty_unregister_ldisc(). 26 27Heed this warning: the reference count field of the registered copies of the 28tty_ldisc structure in the ldisc table counts the number of lines using this 29discipline. The reference count of the tty_ldisc structure within a tty counts 30the number of active users of the ldisc at this instant. In effect it counts 31the number of threads of execution within an ldisc method (plus those about to 32enter and exit although this detail matters not). 33 34.. kernel-doc:: drivers/tty/tty_ldisc.c 35 :identifiers: tty_register_ldisc tty_unregister_ldisc 36 37Other Functions 38=============== 39 40.. kernel-doc:: drivers/tty/tty_ldisc.c 41 :identifiers: tty_set_ldisc tty_ldisc_flush 42 43Line Discipline Operations Reference 44==================================== 45 46.. kernel-doc:: include/linux/tty_ldisc.h 47 :identifiers: tty_ldisc_ops 48 49Driver Access 50============= 51 52Line discipline methods can call the methods of the underlying hardware driver. 53These are documented as a part of struct tty_operations. 54 55TTY Flags 56========= 57 58Line discipline methods have access to :c:member:`tty_struct.flags` field. See 59:doc:`tty_struct`. 60 61Locking 62======= 63 64Callers to the line discipline functions from the tty layer are required to 65take line discipline locks. The same is true of calls from the driver side 66but not yet enforced. 67 68.. kernel-doc:: drivers/tty/tty_ldisc.c 69 :identifiers: tty_ldisc_ref_wait tty_ldisc_ref tty_ldisc_deref 70 71While these functions are slightly slower than the old code they should have 72minimal impact as most receive logic uses the flip buffers and they only 73need to take a reference when they push bits up through the driver. 74 75A caution: The :c:member:`tty_ldisc_ops.open()`, 76:c:member:`tty_ldisc_ops.close()` and :c:member:`tty_driver.set_ldisc()` 77functions are called with the ldisc unavailable. Thus tty_ldisc_ref() will fail 78in this situation if used within these functions. Ldisc and driver code 79calling its own functions must be careful in this case. 80 81Internal Functions 82================== 83 84.. kernel-doc:: drivers/tty/tty_ldisc.c 85 :internal: 86