Documentation: serial: dedup kernel-doc for uart functions

Some of the serial (uart_*) functions are documented twice. Once as
kernel-doc along their sources and once in Documentation. So deduplicate
these texts, merge them into kernel-doc in the sources, and link them
using kernel-doc: from the Documentation.

To be properly linked and rendered, tabulators had to be removed from
the comments.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20220728061056.20799-2-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

diff --git a/Documentation/driver-api/serial/driver.rst b/Documentation/driver-api/serial/driver.rst
index cb0ec6db4f1ef929f763f478460d41c2a0146297..ac9620e97f4b0a894284e780b6ea6ef1b40a9a7f 100644 (file)
--- a/Documentation/driver-api/serial/driver.rst
+++ b/Documentation/driver-api/serial/driver.rst
@@ -69,85 +69,11 @@ uart_ops
 Other functions
 ---------------
 
-uart_update_timeout(port,cflag,baud)
-       Update the frame timing information according to the number of bits,
-       parity, stop bits and baud rate. The FIFO drain timeout is derived
-       from the frame timing information.
-
-       Locking: caller is expected to take port->lock
-
-       Interrupts: n/a
-
-uart_get_baud_rate(port,termios,old,min,max)
-       Return the numeric baud rate for the specified termios, taking
-       account of the special 38400 baud "kludge".  The B0 baud rate
-       is mapped to 9600 baud.
-
-       If the baud rate is not within min..max, then if old is non-NULL,
-       the original baud rate will be tried.  If that exceeds the
-       min..max constraint, 9600 baud will be returned.  termios will
-       be updated to the baud rate in use.
-
-       Note: min..max must always allow 9600 baud to be selected.
-
-       Locking: caller dependent.
-
-       Interrupts: n/a
-
-uart_get_divisor(port,baud)
-       Return the divisor (baud_base / baud) for the specified baud
-       rate, appropriately rounded.
-
-       If 38400 baud and custom divisor is selected, return the
-       custom divisor instead.
-
-       Locking: caller dependent.
-
-       Interrupts: n/a
-
-uart_match_port(port1,port2)
-       This utility function can be used to determine whether two
-       uart_port structures describe the same port.
-
-       Locking: n/a
-
-       Interrupts: n/a
-
-uart_write_wakeup(port)
-       A driver is expected to call this function when the number of
-       characters in the transmit buffer have dropped below a threshold.
-
-       Locking: port->lock should be held.
-
-       Interrupts: n/a
-
-uart_register_driver(drv)
-       Register a uart driver with the core driver.  We in turn register
-       with the tty layer, and initialise the core driver per-port state.
-
-       drv->port should be NULL, and the per-port structures should be
-       registered using uart_add_one_port after this call has succeeded.
-
-       Locking: none
-
-       Interrupts: enabled
-
-uart_unregister_driver()
-       Remove all references to a driver from the core driver.  The low
-       level driver must have removed all its ports via the
-       uart_remove_one_port() if it registered them with uart_add_one_port().
-
-       Locking: none
-
-       Interrupts: enabled
-
-**uart_suspend_port()**
-
-**uart_resume_port()**
-
-**uart_add_one_port()**
-
-**uart_remove_one_port()**
+.. kernel-doc:: drivers/tty/serial/serial_core.c
+   :identifiers: uart_update_timeout uart_get_baud_rate uart_get_divisor
+           uart_match_port uart_write_wakeup uart_register_driver
+           uart_unregister_driver uart_suspend_port uart_resume_port
+           uart_add_one_port uart_remove_one_port
 
 Other notes
 -----------

diff --git a/drivers/tty/serial/serial_core.c b/drivers/tty/serial/serial_core.c
index ac198d0d4c807a86b4a33b9fcd12d00d62e71a3f..c302aa34668d9f0274713fb7430264020000ee2e 100644 (file)
--- a/drivers/tty/serial/serial_core.c
+++ b/drivers/tty/serial/serial_core.c
@@ -97,9 +97,16 @@ static inline struct uart_port *uart_port_check(struct uart_state *state)
        return state->uart_port;
 }
 
