2024-03-26 18:21:56

by Andy Shevchenko

Subject: [PATCH v1 0/2] gpiolib: in-kernel documentation updates

While looking for something I have noticed that in-kernel documentation
for gpiolib implementation may be updated to reflect the current state
of affairs. Hence these two patches.

Andy Shevchenko (2):
gpiolib: Do not mention legacy GPIOF_* in the code
gpiolib: Up to date the kernel documentation

drivers/gpio/gpiolib-acpi.c | 45 ++--
drivers/gpio/gpiolib-cdev.c | 15 +-
drivers/gpio/gpiolib-devres.c | 85 ++++++--
drivers/gpio/gpiolib-legacy.c | 3 +
drivers/gpio/gpiolib-of.c | 102 +++++----
drivers/gpio/gpiolib-swnode.c | 8 +-
drivers/gpio/gpiolib-sysfs.c | 41 ++--
drivers/gpio/gpiolib.c | 388 +++++++++++++++++++++-------------
drivers/gpio/gpiolib.h | 8 +-
9 files changed, 438 insertions(+), 257 deletions(-)

--
2.43.0.rc1.1.gbec44491f096

2024-03-26 20:14:09

by Andy Shevchenko

Subject: [PATCH v1 1/2] gpiolib: Do not mention legacy GPIOF_* in the code

We are going to remove legacy API from kernel, don't mention
it in the code that does not use it already for a while.

Signed-off-by: Andy Shevchenko <[email protected]>
---
drivers/gpio/gpiolib.c | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/drivers/gpio/gpiolib.c b/drivers/gpio/gpiolib.c
index 5589e085ba25..f749ece2d3cd 100644
--- a/drivers/gpio/gpiolib.c
+++ b/drivers/gpio/gpiolib.c
@@ -364,7 +364,10 @@ int gpiod_get_direction(struct gpio_desc *desc)
if (ret < 0)
return ret;

- /* GPIOF_DIR_IN or other positive, otherwise GPIOF_DIR_OUT */
+ /*
+ * GPIO_LINE_DIRECTION_IN or other positive,
+ * otherwise GPIO_LINE_DIRECTION_OUT.
+ */
if (ret > 0)
ret = 1;

--
2.43.0.rc1.1.gbec44491f096

2024-03-26 23:05:11

by Andy Shevchenko

Subject: [PATCH v1 2/2] gpiolib: Up to date the kernel documentation

There are several issues:

- Reference to the non-existing or only single functions out of possible
callees

- No return section

$ scripts/kernel-doc -v -none -Wall drivers/gpio/gpiolib* 2>&1 | grep -w warning | wc -l
67

- Reference to NULL as %NULL in a few cases

- Explicit reference to error codes as Exxx or %Exxx and
numbers with leading %

- Spelling of gpio, irq, SOC (in different capitalization)

- Unaligned style of irqchip, gpiochip references

- Unaligned style of NOTE, FIXME, and TODO

Fix all these. While at it, fix multi-line comment style as well.

Signed-off-by: Andy Shevchenko <[email protected]>
---
drivers/gpio/gpiolib-acpi.c | 45 ++--
drivers/gpio/gpiolib-cdev.c | 15 +-
drivers/gpio/gpiolib-devres.c | 85 ++++++--
drivers/gpio/gpiolib-legacy.c | 3 +
drivers/gpio/gpiolib-of.c | 102 +++++----
drivers/gpio/gpiolib-swnode.c | 8 +-
drivers/gpio/gpiolib-sysfs.c | 41 ++--
drivers/gpio/gpiolib.c | 383 +++++++++++++++++++++-------------
drivers/gpio/gpiolib.h | 8 +-
9 files changed, 434 insertions(+), 256 deletions(-)

diff --git a/drivers/gpio/gpiolib-acpi.c b/drivers/gpio/gpiolib-acpi.c
index 7f140df40f35..dfcfa23e7a59 100644
--- a/drivers/gpio/gpiolib-acpi.c
+++ b/drivers/gpio/gpiolib-acpi.c
@@ -136,8 +136,12 @@ static int acpi_gpiochip_find(struct gpio_chip *gc, const void *data)
* @path: ACPI GPIO controller full path name, (e.g. "\\_SB.GPO1")
* @pin: ACPI GPIO pin number (0-based, controller-relative)
*
- * Return: GPIO descriptor to use with Linux generic GPIO API, or ERR_PTR
- * error value. Specifically returns %-EPROBE_DEFER if the referenced GPIO
+ * Returns:
+ * GPIO descriptor to use with Linux generic GPIO API.
+ * If the GPIO cannot be translated or there is an error an ERR_PTR is
+ * returned.
+ *
+ * Specifically returns -EPROBE_DEFER if the referenced GPIO
* controller does not have GPIO chip registered at the moment. This is to
* support probe deferral.
*/
@@ -156,7 +160,7 @@ static struct gpio_desc *acpi_get_gpiod(char *path, unsigned int pin)
return ERR_PTR(-EPROBE_DEFER);

