UbiquitousOS
/
OpenCloudOS-Kernel
mirror of https://gitee.com/OpenCloudOS/OpenCloudOS-Kernel.git
11
0
Fork 0
Code Issues Projects Releases Wiki Activity

tty: combine tty_operations triple docs into kernel-doc 

In Documentation/driver-api/serial/tty.rst, there are triplicated texts
about some struct tty_operations' hooks. Combine them into existing
kernel-doc comments of struct tty_operations and drop them from the
Documentation/.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-8-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Jiri Slaby 2021-11-26 09:15:55 +01:00 committed by Greg Kroah-Hartman
parent 0c6119f9f7
commit 29d5ef6859
2 changed files with 29 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
Documentation/driver-api/serial/tty.rst
View File

@ -132,74 +132,8 @@ dcd_change() Report to the tty line the current DCD pin status
Driver Access
^^^^^^^^^^^^^
Line discipline methods can call the following methods of the underlying
hardware driver through the function pointers within the tty->driver
structure:
======================= =======================================================
write() Write a block of characters to the tty device.
Returns the number of characters accepted. The
character buffer passed to this method is already
in kernel space.
put_char() Queues a character for writing to the tty device.
If there is no room in the queue, the character is
ignored.
flush_chars() (Optional) If defined, must be called after
queueing characters with put_char() in order to
start transmission.
write_room() Returns the numbers of characters the tty driver
will accept for queueing to be written.
ioctl() Invoke device specific ioctl.
Expects data pointers to refer to userspace.
Returns ENOIOCTLCMD for unrecognized ioctl numbers.
set_termios() Notify the tty driver that the device's termios
settings have changed. New settings are in
tty->termios. Previous settings should be passed in
the "old" argument.
The API is defined such that the driver should return
the actual modes selected. This means that the
driver function is responsible for modifying any
bits in the request it cannot fulfill to indicate
the actual modes being used. A device with no
hardware capability for change (e.g. a USB dongle or
virtual port) can provide NULL for this method.
throttle() Notify the tty driver that input buffers for the
line discipline are close to full, and it should
somehow signal that no more characters should be
sent to the tty.
unthrottle() Notify the tty driver that characters can now be
sent to the tty without fear of overrunning the
input buffers of the line disciplines.
stop() Ask the tty driver to stop outputting characters
to the tty device.
start() Ask the tty driver to resume sending characters
to the tty device.
hangup() Ask the tty driver to hang up the tty device.
break_ctl() (Optional) Ask the tty driver to turn on or off
BREAK status on the RS-232 port. If state is -1,
then the BREAK status should be turned on; if
state is 0, then BREAK should be turned off.
If this routine is not implemented, use ioctls
TIOCSBRK / TIOCCBRK instead.
wait_until_sent() Waits until the device has written out all of the
characters in its transmitter FIFO.
send_xchar() Send a high-priority XON/XOFF character to the device.
======================= =======================================================
Line discipline methods can call the methods of the underlying hardware driver.
These are documented as a part of struct tty_operations.
Flags
^^^^^
@ -262,67 +196,3 @@ 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.
Driver Interface
----------------
======================= =======================================================
open() Called when a device is opened. May sleep
close() Called when a device is closed. At the point of
return from this call the driver must make no
further ldisc calls of any kind. May sleep
write() Called to write bytes to the device. May not
sleep. May occur in parallel in special cases.
Because this includes panic paths drivers generally
shouldn't try and do clever locking here.
put_char() Stuff a single character onto the queue. The
driver is guaranteed following up calls to
flush_chars.
flush_chars() Ask the kernel to write put_char queue
write_room() Return the number of characters that can be stuffed
into the port buffers without overflow (or less).
The ldisc is responsible for being intelligent
about multi-threading of write_room/write calls
ioctl() Called when an ioctl may be for the driver
set_termios() Called on termios change, serialized against
itself by a semaphore. May sleep.
set_ldisc() Notifier for discipline change. At the point this
is done the discipline is not yet usable. Can now
sleep (I think)
throttle() Called by the ldisc to ask the driver to do flow
control. Serialization including with unthrottle
is the job of the ldisc layer.
unthrottle() Called by the ldisc to ask the driver to stop flow
control.
stop() Ldisc notifier to the driver to stop output. As with
throttle the serializations with start() are down
to the ldisc layer.
start() Ldisc notifier to the driver to start output.
hangup() Ask the tty driver to cause a hangup initiated
from the host side. [Can sleep ??]
break_ctl() Send RS232 break. Can sleep. Can get called in
parallel, driver must serialize (for now), and
with write calls.
wait_until_sent() Wait for characters to exit the hardware queue
of the driver. Can sleep
send_xchar() Send XON/XOFF and if possible jump the queue with
it in order to get fast flow control responses.
Cannot sleep ??
======================= =======================================================

