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