Hi,
On 11/30/22 16:55, Andy Shevchenko wrote:
> 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
You need to clarify what single-ended means here. You mean a pin
which is only capable of output I guess ? So now way to figure
out if another participant in the OS/OD bus has its transistor
in the "on" state this pulling the bus high / low agains the bias
resistor(s) which determine the state of the bus in rest ?
Or you mean that the bus is uni-directional, even then being
able to detect a short-circuit is useful.
> + x Push-Pull Out [cached] output buffer
Why, most GPIO drivers are protected against short-circuit to
GND / Vdd and actually reading the input-buffer here will allow
GPIO API consumers to detect such short-circuits if they are
interested in this. This would e.g. be useful to detect
mis-wiring on devices like the Raspberry Pi were users often
connect extra peripherals through breadboards.
IMHO for pins with an input buffer get() should simply
always return the contents of the input buffer. This is what
I believe almost all GPIO drivers currently do and also
keeps the get() methods KISS.
Actually implementing the behavior you suggest here requires
the get() method to differentiate between push-pull and
other mode. This makes the get() method implementation
needlessly complicated and will likely be a source of bugs
as people will get this wrong in some cases and people
will very likely not test all possible combinations from
this big table you are adding here.
IHMO the rules for get() should simply be:
1. Device has an input buffer:
Return input-buffer value for the pin.
2. Devices does not have an input buffer:
Return last set output-buffer value
Regards,
Hans
> + 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
> ===========================
>
Hi again,
On 11/30/22 17:12, Hans de Goede wrote:
> Hi,
>
> On 11/30/22 16:55, Andy Shevchenko wrote:
>> 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
>
> You need to clarify what single-ended means here. You mean a pin
> which is only capable of output I guess ? So now way to figure
> out if another participant in the OS/OD bus has its transistor
> in the "on" state this pulling the bus high / low agains the bias
> resistor(s) which determine the state of the bus in rest ?
>
> Or you mean that the bus is uni-directional? Even then being
> able to detect a short-circuit is useful.
>
>> + x Push-Pull Out [cached] output buffer
>
> Why, most GPIO drivers are protected against short-circuit to
> GND / Vdd and actually reading the input-buffer here will allow
> GPIO API consumers to detect such short-circuits if they are
> interested in this. This would e.g. be useful to detect
> mis-wiring on devices like the Raspberry Pi were users often
> connect extra peripherals through breadboards.
>
> IMHO for pins with an input buffer get() should simply
> always return the contents of the input buffer. This is what
> I believe almost all GPIO drivers currently do and also
> keeps the get() methods KISS.
>
> Actually implementing the behavior you suggest here requires
> the get() method to differentiate between push-pull and
> other mode. This makes the get() method implementation
> needlessly complicated and will likely be a source of bugs
> as people will get this wrong in some cases and people
> will very likely not test all possible combinations from
> this big table you are adding here.
>
> IHMO the rules for get() should simply be:
>
> 1. Device has an input buffer:
> Return input-buffer value for the pin.
>
> 2. Devices does not have an input buffer:
> Return last set output-buffer value
Quick correction device should be pin here, because it
if there is an input buffer or not can differ per pin.
So IHMO the rules for get() should simply be:
1. pin has an input buffer:
return input-buffer value for the pin.
2. pin does not have an input buffer:
return the value last set for the pin's output-buffer
Regards,
Hans
>> + 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
>> ===========================
>>
>
On Wed, Nov 30, 2022 at 05:12:13PM +0100, Hans de Goede wrote:
> On 11/30/22 16:55, Andy Shevchenko wrote:
> > 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.
...
> > +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
>
> You need to clarify what single-ended means here. You mean a pin
> which is only capable of output I guess ? So now way to figure
> out if another participant in the OS/OD bus has its transistor
> in the "on" state this pulling the bus high / low agains the bias
> resistor(s) which determine the state of the bus in rest ?
>
> Or you mean that the bus is uni-directional, even then being
> able to detect a short-circuit is useful.
It's described in the previous chapter(s).
> > + x Push-Pull Out [cached] output buffer
>
> Why, most GPIO drivers are protected against short-circuit to
> GND / Vdd and actually reading the input-buffer here will allow
> GPIO API consumers to detect such short-circuits if they are
> interested in this. This would e.g. be useful to detect
> mis-wiring on devices like the Raspberry Pi were users often
> connect extra peripherals through breadboards.
I think it is nonsense from electronics point of view.
> IMHO for pins with an input buffer get() should simply
> always return the contents of the input buffer. This is what
> I believe almost all GPIO drivers currently do and also
> keeps the get() methods KISS.
As you can see, I disagree on this.
> Actually implementing the behavior you suggest here requires
> the get() method to differentiate between push-pull and
> other mode. This makes the get() method implementation
> needlessly complicated and will likely be a source of bugs
> as people will get this wrong in some cases and people
> will very likely not test all possible combinations from
> this big table you are adding here.
People already are getting wrong this and here is no documentation
on what to do to get it right.
> IHMO the rules for get() should simply be:
>
> 1. Device has an input buffer:
> Return input-buffer value for the pin.
I disagree on this. It makes no sense to read real hw wire state when output
is enabled. If somebody does a short circuit, it's not a Linux issue and
should be recognized on the PCB side (using oscilloscope, multi-meter, etc).
> 2. Devices does not have an input buffer:
> Return last set output-buffer value
> > + 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).
--
With Best Regards,
Andy Shevchenko
On Wed, Nov 30, 2022 at 05:14:38PM +0100, Hans de Goede wrote:
> On 11/30/22 17:12, Hans de Goede wrote:
> > On 11/30/22 16:55, Andy Shevchenko wrote:
...
> > IHMO the rules for get() should simply be:
> >
> > 1. Device has an input buffer:
> > Return input-buffer value for the pin.
> >
> > 2. Devices does not have an input buffer:
> > Return last set output-buffer value
>
> Quick correction device should be pin here, because it
> if there is an input buffer or not can differ per pin.
> So IHMO the rules for get() should simply be:
>
> 1. pin has an input buffer:
> return input-buffer value for the pin.
>
> 2. pin does not have an input buffer:
> return the value last set for the pin's output-buffer
"pin" misleads here. The "pin" can be in native function which may have not be
even connected to GPIO buffers. There are different hardware topologies.
So, no, not a "pin".
--
With Best Regards,
Andy Shevchenko
Hi,
On 11/30/22 17:20, Andy Shevchenko wrote:
> On Wed, Nov 30, 2022 at 05:12:13PM +0100, Hans de Goede wrote:
>> On 11/30/22 16:55, Andy Shevchenko wrote:
>>> 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.
>
> ...
>
>>> +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
>>
>> You need to clarify what single-ended means here. You mean a pin
>> which is only capable of output I guess ? So now way to figure
>> out if another participant in the OS/OD bus has its transistor
>> in the "on" state this pulling the bus high / low agains the bias
>> resistor(s) which determine the state of the bus in rest ?
>>
>> Or you mean that the bus is uni-directional, even then being
>> able to detect a short-circuit is useful.
>
> It's described in the previous chapter(s).
>
>>> + x Push-Pull Out [cached] output buffer
>>
>> Why, most GPIO drivers are protected against short-circuit to
>> GND / Vdd and actually reading the input-buffer here will allow
>> GPIO API consumers to detect such short-circuits if they are
>> interested in this. This would e.g. be useful to detect
>> mis-wiring on devices like the Raspberry Pi were users often
>> connect extra peripherals through breadboards.
>
> I think it is nonsense from electronics point of view.
>
>> IMHO for pins with an input buffer get() should simply
>> always return the contents of the input buffer. This is what
>> I believe almost all GPIO drivers currently do and also
>> keeps the get() methods KISS.
>
> As you can see, I disagree on this.
>
>> Actually implementing the behavior you suggest here requires
>> the get() method to differentiate between push-pull and
>> other mode. This makes the get() method implementation
>> needlessly complicated and will likely be a source of bugs
>> as people will get this wrong in some cases and people
>> will very likely not test all possible combinations from
>> this big table you are adding here.
>
> People already are getting wrong this and here is no documentation
> on what to do to get it right.
>
>> IHMO the rules for get() should simply be:
>>
>> 1. Device has an input buffer:
>> Return input-buffer value for the pin.
>
> I disagree on this. It makes no sense to read real hw wire state when output
> is enabled. If somebody does a short circuit, it's not a Linux issue and
> should be recognized on the PCB side (using oscilloscope, multi-meter, etc).
What is the disadvantage of reading the real hw wire state ?
The list of advantages / disadvantages I can come up with GPIO
controllers which always allow access to the input buffers is:
Disadvantanges of having get() always return the input-buffer
1. It is slower then returning the last output value cached on
the kernel side. But this too wil complicate the driver
code, since this requires populating the cache at boot
(or relying on regmap caching)
Advantages of having get() always return the input-buffer:
1. It leads to a very simple / KISS get() implementation
2. One has to wonder why a GPIO API consumer puts a pin
in push/pull output mode and then calls get() anyways ?
This is an unlikely scenario (making disadvantage 1.
not a problem) and in the unlikely case that an API
consumer does this they likely want the real hw wire state.
I guess the reason why you want to return a cached output value
is because not all GPIO controllers allow access to the input
buffer when in output mode ? At least that is the only good reason
I can come up with ?
Specifically there are GPIO controllers which have a single data
register for the GPIOs rather then separate data in + data out
registers. Even then chances are that a read from the data
register *always* goes to the input-buffer rather then reading
the last written value when in output mode. This is likely since
simply always latching the data from the input-buffer on a read
from a shared in/out data register is easier to implement in hw.
So thinking more about this, I believe that the answer what
to return on a get() from a GPIO configured as push/pull output
is implementation dependent. For GPIO chips with a shared in/out
data register it is the value of that register, which may be
a cached output value or the input-buffer value and for GPIO
chips with a separate register to read the input-buffer it
should simply always be the input buffer.
Regards,
Hans
>
>> 2. Devices does not have an input buffer:
>> Return last set output-buffer value
>
>>> + 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).
>