162306a36Sopenharmony_ci.. SPDX-License-Identifier: GPL-2.0 262306a36Sopenharmony_ci 362306a36Sopenharmony_ci=================== 462306a36Sopenharmony_ciTTY Line Discipline 562306a36Sopenharmony_ci=================== 662306a36Sopenharmony_ci 762306a36Sopenharmony_ci.. contents:: :local: 862306a36Sopenharmony_ci 962306a36Sopenharmony_ciTTY line discipline process all incoming and outgoing character from/to a tty 1062306a36Sopenharmony_cidevice. The default line discipline is :doc:`N_TTY <n_tty>`. It is also a 1162306a36Sopenharmony_cifallback if establishing any other discipline for a tty fails. If even N_TTY 1262306a36Sopenharmony_cifails, N_NULL takes over. That never fails, but also does not process any 1362306a36Sopenharmony_cicharacters -- it throws them away. 1462306a36Sopenharmony_ci 1562306a36Sopenharmony_ciRegistration 1662306a36Sopenharmony_ci============ 1762306a36Sopenharmony_ci 1862306a36Sopenharmony_ciLine disciplines are registered with tty_register_ldisc() passing the ldisc 1962306a36Sopenharmony_cistructure. At the point of registration the discipline must be ready to use and 2062306a36Sopenharmony_ciit is possible it will get used before the call returns success. If the call 2162306a36Sopenharmony_cireturns an error then it won’t get called. Do not re-use ldisc numbers as they 2262306a36Sopenharmony_ciare part of the userspace ABI and writing over an existing ldisc will cause 2362306a36Sopenharmony_cidemons to eat your computer. You must not re-register over the top of the line 2462306a36Sopenharmony_cidiscipline even with the same data or your computer again will be eaten by 2562306a36Sopenharmony_cidemons. In order to remove a line discipline call tty_unregister_ldisc(). 2662306a36Sopenharmony_ci 2762306a36Sopenharmony_ciHeed this warning: the reference count field of the registered copies of the 2862306a36Sopenharmony_citty_ldisc structure in the ldisc table counts the number of lines using this 2962306a36Sopenharmony_cidiscipline. The reference count of the tty_ldisc structure within a tty counts 3062306a36Sopenharmony_cithe number of active users of the ldisc at this instant. In effect it counts 3162306a36Sopenharmony_cithe number of threads of execution within an ldisc method (plus those about to 3262306a36Sopenharmony_cienter and exit although this detail matters not). 3362306a36Sopenharmony_ci 3462306a36Sopenharmony_ci.. kernel-doc:: drivers/tty/tty_ldisc.c 3562306a36Sopenharmony_ci :identifiers: tty_register_ldisc tty_unregister_ldisc 3662306a36Sopenharmony_ci 3762306a36Sopenharmony_ciOther Functions 3862306a36Sopenharmony_ci=============== 3962306a36Sopenharmony_ci 4062306a36Sopenharmony_ci.. kernel-doc:: drivers/tty/tty_ldisc.c 4162306a36Sopenharmony_ci :identifiers: tty_set_ldisc tty_ldisc_flush 4262306a36Sopenharmony_ci 4362306a36Sopenharmony_ciLine Discipline Operations Reference 4462306a36Sopenharmony_ci==================================== 4562306a36Sopenharmony_ci 4662306a36Sopenharmony_ci.. kernel-doc:: include/linux/tty_ldisc.h 4762306a36Sopenharmony_ci :identifiers: tty_ldisc_ops 4862306a36Sopenharmony_ci 4962306a36Sopenharmony_ciDriver Access 5062306a36Sopenharmony_ci============= 5162306a36Sopenharmony_ci 5262306a36Sopenharmony_ciLine discipline methods can call the methods of the underlying hardware driver. 5362306a36Sopenharmony_ciThese are documented as a part of struct tty_operations. 5462306a36Sopenharmony_ci 5562306a36Sopenharmony_ciTTY Flags 5662306a36Sopenharmony_ci========= 5762306a36Sopenharmony_ci 5862306a36Sopenharmony_ciLine discipline methods have access to :c:member:`tty_struct.flags` field. See 5962306a36Sopenharmony_ci:doc:`tty_struct`. 6062306a36Sopenharmony_ci 6162306a36Sopenharmony_ciLocking 6262306a36Sopenharmony_ci======= 6362306a36Sopenharmony_ci 6462306a36Sopenharmony_ciCallers to the line discipline functions from the tty layer are required to 6562306a36Sopenharmony_citake line discipline locks. The same is true of calls from the driver side 6662306a36Sopenharmony_cibut not yet enforced. 6762306a36Sopenharmony_ci 6862306a36Sopenharmony_ci.. kernel-doc:: drivers/tty/tty_ldisc.c 6962306a36Sopenharmony_ci :identifiers: tty_ldisc_ref_wait tty_ldisc_ref tty_ldisc_deref 7062306a36Sopenharmony_ci 7162306a36Sopenharmony_ciWhile these functions are slightly slower than the old code they should have 7262306a36Sopenharmony_ciminimal impact as most receive logic uses the flip buffers and they only 7362306a36Sopenharmony_cineed to take a reference when they push bits up through the driver. 7462306a36Sopenharmony_ci 7562306a36Sopenharmony_ciA caution: The :c:member:`tty_ldisc_ops.open()`, 7662306a36Sopenharmony_ci:c:member:`tty_ldisc_ops.close()` and :c:member:`tty_driver.set_ldisc()` 7762306a36Sopenharmony_cifunctions are called with the ldisc unavailable. Thus tty_ldisc_ref() will fail 7862306a36Sopenharmony_ciin this situation if used within these functions. Ldisc and driver code 7962306a36Sopenharmony_cicalling its own functions must be careful in this case. 8062306a36Sopenharmony_ci 8162306a36Sopenharmony_ciInternal Functions 8262306a36Sopenharmony_ci================== 8362306a36Sopenharmony_ci 8462306a36Sopenharmony_ci.. kernel-doc:: drivers/tty/tty_ldisc.c 8562306a36Sopenharmony_ci :internal: 86