mirrors/linux-stable
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git synced 2024-09-28 13:22:57 +00:00
Code Issues Releases Wiki Activity

tty: more kernel-doc for tty_ldisc

Browse source 
Extend and highlight tty_ldisc documentation for kernel-doc even more.

We don't need to describe tty_ldisc_ref* functions again. Instead, just
include their kernel-doc from code.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-22-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Jiri Slaby 2021-11-26 09:16:09 +01:00 committed by Greg Kroah-Hartman
parent 6f05358661
commit f3e7614732
1 changed files with 19 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
Documentation/tty/tty_ldisc.rst
View file

@ -28,6 +28,12 @@ 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
====================================
@ -53,31 +59,21 @@ 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.
Three calls are now provided::
ldisc = tty_ldisc_ref(tty);
takes a handle to the line discipline in the tty and returns it. If no ldisc
is currently attached or the ldisc is being closed and re-opened at this
point then NULL is returned. While this handle is held the ldisc will not
change or go away::
tty_ldisc_deref(ldisc)
Returns the ldisc reference and allows the ldisc to be closed. Returning the
reference takes away your right to call the ldisc functions until you take
a new reference::
ldisc = tty_ldisc_ref_wait(tty);
Performs the same function as tty_ldisc_ref except that it will wait for an
ldisc change to complete and then return a reference to the new ldisc.
.. kernel-doc:: drivers/tty/tty_ldisc.c
:identifiers: tty_ldisc_ref_wait tty_ldisc_ref tty_ldisc_deref
While these functions are slightly slower than the old code they should have
minimal impact as most receive logic uses the flip buffers and they only
need to take a reference when they push bits up through the driver.
A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc
functions are called with the ldisc unavailable. Thus tty_ldisc_ref will
fail in this situation if used within these functions. Ldisc and driver
code calling its own functions must be careful in this case.
A caution: The :c:member:`tty_ldisc_ops.open()`,
:c:member:`tty_ldisc_ops.close()` and :c:member:`tty_driver.set_ldisc()`
functions are called with the ldisc unavailable. Thus tty_ldisc_ref() will fail
in this situation if used within these functions. Ldisc and driver code
calling its own functions must be careful in this case.
Internal Functions
==================
.. kernel-doc:: drivers/tty/tty_ldisc.c
:internal: