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>

diff --git a/Documentation/driver-api/serial/tty.rst b/Documentation/driver-api/serial/tty.rst
index 4b709f392713d42c68c663d582a524d65de04a81..f7ef10c6f4584722fed06da2d12a0226b4bdfa33 100644 (file)
--- a/Documentation/driver-api/serial/tty.rst
+++ b/Documentation/driver-api/serial/tty.rst
@@ -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 ??
-======================= =======================================================

diff --git a/include/linux/tty_driver.h b/include/linux/tty_driver.h
index 5611992ab26aaef8fcb7e4e484bb43099fae6357..41274d551e2869ee7b56445ac8d8d0a7118cb1f9 100644 (file)
--- a/include/linux/tty_driver.h
+++ b/include/linux/tty_driver.h
@@ -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)``
  *