Skip to contentSkip to conversation

gpiolib: rename gpio_set_debounce_timeout() for consistency

PATCH In review Bartosz Golaszewski 3 participants 11 messages Sep 4, 2023 – Sep 6, 2023

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

PATCH 1/2 gpiolib: rename gpio_set_debounce_timeout() for consistency

From: Bartosz Golaszewski <[email protected]>

All other functions that manipulate a struct gpio_desc use the gpiod_ prefix. Follow this convention and rename gpio_set_debounce_timeout() to gpiod_set_debounce_timeout().

---
 drivers/gpio/gpiolib-acpi.c | 5 +++--
 drivers/gpio/gpiolib.c      | 4 ++--
 drivers/gpio/gpiolib.h      | 2 +-
 3 files changed, 6 insertions(+), 5 deletions(-)
drivers/gpio/gpiolib-acpi.c +3 -2
index fbda452fb4d6..4a390d8f6544 100644
@@ -341,7 +341,7 @@ static struct gpio_desc *acpi_request_own_gpiod(struct gpio_chip *chip,
 		return desc;
 
 	/* ACPI uses hundredths of milliseconds units */
-	ret = gpio_set_debounce_timeout(desc, agpio->debounce_timeout * 10);
+	ret = gpiod_set_debounce_timeout(desc, agpio->debounce_timeout * 10);
 	if (ret)
 		dev_warn(chip->parent,
 			 "Failed to set debounce-timeout for pin 0x%04X, err %d\n",
@@ -1087,7 +1087,8 @@ int acpi_dev_gpio_irq_wake_get_by(struct acpi_device *adev, const char *name, in
 				return ret;
 
 			/* ACPI uses hundredths of milliseconds units */
-			ret = gpio_set_debounce_timeout(desc, info.debounce * 10);
+			ret = gpiod_set_debounce_timeout(desc,
+							 info.debounce * 10);
 			if (ret)
 				return ret;
 
drivers/gpio/gpiolib.c +2 -2
index edffa0d2acaa..6fab0f211e67 100644
@@ -2377,7 +2377,7 @@ static int gpio_set_bias(struct gpio_desc *desc)
 }
 
 /**
- * gpio_set_debounce_timeout() - Set debounce timeout
+ * gpiod_set_debounce_timeout() - Set debounce timeout
  * @desc:	GPIO descriptor to set the debounce timeout
  * @debounce:	Debounce timeout in microseconds
  *
@@ -2386,7 +2386,7 @@ static int gpio_set_bias(struct gpio_desc *desc)
  *
  * Returns 0 on success, or negative error code otherwise.
  */
-int gpio_set_debounce_timeout(struct gpio_desc *desc, unsigned int debounce)
+int gpiod_set_debounce_timeout(struct gpio_desc *desc, unsigned int debounce)
 {
 	return gpio_set_config_with_argument_optional(desc,
 						      PIN_CONFIG_INPUT_DEBOUNCE,
drivers/gpio/gpiolib.h +1 -1
index 9bff5c2cf720..9ea5b88ad304 100644
@@ -219,7 +219,7 @@ static inline int gpiod_request_user(struct gpio_desc *desc, const char *label)
 
 int gpiod_configure_flags(struct gpio_desc *desc, const char *con_id,
 		unsigned long lflags, enum gpiod_flags dflags);
-int gpio_set_debounce_timeout(struct gpio_desc *desc, unsigned int debounce);
+int gpiod_set_debounce_timeout(struct gpio_desc *desc, unsigned int debounce);
 int gpiod_hog(struct gpio_desc *desc, const char *name,
 		unsigned long lflags, enum gpiod_flags dflags);
 int gpiochip_get_ngpios(struct gpio_chip *gc, struct device *dev);
Signature · 1 line
2.39.2
#1 lore raw

PATCH 2/2 gpiolib: rename gpio_chip_hwgpio() for consistency

From: Bartosz Golaszewski <[email protected]>

All other functions that manipulate a struct gpio_desc use the gpiod_ prefix. Follow this convention and rename gpio_chip_hwgpio() to gpiod_get_hwgpio().

---
 drivers/gpio/gpio-aspeed.c   |  6 ++---
 drivers/gpio/gpiolib-cdev.c  | 12 ++++-----
 drivers/gpio/gpiolib-sysfs.c | 10 ++++----
 drivers/gpio/gpiolib.c       | 48 ++++++++++++++++++------------------
 drivers/gpio/gpiolib.h       |  2 +-
 5 files changed, 39 insertions(+), 39 deletions(-)
drivers/gpio/gpio-aspeed.c +3 -3
index da33bbbdacb9..c9cef89e1f65 100644
@@ -23,7 +23,7 @@
 
 /*
  * These two headers aren't meant to be used by GPIO drivers. We need
- * them in order to access gpio_chip_hwgpio() which we need to implement
+ * them in order to access gpiod_get_hwgpio() which we need to implement
  * the aspeed specific API which allows the coprocessor to request
  * access to some GPIOs and to arbitrate between coprocessor and ARM.
  */
@@ -1013,7 +1013,7 @@ int aspeed_gpio_copro_grab_gpio(struct gpio_desc *desc,
 {
 	struct gpio_chip *chip = gpiod_to_chip(desc);
 	struct aspeed_gpio *gpio = gpiochip_get_data(chip);
-	int rc = 0, bindex, offset = gpio_chip_hwgpio(desc);
+	int rc = 0, bindex, offset = gpiod_get_hwgpio(desc);
 	const struct aspeed_gpio_bank *bank = to_bank(offset);
 	unsigned long flags;
 
@@ -1059,7 +1059,7 @@ int aspeed_gpio_copro_release_gpio(struct gpio_desc *desc)
 {
 	struct gpio_chip *chip = gpiod_to_chip(desc);
 	struct aspeed_gpio *gpio = gpiochip_get_data(chip);
-	int rc = 0, bindex, offset = gpio_chip_hwgpio(desc);
+	int rc = 0, bindex, offset = gpiod_get_hwgpio(desc);
 	const struct aspeed_gpio_bank *bank = to_bank(offset);
 	unsigned long flags;
 
drivers/gpio/gpiolib-cdev.c +6 -6
index e39d344feb28..5db38d49941f 100644
@@ -698,7 +698,7 @@ static enum hte_return process_hw_ts_thread(void *p)
 	}
 	le.line_seqno = line->line_seqno;
 	le.seqno = (lr->num_lines == 1) ? le.line_seqno : line->req_seqno;
-	le.offset = gpio_chip_hwgpio(line->desc);
+	le.offset = gpiod_get_hwgpio(line->desc);
 
 	linereq_put_event(lr, &le);
 
@@ -815,7 +815,7 @@ static irqreturn_t edge_irq_thread(int irq, void *p)
 	line->line_seqno++;
 	le.line_seqno = line->line_seqno;
 	le.seqno = (lr->num_lines == 1) ? le.line_seqno : line->req_seqno;
-	le.offset = gpio_chip_hwgpio(line->desc);
+	le.offset = gpiod_get_hwgpio(line->desc);
 
 	linereq_put_event(lr, &le);
 
@@ -913,7 +913,7 @@ static void debounce_work_func(struct work_struct *work)
 
 	lr = line->req;
 	le.timestamp_ns = line_event_timestamp(line);
-	le.offset = gpio_chip_hwgpio(line->desc);
+	le.offset = gpiod_get_hwgpio(line->desc);
 #ifdef CONFIG_HTE
 	if (edflags & GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE) {
 		/* discard events except the last one */
@@ -1610,7 +1610,7 @@ static void linereq_show_fdinfo(struct seq_file *out, struct file *file)
 
 	for (i = 0; i < lr->num_lines; i++)
 		seq_printf(out, "gpio-line:\t%d\n",
-			   gpio_chip_hwgpio(lr->lines[i].desc));
+			   gpiod_get_hwgpio(lr->lines[i].desc));
 }
 #endif
 
@@ -2278,7 +2278,7 @@ static void gpio_desc_to_lineinfo(struct gpio_desc *desc,
 	unsigned int num_attrs = 0;
 
 	memset(info, 0, sizeof(*info));
-	info->offset = gpio_chip_hwgpio(desc);
+	info->offset = gpiod_get_hwgpio(desc);
 
 	/*
 	 * This function takes a mutex so we must check this before taking
@@ -2539,7 +2539,7 @@ static int lineinfo_changed_notify(struct notifier_block *nb,
 	struct gpio_desc *desc = data;
 	int ret;
 
-	if (!test_bit(gpio_chip_hwgpio(desc), cdev->watched_lines))
+	if (!test_bit(gpiod_get_hwgpio(desc), cdev->watched_lines))
 		return NOTIFY_DONE;
 
 	memset(&chg, 0, sizeof(chg));
drivers/gpio/gpiolib-sysfs.c +5 -5
index 50503a4525eb..ee3a0cb62d20 100644
@@ -194,7 +194,7 @@ static int gpio_sysfs_request_irq(struct device *dev, unsigned char flags)
 	 *        Remove this redundant call (along with the corresponding
 	 *        unlock) when those drivers have been fixed.
 	 */
-	ret = gpiochip_lock_as_irq(desc->gdev->chip, gpio_chip_hwgpio(desc));
+	ret = gpiochip_lock_as_irq(desc->gdev->chip, gpiod_get_hwgpio(desc));
 	if (ret < 0)
 		goto err_put_kn;
 
@@ -208,7 +208,7 @@ static int gpio_sysfs_request_irq(struct device *dev, unsigned char flags)
 	return 0;
 
 err_unlock:
-	gpiochip_unlock_as_irq(desc->gdev->chip, gpio_chip_hwgpio(desc));
+	gpiochip_unlock_as_irq(desc->gdev->chip, gpiod_get_hwgpio(desc));
 err_put_kn:
 	sysfs_put(data->value_kn);
 
@@ -226,7 +226,7 @@ static void gpio_sysfs_free_irq(struct device *dev)
 
 	data->irq_flags = 0;
 	free_irq(data->irq, data);
-	gpiochip_unlock_as_irq(desc->gdev->chip, gpio_chip_hwgpio(desc));
+	gpiochip_unlock_as_irq(desc->gdev->chip, gpiod_get_hwgpio(desc));
 	sysfs_put(data->value_kn);
 }
 
@@ -458,7 +458,7 @@ static ssize_t export_store(const struct class *class,
 		return -EINVAL;
 	}
 	gc = desc->gdev->chip;
-	offset = gpio_chip_hwgpio(desc);
+	offset = gpiod_get_hwgpio(desc);
 	if (!gpiochip_line_is_valid(gc, offset)) {
 		pr_warn("%s: GPIO %ld masked\n", __func__, gpio);
 		return -EINVAL;
@@ -613,7 +613,7 @@ int gpiod_export(struct gpio_desc *desc, bool direction_may_change)
 	else
 		data->direction_can_change = false;
 
-	offset = gpio_chip_hwgpio(desc);
+	offset = gpiod_get_hwgpio(desc);
 	if (chip->names && chip->names[offset])
 		ioname = chip->names[offset];
 
drivers/gpio/gpiolib.c +24 -24

184 lines not on this page · raw message

drivers/gpio/gpiolib.h +1 -1
index 9ea5b88ad304..bddf29699289 100644
@@ -227,7 +227,7 @@ int gpiochip_get_ngpios(struct gpio_chip *gc, struct device *dev);
 /*
  * Return the GPIO number of the passed descriptor relative to its chip
  */
-static inline int gpio_chip_hwgpio(const struct gpio_desc *desc)
+static inline int gpiod_get_hwgpio(const struct gpio_desc *desc)
 {
 	return desc - &desc->gdev->descs[0];
 }
Signature · 1 line
2.39.2
#2 lore raw

Re: [PATCH 2/2] gpiolib: rename gpio_chip_hwgpio() for consistency

Quoted 5 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

All other functions that manipulate a struct gpio_desc use the gpiod_ prefix. Follow this convention and rename gpio_chip_hwgpio() to gpiod_get_hwgpio().

Same comment. Also, I don't think it's good idea as it steps on the exported API's toes. I.o.w. I won't mix those two.

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#3 lore raw

Re: [PATCH 2/2] gpiolib: rename gpio_chip_hwgpio() for consistency

Quoted 11 lines · Andy Shevchenko
Quoted 5 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

All other functions that manipulate a struct gpio_desc use the gpiod_ prefix. Follow this convention and rename gpio_chip_hwgpio() to gpiod_get_hwgpio().

Same comment. Also, I don't think it's good idea as it steps on the exported API's toes. I.o.w. I won't mix those two.

Even if I agreed with your other comment, gpio_chip_hwgpio() is a terrible name and if I didn't know, I couldn't tell you what it does just from looking at the name.

Bart

#4 lore raw

Re: [PATCH 2/2] gpiolib: rename gpio_chip_hwgpio() for consistency

Quoted 9 lines · Bartosz Golaszewski
Quoted 7 lines · Andy Shevchenko
Quoted 5 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

All other functions that manipulate a struct gpio_desc use the gpiod_ prefix. Follow this convention and rename gpio_chip_hwgpio() to gpiod_get_hwgpio().

Quoted 6 lines
Quoted 2 lines

Same comment. Also, I don't think it's good idea as it steps on the exported API's toes. I.o.w. I won't mix those two.

Even if I agreed with your other comment, gpio_chip_hwgpio() is a terrible name and if I didn't know, I couldn't tell you what it does just from looking at the name.

That's can be improved, my previous comments were basically to avoid mixing prefixes for internal and external APIs, let's say prefix them similarly, but for internal with space and/or more verbose naming

	gpiod_		gpio_desc_
	gpiochip_	gpio_chip_
	gdev_		gpio_device_

(as an example).

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#5 lore raw

Re: [PATCH 2/2] gpiolib: rename gpio_chip_hwgpio() for consistency

Quoted 18 lines · Andy Shevchenko
Quoted 9 lines · Bartosz Golaszewski
Quoted 7 lines · Andy Shevchenko
Quoted 5 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

All other functions that manipulate a struct gpio_desc use the gpiod_ prefix. Follow this convention and rename gpio_chip_hwgpio() to gpiod_get_hwgpio().

Quoted 6 lines
Quoted 2 lines

Same comment. Also, I don't think it's good idea as it steps on the exported API's toes. I.o.w. I won't mix those two.

Even if I agreed with your other comment, gpio_chip_hwgpio() is a terrible name and if I didn't know, I couldn't tell you what it does just from looking at the name.

Quoted 8 lines

That's can be improved, my previous comments were basically to avoid mixing prefixes for internal and external APIs, let's say prefix them similarly, but for internal with space and/or more verbose naming

        gpiod_          gpio_desc_
        gpiochip_       gpio_chip_
        gdev_           gpio_device_

There's one more possibility. Have all exported symbols be prefixed with gpiod in one way or another and the internal symbols just drop the prefix so it would be like:

gpiod_
gpiochip_
gpio_device_

and

desc_
chip_
device_

Because for internal symbols we already know they refer to gpiolib.

Anyway, I'll drop the patches for now and let's revisit in the future when the consensus is reached.

Bart

Quoted 7 lines

(as an example).

--
With Best Regards,
Andy Shevchenko

#6 lore raw

Re: [PATCH 2/2] gpiolib: rename gpio_chip_hwgpio() for consistency

Quoted 36 lines · Bartosz Golaszewski
Quoted 18 lines · Andy Shevchenko
Quoted 9 lines · Bartosz Golaszewski
Quoted 7 lines · Andy Shevchenko
Quoted 5 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

All other functions that manipulate a struct gpio_desc use the gpiod_ prefix. Follow this convention and rename gpio_chip_hwgpio() to gpiod_get_hwgpio().

Quoted 6 lines
Quoted 2 lines

Same comment. Also, I don't think it's good idea as it steps on the exported API's toes. I.o.w. I won't mix those two.

Even if I agreed with your other comment, gpio_chip_hwgpio() is a terrible name and if I didn't know, I couldn't tell you what it does just from looking at the name.

Quoted 7 lines

That's can be improved, my previous comments were basically to avoid mixing prefixes for internal and external APIs, let's say prefix them similarly, but for internal with space and/or more verbose naming

        gpiod_          gpio_desc_
        gpiochip_       gpio_chip_
        gdev_           gpio_device_

There's one more possibility. Have all exported symbols be prefixed with gpiod in one way or another and the internal symbols just drop the prefix so it would be like:

gpiod_
gpiochip_
gpio_device_

Quoted 7 lines

and

desc_
chip_
device_

Because for internal symbols we already know they refer to gpiolib.

With the above schema we have two caveats, one is not significant (as we have desc_to_gpio() and complimentary API). And another one is device/dev, which is conflicting with global. That's why I still prefer gpio_desc_ and so on.

Quoted 2 lines

Anyway, I'll drop the patches for now and let's revisit in the future when the consensus is reached.

Yes, let's focus on something more important now.

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#7 lore raw

Re: [PATCH 2/2] gpiolib: rename gpio_chip_hwgpio() for consistency

In reply to Bartosz Golaszewski
Quoted 3 lines · Bartosz Golaszewski

gpio_chip_hwgpio() is a
terrible name and if I didn't know, I couldn't tell you what it does just from looking at the name.

Probably my fault.

"For the chip containing this desc obtain the corresponding hardware GPIO number/offset" is what I would put in kerneldoc. (Which is by the way also horrible.)

Let's rename it to something that says clearly what it does. (Rusty Russell's API design hierarchy.)

I guess I would just name it something like *_get_chip_hw_offset() or *_get_chip_hwgpio_offset() but it gets a bit long, maybe it is a bit talkative but easy to understand. (I stay off the prefix discussion.)

Yours,
Linus Walleij

#8 lore raw
In reply to Bartosz Golaszewski
Quoted 5 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

All other functions that manipulate a struct gpio_desc use the gpiod_ prefix. Follow this convention and rename gpio_set_debounce_timeout() to gpiod_set_debounce_timeout().

No, that's not true. This one is inline with the other gpio_set() _internal_ APIs. If renamed, should be done consistently.

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#9 lore raw
Quoted 9 lines · Andy Shevchenko
Quoted 5 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

All other functions that manipulate a struct gpio_desc use the gpiod_ prefix. Follow this convention and rename gpio_set_debounce_timeout() to gpiod_set_debounce_timeout().

No, that's not true. This one is inline with the other gpio_set() _internal_ APIs. If renamed, should be done consistently.

It's even broader, like for_each_gpio_desc(). So, looking at that one I would rather use gpio_desc_ prefix / suffix than gpiod in case you are so eager to rename (Personally I consider this as unneeded churn). Also consider going thru all _internal_ APIs, like gpiod_not_found(), to be renamed to gpio_desc_not_found().

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#10 lore raw
In reply to Andy Shevchenko
Quoted 11 lines · Andy Shevchenko
Quoted 5 lines · Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

All other functions that manipulate a struct gpio_desc use the gpiod_ prefix. Follow this convention and rename gpio_set_debounce_timeout() to gpiod_set_debounce_timeout().

No, that's not true. This one is inline with the other gpio_set() _internal_ APIs. If renamed, should be done consistently.

All the other ones are static to gpiolib.c. With static symbols the naming convention is a bit more relaxed throughout the kernel. But I do agree and I will get to them in time. :)

Bart