iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation: serial: dedup kernel-doc for uart functions

Browse Source 
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>
This commit is contained in:
Jiri Slaby 2022-07-28 08:10:52 +02:00 committed by Greg Kroah-Hartman
parent e60a723368
commit c4bd17a6dd
2 changed files with 87 additions and 138 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
Documentation/driver-api/serial/driver.rst
View File

@ -69,85 +69,11 @@ uart_ops
Other functions Other functions
--------------- ---------------
uart_update_timeout(port,cflag,baud) .. kernel-doc:: drivers/tty/serial/serial_core.c
Update the frame timing information according to the number of bits, :identifiers: uart_update_timeout uart_get_baud_rate uart_get_divisor
parity, stop bits and baud rate. The FIFO drain timeout is derived uart_match_port uart_write_wakeup uart_register_driver
from the frame timing information. uart_unregister_driver uart_suspend_port uart_resume_port
uart_add_one_port uart_remove_one_port
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()**
Other notes Other notes
----------- -----------

141
drivers/tty/serial/serial_core.c
View File

@ -97,9 +97,16 @@ static inline struct uart_port *uart_port_check(struct uart_state *state)
return state->uart_port; return state->uart_port;
} }
/* /**
* This routine is used by the interrupt handler to schedule processing in * uart_write_wakeup - schedule write processing
* the software interrupt portion of the driver. * @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) 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. * uart_update_timeout - update per-port frame timing information
* @port: uart_port structure describing the port * @port: uart_port structure describing the port
* @cflag: termios cflag value * @cflag: termios cflag value
* @baud: speed of the port * @baud: speed of the port
* *
* Set the port frame timing information from which the FIFO timeout * Set the @port frame timing information from which the FIFO timeout value is
* value is derived. The @cflag value should reflect the actual hardware * derived. The @cflag value should reflect the actual hardware settings as
* settings. * number of bits, parity, stop bits and baud rate is taken into account here.
*
* Locking: caller is expected to take @port->lock
*/ */
void void
uart_update_timeout(struct uart_port *port, unsigned int cflag, 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); EXPORT_SYMBOL(uart_update_timeout);
/** /**
* uart_get_baud_rate - return baud rate for a particular port * uart_get_baud_rate - return baud rate for a particular port
* @port: uart_port structure describing the port in question. * @port: uart_port structure describing the port in question.
* @termios: desired termios settings. * @termios: desired termios settings
* @old: old termios (or NULL) * @old: old termios (or %NULL)
* @min: minimum acceptable baud rate * @min: minimum acceptable baud rate
* @max: maximum acceptable baud rate * @max: maximum acceptable baud rate
* *
* Decode the termios structure into a numeric baud rate, * Decode the termios structure into a numeric baud rate, taking account of the
* taking account of the magic 38400 baud rate (with spd_* * magic 38400 baud rate (with spd_* flags), and mapping the %B0 rate to 9600
* flags), and mapping the %B0 rate to 9600 baud. * baud.
* *
* If the new baud rate is invalid, try the old termios setting. * If the new baud rate is invalid, try the @old termios setting. If it's still
* If it's still invalid, we try 9600 baud. * invalid, we try 9600 baud.
* *
* Update the @termios structure to reflect the baud rate * The @termios structure is updated to reflect the baud rate we're actually
* we're actually going to be using. Don't do this for the case * going to be using. Don't do this for the case where B0 is requested ("hang
* where B0 is requested ("hang up"). * up").
*
* Locking: caller dependent
*/ */
unsigned int unsigned int
uart_get_baud_rate(struct uart_port *port, struct ktermios *termios, 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); EXPORT_SYMBOL(uart_get_baud_rate);
/** /**
* uart_get_divisor - return uart clock divisor * uart_get_divisor - return uart clock divisor
* @port: uart_port structure describing the port. * @port: uart_port structure describing the port
* @baud: desired baud rate * @baud: desired baud rate
* *
* Calculate the uart clock divisor for the port. * Calculate the divisor (baud_base / baud) for the specified @baud,
* appropriately rounded.
*
* If 38400 baud and custom divisor is selected, return the custom divisor
* instead.
*
* Locking: caller dependent
*/ */
unsigned int unsigned int
uart_get_divisor(struct uart_port *port, unsigned int baud) 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 * uart_register_driver - register a driver with the uart core layer
* @drv: low level driver structure * @drv: low level driver structure
* *
* Register a uart driver with the core driver. We in turn register * Register a uart driver with the core driver. We in turn register with the
* with the tty layer, and initialise the core driver per-port state. * tty layer, and initialise the core driver per-port state.
* *
* We have a proc file in /proc/tty/driver which is named after the * We have a proc file in /proc/tty/driver which is named after the normal
* normal driver. * driver.
* *
* drv->port should be NULL, and the per-port structures should be * @drv->port should be %NULL, and the per-port structures should be registered
* registered using uart_add_one_port after this call has succeeded. * using uart_add_one_port() after this call has succeeded.
*
* Locking: none, Interrupts: enabled
*/ */
int uart_register_driver(struct uart_driver *drv) int uart_register_driver(struct uart_driver *drv)
{ {
@ -2757,13 +2776,14 @@ out:
EXPORT_SYMBOL(uart_register_driver); EXPORT_SYMBOL(uart_register_driver);
/** /**
* uart_unregister_driver - remove a driver from the uart core layer * uart_unregister_driver - remove a driver from the uart core layer
* @drv: low level driver structure * @drv: low level driver structure
* *
* Remove all references to a driver from the core driver. The low * Remove all references to a driver from the core driver. The low level
* level driver must have removed all its ports via the * driver must have removed all its ports via the uart_remove_one_port() if it
* uart_remove_one_port() if it registered them with uart_add_one_port(). * registered them with uart_add_one_port(). (I.e. @drv->port is %NULL.)
* (ie, drv->port == NULL) *
* Locking: none, Interrupts: enabled
*/ */
void uart_unregister_driver(struct uart_driver *drv) 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 * uart_add_one_port - attach a driver-defined port structure
* @drv: pointer to the uart low level driver structure for this port * @drv: pointer to the uart low level driver structure for this port
* @uport: uart port structure to use 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 * This allows the driver @drv to register its own uart_port structure with the
* with the core driver. The main purpose is to allow the low * core driver. The main purpose is to allow the low level uart drivers to
* level uart drivers to expand uart_port, rather than having yet * expand uart_port, rather than having yet more levels of structures.
* more levels of structures.
*/ */
int uart_add_one_port(struct uart_driver *drv, struct uart_port *uport) 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); EXPORT_SYMBOL(uart_add_one_port);
/** /**
* uart_remove_one_port - detach a driver defined port structure * uart_remove_one_port - detach a driver defined port structure
* @drv: pointer to the uart low level driver structure for this port * @drv: pointer to the uart low level driver structure for this port
* @uport: uart port 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 * This unhooks (and hangs up) the specified port structure from the core
* core driver. No further calls will be made to the low-level code * driver. No further calls will be made to the low-level code for this port.
* for this port.
*/ */
int uart_remove_one_port(struct uart_driver *drv, struct uart_port *uport) int uart_remove_one_port(struct uart_driver *drv, struct uart_port *uport)
{ {
@ -3196,8 +3214,13 @@ out:
} }
EXPORT_SYMBOL(uart_remove_one_port); 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, bool uart_match_port(const struct uart_port *port1,
const struct uart_port *port2) const struct uart_port *port2)