/*
- * FIXME: keep track of the reference to the GPIO device somehow
+ * FIXME: Keep track of the reference to the GPIO device somehow
* instead of putting it here.
*/
return gpio_device_get_desc(gdev, pin);
@@ -203,10 +207,12 @@ bool acpi_gpio_get_irq_resource(struct acpi_resource *ares,
EXPORT_SYMBOL_GPL(acpi_gpio_get_irq_resource);

/**
- * acpi_gpio_get_io_resource - Fetch details of an ACPI resource if it is a GPIO
- * I/O resource or return False if not.
+ * acpi_gpio_get_io_resource - Fetch details of an ACPI resource if it is a GpioIo resource
* @ares: Pointer to the ACPI resource to fetch
* @agpio: Pointer to a &struct acpi_resource_gpio to store the output pointer
+ *
+ * Returns:
+ * true if GpioIo resource is found, false otherwise.
*/
bool acpi_gpio_get_io_resource(struct acpi_resource *ares,
struct acpi_resource_gpio **agpio)
@@ -487,7 +493,7 @@ static acpi_status acpi_gpiochip_alloc_event(struct acpi_resource *ares,
}

/**
- * acpi_gpiochip_request_interrupts() - Register isr for gpio chip ACPI events
+ * acpi_gpiochip_request_interrupts() - Register isr for GPIO chip ACPI events
* @chip: GPIO chip
*
* ACPI5 platforms can use GPIO signaled ACPI events. These GPIO interrupts are
@@ -664,7 +670,7 @@ __acpi_gpio_update_gpiod_flags(enum gpiod_flags *flags, enum gpiod_flags update)
* Check if caller supplied incompatible GPIO initialization
* flags.
*
- * Return %-EINVAL to notify that firmware has different
+ * Return -EINVAL to notify that firmware has different
* settings and we are going to use them.
*/
if (((*flags & GPIOD_FLAGS_BIT_DIR_SET) && (diff & GPIOD_FLAGS_BIT_DIR_OUT)) ||
@@ -764,7 +770,7 @@ static int acpi_populate_gpio_lookup(struct acpi_resource *ares, void *data)
/*
* Polarity and triggering are only specified for GpioInt
* resource.
- * Note: we expect here:
+ * NOTE: We expect here:
* - ACPI_ACTIVE_LOW == GPIO_ACTIVE_LOW
* - ACPI_ACTIVE_HIGH == GPIO_ACTIVE_HIGH
*/
@@ -847,22 +853,24 @@ static int acpi_gpio_property_lookup(struct fwnode_handle *fwnode,
* acpi_get_gpiod_by_index() - get a GPIO descriptor from device resources
* @adev: pointer to a ACPI device to get GPIO from
* @propname: Property name of the GPIO (optional)
- * @index: index of GpioIo/GpioInt resource (starting from %0)
+ * @index: index of GpioIo/GpioInt resource (starting from 0)
* @info: info pointer to fill in (optional)
*
* Function goes through ACPI resources for @adev and based on @index looks
* up a GpioIo/GpioInt resource, translates it to the Linux GPIO descriptor,
* and returns it. @index matches GpioIo/GpioInt resources only so if there
- * are total %3 GPIO resources, the index goes from %0 to %2.
+ * are total 3 GPIO resources, the index goes from 0 to 2.
*
* If @propname is specified the GPIO is looked using device property. In
* that case @index is used to select the GPIO entry in the property value
* (in case of multiple).
*
- * If the GPIO cannot be translated or there is an error, an ERR_PTR is
+ * Returns:
+ * GPIO descriptor to use with Linux generic GPIO API.
+ * If the GPIO cannot be translated or there is an error an ERR_PTR is
* returned.
*
- * Note: if the GPIO resource has multiple entries in the pin list, this
+ * NOTE: If the GPIO resource has multiple entries in the pin list, this
* function only returns the first.
*/
static struct gpio_desc *acpi_get_gpiod_by_index(struct acpi_device *adev,
@@ -903,13 +911,15 @@ static struct gpio_desc *acpi_get_gpiod_by_index(struct acpi_device *adev,
* acpi_get_gpiod_from_data() - get a GPIO descriptor from ACPI data node
* @fwnode: pointer to an ACPI firmware node to get the GPIO information from
* @propname: Property name of the GPIO
- * @index: index of GpioIo/GpioInt resource (starting from %0)
+ * @index: index of GpioIo/GpioInt resource (starting from 0)
* @info: info pointer to fill in (optional)
*
* This function uses the property-based GPIO lookup to get to the GPIO
* resource with the relevant information from a data-only ACPI firmware node
* and uses that to obtain the GPIO descriptor to return.
*
+ * Returns:
+ * GPIO descriptor to use with Linux generic GPIO API.
* If the GPIO cannot be translated or there is an error an ERR_PTR is
* returned.
*/
@@ -1007,7 +1017,7 @@ struct gpio_desc *acpi_find_gpio(struct fwnode_handle *fwnode,
* acpi_dev_gpio_irq_wake_get_by() - Find GpioInt and translate it to Linux IRQ number
* @adev: pointer to a ACPI device to get IRQ from
* @name: optional name of GpioInt resource
- * @index: index of GpioInt resource (starting from %0)
+ * @index: index of GpioInt resource (starting from 0)
* @wake_capable: Set to true if the IRQ is wake capable
*
* If the device has one or more GpioInt resources, this function can be
@@ -1023,7 +1033,8 @@ struct gpio_desc *acpi_find_gpio(struct fwnode_handle *fwnode,
* The GPIO is considered wake capable if the GpioInt resource specifies
* SharedAndWake or ExclusiveAndWake.
*
- * Return: Linux IRQ number (> %0) on success, negative errno on failure.
+ * Returns:
+ * Linux IRQ number (> 0) on success, negative errno on failure.
*/
int acpi_dev_gpio_irq_wake_get_by(struct acpi_device *adev, const char *name, int index,
bool *wake_capable)
@@ -1406,8 +1417,8 @@ static int acpi_find_gpio_count(struct acpi_resource *ares, void *data)
* @fwnode: firmware node of the GPIO consumer
* @con_id: function within the GPIO consumer
*
- * Return:
- * The number of GPIOs associated with a firmware node / function or %-ENOENT,
+ * Returns:
+ * The number of GPIOs associated with a firmware node / function or -ENOENT,
* if no GPIO has been assigned to the requested function.
*/
int acpi_gpio_count(const struct fwnode_handle *fwnode, const char *con_id)
diff --git a/drivers/gpio/gpiolib-cdev.c b/drivers/gpio/gpiolib-cdev.c
index f384fa278764..b4369a8b4381 100644
--- a/drivers/gpio/gpiolib-cdev.c
+++ b/drivers/gpio/gpiolib-cdev.c
@@ -54,7 +54,8 @@ static_assert(IS_ALIGNED(sizeof(struct gpio_v2_line_info_changed), 8));
static_assert(IS_ALIGNED(sizeof(struct gpio_v2_line_event), 8));
static_assert(IS_ALIGNED(sizeof(struct gpio_v2_line_values), 8));

-/* Character device interface to GPIO.
+/*
+ * Character device interface to GPIO.
*
* The GPIO character device, /dev/gpiochipN, provides userspace an
* interface to gpiolib GPIOs via ioctl()s.
@@ -531,7 +532,7 @@ static DEFINE_SPINLOCK(supinfo_lock);
* @event_buffer_size: the number of elements allocated in @events
* @events: KFIFO for the GPIO events
* @seqno: the sequence number for edge events generated on all lines in
- * this line request. Note that this is not used when @num_lines is 1, as
+ * this line request. NOTE: This is not used when @num_lines is 1, as
* the line_seqno is then the same and is cheaper to calculate.
* @config_mutex: mutex for serializing ioctl() calls to ensure consistency
* of configuration, particularly multi-step accesses to desc flags and
@@ -2684,7 +2685,9 @@ static ssize_t lineinfo_watch_read(struct file *file, char __user *buf,
* gpio_chrdev_open() - open the chardev for ioctl operations
* @inode: inode for this chardev
* @file: file struct for storing private data
- * Returns 0 on success
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
static int gpio_chrdev_open(struct inode *inode, struct file *file)
{
@@ -2695,7 +2698,7 @@ static int gpio_chrdev_open(struct inode *inode, struct file *file)

guard(srcu)(&gdev->srcu);

- /* Fail on open if the backing gpiochip is gone */
+ /* Fail on open if the backing GPIO chip is gone */
if (!rcu_access_pointer(gdev->chip))
return -ENODEV;

@@ -2750,7 +2753,9 @@ static int gpio_chrdev_open(struct inode *inode, struct file *file)
* gpio_chrdev_release() - close chardev after ioctl operations
* @inode: inode for this chardev
* @file: file struct for storing private data
- * Returns 0 on success
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
static int gpio_chrdev_release(struct inode *inode, struct file *file)
{
diff --git a/drivers/gpio/gpiolib-devres.c b/drivers/gpio/gpiolib-devres.c
index 4987e62dcb3d..20e3eae785b6 100644
--- a/drivers/gpio/gpiolib-devres.c
+++ b/drivers/gpio/gpiolib-devres.c
@@ -1,6 +1,6 @@
/* SPDX-License-Identifier: GPL-2.0 */
/*
- * devres.c - managed gpio resources
+ * Managed GPIO resources.
* This file is based on kernel/irq/devres.c
*
* Copyright (c) 2011 John Crispin <[email protected]>
@@ -52,6 +52,11 @@ static int devm_gpiod_match_array(struct device *dev, void *res, void *data)
* Managed gpiod_get(). GPIO descriptors returned from this function are
* automatically disposed on driver detach. See gpiod_get() for detailed
* information about behavior and return values.
+ *
+ * Returns:
+ * The GPIO descriptor corresponding to the function @con_id of device
+ * dev, -ENOENT if no GPIO has been assigned to the requested function, or
+ * another IS_ERR() code if an error occurred while trying to acquire the GPIO.
*/
struct gpio_desc *__must_check devm_gpiod_get(struct device *dev,
const char *con_id,
@@ -70,6 +75,11 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get);
* Managed gpiod_get_optional(). GPIO descriptors returned from this function
* are automatically disposed on driver detach. See gpiod_get_optional() for
* detailed information about behavior and return values.
+ *
+ * Returns:
+ * The GPIO descriptor corresponding to the function @con_id of device
+ * dev, NULL if no GPIO has been assigned to the requested function, or
+ * another IS_ERR() code if an error occurred while trying to acquire the GPIO.
*/
struct gpio_desc *__must_check devm_gpiod_get_optional(struct device *dev,
const char *con_id,
@@ -89,6 +99,11 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get_optional);
* Managed gpiod_get_index(). GPIO descriptors returned from this function are
* automatically disposed on driver detach. See gpiod_get_index() for detailed
* information about behavior and return values.
+ *
+ * Returns:
+ * The GPIO descriptor corresponding to the function @con_id of device
+ * dev, -ENOENT if no GPIO has been assigned to the requested function, or
+ * another IS_ERR() code if an error occurred while trying to acquire the GPIO.
*/
struct gpio_desc *__must_check devm_gpiod_get_index(struct device *dev,
const char *con_id,
@@ -141,8 +156,10 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get_index);
* GPIO descriptors returned from this function are automatically disposed on
* driver detach.
*
- * On successful request the GPIO pin is configured in accordance with
- * provided @flags.
+ * Returns:
+ * The GPIO descriptor corresponding to the function @con_id of device
+ * dev, -ENOENT if no GPIO has been assigned to the requested function, or
+ * another IS_ERR() code if an error occurred while trying to acquire the GPIO.
*/
struct gpio_desc *devm_fwnode_gpiod_get_index(struct device *dev,
struct fwnode_handle *fwnode,
@@ -182,6 +199,11 @@ EXPORT_SYMBOL_GPL(devm_fwnode_gpiod_get_index);
* function are automatically disposed on driver detach. See
* gpiod_get_index_optional() for detailed information about behavior and
* return values.
+ *
+ * Returns:
+ * The GPIO descriptor corresponding to the function @con_id of device
+ * dev, NULL if no GPIO has been assigned to the requested function, or
+ * another IS_ERR() code if an error occurred while trying to acquire the GPIO.
*/
struct gpio_desc *__must_check devm_gpiod_get_index_optional(struct device *dev,
const char *con_id,
@@ -207,6 +229,12 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get_index_optional);
* Managed gpiod_get_array(). GPIO descriptors returned from this function are
* automatically disposed on driver detach. See gpiod_get_array() for detailed
* information about behavior and return values.
+ *
+ * Returns:
+ * The GPIO descriptors corresponding to the function @con_id of device
+ * dev, -ENOENT if no GPIO has been assigned to the requested function,
+ * or another IS_ERR() code if an error occurred while trying to acquire
+ * the GPIOs.
*/
struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev,
const char *con_id,
@@ -243,6 +271,12 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get_array);
* function are automatically disposed on driver detach.
* See gpiod_get_array_optional() for detailed information about behavior and
* return values.
+ *
+ * Returns:
+ * The GPIO descriptors corresponding to the function @con_id of device
+ * dev, NULL if no GPIO has been assigned to the requested function,
+ * or another IS_ERR() code if an error occurred while trying to acquire
+ * the GPIOs.
*/
struct gpio_descs *__must_check
devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
@@ -275,7 +309,7 @@ void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)
EXPORT_SYMBOL_GPL(devm_gpiod_put);

/**
- * devm_gpiod_unhinge - Remove resource management from a gpio descriptor
+ * devm_gpiod_unhinge - Remove resource management from a GPIO descriptor
* @dev: GPIO consumer
* @desc: GPIO descriptor to remove resource management from
*
@@ -283,7 +317,6 @@ EXPORT_SYMBOL_GPL(devm_gpiod_put);
* you want to hand over lifecycle management of a descriptor to another
* mechanism.
*/
-
void devm_gpiod_unhinge(struct device *dev, struct gpio_desc *desc)
{
int ret;
@@ -328,15 +361,20 @@ static void devm_gpio_release(struct device *dev, void *res)
}

/**
- * devm_gpio_request - request a GPIO for a managed device
- * @dev: device to request the GPIO for
- * @gpio: GPIO to allocate
- * @label: the name of the requested GPIO
+ * devm_gpio_request - request a GPIO for a managed device
+ * @dev: device to request the GPIO for
+ * @gpio: GPIO to allocate
+ * @label: the name of the requested GPIO
*
- * Except for the extra @dev argument, this function takes the
- * same arguments and performs the same function as
- * gpio_request(). GPIOs requested with this function will be
- * automatically freed on driver detach.
+ * Except for the extra @dev argument, this function takes the
+ * same arguments and performs the same function as gpio_request().
+ * GPIOs requested with this function will be automatically freed
+ * on driver detach.
+ *
+ * **DEPRECATED** This function is deprecated and must not be used in new code.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int devm_gpio_request(struct device *dev, unsigned gpio, const char *label)
{
@@ -361,11 +399,16 @@ int devm_gpio_request(struct device *dev, unsigned gpio, const char *label)
EXPORT_SYMBOL_GPL(devm_gpio_request);

/**
- * devm_gpio_request_one - request a single GPIO with initial setup
- * @dev: device to request for
- * @gpio: the GPIO number
- * @flags: GPIO configuration as specified by GPIOF_*
- * @label: a literal description string of this GPIO
+ * devm_gpio_request_one - request a single GPIO with initial setup
+ * @dev: device to request for
+ * @gpio: the GPIO number
+ * @flags: GPIO configuration as specified by GPIOF_*
+ * @label: a literal description string of this GPIO
+ *
+ * **DEPRECATED** This function is deprecated and must not be used in new code.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int devm_gpio_request_one(struct device *dev, unsigned gpio,
unsigned long flags, const char *label)
@@ -399,15 +442,15 @@ static void devm_gpio_chip_release(void *data)

/**
* devm_gpiochip_add_data_with_key() - Resource managed gpiochip_add_data_with_key()
- * @dev: pointer to the device that gpio_chip belongs to.
+ * @dev: pointer to the device that GPIO chip belongs to.
* @gc: the GPIO chip to register
* @data: driver-private data associated with this chip
* @lock_key: lockdep class for IRQ lock
* @request_key: lockdep class for IRQ request
*
- * Context: potentially before irqs will work
+ * Context: potentially before IRQs will work
*
- * The gpio chip automatically be released when the device is unbound.
+ * The GPIO chip automatically be released when the device is unbound.
*
* Returns:
* A negative errno if the chip can't be registered, such as because the
diff --git a/drivers/gpio/gpiolib-legacy.c b/drivers/gpio/gpiolib-legacy.c
index 5a9911ae9125..d27142418f9f 100644
--- a/drivers/gpio/gpiolib-legacy.c
+++ b/drivers/gpio/gpiolib-legacy.c
@@ -22,6 +22,9 @@ EXPORT_SYMBOL_GPL(gpio_free);
* @label: a literal description string of this GPIO
*
* **DEPRECATED** This function is deprecated and must not be used in new code.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpio_request_one(unsigned gpio, unsigned long flags, const char *label)
{
diff --git a/drivers/gpio/gpiolib-of.c b/drivers/gpio/gpiolib-of.c
index cb0cefaec37e..7c0e2528d097 100644
--- a/drivers/gpio/gpiolib-of.c
+++ b/drivers/gpio/gpiolib-of.c
@@ -43,22 +43,25 @@ enum of_gpio_flags {
/**
* of_gpio_named_count() - Count GPIOs for a device
* @np: device node to count GPIOs for
- * @propname: property name containing gpio specifier(s)
+ * @propname: property name containing GPIO specifier(s)
*
* The function returns the count of GPIOs specified for a node.
- * Note that the empty GPIO specifiers count too. Returns either
- * Number of gpios defined in property,
- * -EINVAL for an incorrectly formed gpios property, or
- * -ENOENT for a missing gpios property
+ * NOTE: The empty GPIO specifiers count too.
*
- * Example:
- * gpios = <0
- * &gpio1 1 2
- * 0
- * &gpio2 3 4>;
+ * Returns:
+ * Either number of GPIOs defined in the property, or
+ * * -EINVAL for an incorrectly formed "gpios" property, or
+ * * -ENOENT for a missing "gpios" property.
+ *
+ * Example::
+ *
+ * gpios = <0
+ * &gpio1 1 2
+ * 0
+ * &gpio2 3 4>;
*
* The above example defines four GPIOs, two of which are not specified.
- * This function will return '4'
+ * This function will return '4'.
*/
static int of_gpio_named_count(const struct device_node *np,
const char *propname)
@@ -77,6 +80,11 @@ static int of_gpio_named_count(const struct device_node *np,
* "gpios" for the chip select lines. If we detect this, we redirect
* the counting of "cs-gpios" to count "gpios" transparent to the
* driver.
+ *
+ * Returns:
+ * Either number of GPIOs defined in the property, or
+ * * -EINVAL for an incorrectly formed "gpios" property, or
+ * * -ENOENT for a missing "gpios" property.
*/
static int of_gpio_spi_cs_get_count(const struct device_node *np,
const char *con_id)
@@ -151,7 +159,7 @@ static struct gpio_desc *of_xlate_and_get_gpiod_flags(struct gpio_chip *chip,
}

/*
- * Overrides stated polarity of a gpio line and warns when there is a
+ * Overrides stated polarity of a GPIO line and warns when there is a
* discrepancy.
*/
static void of_gpio_quirk_polarity(const struct device_node *np,
@@ -174,7 +182,7 @@ static void of_gpio_quirk_polarity(const struct device_node *np,

/*
* This quirk does static polarity overrides in cases where existing
- * DTS specified incorrect polarity.
+ * device tree specified incorrect polarity.
*/
static void of_gpio_try_fixup_polarity(const struct device_node *np,
const char *propname,
@@ -275,7 +283,7 @@ static void of_gpio_set_polarity_by_property(const struct device_node *np,
#if IS_ENABLED(CONFIG_MMC_ATMELMCI)
/*
* The Atmel HSMCI has compatible property in the parent node and
- * gpio property in a child node
+ * GPIO property in a child node.
*/
if (of_device_is_compatible(np->parent, "atmel,hsmci")) {
np_compat = np->parent;
@@ -361,11 +369,12 @@ static void of_gpio_flags_quirks(const struct device_node *np,
/**
* of_get_named_gpiod_flags() - Get a GPIO descriptor and flags for GPIO API
* @np: device node to get GPIO from
- * @propname: property name containing gpio specifier(s)
+ * @propname: property name containing GPIO specifier(s)
* @index: index of the GPIO
* @flags: a flags pointer to fill in
*
- * Returns GPIO descriptor to use with Linux GPIO API, or one of the errno
+ * Returns:
+ * GPIO descriptor to use with Linux GPIO API, or one of the errno
* value on the error condition. If @flags is not NULL the function also fills
* in flags for the GPIO.
*/
@@ -412,12 +421,13 @@ static struct gpio_desc *of_get_named_gpiod_flags(const struct device_node *np,
/**
* of_get_named_gpio() - Get a GPIO number to use with GPIO API
* @np: device node to get GPIO from
- * @propname: Name of property containing gpio specifier(s)
+ * @propname: Name of property containing GPIO specifier(s)
* @index: index of the GPIO
*
* **DEPRECATED** This function is deprecated and must not be used in new code.
*
- * Returns GPIO number to use with Linux generic GPIO API, or one of the errno
+ * Returns:
+ * GPIO number to use with Linux generic GPIO API, or one of the errno
* value on the error condition.
*/
int of_get_named_gpio(const struct device_node *np, const char *propname,
@@ -475,7 +485,7 @@ static struct gpio_desc *of_find_gpio_rename(struct device_node *np,
/*
* Compatible string can be set to NULL in case where
* matching to a particular compatible is not practical,
- * but it should only be done for gpio names that have
+ * but it should only be done for GPIO names that have
* vendor prefix to reduce risk of false positives.
* Addition of such entries is strongly discouraged.
*/
@@ -587,7 +597,7 @@ static struct gpio_desc *of_find_gpio_rename(struct device_node *np,
legacy_id = gpios[i].legacy_id ?: gpios[i].con_id;
desc = of_get_named_gpiod_flags(np, legacy_id, idx, of_flags);
if (!gpiod_not_found(desc)) {
- pr_info("%s uses legacy gpio name '%s' instead of '%s-gpios'\n",
+ pr_info("%s uses legacy GPIO name '%s' instead of '%s-gpios'\n",
of_node_full_name(np), legacy_id, con_id);
return desc;
}
@@ -622,7 +632,7 @@ static struct gpio_desc *of_find_mt2701_gpio(struct device_node *np,

desc = of_get_named_gpiod_flags(np, legacy_id, 0, of_flags);
if (!gpiod_not_found(desc))
- pr_info("%s is using legacy gpio name '%s' instead of '%s-gpios'\n",
+ pr_info("%s is using legacy GPIO name '%s' instead of '%s-gpios'\n",
of_node_full_name(np), legacy_id, con_id);

return desc;
@@ -654,7 +664,6 @@ static struct gpio_desc *of_find_trigger_gpio(struct device_node *np,
return desc;
}

-
typedef struct gpio_desc *(*of_find_gpio_quirk)(struct device_node *np,
const char *con_id,
unsigned int idx,
@@ -708,11 +717,11 @@ struct gpio_desc *of_find_gpio(struct device_node *np, const char *con_id,
* @chip: GPIO chip whose hog is parsed
* @idx: Index of the GPIO to parse
* @name: GPIO line name
- * @lflags: bitmask of gpio_lookup_flags GPIO_* values - returned from
- * of_find_gpio() or of_parse_own_gpio()
+ * @lflags: bitmask of gpio_lookup_flags GPIO_* values - returned from *_find_gpio()
* @dflags: gpiod_flags - optional GPIO initialization flags
*
- * Returns GPIO descriptor to use with Linux GPIO API, or one of the errno
+ * Returns:
+ * GPIO descriptor to use with Linux GPIO API, or one of the errno
* value on the error condition.
*/
static struct gpio_desc *of_parse_own_gpio(struct device_node *np,
@@ -777,10 +786,11 @@ static struct gpio_desc *of_parse_own_gpio(struct device_node *np,

/**
* of_gpiochip_add_hog - Add all hogs in a hog device node
- * @chip: gpio chip to act on
+ * @chip: GPIO chip to act on
* @hog: device node describing the hogs
*
- * Returns error if it fails otherwise 0 on success.
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
static int of_gpiochip_add_hog(struct gpio_chip *chip, struct device_node *hog)
{
@@ -809,12 +819,14 @@ static int of_gpiochip_add_hog(struct gpio_chip *chip, struct device_node *hog)
}

/**
- * of_gpiochip_scan_gpios - Scan gpio-controller for gpio definitions
- * @chip: gpio chip to act on
+ * of_gpiochip_scan_gpios - Scan gpio-controller for GPIO definitions
+ * @chip: GPIO chip to act on
*
- * This is only used by of_gpiochip_add to request/set GPIO initial
+ * This is only used by of_gpiochip_add() to request/set GPIO initial
* configuration.
- * It returns error if it fails otherwise 0 on success.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
static int of_gpiochip_scan_gpios(struct gpio_chip *chip)
{
@@ -840,7 +852,7 @@ static int of_gpiochip_scan_gpios(struct gpio_chip *chip)
#ifdef CONFIG_OF_DYNAMIC
/**
* of_gpiochip_remove_hog - Remove all hogs in a hog device node
- * @chip: gpio chip to act on
+ * @chip: GPIO chip to act on
* @hog: device node describing the hogs
*/
static void of_gpiochip_remove_hog(struct gpio_chip *chip,
@@ -920,13 +932,16 @@ struct notifier_block gpio_of_notifier = {

/**
* of_gpio_simple_xlate - translate gpiospec to the GPIO number and flags
- * @gc: pointer to the gpio_chip structure
+ * @gc: pointer to the struct gpio_chip
* @gpiospec: GPIO specifier as found in the device tree
* @flags: a flags pointer to fill in
*
* This is simple translation function, suitable for the most 1:1 mapped
* GPIO chips. This function performs only one sanity check: whether GPIO
- * is less than ngpios (that is specified in the gpio_chip).
+ * is less than ngpios (that is specified in the @gc).
+ *
+ * Returns:
+ * GPIO number (>= 0) on success, negative errno on failure.
*/
static int of_gpio_simple_xlate(struct gpio_chip *gc,
const struct of_phandle_args *gpiospec,
@@ -934,7 +949,7 @@ static int of_gpio_simple_xlate(struct gpio_chip *gc,
{
/*
* We're discouraging gpio_cells < 2, since that way you'll have to
- * write your own xlate function (that will have to retrieve the GPIO
+ * write your own .xlate function (that will have to retrieve the GPIO
* number and the flags from a single gpio cell -- this is possible,
* but not recommended).
*/
@@ -960,22 +975,27 @@ static int of_gpio_simple_xlate(struct gpio_chip *gc,
/**
* of_mm_gpiochip_add_data - Add memory mapped GPIO chip (bank)
* @np: device node of the GPIO chip
- * @mm_gc: pointer to the of_mm_gpio_chip allocated structure
+ * @mm_gc: pointer to the allocated struct of_mm_gpio_chip
* @data: driver data to store in the struct gpio_chip
*
- * To use this function you should allocate and fill mm_gc with:
+ * **DEPRECATED** This function is deprecated and must not be used in new code.
*
- * 1) In the gpio_chip structure:
+ * To use this function you should allocate and fill @mm_gc with:
+ *
+ * 1) In the struct gpio_chip:
* - all the callbacks
* - of_gpio_n_cells
* - of_xlate callback (optional)
*
- * 3) In the of_mm_gpio_chip structure:
+ * 3) In the struct of_mm_gpio_chip:
* - save_regs callback (optional)
*
* If succeeded, this function will map bank's memory and will
* do all necessary work for you. Then you'll able to use .regs
* to manage GPIOs from the callbacks.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int of_mm_gpiochip_add_data(struct device_node *np,
struct of_mm_gpio_chip *mm_gc,
@@ -1018,7 +1038,9 @@ EXPORT_SYMBOL_GPL(of_mm_gpiochip_add_data);

/**
* of_mm_gpiochip_remove - Remove memory mapped GPIO chip (bank)
- * @mm_gc: pointer to the of_mm_gpio_chip allocated structure
+ * @mm_gc: pointer to the allocated struct of_mm_gpio_chip
+ *
+ * **DEPRECATED** This function is deprecated and must not be used in new code.
*/
void of_mm_gpiochip_remove(struct of_mm_gpio_chip *mm_gc)
{
diff --git a/drivers/gpio/gpiolib-swnode.c b/drivers/gpio/gpiolib-swnode.c
index fa52bdb1a29a..100fc18a468c 100644
--- a/drivers/gpio/gpiolib-swnode.c
+++ b/drivers/gpio/gpiolib-swnode.c
@@ -21,7 +21,7 @@ static void swnode_format_propname(const char *con_id, char *propname,
size_t max_size)
{
/*
- * Note we do not need to try both -gpios and -gpio suffixes,
+ * NOTE: We do not need to try both -gpios and -gpio suffixes,
* as, unlike OF and ACPI, we can fix software nodes to conform
* to the proper binding.
*/
@@ -92,12 +92,12 @@ struct gpio_desc *swnode_find_gpio(struct fwnode_handle *fwnode,

/**
* swnode_gpio_count - count the GPIOs associated with a device / function
- * @fwnode: firmware node of the GPIO consumer, can be %NULL for
+ * @fwnode: firmware node of the GPIO consumer, can be NULL for
* system-global GPIOs
* @con_id: function within the GPIO consumer
*
- * Return:
- * The number of GPIOs associated with a device / function or %-ENOENT,
+ * Returns:
+ * The number of GPIOs associated with a device / function or -ENOENT,
* if no GPIO has been assigned to the requested function.
*/
int swnode_gpio_count(const struct fwnode_handle *fwnode, const char *con_id)
diff --git a/drivers/gpio/gpiolib-sysfs.c b/drivers/gpio/gpiolib-sysfs.c
index 26202586fd39..94f75ebca32f 100644
--- a/drivers/gpio/gpiolib-sysfs.c
+++ b/drivers/gpio/gpiolib-sysfs.c
@@ -44,8 +44,8 @@ struct gpiod_data {
};

/*
- * Lock to serialise gpiod export and unexport, and prevent re-export of
- * gpiod whose chip is being unregistered.
+ * Lock to serialise GPIO export and unexport, and prevent re-export of
+ * GPIO whose chip is being unregistered.
*/
static DEFINE_MUTEX(sysfs_lock);

@@ -193,12 +193,12 @@ static int gpio_sysfs_request_irq(struct device *dev, unsigned char flags)
IRQF_TRIGGER_FALLING : IRQF_TRIGGER_RISING;

/*
- * FIXME: This should be done in the irq_request_resources callback
- * when the irq is requested, but a few drivers currently fail
- * to do so.
+ * FIXME: This should be done in the .irq_request_resources callback
+ * when the IRQ is requested, but a few drivers currently fail
+ * to do so.
*
- * Remove this redundant call (along with the corresponding
- * unlock) when those drivers have been fixed.
+ * Remove this redundant call (along with the corresponding
+ * unlock) when those drivers have been fixed.
*/
ret = gpiochip_lock_as_irq(guard.gc, gpio_chip_hwgpio(desc));
if (ret < 0)
@@ -222,7 +222,7 @@ static int gpio_sysfs_request_irq(struct device *dev, unsigned char flags)
}

/*
- * Caller holds gpiod-data mutex (unless called after class-device
+ * Caller holds gpiod_data mutex (unless called after class-device
* deregistration).
*/
static void gpio_sysfs_free_irq(struct device *dev)
@@ -299,7 +299,7 @@ static ssize_t edge_store(struct device *dev,
}
static DEVICE_ATTR_RW(edge);

-/* Caller holds gpiod-data mutex. */
+/* Caller holds gpiod_data mutex. */
static int gpio_sysfs_set_active_low(struct device *dev, int value)
{
struct gpiod_data *data = dev_get_drvdata(dev);
@@ -477,7 +477,8 @@ static ssize_t export_store(const struct class *class,
return -EINVAL;
}

- /* No extra locking here; FLAG_SYSFS just signifies that the
+ /*
+ * No extra locking here; FLAG_SYSFS just signifies that the
* request and export were done by on behalf of userspace, so
* they may be undone on its behalf too.
*/
@@ -526,7 +527,8 @@ static ssize_t unexport_store(const struct class *class,

status = -EINVAL;

- /* No extra locking here; FLAG_SYSFS just signifies that the
+ /*
+ * No extra locking here; FLAG_SYSFS just signifies that the
* request and export were done by on behalf of userspace, so
* they may be undone on its behalf too.
*/
@@ -568,7 +570,8 @@ static struct class gpio_class = {
* will see "direction" sysfs attribute which may be used to change
* the gpio's direction. A "value" attribute will always be provided.
*
- * Returns zero on success, else an error.
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_export(struct gpio_desc *desc, bool direction_may_change)
{
@@ -667,7 +670,8 @@ static int match_export(struct device *dev, const void *desc)
* Set up a symlink from /sys/.../dev/name to /sys/class/gpio/gpioN
* node. Caller is responsible for unlinking.
*
- * Returns zero on success, else an error.
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_export_link(struct device *dev, const char *name,
struct gpio_desc *desc)
@@ -723,7 +727,7 @@ void gpiod_unexport(struct gpio_desc *desc)
device_unregister(dev);

/*
- * Release irq after deregistration to prevent race with edge_store.
+ * Release IRQ after deregistration to prevent race with edge_store.
*/
if (data->irq_flags)
gpio_sysfs_free_irq(dev);
@@ -747,7 +751,7 @@ int gpiochip_sysfs_register(struct gpio_device *gdev)
struct device *dev;

/*
- * Many systems add gpio chips for SOC support very early,
+ * Many systems add GPIO chips for SoC support very early,
* before driver model support is available. In those cases we
* register later, in gpiolib_sysfs_init() ... here we just
* verify that _some_ field of gpio_class got initialized.
@@ -795,7 +799,7 @@ void gpiochip_sysfs_unregister(struct gpio_device *gdev)

device_unregister(gdev->mockdev);

- /* prevent further gpiod exports */
+ /* prevent further GPIO exports */
gdev->mockdev = NULL;
}

@@ -805,7 +809,7 @@ void gpiochip_sysfs_unregister(struct gpio_device *gdev)
if (!chip)
return;

- /* unregister gpiod class devices owned by sysfs */
+ /* unregister GPIO class devices owned by sysfs */
for_each_gpio_desc_with_flag(chip, desc, FLAG_SYSFS) {
gpiod_unexport(desc);
gpiod_free(desc);
@@ -840,7 +844,8 @@ static int __init gpiolib_sysfs_init(void)
if (status < 0)
return status;

- /* Scan and register the gpio_chips which registered very
+ /*
+ * Scan and register the gpio_chips which registered very
* early (e.g. before the class_register above was called).
*
* We run before arch_initcall() so chip->dev nodes can have
diff --git a/drivers/gpio/gpiolib.c b/drivers/gpio/gpiolib.c
index f749ece2d3cd..29c9374f8843 100644
--- a/drivers/gpio/gpiolib.c
+++ b/drivers/gpio/gpiolib.c
@@ -41,10 +41,11 @@
#define CREATE_TRACE_POINTS
#include <trace/events/gpio.h>

-/* Implementation infrastructure for GPIO interfaces.
+/*
+ * Implementation infrastructure for GPIO interfaces.
*
* The GPIO programming interface allows for inlining speed-critical
- * get/set operations for common cases, so that access to SOC-integrated
+ * get/set operations for common cases, so that access to SoC-integrated
* GPIOs can sometimes cost only an instruction or two per bit.
*/

@@ -72,7 +73,7 @@ static const struct bus_type gpio_bus_type = {
};

/*
- * Number of GPIOs to use for the fast path in set array
+ * Number of GPIOs to use for the fast path in set array.
*/
#define FASTPATH_NGPIO CONFIG_GPIOLIB_FASTPATH_LIMIT

@@ -134,7 +135,7 @@ static int desc_set_label(struct gpio_desc *desc, const char *label)
* @gpio: global GPIO number
*
* Returns:
- * The GPIO descriptor associated with the given GPIO, or %NULL if no GPIO
+ * The GPIO descriptor associated with the given GPIO, or NULL if no GPIO
* with the given number exists in the system.
*/
struct gpio_desc *gpio_to_desc(unsigned gpio)
@@ -169,8 +170,8 @@ EXPORT_SYMBOL_GPL(gpiochip_get_desc);
* @hwnum: hardware number of the GPIO for this chip
*
* Returns:
- * A pointer to the GPIO descriptor or %EINVAL if no GPIO exists in the given
- * chip for the specified hardware number or %ENODEV if the underlying chip
+ * A pointer to the GPIO descriptor or -EINVAL if no GPIO exists in the given
+ * chip for the specified hardware number or -ENODEV if the underlying chip
* already vanished.
*
* The reference count of struct gpio_device is *NOT* increased like when the
@@ -204,7 +205,6 @@ int desc_to_gpio(const struct gpio_desc *desc)
}
EXPORT_SYMBOL_GPL(desc_to_gpio);

-
/**
* gpiod_to_chip - Return the GPIO chip to which a GPIO descriptor belongs
* @desc: descriptor to return the chip of
@@ -213,6 +213,9 @@ EXPORT_SYMBOL_GPL(desc_to_gpio);
* This function is unsafe and should not be used. Using the chip address
* without taking the SRCU read lock may result in dereferencing a dangling
* pointer.
+ *
+ * Returns:
+ * Address of the GPIO chip backing this device.
*/
struct gpio_chip *gpiod_to_chip(const struct gpio_desc *desc)
{
@@ -272,7 +275,7 @@ const char *gpio_device_get_label(struct gpio_device *gdev)
EXPORT_SYMBOL(gpio_device_get_label);

/**
- * gpio_device_get_chip() - Get the gpio_chip implementation of this GPIO device
+ * gpio_device_get_chip() - Get the GPIO chip implementation of this GPIO device
* @gdev: GPIO device
*
* Returns:
@@ -325,7 +328,8 @@ static int gpiochip_find_base_unlocked(u16 ngpio)
* gpiod_get_direction - return the current direction of a GPIO
* @desc: GPIO to get the direction of
*
- * Returns 0 for output, 1 for input, or an error code in case of error.
+ * Returns:
+ * 0 for output, 1 for input, or an error code in case of error.
*
* This function may sleep if gpiod_cansleep() is true.
*/
@@ -380,10 +384,10 @@ EXPORT_SYMBOL_GPL(gpiod_get_direction);

/*
* Add a new chip to the global chips list, keeping the list of chips sorted
- * by range(means [base, base + ngpio - 1]) order.
+ * by range (means [base, base + ngpio - 1]) order.
*
- * Return -EBUSY if the new chip overlaps with some other chip's integer
- * space.
+ * Returns:
+ * -EBUSY if the new chip overlaps with some other chip's integer space.
*/
static int gpiodev_add_to_list_unlocked(struct gpio_device *gdev)
{
@@ -430,8 +434,8 @@ static int gpiodev_add_to_list_unlocked(struct gpio_device *gdev)
}

/*
- * Convert a GPIO name to its descriptor
- * Note that there is no guarantee that GPIO names are globally unique!
+ * Convert a GPIO name to its descriptor.
+ * NOTE: There is no guarantee that GPIO names are globally unique!
* Hence this function will return, if it exists, a reference to the first GPIO
* line found that matches the given name.
*/
@@ -467,7 +471,7 @@ static struct gpio_desc *gpio_name_to_desc(const char * const name)
* Take the names from gc->names and assign them to their GPIO descriptors.
* Warn if a name is already used for a GPIO line on a different GPIO chip.
*
- * Note that:
+ * NOTE:
* 1. Non-unique names are still accepted,
* 2. Name collisions within the same GPIO chip are not reported.
*/
@@ -517,11 +521,11 @@ static int gpiochip_set_names(struct gpio_chip *chip)

/*
* When offset is set in the driver side we assume the driver internally
- * is using more than one gpiochip per the same device. We have to stop
+ * is using more than one GPIO chip per the same device. We have to stop
* setting friendly names if the specified ones with 'gpio-line-names'
* are less than the offset in the device itself. This means all the
* lines are not present for every single pin within all the internal
- * gpiochips.
+ * GPIO chips.
*/
if (count <= chip->offset) {
dev_warn(dev, "gpio-line-names too short (length %d), cannot map names for the gpiochip at offset %u\n",
@@ -542,8 +546,8 @@ static int gpiochip_set_names(struct gpio_chip *chip)
}

/*
- * When more that one gpiochip per device is used, 'count' can
- * contain at most number gpiochips x chip->ngpio. We have to
+ * When more that one GPIO chip per device is used, 'count' can
+ * contain at most number GPIO chips x chip->ngpio. We have to
* correctly distribute all defined lines taking into account
* chip->offset as starting point from where we will assign
* the names to pins from the 'names' array. Since property
@@ -1096,10 +1100,10 @@ int gpiochip_add_data_with_key(struct gpio_chip *gc, void *data,
EXPORT_SYMBOL_GPL(gpiochip_add_data_with_key);

/**
- * gpiochip_remove() - unregister a gpio_chip
+ * gpiochip_remove() - unregister a GPIO chip
* @gc: the chip to unregister
*
- * A gpio_chip with any GPIOs still requested may not be removed.
+ * A GPIO chip with any GPIOs still requested may not be removed.
*/
void gpiochip_remove(struct gpio_chip *gc)
{
@@ -1128,7 +1132,7 @@ void gpiochip_remove(struct gpio_chip *gc)
gpiochip_set_data(gc, NULL);

/*
- * The gpiochip side puts its use of the device to rest here:
+ * The GPIO chip side puts its use of the device to rest here:
* if there are no userspace clients, the chardev and device will
* be removed, else it will be dangling until the last user is
* gone.
@@ -1141,7 +1145,7 @@ EXPORT_SYMBOL_GPL(gpiochip_remove);
/**
* gpio_device_find() - find a specific GPIO device
* @data: data to pass to match function
- * @match: Callback function to check gpio_chip
+ * @match: Callback function to check struct gpio_chip
*
* Returns:
* New reference to struct gpio_device.
@@ -1152,9 +1156,9 @@ EXPORT_SYMBOL_GPL(gpiochip_remove);
* returns non-zero, this function will return to the caller and not iterate
* over any more gpio_devices.
*
- * The callback takes the GPIO chip structure as argument. During the execution
- * of the callback function the chip is protected from being freed. TODO: This
- * actually has yet to be implemented.
+ * The callback takes the struct gpio_chip as argument. During the execution
+ * of the callback function the chip is protected from being freed.
+ * TODO: this actually has yet to be implemented.
*
* If the function returns non-NULL, the returned reference must be freed by
* the caller using gpio_device_put().
@@ -1273,7 +1277,7 @@ EXPORT_SYMBOL_GPL(gpio_device_to_device);
#ifdef CONFIG_GPIOLIB_IRQCHIP

/*
- * The following is irqchip helper code for gpiochips.
+ * The following is irqchip helper code for GPIO chips.
*/

static int gpiochip_irqchip_init_hw(struct gpio_chip *gc)
@@ -1321,9 +1325,8 @@ static bool gpiochip_irqchip_irq_valid(const struct gpio_chip *gc,
#ifdef CONFIG_IRQ_DOMAIN_HIERARCHY

/**
- * gpiochip_set_hierarchical_irqchip() - connects a hierarchical irqchip
- * to a gpiochip
- * @gc: the gpiochip to set the irqchip hierarchical handler to
+ * gpiochip_set_hierarchical_irqchip() - connects a hierarchical irqchip to a GPIO chip
+ * @gc: the GPIO chip to set the irqchip hierarchical handler to
* @irqchip: the irqchip to handle this level of the hierarchy, the interrupt
* will then percolate up to the parent
*/
@@ -1336,7 +1339,7 @@ static void gpiochip_set_hierarchical_irqchip(struct gpio_chip *gc,

/*
* This is for legacy and boardfile "irqchip" fwnodes: allocate
- * irqs upfront instead of dynamically since we don't have the
+ * IRQs upfront instead of dynamically since we don't have the
* dynamic type of allocation that hardware description languages
* provide. Once all GPIO drivers using board files are gone from
* the kernel we can delete this code, but for a transitional period
@@ -1396,9 +1399,8 @@ static int gpiochip_hierarchy_irq_domain_translate(struct irq_domain *d,
unsigned int *type)
{
/* We support standard DT translation */
- if (is_of_node(fwspec->fwnode) && fwspec->param_count == 2) {
+ if (is_of_node(fwspec->fwnode) && fwspec->param_count == 2)
return irq_domain_translate_twocell(d, fwspec, hwirq, type);
- }

/* This is for board files and others not using DT */
if (is_fwnode_irqchip(fwspec->fwnode)) {
@@ -1449,7 +1451,7 @@ static int gpiochip_hierarchy_irq_domain_alloc(struct irq_domain *d,
chip_dbg(gc, "found parent hwirq %u\n", parent_hwirq);

/*
- * We set handle_bad_irq because the .set_type() should
+ * Driver has to set handle_bad_irq() because the .set_type() should
* always be invoked and set the right type of handler.
*/
irq_domain_set_info(d,
@@ -1473,7 +1475,7 @@ static int gpiochip_hierarchy_irq_domain_alloc(struct irq_domain *d,
ret = irq_domain_alloc_irqs_parent(d, irq, 1, &gpio_parent_fwspec);
/*
* If the parent irqdomain is msi, the interrupts have already
- * been allocated, so the EEXIST is good.
+ * been allocated, so the -EEXIST is good.
*/
if (irq_domain_is_msi(d->parent) && (ret == -EEXIST))
ret = 0;
@@ -1493,13 +1495,16 @@ static unsigned int gpiochip_child_offset_to_irq_noop(struct gpio_chip *gc,

/**
* gpiochip_irq_domain_activate() - Lock a GPIO to be used as an IRQ
- * @domain: The IRQ domain used by this IRQ chip
+ * @domain: The IRQ domain used by this irqchip
* @data: Outermost irq_data associated with the IRQ
* @reserve: If set, only reserve an interrupt vector instead of assigning one
*
* This function is a wrapper that calls gpiochip_lock_as_irq() and is to be
* used as the activate function for the &struct irq_domain_ops. The host_data
* for the IRQ domain must be the &struct gpio_chip.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
static int gpiochip_irq_domain_activate(struct irq_domain *domain,
struct irq_data *data, bool reserve)
@@ -1512,7 +1517,7 @@ static int gpiochip_irq_domain_activate(struct irq_domain *domain,

/**
* gpiochip_irq_domain_deactivate() - Unlock a GPIO used as an IRQ
- * @domain: The IRQ domain used by this IRQ chip
+ * @domain: The IRQ domain used by this irqchip
* @data: Outermost irq_data associated with the IRQ
*
* This function is a wrapper that will call gpiochip_unlock_as_irq() and is to
@@ -1638,12 +1643,15 @@ static bool gpiochip_hierarchy_is_hierarchical(struct gpio_chip *gc)
/**
* gpiochip_irq_map() - maps an IRQ into a GPIO irqchip
* @d: the irqdomain used by this irqchip
- * @irq: the global irq number used by this GPIO irqchip irq
- * @hwirq: the local IRQ/GPIO line offset on this gpiochip
+ * @irq: the global IRQ number used by this GPIO irqchip IRQ
+ * @hwirq: the local IRQ/GPIO line offset on this GPIO chip
*
* This function will set up the mapping for a certain IRQ line on a
- * gpiochip by assigning the gpiochip as chip data, and using the irqchip
- * stored inside the gpiochip.
+ * GPIO chip by assigning the struct gpio_chip as chip data, and using the irqchip
+ * stored inside the struct gpio_chip.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
static int gpiochip_irq_map(struct irq_domain *d, unsigned int irq,
irq_hw_number_t hwirq)
@@ -1656,7 +1664,7 @@ static int gpiochip_irq_map(struct irq_domain *d, unsigned int irq,

irq_set_chip_data(irq, gc);
/*
- * This lock class tells lockdep that GPIO irqs are in a different
+ * This lock class tells lockdep that GPIO IRQs are in a different
* category than their parents, so it won't report false recursion.
*/
irq_set_lockdep_class(irq, gc->irq.lock_key, gc->irq.request_key);
@@ -1722,7 +1730,7 @@ static int gpiochip_to_irq(struct gpio_chip *gc, unsigned int offset)
/*
* Avoid race condition with other code, which tries to lookup
* an IRQ before the irqchip has been properly registered,
- * i.e. while gpiochip is still being brought up.
+ * i.e. while GPIO chip is still being brought up.
*/
if (!gc->irq.initialized)
return -EPROBE_DEFER;
@@ -1874,10 +1882,13 @@ static int gpiochip_irqchip_add_allocated_domain(struct gpio_chip *gc,
}

/**
- * gpiochip_add_irqchip() - adds an IRQ chip to a GPIO chip
- * @gc: the GPIO chip to add the IRQ chip to
+ * gpiochip_add_irqchip() - adds an irqchip to a GPIO chip
+ * @gc: the GPIO chip to add the irqchip to
* @lock_key: lockdep class for IRQ lock
* @request_key: lockdep class for IRQ request
+ *
+ * Returns:
+ * 0 on success, or a negative error-code on failure.
*/
static int gpiochip_add_irqchip(struct gpio_chip *gc,
struct lock_class_key *lock_key,
@@ -1914,11 +1925,10 @@ static int gpiochip_add_irqchip(struct gpio_chip *gc,
gc->irq.request_key = request_key;

/* If a parent irqdomain is provided, let's build a hierarchy */
- if (gpiochip_hierarchy_is_hierarchical(gc)) {
+ if (gpiochip_hierarchy_is_hierarchical(gc))
domain = gpiochip_hierarchy_create_domain(gc);
- } else {
+ else
domain = gpiochip_simple_create_domain(gc);
- }
if (IS_ERR(domain))
return PTR_ERR(domain);

@@ -1932,8 +1942,8 @@ static int gpiochip_add_irqchip(struct gpio_chip *gc,
data = gc->irq.parent_handler_data ?: gc;

/*
- * The parent IRQ chip is already using the chip_data
- * for this IRQ chip, so our callbacks simply use the
+ * The parent irqchip is already using the chip_data
+ * for this irqchip, so our callbacks simply use the
* handler_data.
*/
irq_set_chained_handler_and_data(gc->irq.parents[i],
@@ -1954,10 +1964,10 @@ static int gpiochip_add_irqchip(struct gpio_chip *gc,
}

/**
- * gpiochip_irqchip_remove() - removes an irqchip added to a gpiochip
- * @gc: the gpiochip to remove the irqchip from
+ * gpiochip_irqchip_remove() - removes an irqchip added to a struct gpio_chip
+ * @gc: the struct gpio_chip to remove the irqchip from
*
- * This is called only from gpiochip_remove()
+ * This is called only from gpiochip_remove().
*/
static void gpiochip_irqchip_remove(struct gpio_chip *gc)
{
@@ -2008,11 +2018,14 @@ static void gpiochip_irqchip_remove(struct gpio_chip *gc)
}

/**
- * gpiochip_irqchip_add_domain() - adds an irqdomain to a gpiochip
- * @gc: the gpiochip to add the irqchip to
- * @domain: the irqdomain to add to the gpiochip
+ * gpiochip_irqchip_add_domain() - adds an irqdomain to a struct gpio_chip
+ * @gc: the struct gpio_chip to add the irqchip to
+ * @domain: the irqdomain to add to the struct gpio_chip
*
- * This function adds an IRQ domain to the gpiochip.
+ * This function adds an IRQ domain to the struct gpio_chip.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiochip_irqchip_add_domain(struct gpio_chip *gc,
struct irq_domain *domain)
@@ -2046,9 +2059,12 @@ static inline void gpiochip_irqchip_free_valid_mask(struct gpio_chip *gc)
#endif /* CONFIG_GPIOLIB_IRQCHIP */

/**
- * gpiochip_generic_request() - request the gpio function for a pin
- * @gc: the gpiochip owning the GPIO
+ * gpiochip_generic_request() - request the GPIO function for a pin
+ * @gc: the GPIO chip owning the GPIO
* @offset: the offset of the GPIO to request for GPIO function
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiochip_generic_request(struct gpio_chip *gc, unsigned int offset)
{
@@ -2062,8 +2078,8 @@ int gpiochip_generic_request(struct gpio_chip *gc, unsigned int offset)
EXPORT_SYMBOL_GPL(gpiochip_generic_request);

/**
- * gpiochip_generic_free() - free the gpio function from a pin
- * @gc: the gpiochip to request the gpio function for
+ * gpiochip_generic_free() - free the GPIO function from a pin
+ * @gc: the GPIO chip to request the GPIO function for
* @offset: the offset of the GPIO to free from GPIO function
*/
void gpiochip_generic_free(struct gpio_chip *gc, unsigned int offset)
@@ -2079,9 +2095,12 @@ EXPORT_SYMBOL_GPL(gpiochip_generic_free);

/**
* gpiochip_generic_config() - apply configuration for a pin
- * @gc: the gpiochip owning the GPIO
+ * @gc: the GPIO chip owning the GPIO
* @offset: the offset of the GPIO to apply the configuration
* @config: the configuration to be applied
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiochip_generic_config(struct gpio_chip *gc, unsigned int offset,
unsigned long config)
@@ -2099,15 +2118,18 @@ EXPORT_SYMBOL_GPL(gpiochip_generic_config);

/**
* gpiochip_add_pingroup_range() - add a range for GPIO <-> pin mapping
- * @gc: the gpiochip to add the range for
+ * @gc: the GPIO chip to add the range for
* @pctldev: the pin controller to map to
- * @gpio_offset: the start offset in the current gpio_chip number space
+ * @gpio_offset: the start offset in the current @gc number space
* @pin_group: name of the pin group inside the pin controller
*
* Calling this function directly from a DeviceTree-supported
* pinctrl driver is DEPRECATED. Please see Section 2.1 of
* Documentation/devicetree/bindings/gpio/gpio.txt on how to
- * bind pinctrl and gpio drivers via the "gpio-ranges" property.
+ * bind pinctrl and GPIO drivers via the "gpio-ranges" property.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiochip_add_pingroup_range(struct gpio_chip *gc,
struct pinctrl_dev *pctldev,
@@ -2152,20 +2174,20 @@ EXPORT_SYMBOL_GPL(gpiochip_add_pingroup_range);

/**
* gpiochip_add_pin_range() - add a range for GPIO <-> pin mapping
- * @gc: the gpiochip to add the range for
+ * @gc: the GPIO chip to add the range for
* @pinctl_name: the dev_name() of the pin controller to map to
- * @gpio_offset: the start offset in the current gpio_chip number space
+ * @gpio_offset: the start offset in the current @gc number space
* @pin_offset: the start offset in the pin controller number space
* @npins: the number of pins from the offset of each pin space (GPIO and
* pin controller) to accumulate in this range
*
- * Returns:
- * 0 on success, or a negative error-code on failure.
- *
* Calling this function directly from a DeviceTree-supported
* pinctrl driver is DEPRECATED. Please see Section 2.1 of
* Documentation/devicetree/bindings/gpio/gpio.txt on how to
- * bind pinctrl and gpio drivers via the "gpio-ranges" property.
+ * bind pinctrl and GPIO drivers via the "gpio-ranges" property.
+ *
+ * Returns:
+ * 0 on success, or a negative error-code on failure.
*/
int gpiochip_add_pin_range(struct gpio_chip *gc, const char *pinctl_name,
unsigned int gpio_offset, unsigned int pin_offset,
@@ -2227,7 +2249,8 @@ EXPORT_SYMBOL_GPL(gpiochip_remove_pin_ranges);

#endif /* CONFIG_PINCTRL */

-/* These "optional" allocation calls help prevent drivers from stomping
+/*
+ * These "optional" allocation calls help prevent drivers from stomping
* on each other, and help provide better diagnostics in debugfs.
* They're called even less than the "set direction" calls.
*/
@@ -2243,10 +2266,11 @@ static int gpiod_request_commit(struct gpio_desc *desc, const char *label)
if (test_and_set_bit(FLAG_REQUESTED, &desc->flags))
return -EBUSY;

- /* NOTE: gpio_request() can be called in early boot,
- * before IRQs are enabled, for non-sleeping (SOC) GPIOs.
+ /*
+ * NOTE:
+ * gpio_request() can be called in early boot, before IRQs are enabled,
+ * for non-sleeping (SoC) GPIOs.
*/
-
if (guard.gc->request) {
offset = gpio_chip_hwgpio(desc);
if (gpiochip_line_is_valid(guard.gc, offset))
@@ -2373,7 +2397,7 @@ void gpiod_free(struct gpio_desc *desc)
* Returns:
* Pointer to a copy of the consumer label if the line is requested or NULL
* if it's not. If a valid pointer was returned, it must be freed using
- * kfree(). In case of a memory allocation error, the function returns %ENOMEM.
+ * kfree(). In case of a memory allocation error, the function returns -ENOMEM.
*
* Must not be called from atomic context.
*/
@@ -2475,10 +2499,9 @@ EXPORT_SYMBOL_GPL(gpiochip_free_own_desc);
*
* As a rule these aren't called more than once (except for drivers
* using the open-drain emulation idiom) so these are natural places
- * to accumulate extra debugging checks. Note that we can't (yet)
+ * to accumulate extra debugging checks. NOTE: We can't (yet)
* rely on gpio_request() having been called beforehand.
*/
-
static int gpio_do_set_config(struct gpio_chip *gc, unsigned int offset,
unsigned long config)
{
@@ -2569,7 +2592,8 @@ static int gpio_set_bias(struct gpio_desc *desc)
* The function calls the certain GPIO driver to set debounce timeout
* in the hardware.
*
- * Returns 0 on success, or negative error code otherwise.
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpio_set_debounce_timeout(struct gpio_desc *desc, unsigned int debounce)
{
@@ -2585,7 +2609,8 @@ int gpio_set_debounce_timeout(struct gpio_desc *desc, unsigned int debounce)
* Set the direction of the passed GPIO to input, such as gpiod_get_value() can
* be called safely on it.
*
- * Return 0 in case of success, else an error code.
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_direction_input(struct gpio_desc *desc)
{
@@ -2646,7 +2671,7 @@ static int gpiod_direction_output_raw_commit(struct gpio_desc *desc, int value)
return -ENODEV;

/*
- * It's OK not to specify .direction_output() if the gpiochip is
+ * It's OK not to specify .direction_output() if the GPIO chip is
* output-only, but if there is then not even a .set() operation it
* is pretty tricky to drive the output line.
*/
@@ -2692,7 +2717,8 @@ static int gpiod_direction_output_raw_commit(struct gpio_desc *desc, int value)
* be called safely on it. The initial value of the output must be specified
* as raw value on the physical line without regard for the ACTIVE_LOW status.
*
- * Return 0 in case of success, else an error code.
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_direction_output_raw(struct gpio_desc *desc, int value)
{
@@ -2711,7 +2737,8 @@ EXPORT_SYMBOL_GPL(gpiod_direction_output_raw);
* as the logical value of the GPIO, i.e. taking its ACTIVE_LOW status into
* account.
*
- * Return 0 in case of success, else an error code.
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_direction_output(struct gpio_desc *desc, int value)
{
@@ -2784,7 +2811,8 @@ EXPORT_SYMBOL_GPL(gpiod_direction_output);
* @desc: GPIO to enable.
* @flags: Flags related to GPIO edge.
*
- * Return 0 in case of success, else negative error code.
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_enable_hw_timestamp_ns(struct gpio_desc *desc, unsigned long flags)
{
@@ -2816,7 +2844,8 @@ EXPORT_SYMBOL_GPL(gpiod_enable_hw_timestamp_ns);
* @desc: GPIO to disable.
* @flags: Flags related to GPIO edge, same value as used during enable call.
*
- * Return 0 in case of success, else negative error code.
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_disable_hw_timestamp_ns(struct gpio_desc *desc, unsigned long flags)
{
@@ -2848,7 +2877,7 @@ EXPORT_SYMBOL_GPL(gpiod_disable_hw_timestamp_ns);
* @config: Same packed config format as generic pinconf
*
* Returns:
- * 0 on success, %-ENOTSUPP if the controller doesn't support setting the
+ * 0 on success, -ENOTSUPP if the controller doesn't support setting the
* configuration.
*/
int gpiod_set_config(struct gpio_desc *desc, unsigned long config)
@@ -2869,7 +2898,7 @@ EXPORT_SYMBOL_GPL(gpiod_set_config);
* @debounce: debounce time in microseconds
*
* Returns:
- * 0 on success, %-ENOTSUPP if the controller doesn't support setting the
+ * 0 on success, -ENOTSUPP if the controller doesn't support setting the
* debounce time.
*/
int gpiod_set_debounce(struct gpio_desc *desc, unsigned int debounce)
@@ -2906,9 +2935,10 @@ int gpiod_set_transitory(struct gpio_desc *desc, bool transitory)

/**
* gpiod_is_active_low - test whether a GPIO is active-low or not
- * @desc: the gpio descriptor to test
+ * @desc: the GPIO descriptor to test
*
- * Returns 1 if the GPIO is active-low, 0 otherwise.
+ * Returns:
+ * 1 if the GPIO is active-low, 0 otherwise.
*/
int gpiod_is_active_low(const struct gpio_desc *desc)
{
@@ -2919,7 +2949,7 @@ EXPORT_SYMBOL_GPL(gpiod_is_active_low);

/**
* gpiod_toggle_active_low - toggle whether a GPIO is active-low or not
- * @desc: the gpio descriptor to change
+ * @desc: the GPIO descriptor to change
*/
void gpiod_toggle_active_low(struct gpio_desc *desc)
{
@@ -2933,7 +2963,8 @@ static int gpio_chip_get_value(struct gpio_chip *gc, const struct gpio_desc *des
return gc->get ? gc->get(gc, gpio_chip_hwgpio(desc)) : -EIO;
}

-/* I/O calls are only valid after configuration completed; the relevant
+/*
+ * I/O calls are only valid after configuration completed; the relevant
* "is this a valid GPIO" error checks should already have been done.
*
* "Get" operations are often inlinable as reading a pin value register,
@@ -2947,7 +2978,7 @@ static int gpio_chip_get_value(struct gpio_chip *gc, const struct gpio_desc *des
*
* IMPORTANT!!! The hot paths -- get/set value -- assume that callers
* have requested the GPIO. That can include implicit requesting by
- * a direction setting call. Marking a gpio as requested locks its chip
+ * a direction setting call. Marking a GPIO as requested locks its chip
* in memory, guaranteeing that these table lookups need no more locking
* and that gpiochip_remove() will fail.
*
@@ -2961,7 +2992,7 @@ static int gpiod_get_raw_value_commit(const struct gpio_desc *desc)
struct gpio_chip *gc;
int value;

- /* FIXME Unable to use gpio_chip_guard due to const desc. */
+ /* FIXME: Unable to use gpio_chip_guard() due to const desc. */
gdev = desc->gdev;

guard(srcu)(&gdev->srcu);
@@ -3120,10 +3151,11 @@ int gpiod_get_array_value_complex(bool raw, bool can_sleep,
}

/**
- * gpiod_get_raw_value() - return a gpio's raw value
- * @desc: gpio whose value will be returned
+ * gpiod_get_raw_value() - return a GPIO's raw value
+ * @desc: GPIO whose value will be returned
*
- * Return the GPIO's raw value, i.e. the value of the physical line disregarding
+ * Returns:
+ * The GPIO's raw value, i.e. the value of the physical line disregarding
* its ACTIVE_LOW status, or negative errno on failure.
*
* This function can be called from contexts where we cannot sleep, and will
@@ -3139,10 +3171,11 @@ int gpiod_get_raw_value(const struct gpio_desc *desc)
EXPORT_SYMBOL_GPL(gpiod_get_raw_value);

/**
- * gpiod_get_value() - return a gpio's value
- * @desc: gpio whose value will be returned
+ * gpiod_get_value() - return a GPIO's value
+ * @desc: GPIO whose value will be returned
*
- * Return the GPIO's logical value, i.e. taking the ACTIVE_LOW status into
+ * Returns:
+ * The GPIO's logical value, i.e. taking the ACTIVE_LOW status into
* account, or negative errno on failure.
*
* This function can be called from contexts where we cannot sleep, and will
@@ -3175,11 +3208,13 @@ EXPORT_SYMBOL_GPL(gpiod_get_value);
* @value_bitmap: bitmap to store the read values
*
* Read the raw values of the GPIOs, i.e. the values of the physical lines
- * without regard for their ACTIVE_LOW status. Return 0 in case of success,
- * else an error code.
+ * without regard for their ACTIVE_LOW status.
*
* This function can be called from contexts where we cannot sleep,
* and it will complain if the GPIO chip functions potentially sleep.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_get_raw_array_value(unsigned int array_size,
struct gpio_desc **desc_array,
@@ -3202,10 +3237,13 @@ EXPORT_SYMBOL_GPL(gpiod_get_raw_array_value);
* @value_bitmap: bitmap to store the read values
*
* Read the logical values of the GPIOs, i.e. taking their ACTIVE_LOW status
- * into account. Return 0 in case of success, else an error code.
+ * into account.
*
* This function can be called from contexts where we cannot sleep,
* and it will complain if the GPIO chip functions potentially sleep.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_get_array_value(unsigned int array_size,
struct gpio_desc **desc_array,
@@ -3221,8 +3259,8 @@ int gpiod_get_array_value(unsigned int array_size,
EXPORT_SYMBOL_GPL(gpiod_get_array_value);

/*
- * gpio_set_open_drain_value_commit() - Set the open drain gpio's value.
- * @desc: gpio descriptor whose state need to be set.
+ * gpio_set_open_drain_value_commit() - Set the open drain GPIO's value.
+ * @desc: GPIO descriptor whose state need to be set.
* @value: Non-zero for setting it HIGH otherwise it will set to LOW.
*/
static void gpio_set_open_drain_value_commit(struct gpio_desc *desc, bool value)
@@ -3248,8 +3286,8 @@ static void gpio_set_open_drain_value_commit(struct gpio_desc *desc, bool value)
}

/*
- * _gpio_set_open_source_value() - Set the open source gpio's value.
- * @desc: gpio descriptor whose state need to be set.
+ * _gpio_set_open_source_value() - Set the open source GPIO's value.
+ * @desc: GPIO descriptor whose state need to be set.
* @value: Non-zero for setting it HIGH otherwise it will set to LOW.
*/
static void gpio_set_open_source_value_commit(struct gpio_desc *desc, bool value)
@@ -3421,8 +3459,8 @@ int gpiod_set_array_value_complex(bool raw, bool can_sleep,
}

/**
- * gpiod_set_raw_value() - assign a gpio's raw value
- * @desc: gpio whose value will be assigned
+ * gpiod_set_raw_value() - assign a GPIO's raw value
+ * @desc: GPIO whose value will be assigned
* @value: value to assign
*
* Set the raw value of the GPIO, i.e. the value of its physical line without
@@ -3462,8 +3500,8 @@ static void gpiod_set_value_nocheck(struct gpio_desc *desc, int value)
}

/**
- * gpiod_set_value() - assign a gpio's value
- * @desc: gpio whose value will be assigned
+ * gpiod_set_value() - assign a GPIO's value
+ * @desc: GPIO whose value will be assigned
* @value: value to assign
*
* Set the logical value of the GPIO, i.e. taking its ACTIVE_LOW,
@@ -3493,6 +3531,9 @@ EXPORT_SYMBOL_GPL(gpiod_set_value);
*
* This function can be called from contexts where we cannot sleep, and will
* complain if the GPIO chip functions potentially sleep.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_set_raw_array_value(unsigned int array_size,
struct gpio_desc **desc_array,
@@ -3518,6 +3559,9 @@ EXPORT_SYMBOL_GPL(gpiod_set_raw_array_value);
*
* This function can be called from contexts where we cannot sleep, and will
* complain if the GPIO chip functions potentially sleep.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_set_array_value(unsigned int array_size,
struct gpio_desc **desc_array,
@@ -3533,9 +3577,11 @@ int gpiod_set_array_value(unsigned int array_size,
EXPORT_SYMBOL_GPL(gpiod_set_array_value);

/**
- * gpiod_cansleep() - report whether gpio value access may sleep
- * @desc: gpio to check
+ * gpiod_cansleep() - report whether GPIO value access may sleep
+ * @desc: GPIO to check
*
+ * Returns:
+ * 0 for non-sleepable, 1 for sleepable, or an error code in case of error.
*/
int gpiod_cansleep(const struct gpio_desc *desc)
{
@@ -3546,8 +3592,11 @@ EXPORT_SYMBOL_GPL(gpiod_cansleep);

/**
* gpiod_set_consumer_name() - set the consumer name for the descriptor
- * @desc: gpio to set the consumer name on
+ * @desc: GPIO to set the consumer name on
* @name: the new consumer name
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_set_consumer_name(struct gpio_desc *desc, const char *name)
{
@@ -3559,10 +3608,10 @@ EXPORT_SYMBOL_GPL(gpiod_set_consumer_name);

/**
* gpiod_to_irq() - return the IRQ corresponding to a GPIO
- * @desc: gpio whose IRQ will be returned (already requested)
+ * @desc: GPIO whose IRQ will be returned (already requested)
*
- * Return the IRQ corresponding to the passed GPIO, or an error code in case of
- * error.
+ * Returns:
+ * The IRQ corresponding to the passed GPIO, or an error code in case of error.
*/
int gpiod_to_irq(const struct gpio_desc *desc)
{
@@ -3579,7 +3628,7 @@ int gpiod_to_irq(const struct gpio_desc *desc)
return -EINVAL;

gdev = desc->gdev;
- /* FIXME Cannot use gpio_chip_guard due to const desc. */
+ /* FIXME: Cannot use gpio_chip_guard() due to const desc. */
guard(srcu)(&gdev->srcu);
gc = srcu_dereference(gdev->chip, &gdev->srcu);
if (!gc)
@@ -3600,7 +3649,7 @@ int gpiod_to_irq(const struct gpio_desc *desc)
/*
* Avoid race condition with other code, which tries to lookup
* an IRQ before the irqchip has been properly registered,
- * i.e. while gpiochip is still being brought up.
+ * i.e. while GPIO chip is still being brought up.
*/
return -EPROBE_DEFER;
}
@@ -3616,6 +3665,9 @@ EXPORT_SYMBOL_GPL(gpiod_to_irq);
*
* This is used directly by GPIO drivers that want to lock down
* a certain GPIO line to be used for IRQs.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiochip_lock_as_irq(struct gpio_chip *gc, unsigned int offset)
{
@@ -3764,10 +3816,11 @@ bool gpiochip_line_is_persistent(struct gpio_chip *gc, unsigned int offset)
EXPORT_SYMBOL_GPL(gpiochip_line_is_persistent);

/**
- * gpiod_get_raw_value_cansleep() - return a gpio's raw value
- * @desc: gpio whose value will be returned
+ * gpiod_get_raw_value_cansleep() - return a GPIO's raw value
+ * @desc: GPIO whose value will be returned
*
- * Return the GPIO's raw value, i.e. the value of the physical line disregarding
+ * Returns:
+ * The GPIO's raw value, i.e. the value of the physical line disregarding
* its ACTIVE_LOW status, or negative errno on failure.
*
* This function is to be called from contexts that can sleep.
@@ -3781,10 +3834,11 @@ int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc)
EXPORT_SYMBOL_GPL(gpiod_get_raw_value_cansleep);

/**
- * gpiod_get_value_cansleep() - return a gpio's value
- * @desc: gpio whose value will be returned
+ * gpiod_get_value_cansleep() - return a GPIO's value
+ * @desc: GPIO whose value will be returned
*
- * Return the GPIO's logical value, i.e. taking the ACTIVE_LOW status into
+ * Returns:
+ * The GPIO's logical value, i.e. taking the ACTIVE_LOW status into
* account, or negative errno on failure.
*
* This function is to be called from contexts that can sleep.
@@ -3814,10 +3868,12 @@ EXPORT_SYMBOL_GPL(gpiod_get_value_cansleep);
* @value_bitmap: bitmap to store the read values
*
* Read the raw values of the GPIOs, i.e. the values of the physical lines
- * without regard for their ACTIVE_LOW status. Return 0 in case of success,
- * else an error code.
+ * without regard for their ACTIVE_LOW status.
*
* This function is to be called from contexts that can sleep.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_get_raw_array_value_cansleep(unsigned int array_size,
struct gpio_desc **desc_array,
@@ -3841,9 +3897,12 @@ EXPORT_SYMBOL_GPL(gpiod_get_raw_array_value_cansleep);
* @value_bitmap: bitmap to store the read values
*
* Read the logical values of the GPIOs, i.e. taking their ACTIVE_LOW status
- * into account. Return 0 in case of success, else an error code.
+ * into account.
*
* This function is to be called from contexts that can sleep.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_get_array_value_cansleep(unsigned int array_size,
struct gpio_desc **desc_array,
@@ -3860,8 +3919,8 @@ int gpiod_get_array_value_cansleep(unsigned int array_size,
EXPORT_SYMBOL_GPL(gpiod_get_array_value_cansleep);

/**
- * gpiod_set_raw_value_cansleep() - assign a gpio's raw value
- * @desc: gpio whose value will be assigned
+ * gpiod_set_raw_value_cansleep() - assign a GPIO's raw value
+ * @desc: GPIO whose value will be assigned
* @value: value to assign
*
* Set the raw value of the GPIO, i.e. the value of its physical line without
@@ -3878,8 +3937,8 @@ void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)
EXPORT_SYMBOL_GPL(gpiod_set_raw_value_cansleep);

/**
- * gpiod_set_value_cansleep() - assign a gpio's value
- * @desc: gpio whose value will be assigned
+ * gpiod_set_value_cansleep() - assign a GPIO's value
+ * @desc: GPIO whose value will be assigned
* @value: value to assign
*
* Set the logical value of the GPIO, i.e. taking its ACTIVE_LOW status into
@@ -3906,6 +3965,9 @@ EXPORT_SYMBOL_GPL(gpiod_set_value_cansleep);
* without regard for their ACTIVE_LOW status.
*
* This function is to be called from contexts that can sleep.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_set_raw_array_value_cansleep(unsigned int array_size,
struct gpio_desc **desc_array,
@@ -3948,6 +4010,9 @@ void gpiod_add_lookup_tables(struct gpiod_lookup_table **tables, size_t n)
* into account.
*
* This function is to be called from contexts that can sleep.
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_set_array_value_cansleep(unsigned int array_size,
struct gpio_desc **desc_array,
@@ -3999,7 +4064,7 @@ EXPORT_SYMBOL_GPL(gpiod_remove_lookup_table);

/**
* gpiod_add_hogs() - register a set of GPIO hogs from machine code
- * @hogs: table of gpio hog entries with a zeroed sentinel at the end
+ * @hogs: table of GPIO hog entries with a zeroed sentinel at the end
*/
void gpiod_add_hogs(struct gpiod_hog *hogs)
{
@@ -4281,9 +4346,12 @@ EXPORT_SYMBOL_GPL(fwnode_gpiod_get_index);

/**
* gpiod_count - return the number of GPIOs associated with a device / function
- * or -ENOENT if no GPIO has been assigned to the requested function
* @dev: GPIO consumer, can be NULL for system-global GPIOs
* @con_id: function within the GPIO consumer
+ *
+ * Returns:
+ * The number of GPIOs associated with a device / function or -ENOENT if no
+ * GPIO has been assigned to the requested function.
*/
int gpiod_count(struct device *dev, const char *con_id)
{
@@ -4310,7 +4378,8 @@ EXPORT_SYMBOL_GPL(gpiod_count);
* @con_id: function within the GPIO consumer
* @flags: optional GPIO initialization flags
*
- * Return the GPIO descriptor corresponding to the function con_id of device
+ * Returns:
+ * The GPIO descriptor corresponding to the function @con_id of device
* dev, -ENOENT if no GPIO has been assigned to the requested function, or
* another IS_ERR() code if an error occurred while trying to acquire the GPIO.
*/
@@ -4330,6 +4399,11 @@ EXPORT_SYMBOL_GPL(gpiod_get);
* This is equivalent to gpiod_get(), except that when no GPIO was assigned to
* the requested function it will return NULL. This is convenient for drivers
* that need to handle optional GPIOs.
+ *
+ * Returns:
+ * The GPIO descriptor corresponding to the function @con_id of device
+ * dev, NULL if no GPIO has been assigned to the requested function, or
+ * another IS_ERR() code if an error occurred while trying to acquire the GPIO.
*/
struct gpio_desc *__must_check gpiod_get_optional(struct device *dev,
const char *con_id,
@@ -4339,16 +4413,15 @@ struct gpio_desc *__must_check gpiod_get_optional(struct device *dev,
}
EXPORT_SYMBOL_GPL(gpiod_get_optional);

-
/**
* gpiod_configure_flags - helper function to configure a given GPIO
- * @desc: gpio whose value will be assigned
+ * @desc: GPIO whose value will be assigned
* @con_id: function within the GPIO consumer
- * @lflags: bitmask of gpio_lookup_flags GPIO_* values - returned from
- * of_find_gpio() or of_get_gpio_hog()
+ * @lflags: bitmask of gpio_lookup_flags GPIO_* values - returned from *_find_gpio()
* @dflags: gpiod_flags - optional GPIO initialization flags
*
- * Return 0 on success, -ENOENT if no GPIO has been assigned to the
+ * Returns:
+ * 0 on success, -ENOENT if no GPIO has been assigned to the
* requested function and/or index, or another IS_ERR() code if an error
* occurred while trying to acquire the GPIO.
*/
@@ -4423,7 +4496,8 @@ int gpiod_configure_flags(struct gpio_desc *desc, const char *con_id,
* This variant of gpiod_get() allows to access GPIOs other than the first
* defined one for functions that define several GPIOs.
*
- * Return a valid GPIO descriptor, -ENOENT if no GPIO has been assigned to the
+ * Returns:
+ * A valid GPIO descriptor, -ENOENT if no GPIO has been assigned to the
* requested function and/or index, or another IS_ERR() code if an error
* occurred while trying to acquire the GPIO.
*/
@@ -4451,6 +4525,11 @@ EXPORT_SYMBOL_GPL(gpiod_get_index);
* This is equivalent to gpiod_get_index(), except that when no GPIO with the
* specified index was assigned to the requested function it will return NULL.
* This is convenient for drivers that need to handle optional GPIOs.
+ *
+ * Returns:
+ * A valid GPIO descriptor, NULL if no GPIO has been assigned to the
+ * requested function and/or index, or another IS_ERR() code if an error
+ * occurred while trying to acquire the GPIO.
*/
struct gpio_desc *__must_check gpiod_get_index_optional(struct device *dev,
const char *con_id,
@@ -4469,11 +4548,13 @@ EXPORT_SYMBOL_GPL(gpiod_get_index_optional);

/**
* gpiod_hog - Hog the specified GPIO desc given the provided flags
- * @desc: gpio whose value will be assigned
+ * @desc: GPIO whose value will be assigned
* @name: gpio line name
- * @lflags: bitmask of gpio_lookup_flags GPIO_* values - returned from
- * of_find_gpio() or of_get_gpio_hog()
+ * @lflags: bitmask of gpio_lookup_flags GPIO_* values - returned from *_find_gpio()
* @dflags: gpiod_flags - optional GPIO initialization flags
+ *
+ * Returns:
+ * 0 on success, or negative errno on failure.
*/
int gpiod_hog(struct gpio_desc *desc, const char *name,
unsigned long lflags, enum gpiod_flags dflags)
@@ -4512,7 +4593,7 @@ int gpiod_hog(struct gpio_desc *desc, const char *name,

/**
* gpiochip_free_hogs - Scan gpio-controller chip and release GPIO hog
- * @gc: gpio chip to act on
+ * @gc: GPIO chip to act on
*/
static void gpiochip_free_hogs(struct gpio_chip *gc)
{
@@ -4530,9 +4611,11 @@ static void gpiochip_free_hogs(struct gpio_chip *gc)
*
* This function acquires all the GPIOs defined under a given function.
*
- * Return a struct gpio_descs containing an array of descriptors, -ENOENT if
- * no GPIO has been assigned to the requested function, or another IS_ERR()
- * code if an error occurred while trying to acquire the GPIOs.
+ * Returns:
+ * The GPIO descriptors corresponding to the function @con_id of device
+ * dev, -ENOENT if no GPIO has been assigned to the requested function,
+ * or another IS_ERR() code if an error occurred while trying to acquire
+ * the GPIOs.
*/
struct gpio_descs *__must_check gpiod_get_array(struct device *dev,
const char *con_id,
@@ -4658,6 +4741,12 @@ EXPORT_SYMBOL_GPL(gpiod_get_array);
*
* This is equivalent to gpiod_get_array(), except that when no GPIO was
* assigned to the requested function it will return NULL.
+ *
+ * Returns:
+ * The GPIO descriptors corresponding to the function @con_id of device
+ * dev, NULL if no GPIO has been assigned to the requested function,
+ * or another IS_ERR() code if an error occurred while trying to acquire
+ * the GPIOs.
*/
struct gpio_descs *__must_check gpiod_get_array_optional(struct device *dev,
const char *con_id,
diff --git a/drivers/gpio/gpiolib.h b/drivers/gpio/gpiolib.h
index 7f94580efdbc..cb950a3384e3 100644
--- a/drivers/gpio/gpiolib.h
+++ b/drivers/gpio/gpiolib.h
@@ -28,7 +28,7 @@
* @mockdev: class device used by the deprecated sysfs interface (may be
* NULL)
* @owner: helps prevent removal of modules exporting active GPIOs
- * @chip: pointer to the corresponding gpiochip, holding static
+ * @chip: pointer to the corresponding struct gpio_chip, holding static
* data for this device
* @descs: array of ngpio descriptors.
* @ngpio: the number of GPIO lines on this GPIO device, equal to the size
@@ -73,10 +73,10 @@ struct gpio_device {

#ifdef CONFIG_PINCTRL
/*
- * If CONFIG_PINCTRL is enabled, then gpio controllers can optionally
+ * If CONFIG_PINCTRL is enabled, then GPIO chips can optionally
* describe the actual pin range which they serve in an SoC. This
* information would be used by pinctrl subsystem to configure
- * corresponding pins for gpio usage.
+ * corresponding pins for GPIO usage.
*/
struct list_head pin_ranges;
#endif
@@ -240,7 +240,7 @@ int gpiochip_get_ngpios(struct gpio_chip *gc, struct device *dev);
const char *gpiod_get_label(struct gpio_desc *desc);

/*
- * Return the GPIO number of the passed descriptor relative to its chip
+ * Return the GPIO number of the passed descriptor relative to its chip.
*/
static inline int gpio_chip_hwgpio(const struct gpio_desc *desc)
{
--
2.43.0.rc1.1.gbec44491f096

2024-04-03 10:50:46

by Andy Shevchenko

Subject: Re: [PATCH v1 0/2] gpiolib: in-kernel documentation updates

On Tue, Mar 26, 2024 at 08:11:19PM +0200, Andy Shevchenko wrote:
> While looking for something I have noticed that in-kernel documentation
> for gpiolib implementation may be updated to reflect the current state
> of affairs. Hence these two patches.

Bart, do you have any comments here?

--
With Best Regards,
Andy Shevchenko

2024-04-03 11:14:55

by Bartosz Golaszewski

Subject: Re: [PATCH v1 1/2] gpiolib: Do not mention legacy GPIOF_* in the code

On Tue, Mar 26, 2024 at 7:12 PM Andy Shevchenko
<[email protected]> wrote:
>
> We are going to remove legacy API from kernel, don't mention
> it in the code that does not use it already for a while.
>
> Signed-off-by: Andy Shevchenko <[email protected]>
> ---
> drivers/gpio/gpiolib.c | 5 ++++-
> 1 file changed, 4 insertions(+), 1 deletion(-)
>
> diff --git a/drivers/gpio/gpiolib.c b/drivers/gpio/gpiolib.c
> index 5589e085ba25..f749ece2d3cd 100644
> --- a/drivers/gpio/gpiolib.c
> +++ b/drivers/gpio/gpiolib.c
> @@ -364,7 +364,10 @@ int gpiod_get_direction(struct gpio_desc *desc)
> if (ret < 0)
> return ret;
>
> - /* GPIOF_DIR_IN or other positive, otherwise GPIOF_DIR_OUT */
> + /*
> + * GPIO_LINE_DIRECTION_IN or other positive,
> + * otherwise GPIO_LINE_DIRECTION_OUT.
> + */
> if (ret > 0)
> ret = 1;
>
> --
> 2.43.0.rc1.1.gbec44491f096
>

Applied, thanks!

Bart

2024-04-03 16:58:17

by Bartosz Golaszewski

Subject: Re: [PATCH v1 2/2] gpiolib: Up to date the kernel documentation

On Tue, Mar 26, 2024 at 7:12 PM Andy Shevchenko
<[email protected]> wrote:
>
> There are several issues:
>
> - Reference to the non-existing or only single functions out of possible
> callees
>
> - No return section
>
> $ scripts/kernel-doc -v -none -Wall drivers/gpio/gpiolib* 2>&1 | grep -w warning | wc -l
> 67
>
> - Reference to NULL as %NULL in a few cases
>
> - Explicit reference to error codes as Exxx or %Exxx and
> numbers with leading %
>
> - Spelling of gpio, irq, SOC (in different capitalization)
>
> - Unaligned style of irqchip, gpiochip references
>
> - Unaligned style of NOTE, FIXME, and TODO
>
> Fix all these. While at it, fix multi-line comment style as well.
>
> Signed-off-by: Andy Shevchenko <[email protected]>

Could you split it into separate patches by subject (one for
capitalization, one for %NULL, etc.)? As is, it's a huge dump that's
hard to review.

Bart

2024-04-03 16:59:47

by Andy Shevchenko

Subject: Re: [PATCH v1 2/2] gpiolib: Up to date the kernel documentation

On Wed, Apr 03, 2024 at 02:59:32PM +0200, Bartosz Golaszewski wrote:
> On Tue, Mar 26, 2024 at 7:12 PM Andy Shevchenko
> <[email protected]> wrote:
> >
> > There are several issues:
> >
> > - Reference to the non-existing or only single functions out of possible
> > callees
> >
> > - No return section
> >
> > $ scripts/kernel-doc -v -none -Wall drivers/gpio/gpiolib* 2>&1 | grep -w warning | wc -l
> > 67
> >
> > - Reference to NULL as %NULL in a few cases
> >
> > - Explicit reference to error codes as Exxx or %Exxx and
> > numbers with leading %
> >
> > - Spelling of gpio, irq, SOC (in different capitalization)
> >
> > - Unaligned style of irqchip, gpiochip references
> >
> > - Unaligned style of NOTE, FIXME, and TODO
> >
> > Fix all these. While at it, fix multi-line comment style as well.
> >
> > Signed-off-by: Andy Shevchenko <[email protected]>
>
> Could you split it into separate patches by subject (one for
> capitalization, one for %NULL, etc.)? As is, it's a huge dump that's
> hard to review.

Sure.

--
With Best Regards,
Andy Shevchenko