Commit 27940abd authored by Jiri Slaby's avatar Jiri Slaby Committed by Greg Kroah-Hartman
Browse files

Documentation: serial: move GPIO kernel-doc to the functions 



The GPIO uart functions are documented in Documentation. Move and
transform this documentation into kernel-doc directly in the code and
reference it in Documentation using kernel-doc:.

This makes it easier to update, maintain and check by the build.

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


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

Documentation/driver-api/serial/driver.rst

+4 −28
Original line number Diff line number Diff line
@@ -94,31 +94,7 @@ Modem control lines via GPIO 


Some helpers are provided in order to set/get modem control lines via GPIO.



mctrl_gpio_init(port, idx):

	This will get the {cts,rts,...}-gpios from device tree if they are

	present and request them, set direction etc, and return an

	allocated structure. `devm_*` functions are used, so there's no need

	to call mctrl_gpio_free().

	As this sets up the irq handling make sure to not handle changes to the

	gpio input lines in your driver, too.



mctrl_gpio_free(dev, gpios):

	This will free the requested gpios in mctrl_gpio_init().

	As `devm_*` functions are used, there's generally no need to call

	this function.



mctrl_gpio_to_gpiod(gpios, gidx)

	This returns the gpio_desc structure associated to the modem line

	index.



mctrl_gpio_set(gpios, mctrl):

	This will sets the gpios according to the mctrl state.



mctrl_gpio_get(gpios, mctrl):

	This will update mctrl with the gpios values.



mctrl_gpio_enable_ms(gpios):

	Enables irqs and handling of changes to the ms lines.



mctrl_gpio_disable_ms(gpios):

	Disables irqs and handling of changes to the ms lines.
 
.. kernel-doc:: drivers/tty/serial/serial_mctrl_gpio.c

   :identifiers: mctrl_gpio_init mctrl_gpio_free mctrl_gpio_to_gpiod

           mctrl_gpio_set mctrl_gpio_get mctrl_gpio_enable_ms

           mctrl_gpio_disable_ms

drivers/tty/serial/serial_mctrl_gpio.c

+48 −0
Original line number Diff line number Diff line
@@ -42,6 +42,13 @@ static bool mctrl_gpio_flags_is_dir_out(unsigned int idx) 
	return mctrl_gpios_desc[idx].flags & GPIOD_FLAGS_BIT_DIR_OUT;

}



/**

 * mctrl_gpio_set - set gpios according to mctrl state

 * @gpios: gpios to set

 * @mctrl: state to set

 *

 * Set the gpios according to the mctrl state.

 */

void mctrl_gpio_set(struct mctrl_gpios *gpios, unsigned int mctrl)

{

	enum mctrl_gpio_idx i;
@@ -63,6 +70,12 @@ void mctrl_gpio_set(struct mctrl_gpios *gpios, unsigned int mctrl) 
}

EXPORT_SYMBOL_GPL(mctrl_gpio_set);



/**

 * mctrl_gpio_to_gpiod - obtain gpio_desc of modem line index

 * @gpios: gpios to look into

 * @gidx: index of the modem line

 * Returns: the gpio_desc structure associated to the modem line index

 */

struct gpio_desc *mctrl_gpio_to_gpiod(struct mctrl_gpios *gpios,

				      enum mctrl_gpio_idx gidx)

{
@@ -73,6 +86,14 @@ struct gpio_desc *mctrl_gpio_to_gpiod(struct mctrl_gpios *gpios, 
}

EXPORT_SYMBOL_GPL(mctrl_gpio_to_gpiod);



/**

 * mctrl_gpio_get - update mctrl with the gpios values.

 * @gpios: gpios to get the info from

 * @mctrl: mctrl to set

 * Returns: modified mctrl (the same value as in @mctrl)

 *

 * Update mctrl with the gpios values.

 */

unsigned int mctrl_gpio_get(struct mctrl_gpios *gpios, unsigned int *mctrl)

{

	enum mctrl_gpio_idx i;
@@ -189,6 +210,17 @@ static irqreturn_t mctrl_gpio_irq_handle(int irq, void *context) 
	return IRQ_HANDLED;

}



/**

 * mctrl_gpio_init - initialize uart gpios

 * @port: port to initialize gpios for

 * @idx: index of the gpio in the @port's device

 *

 * This will get the {cts,rts,...}-gpios from device tree if they are present

 * and request them, set direction etc, and return an allocated structure.

 * `devm_*` functions are used, so there's no need to call mctrl_gpio_free().

 * As this sets up the irq handling, make sure to not handle changes to the

 * gpio input lines in your driver, too.

 */

struct mctrl_gpios *mctrl_gpio_init(struct uart_port *port, unsigned int idx)

{

	struct mctrl_gpios *gpios;
@@ -235,6 +267,14 @@ struct mctrl_gpios *mctrl_gpio_init(struct uart_port *port, unsigned int idx) 
}

EXPORT_SYMBOL_GPL(mctrl_gpio_init);



/**

 * mctrl_gpio_free - explicitly free uart gpios

 * @dev: uart port's device

 * @gpios: gpios structure to be freed

 *

 * This will free the requested gpios in mctrl_gpio_init(). As `devm_*`

 * functions are used, there's generally no need to call this function.

 */

void mctrl_gpio_free(struct device *dev, struct mctrl_gpios *gpios)

{

	enum mctrl_gpio_idx i;
@@ -253,6 +293,10 @@ void mctrl_gpio_free(struct device *dev, struct mctrl_gpios *gpios) 
}

EXPORT_SYMBOL_GPL(mctrl_gpio_free);



/**

 * mctrl_gpio_enable_ms - enable irqs and handling of changes to the ms lines

 * @gpios: gpios to enable

 */

void mctrl_gpio_enable_ms(struct mctrl_gpios *gpios)

{

	enum mctrl_gpio_idx i;
@@ -278,6 +322,10 @@ void mctrl_gpio_enable_ms(struct mctrl_gpios *gpios) 
}

EXPORT_SYMBOL_GPL(mctrl_gpio_enable_ms);



/**

 * mctrl_gpio_disable_ms - disable irqs and handling of changes to the ms lines

 * @gpios: gpios to disable

 */

void mctrl_gpio_disable_ms(struct mctrl_gpios *gpios)

{

	enum mctrl_gpio_idx i;