The true Hi-Z (a.k.a. high impedance) mode is when pin is completely
disconnected from the chip. This includes input buffer as well.
Nevertheless, some hardware may not support that mode and they are
considering input only as Hi-Z, but more precisely it is an equivalent
to that, in electronics it's basically "an antenna mode".
Sligthly correct documentation to take the above into consideration.
Signed-off-by: Andy Shevchenko <[email protected]>
---
Documentation/driver-api/gpio/driver.rst | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst
index 6baaeab79534..bf6319cc531b 100644
--- a/Documentation/driver-api/gpio/driver.rst
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -218,10 +218,10 @@ not support open drain/open source in hardware, the GPIO library will instead
use a trick: when a line is set as output, if the line is flagged as open
drain, and the IN output value is low, it will be driven low as usual. But
if the IN output value is set to high, it will instead *NOT* be driven high,
-instead it will be switched to input, as input mode is high impedance, thus
-achieving an "open drain emulation" of sorts: electrically the behaviour will
-be identical, with the exception of possible hardware glitches when switching
-the mode of the line.
+instead it will be switched to input, as input mode is an equivalent to
+high impedance, thus achieving an "open drain emulation" of sorts: electrically
+the behaviour will be identical, with the exception of possible hardware glitches
+when switching the mode of the line.
For open source configuration the same principle is used, just that instead
of actively driving the line low, it is set to input.
--
2.35.1
The ->get() callback depending on other settings and hardware support
may return different values, while the line outside the chip is kept
in the same state. Let's discuss that in the documentation.
Signed-off-by: Andy Shevchenko <[email protected]>
---
Documentation/driver-api/gpio/driver.rst | 24 ++++++++++++++++++++++++
1 file changed, 24 insertions(+)
diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst
index bf6319cc531b..3d2f36001a7a 100644
--- a/Documentation/driver-api/gpio/driver.rst
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -251,6 +251,30 @@ supports more versatile control over electrical properties and can handle
different pull-up or pull-down resistance values.
+Considerations of the ->get() returned value
+--------------------------------------------
+
+Due to different possible electrical configurations and software applications
+the value that ->get() callback returns may vary depending on the other settings.
+This will allow to use pins in the I2C emulation mode or other not so standard
+uses.
+
+The below table gathered the most used cases.
+
+========== ========== =============== =======================
+ Input Output State What value to return?
+========== ========== =============== =======================
+ Disabled Disabled Hi-Z input buffer
+ Disabled OS/OD/etc Single ended [cached] output buffer
+ x Push-Pull Out [cached] output buffer
+ Enabled Disabled In input buffer
+ Enabled OS/OD/etc Bidirectional input buffer
+========== ========== =============== =======================
+
+The [cached] here is used in a broader sense: either pure software cache, or
+read back value from the GPIO output buffer (not all hardware support that).
+
+
GPIO drivers providing IRQs
===========================
--
2.35.1
The code blocks are indented with two spaces, if the leading TAB
is occurred the syntax highlighting might be broken in some editors.
To prevent that unify all code blocks by using spaces instead of
leading TAB(s).
Signed-off-by: Andy Shevchenko <[email protected]>
---
Documentation/driver-api/gpio/driver.rst | 28 ++++++++++++------------
1 file changed, 14 insertions(+), 14 deletions(-)
diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst
index 3d2f36001a7a..d69ea7547aee 100644
--- a/Documentation/driver-api/gpio/driver.rst
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -7,7 +7,7 @@ This document serves as a guide for writers of GPIO chip drivers.
Each GPIO controller driver needs to include the following header, which defines
the structures used to define a GPIO driver::
- #include <linux/gpio/driver.h>
+ #include <linux/gpio/driver.h>
Internal Representation of GPIOs
@@ -144,7 +144,7 @@ is not open, it will present a high-impedance (tristate) to the external rail::
in ----|| |/
||--+ in ----|
| |\
- GND GND
+ GND GND
This configuration is normally used as a way to achieve one of two things:
@@ -574,10 +574,10 @@ the interrupt separately and go with it:
struct my_gpio *g;
struct gpio_irq_chip *girq;
- ret = devm_request_threaded_irq(dev, irq, NULL,
- irq_thread_fn, IRQF_ONESHOT, "my-chip", g);
+ ret = devm_request_threaded_irq(dev, irq, NULL, irq_thread_fn,
+ IRQF_ONESHOT, "my-chip", g);
if (ret < 0)
- return ret;
+ return ret;
/* Get a pointer to the gpio_irq_chip */
girq = &g->gc.irq;
@@ -705,12 +705,12 @@ certain operations and keep track of usage inside of the gpiolib subsystem.
Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
to mark the GPIO as being used as an IRQ::
- int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset)
+ int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset)
This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
is released::
- void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset)
+ void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset)
When implementing an irqchip inside a GPIO driver, these two functions should
typically be called in the .startup() and .shutdown() callbacks from the
@@ -732,12 +732,12 @@ When a GPIO is used as an IRQ signal, then gpiolib also needs to know if
the IRQ is enabled or disabled. In order to inform gpiolib about this,
the irqchip driver should call::
- void gpiochip_disable_irq(struct gpio_chip *chip, unsigned int offset)
+ void gpiochip_disable_irq(struct gpio_chip *chip, unsigned int offset)
This allows drivers to drive the GPIO as an output while the IRQ is
disabled. When the IRQ is enabled again, a driver should call::
- void gpiochip_enable_irq(struct gpio_chip *chip, unsigned int offset)
+ void gpiochip_enable_irq(struct gpio_chip *chip, unsigned int offset)
When implementing an irqchip inside a GPIO driver, these two functions should
typically be called in the .irq_disable() and .irq_enable() callbacks from the
@@ -787,12 +787,12 @@ Sometimes it is useful to allow a GPIO chip driver to request its own GPIO
descriptors through the gpiolib API. A GPIO driver can use the following
functions to request and free descriptors::
- struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc,
- u16 hwnum,
- const char *label,
- enum gpiod_flags flags)
+ struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc,
+ u16 hwnum,
+ const char *label,
+ enum gpiod_flags flags)
- void gpiochip_free_own_desc(struct gpio_desc *desc)
+ void gpiochip_free_own_desc(struct gpio_desc *desc)
Descriptors requested with gpiochip_request_own_desc() must be released with
gpiochip_free_own_desc().
--
2.35.1
On Wed, Nov 30, 2022 at 4:55 PM Andy Shevchenko
<[email protected]> wrote:
> The true Hi-Z (a.k.a. high impedance) mode is when pin is completely
> disconnected from the chip. This includes input buffer as well.
> Nevertheless, some hardware may not support that mode and they are
> considering input only as Hi-Z, but more precisely it is an equivalent
> to that, in electronics it's basically "an antenna mode".
>
> Sligthly correct documentation to take the above into consideration.
>
> Signed-off-by: Andy Shevchenko <[email protected]>
Reviewed-by: Linus Walleij <[email protected]>
Yours,
Linus Walleij
On Wed, Nov 30, 2022 at 4:55 PM Andy Shevchenko
<[email protected]> wrote:
> The code blocks are indented with two spaces, if the leading TAB
> is occurred the syntax highlighting might be broken in some editors.
> To prevent that unify all code blocks by using spaces instead of
> leading TAB(s).
>
> Signed-off-by: Andy Shevchenko <[email protected]>
Acked-by: Linus Walleij <[email protected]>
Yours,
Linus Walleij
On Wed, Nov 30, 2022 at 4:55 PM Andy Shevchenko
<[email protected]> wrote:
> +The below table gathered the most used cases.
> +
> +========== ========== =============== =======================
> + Input Output State What value to return?
> +========== ========== =============== =======================
> + Disabled Disabled Hi-Z input buffer
> + Disabled OS/OD/etc Single ended [cached] output buffer
> + x Push-Pull Out [cached] output buffer
> + Enabled Disabled In input buffer
> + Enabled OS/OD/etc Bidirectional input buffer
> +========== ========== =============== =======================
This looks about right to me, but we need more input, Kent?
Yours,
Linus Walleij
Hi Linus,
On 12/3/22 10:38, Linus Walleij wrote:
> On Wed, Nov 30, 2022 at 4:55 PM Andy Shevchenko
> <[email protected]> wrote:
>
>> +The below table gathered the most used cases.
>> +
>> +========== ========== =============== =======================
>> + Input Output State What value to return?
>> +========== ========== =============== =======================
>> + Disabled Disabled Hi-Z input buffer
>> + Disabled OS/OD/etc Single ended [cached] output buffer
>> + x Push-Pull Out [cached] output buffer
>> + Enabled Disabled In input buffer
>> + Enabled OS/OD/etc Bidirectional input buffer
>> +========== ========== =============== =======================
>
> This looks about right to me, but we need more input, Kent?
As I already mentioned in earlier replies to me this
seems to make things needlessly complicated for GPIO chips
where there are separate registers for reading the input-buffer vs
setting the output-buffer.
To implement the above drivers for these would need to check if
the pin is in push/pull mode and then read the register setting
the output-buffer in get() while reading the register reading
from the input-buffer in other cases in get().
I fail to see any downsides to just always reading
the register reading the input-buffer on GPIO chips like this,
when the pin in in push/pull output mode that should simply
give us the right value and when it does not this could
help detect short-circuits to Gnd/Vdd.
Where as I fear that implementing 2 different strategies in
get() for these kinda GPIO chips, will most likely be a
source of bug. Esp. since testing all the permutations
from the above table is going to be tricky in many cases.
If we go this route and demand that drivers for GPIO chips
with a separate (read-only) register for the input-buffer
sometimes read the register for the output-buffer on get()
can we then add a helper to the core which returns which
of the 2 registers should be used so that drivers don't
have to duplicate the logic for checking this ?
Regards,
Hans
On Sat, Dec 03, 2022 at 10:38:45AM +0100, Linus Walleij wrote:
> On Wed, Nov 30, 2022 at 4:55 PM Andy Shevchenko
> <[email protected]> wrote:
>
> > +The below table gathered the most used cases.
> > +
> > +========== ========== =============== =======================
> > + Input Output State What value to return?
> > +========== ========== =============== =======================
> > + Disabled Disabled Hi-Z input buffer
> > + Disabled OS/OD/etc Single ended [cached] output buffer
> > + x Push-Pull Out [cached] output buffer
> > + Enabled Disabled In input buffer
> > + Enabled OS/OD/etc Bidirectional input buffer
> > +========== ========== =============== =======================
>
> This looks about right to me, but we need more input, Kent?
>
Firstly, I'm all for tightening up the driver contract, and hope that
whatever is decided will also be updated in driver.h itself.
I can also understand Andy wanting to add support for Bidirectional
using the existing API.
But, and please correct me if I'm wrong, the user has no control over
whether an open drain output is single ended or bidirectional, and
no visibility as to which the driver supports or chooses.
So the contract is still vague.
My preference would be for the driver API to be extended with a new
callback for the output buffer, say get_output(), and have the existing
get() always return the input buffer. Both would return an error if the
buffer is unavailable or disconnected, e.g. in the Hi-Z case.
As per Hans' suggestions, this would keep the drivers simple.
Then cdev could determine the approriate buffer to return, depending
on the mode. Or, better yet, we extend that through the uAPI and
handball that decision to the user.
Cheers,
Kent.
On Mon, Dec 05, 2022 at 09:43:32AM +0800, Kent Gibson wrote:
> On Sat, Dec 03, 2022 at 10:38:45AM +0100, Linus Walleij wrote:
> > On Wed, Nov 30, 2022 at 4:55 PM Andy Shevchenko
> > <[email protected]> wrote:
> >
> > > +The below table gathered the most used cases.
> > > +
> > > +========== ========== =============== =======================
> > > + Input Output State What value to return?
> > > +========== ========== =============== =======================
> > > + Disabled Disabled Hi-Z input buffer
> > > + Disabled OS/OD/etc Single ended [cached] output buffer
> > > + x Push-Pull Out [cached] output buffer
> > > + Enabled Disabled In input buffer
> > > + Enabled OS/OD/etc Bidirectional input buffer
> > > +========== ========== =============== =======================
> >
> > This looks about right to me, but we need more input, Kent?
> >
>
> Firstly, I'm all for tightening up the driver contract, and hope that
> whatever is decided will also be updated in driver.h itself.
>
> I can also understand Andy wanting to add support for Bidirectional
> using the existing API.
>
> But, and please correct me if I'm wrong, the user has no control over
> whether an open drain output is single ended or bidirectional, and
> no visibility as to which the driver supports or chooses.
> So the contract is still vague.
>
> My preference would be for the driver API to be extended with a new
> callback for the output buffer, say get_output(), and have the existing
> get() always return the input buffer. Both would return an error if the
> buffer is unavailable or disconnected, e.g. in the Hi-Z case.
> As per Hans' suggestions, this would keep the drivers simple.
That's not about keeping driver simple, it's about how from hardware
(electrical) point of view we should recognize the GPIO signal value.
And I disagree on the input buffer to be always involved (in particular,
not all hardware may support that anyway). That said, I will send an answer
to all you guys, but just to make sure that we are on the different pages
here I state yet another time that this is not about solely software p.o.v.
And yes, there is no simple answer to the question.
> Then cdev could determine the approriate buffer to return, depending
> on the mode. Or, better yet, we extend that through the uAPI and
> handball that decision to the user.
TL;DR: I don't like this idea.
--
With Best Regards,
Andy Shevchenko
On Mon, Dec 05, 2022 at 02:08:32PM +0200, Andy Shevchenko wrote:
> On Mon, Dec 05, 2022 at 09:43:32AM +0800, Kent Gibson wrote:
> > On Sat, Dec 03, 2022 at 10:38:45AM +0100, Linus Walleij wrote:
> > > On Wed, Nov 30, 2022 at 4:55 PM Andy Shevchenko
> > > <[email protected]> wrote:
> > >
> > > > +The below table gathered the most used cases.
> > > > +
> > > > +========== ========== =============== =======================
> > > > + Input Output State What value to return?
> > > > +========== ========== =============== =======================
> > > > + Disabled Disabled Hi-Z input buffer
> > > > + Disabled OS/OD/etc Single ended [cached] output buffer
> > > > + x Push-Pull Out [cached] output buffer
> > > > + Enabled Disabled In input buffer
> > > > + Enabled OS/OD/etc Bidirectional input buffer
> > > > +========== ========== =============== =======================
> > >
> > > This looks about right to me, but we need more input, Kent?
> > >
> >
> > Firstly, I'm all for tightening up the driver contract, and hope that
> > whatever is decided will also be updated in driver.h itself.
> >
> > I can also understand Andy wanting to add support for Bidirectional
> > using the existing API.
> >
> > But, and please correct me if I'm wrong, the user has no control over
> > whether an open drain output is single ended or bidirectional, and
> > no visibility as to which the driver supports or chooses.
> > So the contract is still vague.
> >
> > My preference would be for the driver API to be extended with a new
> > callback for the output buffer, say get_output(), and have the existing
> > get() always return the input buffer. Both would return an error if the
> > buffer is unavailable or disconnected, e.g. in the Hi-Z case.
> > As per Hans' suggestions, this would keep the drivers simple.
>
> That's not about keeping driver simple, it's about how from hardware
> (electrical) point of view we should recognize the GPIO signal value.
> And I disagree on the input buffer to be always involved (in particular,
> not all hardware may support that anyway). That said, I will send an answer
> to all you guys, but just to make sure that we are on the different pages
> here I state yet another time that this is not about solely software p.o.v.
> And yes, there is no simple answer to the question.
>
To be clear, my suggestion is focussed on providing visibility to allow
the user to determine if their hardware supports their use case - without
them having to get out a scope to check.
And it doesn't care what those use cases are.
The fact that it also keeps the driver logic simple is a happy
coincidence, but I agree with Hans that that is a huge benefit and so
reiterated it above. My bad if that gave the impression that was my
primary focus.
> > Then cdev could determine the approriate buffer to return, depending
> > on the mode. Or, better yet, we extend that through the uAPI and
> > handball that decision to the user.
>
> TL;DR: I don't like this idea.
>
And yours paints us into a corner.
Cheers,
Kent.
On Mon, Dec 5, 2022 at 2:43 AM Kent Gibson <[email protected]> wrote:
> My preference would be for the driver API to be extended with a new
> callback for the output buffer, say get_output(), and have the existing
> get() always return the input buffer.
This has a certain elegance to it, as it cuts to the bone of the
problem and partition it in two halves, reflecting the two pieces
of hardware: input and output buffer. Also follows Rusty Russells
API hierarchy.
Yours,
Linus Walleij
On Wed, Dec 07, 2022 at 01:06:46AM +0100, Linus Walleij wrote:
> On Mon, Dec 5, 2022 at 2:43 AM Kent Gibson <[email protected]> wrote:
>
> > My preference would be for the driver API to be extended with a new
> > callback for the output buffer, say get_output(), and have the existing
> > get() always return the input buffer.
>
> This has a certain elegance to it, as it cuts to the bone of the
> problem and partition it in two halves, reflecting the two pieces
> of hardware: input and output buffer. Also follows Rusty Russells
> API hierarchy.
The (one of) problem is that not all hardware may support input and output
be enabled at the same time. What would that new API return in that case
and how it would be better with get() returning the value depending on
direction?
--
With Best Regards,
Andy Shevchenko
On Wed, Dec 07, 2022 at 11:55:50AM +0200, Andy Shevchenko wrote:
> On Wed, Dec 07, 2022 at 01:06:46AM +0100, Linus Walleij wrote:
> > On Mon, Dec 5, 2022 at 2:43 AM Kent Gibson <[email protected]> wrote:
> >
> > > My preference would be for the driver API to be extended with a new
> > > callback for the output buffer, say get_output(), and have the existing
> > > get() always return the input buffer.
> >
> > This has a certain elegance to it, as it cuts to the bone of the
> > problem and partition it in two halves, reflecting the two pieces
> > of hardware: input and output buffer. Also follows Rusty Russells
> > API hierarchy.
>
> The (one of) problem is that not all hardware may support input and output
> be enabled at the same time.
Exactly - and you want to hide that from the user.
> What would that new API return in that case
> and how it would be better with get() returning the value depending on
> direction?
>
It would return an error for whichever is not supported. So get()
returns an error when the input buffer is unavailable, and get_output()
returns an error when the output buffer is unavailable. And that is for
whatever reason, e.g. the selected mode or lacking hardware or driver
support.
It is better because the user is explicitly informed that the buffer
they are trying to read from is not supported by the current
configuration. And they get to choose which buffer they want to read
as they see fit - not have that selection made for them by magic.
Cheers,
Kent.
On Wed, Dec 7, 2022 at 10:56 AM Andy Shevchenko
<[email protected]> wrote:
> On Wed, Dec 07, 2022 at 01:06:46AM +0100, Linus Walleij wrote:
> > On Mon, Dec 5, 2022 at 2:43 AM Kent Gibson <[email protected]> wrote:
> >
> > > My preference would be for the driver API to be extended with a new
> > > callback for the output buffer, say get_output(), and have the existing
> > > get() always return the input buffer.
> >
> > This has a certain elegance to it, as it cuts to the bone of the
> > problem and partition it in two halves, reflecting the two pieces
> > of hardware: input and output buffer. Also follows Rusty Russells
> > API hierarchy.
>
> The (one of) problem is that not all hardware may support input and output
> be enabled at the same time. What would that new API return in that case
> and how it would be better with get() returning the value depending on
> direction?
I imagine we would leave the .get_output() unassigned and the core
would just rely on whatever behaviour it has now, so in *that* case,
the implementation of .get() will need to be more elaborate.
Yours,
Linus Walleij
On Sat, Dec 03, 2022 at 10:33:50AM +0100, Linus Walleij wrote:
> On Wed, Nov 30, 2022 at 4:55 PM Andy Shevchenko
> <[email protected]> wrote:
>
> > The true Hi-Z (a.k.a. high impedance) mode is when pin is completely
> > disconnected from the chip. This includes input buffer as well.
> > Nevertheless, some hardware may not support that mode and they are
> > considering input only as Hi-Z, but more precisely it is an equivalent
> > to that, in electronics it's basically "an antenna mode".
> >
> > Sligthly correct documentation to take the above into consideration.
> >
> > Signed-off-by: Andy Shevchenko <[email protected]>
>
> Reviewed-by: Linus Walleij <[email protected]>
Bart, can you apply only the first patch from the series, on which we have
a consensus (I believe?).
--
With Best Regards,
Andy Shevchenko
On Fri, Mar 10, 2023 at 6:25 PM Andy Shevchenko
<[email protected]> wrote:
>
> On Sat, Dec 03, 2022 at 10:33:50AM +0100, Linus Walleij wrote:
> > On Wed, Nov 30, 2022 at 4:55 PM Andy Shevchenko
> > <[email protected]> wrote:
> >
> > > The true Hi-Z (a.k.a. high impedance) mode is when pin is completely
> > > disconnected from the chip. This includes input buffer as well.
> > > Nevertheless, some hardware may not support that mode and they are
> > > considering input only as Hi-Z, but more precisely it is an equivalent
> > > to that, in electronics it's basically "an antenna mode".
> > >
> > > Sligthly correct documentation to take the above into consideration.
> > >
> > > Signed-off-by: Andy Shevchenko <[email protected]>
> >
> > Reviewed-by: Linus Walleij <[email protected]>
>
> Bart, can you apply only the first patch from the series, on which we have
> a consensus (I believe?).
>
> --
> With Best Regards,
> Andy Shevchenko
>
>
Applied, thanks!
Bart