Commit 987233b3 authored by Jiri Slaby's avatar Jiri Slaby Committed by Greg Kroah-Hartman
Browse files

tty: serial: serial_core, reformat kernel-doc for functions 



There are many annotated functions in serial_core.c, but they do not
completely conform to the kernel-doc style. So reformat them and link
them from the Documentation.

Signed-off-by: default avatarJiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20220728061056.20799-5-jslaby@suse.cz


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent d34d7c4b

Documentation/driver-api/serial/driver.rst

+7 −4
Original line number Diff line number Diff line
@@ -25,10 +25,10 @@ Console Support 
---------------



The serial core provides a few helper functions.  This includes identifing

the correct port structure (via uart_get_console) and decoding command line

arguments (uart_parse_options).

the correct port structure (via uart_get_console()) and decoding command line

arguments (uart_parse_options()).



There is also a helper function (uart_console_write) which performs a

There is also a helper function (uart_console_write()) which performs a

character by character write, translating newlines to CRLF sequences.

Driver writers are recommended to use this function rather than implementing

their own version.
@@ -73,7 +73,10 @@ Other functions 
   :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

           uart_add_one_port uart_remove_one_port uart_console_write

           uart_parse_earlycon uart_parse_options uart_set_options

           uart_get_lsr_info uart_handle_dcd_change uart_handle_cts_change

           uart_try_toggle_sysrq



Other notes

-----------

drivers/tty/serial/serial_core.c

+53 −54
Original line number Diff line number Diff line
@@ -2119,20 +2119,19 @@ uart_get_console(struct uart_port *ports, int nr, struct console *co) 
 * @p:	     ptr to 2nd field (ie., just beyond '<name>,')

 * @iotype:  ptr for decoded iotype (out)

 * @addr:    ptr for decoded mapbase/iobase (out)

 *	@options: ptr for <options> field; NULL if not present (out)

 * @options: ptr for <options> field; %NULL if not present (out)

 *

 *	Decodes earlycon kernel command line parameters of the form

 *	   earlycon=<name>,io|mmio|mmio16|mmio32|mmio32be|mmio32native,<addr>,<options>

 *	   console=<name>,io|mmio|mmio16|mmio32|mmio32be|mmio32native,<addr>,<options>

 * Decodes earlycon kernel command line parameters of the form:

 *  * earlycon=<name>,io|mmio|mmio16|mmio32|mmio32be|mmio32native,<addr>,<options>

 *  * console=<name>,io|mmio|mmio16|mmio32|mmio32be|mmio32native,<addr>,<options>

 *

 *	The optional form

 * The optional form:

 *  * earlycon=<name>,0x<addr>,<options>

 *  * console=<name>,0x<addr>,<options>

 *

 *	   earlycon=<name>,0x<addr>,<options>

 *	   console=<name>,0x<addr>,<options>

 * is also accepted; the returned @iotype will be %UPIO_MEM.

 *

 *	is also accepted; the returned @iotype will be UPIO_MEM.

 *

 *	Returns 0 on success or -EINVAL on failure

 * Returns: 0 on success or -%EINVAL on failure

 */

int uart_parse_earlycon(char *p, unsigned char *iotype, resource_size_t *addr,

			char **options)
@@ -2184,7 +2183,7 @@ EXPORT_SYMBOL_GPL(uart_parse_earlycon); 
 * @bits: pointer to an 'int' variable for the number of data bits.

 * @flow: pointer to an 'int' variable for the flow control character.

 *

 *	uart_parse_options decodes a string containing the serial console

 * uart_parse_options() decodes a string containing the serial console

 * options. The format of the string is <baud><parity><bits><flow>,

 * eg: 115200n8r

 */
@@ -3252,7 +3251,7 @@ EXPORT_SYMBOL(uart_match_port); 
 * @uport: uart_port structure for the open port

 * @status: new carrier detect status, nonzero if active

 *

 *	Caller must hold uport->lock

 * Caller must hold uport->lock.

 */

void uart_handle_dcd_change(struct uart_port *uport, unsigned int status)

{
@@ -3287,7 +3286,7 @@ EXPORT_SYMBOL_GPL(uart_handle_dcd_change); 
 * @uport: uart_port structure for the open port

 * @status: new clear to send status, nonzero if active

 *

 *	Caller must hold uport->lock

 * Caller must hold uport->lock.

 */

void uart_handle_cts_change(struct uart_port *uport, unsigned int status)

{
@@ -3365,8 +3364,8 @@ static DECLARE_WORK(sysrq_enable_work, uart_sysrq_on); 
 * Enables magic SysRq when the required sequence is met on port

 * (see CONFIG_MAGIC_SYSRQ_SERIAL_SEQUENCE).

 *

 *	Returns false if @ch is out of enabling sequence and should be

 *	handled some other way, true if @ch was consumed.

 * Returns: %false if @ch is out of enabling sequence and should be

 * handled some other way, %true if @ch was consumed.

 */

bool uart_try_toggle_sysrq(struct uart_port *port, unsigned int ch)

{