renegade-project/linux-next
2
0
Fork 0
mirror of https://github.com/edk2-porting/linux-next.git synced 2024-12-16 09:13:55 +08:00
Code

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

Browse Source 
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: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20220728061056.20799-3-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Jiri Slaby 2022-07-28 08:10:53 +02:00 committed by Greg Kroah-Hartman
parent c4bd17a6dd
commit 27940abd55
2 changed files with 52 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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

48
drivers/tty/serial/serial_mctrl_gpio.c
View File

@ -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;