36
include/linux/tty_driver.h
View File

@ -47,15 +47,17 @@ struct serial_struct;
* routine is mandatory; if this routine is not filled in, the attempted
* open will fail with %ENODEV.
*
* Required method. Called with tty lock held.
* Required method. Called with tty lock held. May sleep.
*
* @close: ``void ()(struct tty_struct *tty, struct file *)``
*
* This routine is called when a particular @tty device is closed.
* This routine is called when a particular @tty device is closed. At the
* point of return from this call the driver must make no further ldisc
* calls of any kind.
*
* Remark: called even if the corresponding @open() failed.
*
* Required method. Called with tty lock held.
* Required method. Called with tty lock held. May sleep.
*
* @shutdown: ``void ()(struct tty_struct *tty)``
*
@ -77,7 +79,10 @@ struct serial_struct;
* user space or kernel space. This routine will return the
* number of characters actually accepted for writing.
*
* Optional: Required for writable devices.
* May occur in parallel in special cases. Because this includes panic
* paths drivers generally shouldn't try and do clever locking here.
*
* Optional: Required for writable devices. May not sleep.
*
* @put_char: ``int ()(struct tty_struct *tty, unsigned char ch)``
*
@ -105,6 +110,9 @@ struct serial_struct;
* to change as output buffers get emptied, or if the output flow
* control is acted.
*
* The ldisc is responsible for being intelligent about multi-threading of
* write_room/write calls
*
* Required if @write method is provided else not needed. Do not call this
* function directly, call tty_write_room()
*
@ -136,14 +144,21 @@ struct serial_struct;
* @set_termios: ``void ()(struct tty_struct *tty, struct ktermios *old)``
*
* This routine allows the @tty driver to be notified when device's
* termios settings have changed.
* termios settings have changed. New settings are in @tty->termios.
* Previous settings are passed in the @old argument.
*
* Optional: Called under the @tty->termios_rwsem.
* The API is defined such that the driver should return the actual modes
* selected. This means that the driver is responsible for modifying any
* bits in @tty->termios it cannot fulfill to indicate the actual modes
* being used.
*
* Optional. Called under the @tty->termios_rwsem. May sleep.
*
* @set_ldisc: ``void ()(struct tty_struct *tty)``
*
* This routine allows the @tty driver to be notified when the device's
* line discipline is being changed.
* line discipline is being changed. At the point this is done the
* discipline is not yet usable.
*
* Optional. Called under the @tty->ldisc_sem and @tty->termios_rwsem.
*
@ -153,6 +168,9 @@ struct serial_struct;
* discipline are close to full, and it should somehow signal that no more
* characters should be sent to the @tty.
*
* Serialization including with @unthrottle() is the job of the ldisc
* layer.
*
* Optional: Always invoke via tty_throttle_safe(). Called under the
* @tty->termios_rwsem.
*
@ -204,7 +222,7 @@ struct serial_struct;
* hardware is expected to do the delay work itself. 0 and -1 are still
* used for on/off.
*
* Optional: Required for %TCSBRK/%BRKP/etc. handling.
* Optional: Required for %TCSBRK/%BRKP/etc. handling. May sleep.
*
* @flush_buffer: ``void ()(struct tty_struct *tty)``
*
@ -222,7 +240,7 @@ struct serial_struct;
* reached.
*
* Optional: If not provided, the device is assumed to have no FIFO.
* Usually correct to invoke via tty_wait_until_sent().
* Usually correct to invoke via tty_wait_until_sent(). May sleep.
*
* @send_xchar: ``void ()(struct tty_struct *tty, char ch)``
*