Documentation/driver-api/tty/tty_ldisc.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   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 re-use 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: