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