gpiolib: in-kernel documentation updates
cover 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(-)
Signature · 1 line
2.43.0.rc1.1.gbec44491f096
PATCH 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.
--- drivers/gpio/gpiolib.c | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
drivers/gpio/gpiolib.c +4 -1
@@ -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 ;
Signature · 1 line
2.43.0.rc1.1.gbec44491f096
Bartosz Golaszewski
AppliedRe: [PATCH v1 1/2] gpiolib: Do not mention legacy GPIOF_* in the code
Quoted 26 lines · Andy Shevchenko
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(-)drivers/gpio/gpiolib.c +4
-2@@ -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 ; --
Quoted 2 lines
2.43.0.rc1.1.gbec44491f096
Applied, thanks!
Bart
PATCH 2/2 gpiolib: Up to date the kernel documentation
In reply to Andy ShevchenkoThere 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.
--- 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(-)
drivers/gpio/gpiolib-acpi.c +28 -17
@@ -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)
drivers/gpio/gpiolib-cdev.c +10 -5
@@ -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) {
drivers/gpio/gpiolib-devres.c +64 -21
169 lines not on this page · raw message
drivers/gpio/gpiolib-legacy.c +3 -0
@@ -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) {
drivers/gpio/gpiolib-of.c +62 -40
251 lines not on this page · raw message
drivers/gpio/gpiolib-swnode.c +4 -4
@@ -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)
drivers/gpio/gpiolib-sysfs.c +23 -18
120 lines not on this page · raw message
drivers/gpio/gpiolib.c +236 -147
999 lines not on this page · raw message
drivers/gpio/gpiolib.h +4 -4
@@ -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) {
Signature · 1 line
2.43.0.rc1.1.gbec44491f096
Re: [PATCH v1 2/2] gpiolib: Up to date the kernel documentation
Quoted 18 lines · Andy Shevchenko
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)
Quoted 7 lines
- 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
Re: [PATCH v1 2/2] gpiolib: Up to date the kernel documentation
Quoted 24 lines · Bartosz Golaszewski
Quoted 22 lines · Andy Shevchenko
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
Quoted 7 lines
Quoted 3 lines
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.
Signature · 2 lines
With Best Regards, Andy Shevchenko
Quoted 3 lines · Andy Shevchenko
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?
Signature · 2 lines
With Best Regards, Andy Shevchenko