Documentation/driver-api/tty/tty_ldisc.rst

File Facts

System

Linux kernel

Corpus path

Documentation/driver-api/tty/tty_ldisc.rst

Extension

.rst

Size

3142 bytes

Lines

86

Domain

Support Tooling And Documentation

Bucket

Documentation

Inferred role

Support Tooling And Documentation: documentation

Status

atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

• Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.
• Defines or uses C structs; map object ownership, embedded links, reference counts, and lock ownership.

Dependency Surface

• No C-style include directives detected by the generator.

Detected Declarations

• No top-level syscall, struct, function, initcall, or export declaration detected by the generator.

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

===================
TTY Line Discipline
===================

.. contents:: :local:

TTY line discipline process all incoming and outgoing character from/to a tty
device. The default line discipline is :doc:`N_TTY <n_tty>`. It is also a
fallback if establishing any other discipline for a tty fails. If even N_TTY
fails, N_NULL takes over. That never fails, but also does not process any
characters -- it throws them away.

Registration
============

Line disciplines are registered with tty_register_ldisc() passing the ldisc
structure. At the point of registration the discipline must be ready to use and
it is possible it will get used before the call returns success. If the call
returns an error then it won’t get called. Do not reuse ldisc numbers as they
are part of the userspace ABI and writing over an existing ldisc will cause
demons to eat your computer. You must not re-register over the top of the line
discipline even with the same data or your computer again will be eaten by
demons. In order to remove a line discipline call tty_unregister_ldisc().

Heed this warning: the reference count field of the registered copies of the
tty_ldisc structure in the ldisc table counts the number of lines using this
discipline. The reference count of the tty_ldisc structure within a tty counts
the number of active users of the ldisc at this instant. In effect it counts
the number of threads of execution within an ldisc method (plus those about to
enter and exit although this detail matters not).

.. kernel-doc:: drivers/tty/tty_ldisc.c
   :identifiers: tty_register_ldisc tty_unregister_ldisc

Other Functions
===============

.. kernel-doc:: drivers/tty/tty_ldisc.c
   :identifiers: tty_set_ldisc tty_ldisc_flush

Line Discipline Operations Reference
====================================

.. kernel-doc:: include/linux/tty_ldisc.h
   :identifiers: tty_ldisc_ops

Driver Access
=============

Line discipline methods can call the methods of the underlying hardware driver.
These are documented as a part of struct tty_operations.

TTY Flags
=========

Line discipline methods have access to :c:member:`tty_struct.flags` field. See
:doc:`tty_struct`.

Locking
=======

Callers to the line discipline functions from the tty layer are required to
take line discipline locks. The same is true of calls from the driver side
but not yet enforced.

.. kernel-doc:: drivers/tty/tty_ldisc.c
   :identifiers: tty_ldisc_ref_wait tty_ldisc_ref tty_ldisc_deref

Annotation

• Atlas domain: Support Tooling And Documentation / Documentation.
• Implementation status: atlas-only.

Implementation Notes

• This generated page is the file-by-file coverage layer; curated subsystem chapters should link here when they synthesize a multi-file control flow.
• Core OS pages should be promoted from atlas-only to deep-reviewed when they explain data structures, invariants, locking, lifecycle, and C implementation snippets.
• Driver-family pages are intentionally pattern-oriented unless they are part of the selected PCIe/NVMe representative device path.