[PATCH] gpio: improve the API contract for setting direction

[PATCH] gpio: improve the API contract for setting direction

[Bartosz Golaszewski]

From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

If a GPIO driver returns a positive integer from one of the direction
setter callbacks, we'll end up propagating it to user-space. Whether we
should sanitize the values returned by callbacks is a different question
but let's first improve the documentation and fortify the contract with
GPIO providers.

Reported-by: José Guilherme de Castro Rodrigues <joseguilhermebh@hotmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 include/linux/gpio/driver.h | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/include/linux/gpio/driver.h b/include/linux/gpio/driver.h
index 9a5c6c76e653..c1c516b8a880 100644
--- a/include/linux/gpio/driver.h
+++ b/include/linux/gpio/driver.h
@@ -335,10 +335,12 @@ struct gpio_irq_chip {
  *	(same as GPIO_LINE_DIRECTION_OUT / GPIO_LINE_DIRECTION_IN),
  *	or negative error. It is recommended to always implement this
  *	function, even on input-only or output-only gpio chips.
- * @direction_input: configures signal "offset" as input, or returns error
- *	This can be omitted on input-only or output-only gpio chips.
- * @direction_output: configures signal "offset" as output, or returns error
- *	This can be omitted on input-only or output-only gpio chips.
+ * @direction_input: configures signal "offset" as input, or returns a negative
+ *	error number. This can be omitted on input-only or output-only gpio
+ *	chips.
+ * @direction_output: configures signal "offset" as output, or returns
+ *	a negative error number. This can be omitted on input-only or
+ *	output-only gpio chips.
  * @get: returns value for signal "offset", 0=low, 1=high, or negative error
  * @get_multiple: reads values for multiple signals defined by "mask" and
  *	stores them in "bits", returns 0 on success or negative error
-- 
2.40.1

Re: [PATCH] gpio: improve the API contract for setting direction

[Kent Gibson]

On Wed, Jan 24, 2024 at 11:18:03AM +0100, Bartosz Golaszewski wrote:
> From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
>
> If a GPIO driver returns a positive integer from one of the direction
> setter callbacks, we'll end up propagating it to user-space. Whether we
> should sanitize the values returned by callbacks is a different question
> but let's first improve the documentation and fortify the contract with
> GPIO providers.
>
> Reported-by: José Guilherme de Castro Rodrigues <joseguilhermebh@hotmail.com>
> Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
> ---
>  include/linux/gpio/driver.h | 10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)
>
> diff --git a/include/linux/gpio/driver.h b/include/linux/gpio/driver.h
> index 9a5c6c76e653..c1c516b8a880 100644
> --- a/include/linux/gpio/driver.h
> +++ b/include/linux/gpio/driver.h
> @@ -335,10 +335,12 @@ struct gpio_irq_chip {
>   *	(same as GPIO_LINE_DIRECTION_OUT / GPIO_LINE_DIRECTION_IN),
>   *	or negative error. It is recommended to always implement this
>   *	function, even on input-only or output-only gpio chips.
> - * @direction_input: configures signal "offset" as input, or returns error
> - *	This can be omitted on input-only or output-only gpio chips.
> - * @direction_output: configures signal "offset" as output, or returns error
> - *	This can be omitted on input-only or output-only gpio chips.
> + * @direction_input: configures signal "offset" as input, or returns a negative
> + *	error number. This can be omitted on input-only or output-only gpio
> + *	chips.
> + * @direction_output: configures signal "offset" as output, or returns
> + *	a negative error number. This can be omitted on input-only or
> + *	output-only gpio chips.
>   * @get: returns value for signal "offset", 0=low, 1=high, or negative error
>   * @get_multiple: reads values for multiple signals defined by "mask" and
>   *	stores them in "bits", returns 0 on success or negative error

Also specify 0 on success, as per @get_multiple?

It would be good to revise the documentation for all the ops, but this
is a start.

Cheers,
Kent.