-/*
- * This routine is used by the interrupt handler to schedule processing in
- * the software interrupt portion of the driver.
+/**
+ * uart_write_wakeup - schedule write processing
+ * @port: port to be processed
+ *
+ * This routine is used by the interrupt handler to schedule processing in the
+ * software interrupt portion of the driver. A driver is expected to call this
+ * function when the number of characters in the transmit buffer have dropped
+ * below a threshold.
+ *
+ * Locking: @port->lock should be held
  */
 void uart_write_wakeup(struct uart_port *port)
 {
@@ -327,14 +334,16 @@ static void uart_shutdown(struct tty_struct *tty, struct uart_state *state)
 }
 
 /**
- *     uart_update_timeout - update per-port frame timing information.
- *     @port:  uart_port structure describing the port
- *     @cflag: termios cflag value
- *     @baud:  speed of the port
+ * uart_update_timeout - update per-port frame timing information
+ * @port: uart_port structure describing the port
+ * @cflag: termios cflag value
+ * @baud: speed of the port
  *
- *     Set the port frame timing information from which the FIFO timeout
- *     value is derived. The @cflag value should reflect the actual hardware
- *     settings.
+ * Set the @port frame timing information from which the FIFO timeout value is
+ * derived. The @cflag value should reflect the actual hardware settings as
+ * number of bits, parity, stop bits and baud rate is taken into account here.
+ *
+ * Locking: caller is expected to take @port->lock
  */
 void
 uart_update_timeout(struct uart_port *port, unsigned int cflag,
@@ -349,23 +358,25 @@ uart_update_timeout(struct uart_port *port, unsigned int cflag,
 EXPORT_SYMBOL(uart_update_timeout);
 
 /**
- *     uart_get_baud_rate - return baud rate for a particular port
- *     @port: uart_port structure describing the port in question.
- *     @termios: desired termios settings.
- *     @old: old termios (or NULL)
- *     @min: minimum acceptable baud rate
- *     @max: maximum acceptable baud rate
+ * uart_get_baud_rate - return baud rate for a particular port
+ * @port: uart_port structure describing the port in question.
+ * @termios: desired termios settings
+ * @old: old termios (or %NULL)
+ * @min: minimum acceptable baud rate
+ * @max: maximum acceptable baud rate
+ *
+ * Decode the termios structure into a numeric baud rate, taking account of the
+ * magic 38400 baud rate (with spd_* flags), and mapping the %B0 rate to 9600
+ * baud.
  *
- *     Decode the termios structure into a numeric baud rate,
- *     taking account of the magic 38400 baud rate (with spd_*
- *     flags), and mapping the %B0 rate to 9600 baud.
+ * If the new baud rate is invalid, try the @old termios setting. If it's still
+ * invalid, we try 9600 baud.
  *
- *     If the new baud rate is invalid, try the old termios setting.
- *     If it's still invalid, we try 9600 baud.
+ * The @termios structure is updated to reflect the baud rate we're actually
+ * going to be using. Don't do this for the case where B0 is requested ("hang
+ * up").
  *
- *     Update the @termios structure to reflect the baud rate
- *     we're actually going to be using. Don't do this for the case
- *     where B0 is requested ("hang up").
+ * Locking: caller dependent
  */
 unsigned int
 uart_get_baud_rate(struct uart_port *port, struct ktermios *termios,
@@ -450,11 +461,17 @@ uart_get_baud_rate(struct uart_port *port, struct ktermios *termios,
 EXPORT_SYMBOL(uart_get_baud_rate);
 
 /**
- *     uart_get_divisor - return uart clock divisor
- *     @port: uart_port structure describing the port.
- *     @baud: desired baud rate
+ * uart_get_divisor - return uart clock divisor
+ * @port: uart_port structure describing the port
+ * @baud: desired baud rate
+ *
+ * Calculate the divisor (baud_base / baud) for the specified @baud,
+ * appropriately rounded.
  *
- *     Calculate the uart clock divisor for the port.
+ * If 38400 baud and custom divisor is selected, return the custom divisor
+ * instead.
+ *
+ * Locking: caller dependent
  */
 unsigned int
 uart_get_divisor(struct uart_port *port, unsigned int baud)
@@ -2683,17 +2700,19 @@ static const struct tty_port_operations uart_port_ops = {
 };
 
 /**
- *     uart_register_driver - register a driver with the uart core layer
- *     @drv: low level driver structure
+ * uart_register_driver - register a driver with the uart core layer
+ * @drv: low level driver structure
+ *
+ * Register a uart driver with the core driver. We in turn register with the
+ * tty layer, and initialise the core driver per-port state.
  *
- *     Register a uart driver with the core driver.  We in turn register
- *     with the tty layer, and initialise the core driver per-port state.
+ * We have a proc file in /proc/tty/driver which is named after the normal
+ * driver.
  *
- *     We have a proc file in /proc/tty/driver which is named after the
- *     normal driver.
+ * @drv->port should be %NULL, and the per-port structures should be registered
+ * using uart_add_one_port() after this call has succeeded.
  *
- *     drv->port should be NULL, and the per-port structures should be
- *     registered using uart_add_one_port after this call has succeeded.
+ * Locking: none, Interrupts: enabled
  */
 int uart_register_driver(struct uart_driver *drv)
 {
@@ -2757,13 +2776,14 @@ out:
 EXPORT_SYMBOL(uart_register_driver);
 
 /**
- *     uart_unregister_driver - remove a driver from the uart core layer
- *     @drv: low level driver structure
+ * uart_unregister_driver - remove a driver from the uart core layer
+ * @drv: low level driver structure
+ *
+ * Remove all references to a driver from the core driver. The low level
+ * driver must have removed all its ports via the uart_remove_one_port() if it
+ * registered them with uart_add_one_port(). (I.e. @drv->port is %NULL.)
  *
- *     Remove all references to a driver from the core driver.  The low
- *     level driver must have removed all its ports via the
- *     uart_remove_one_port() if it registered them with uart_add_one_port().
- *     (ie, drv->port == NULL)
+ * Locking: none, Interrupts: enabled
  */
 void uart_unregister_driver(struct uart_driver *drv)
 {
@@ -3012,16 +3032,15 @@ static const struct attribute_group tty_dev_attr_group = {
 };
 
 /**
- *     uart_add_one_port - attach a driver-defined port structure
- *     @drv: pointer to the uart low level driver structure for this port
- *     @uport: uart port structure to use for this port.
+ * uart_add_one_port - attach a driver-defined port structure
+ * @drv: pointer to the uart low level driver structure for this port
+ * @uport: uart port structure to use for this port.
  *
- *     Context: task context, might sleep
+ * Context: task context, might sleep
  *
- *     This allows the driver to register its own uart_port structure
- *     with the core driver.  The main purpose is to allow the low
- *     level uart drivers to expand uart_port, rather than having yet
- *     more levels of structures.
+ * This allows the driver @drv to register its own uart_port structure with the
+ * core driver. The main purpose is to allow the low level uart drivers to
+ * expand uart_port, rather than having yet more levels of structures.
  */
 int uart_add_one_port(struct uart_driver *drv, struct uart_port *uport)
 {
@@ -3116,15 +3135,14 @@ int uart_add_one_port(struct uart_driver *drv, struct uart_port *uport)
 EXPORT_SYMBOL(uart_add_one_port);
 
 /**
- *     uart_remove_one_port - detach a driver defined port structure
- *     @drv: pointer to the uart low level driver structure for this port
- *     @uport: uart port structure for this port
+ * uart_remove_one_port - detach a driver defined port structure
+ * @drv: pointer to the uart low level driver structure for this port
+ * @uport: uart port structure for this port
  *
- *     Context: task context, might sleep
+ * Context: task context, might sleep
  *
- *     This unhooks (and hangs up) the specified port structure from the
- *     core driver.  No further calls will be made to the low-level code
- *     for this port.
+ * This unhooks (and hangs up) the specified port structure from the core
+ * driver. No further calls will be made to the low-level code for this port.
  */
 int uart_remove_one_port(struct uart_driver *drv, struct uart_port *uport)
 {
@@ -3196,8 +3214,13 @@ out:
 }
 EXPORT_SYMBOL(uart_remove_one_port);
 
-/*
- *     Are the two ports equivalent?
+/**
+ * uart_match_port - are the two ports equivalent?
+ * @port1: first port
+ * @port2: second port
+ *
+ * This utility function can be used to determine whether two uart_port
+ * structures describe the same port.
  */
 bool uart_match_port(const struct uart_port *port1,
                const struct uart_port *port2)