diff mbox series

[20/23] tty: make tty_ldisc docs up-to-date

Message ID 20211126081611.11001-21-jslaby@suse.cz
State New
Headers show
Series tty: documentation revamp | expand

Commit Message

Jiri Slaby Nov. 26, 2021, 8:16 a.m. UTC
Some of the docs in this document were a bit obsolete. Clean it up a bit
and make it correspond to the current state.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
---
 Documentation/tty/tty_ldisc.rst | 39 ++++++++++++++++-----------------
 1 file changed, 19 insertions(+), 20 deletions(-)
diff mbox series

Patch

diff --git a/Documentation/tty/tty_ldisc.rst b/Documentation/tty/tty_ldisc.rst
index 8e48ab72f965..69dee9ca6540 100644
--- a/Documentation/tty/tty_ldisc.rst
+++ b/Documentation/tty/tty_ldisc.rst
@@ -6,31 +6,30 @@  TTY Line Discipline
 
 .. contents:: :local:
 
-Line disciplines are registered with tty_register_ldisc() passing the
-discipline number and 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 re-use ldisc numbers as they are part of the userspace ABI
-and writing over an existing ldisc will cause demons to eat your computer.
-After the return the ldisc data has been copied so you may free your own
-copy of the structure. You must not re-register over the top of the line
+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 re-use 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().
-In ancient times this always worked. In modern times the function will
-return -EBUSY if the ldisc is currently in use. Since the ldisc referencing
-code manages the module counts this should not usually be a concern.
+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).
+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
 
-Line Discipline Methods
-=======================
+Line Discipline Operations Reference
+====================================
 
 .. kernel-doc:: include/linux/tty_ldisc.h
    :identifiers: tty_ldisc_ops