Skip to contentSkip to conversation

gpiolib: in-kernel documentation updates

PATCH Applied Andy Shevchenko 2 participants 7 messages Mar 26, 2024 – Apr 3, 2024

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index 5589e085ba25..f749ece2d3cd 100644
@@ -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
#2 lore raw

Re: [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.

---
 drivers/gpio/gpiolib.c | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
drivers/gpio/gpiolib.c +4 -2
index 5589e085ba25..f749ece2d3cd 100644
@@ -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

#3 lore raw

PATCH 2/2 gpiolib: Up to date the kernel documentation

In reply to 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

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
index 7f140df40f35..dfcfa23e7a59 100644
@@ -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
index f384fa278764..b4369a8b4381 100644
@@ -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
index 5a9911ae9125..d27142418f9f 100644
@@ -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
index fa52bdb1a29a..100fc18a468c 100644
@@ -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
index 7f94580efdbc..cb950a3384e3 100644
@@ -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
#4 lore raw

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.

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

#5 lore raw

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.

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
#6 lore raw
In reply to 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