I was confused about the gpiod_flags values and thought that
GPIOD_OUT_LOW and GPIOD_OUT_HIGH set the line to be active low / active
high. This is not true, but I got the misconception because the flags
GPIOD_OUT_*_OPEN_DRAIN do change line configuration and there's a
subchapter about *active low* and *open drain* semantics.
Add an explicit mention that the initial value is a logical value (and
not the line configuration or physical line level). Also add a mention
of the function gpiod_toggle_active_low which was previously missing
from this document.
Signed-off-by: Hannu Hartikainen <[email protected]>
---
Documentation/driver-api/gpio/consumer.rst | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)
diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst
index 3366a991b4aa..47869ca8ccf0 100644
--- a/Documentation/driver-api/gpio/consumer.rst
+++ b/Documentation/driver-api/gpio/consumer.rst
@@ -72,6 +72,10 @@ for the GPIO. Values can be:
* GPIOD_OUT_HIGH_OPEN_DRAIN same as GPIOD_OUT_HIGH but also enforce the line
to be electrically used with open drain.
+Note that the initial value is *logical* and the physical line level depends on
+whether the line is configured active high or active low (see
+:ref:`active_low_semantics`).
+
The two last flags are used for use cases where open drain is mandatory, such
as I2C: if the line is not already configured as open drain in the mappings
(see board.txt), then open drain will be enforced anyway and a warning will be
@@ -252,6 +256,8 @@ that can't be accessed from hardIRQ handlers, these calls act the same as the
spinlock-safe calls.
+.. _active_low_semantics:
+
The active low and open drain semantics
---------------------------------------
As a consumer should not have to care about the physical line level, all of the
@@ -309,9 +315,11 @@ work on the raw line value::
void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)
int gpiod_direction_output_raw(struct gpio_desc *desc, int value)
-The active low state of a GPIO can also be queried using the following call::
+The active low state of a GPIO can also be queried and toggled using the
+following calls::
int gpiod_is_active_low(const struct gpio_desc *desc)
+ void gpiod_toggle_active_low(struct gpio_desc *desc)
Note that these functions should only be used with great moderation; a driver
should not have to care about the physical line level or open drain semantics.
--
2.32.0
On Thu, Jul 8, 2021 at 5:21 PM Hannu Hartikainen <[email protected]> wrote:
>
> I was confused about the gpiod_flags values and thought that
> GPIOD_OUT_LOW and GPIOD_OUT_HIGH set the line to be active low / active
> high. This is not true, but I got the misconception because the flags
> GPIOD_OUT_*_OPEN_DRAIN do change line configuration and there's a
> subchapter about *active low* and *open drain* semantics.
>
> Add an explicit mention that the initial value is a logical value (and
> not the line configuration or physical line level). Also add a mention
> of the function gpiod_toggle_active_low which was previously missing
> from this document.
>
> Signed-off-by: Hannu Hartikainen <[email protected]>
> ---
> Documentation/driver-api/gpio/consumer.rst | 10 +++++++++-
> 1 file changed, 9 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst
> index 3366a991b4aa..47869ca8ccf0 100644
> --- a/Documentation/driver-api/gpio/consumer.rst
> +++ b/Documentation/driver-api/gpio/consumer.rst
> @@ -72,6 +72,10 @@ for the GPIO. Values can be:
> * GPIOD_OUT_HIGH_OPEN_DRAIN same as GPIOD_OUT_HIGH but also enforce the line
> to be electrically used with open drain.
>
> +Note that the initial value is *logical* and the physical line level depends on
> +whether the line is configured active high or active low (see
> +:ref:`active_low_semantics`).
> +
> The two last flags are used for use cases where open drain is mandatory, such
> as I2C: if the line is not already configured as open drain in the mappings
> (see board.txt), then open drain will be enforced anyway and a warning will be
> @@ -252,6 +256,8 @@ that can't be accessed from hardIRQ handlers, these calls act the same as the
> spinlock-safe calls.
>
>
> +.. _active_low_semantics:
> +
> The active low and open drain semantics
> ---------------------------------------
> As a consumer should not have to care about the physical line level, all of the
> @@ -309,9 +315,11 @@ work on the raw line value::
> void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)
> int gpiod_direction_output_raw(struct gpio_desc *desc, int value)
>
> -The active low state of a GPIO can also be queried using the following call::
> +The active low state of a GPIO can also be queried and toggled using the
> +following calls::
>
> int gpiod_is_active_low(const struct gpio_desc *desc)
> + void gpiod_toggle_active_low(struct gpio_desc *desc)
>
> Note that these functions should only be used with great moderation; a driver
> should not have to care about the physical line level or open drain semantics.
> --
> 2.32.0
>
Makes sense, applied!
Bartosz