Documentation: gpio: Input mode is not true Hi-Z
Subsystems (2)
PATCH 1/3 Documentation: gpio: Input mode is not true Hi-Z
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.
--- Documentation/driver-api/gpio/driver.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/driver-api/gpio/driver.rst +4 -4
@@ -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.
Signature · 1 line
2.35.1
PATCH 2/3 Documentation: gpio: Add a section on what to return in ->get() callback
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.
--- Documentation/driver-api/gpio/driver.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+)
Documentation/driver-api/gpio/driver.rst +24 -0
@@ -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 ===========================
Signature · 1 line
2.35.1
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
Hi,
Quoted 22 lines · Andy Shevchenko
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(+)Documentation/driver-api/gpio/driver.rst +5
-0@@ -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.
Documentation/driver-api/gpio/driver.rst supports more versatile control over electrical properties and can handle · line 268
Quoted 10 lines
Documentation/driver-api/gpio/driver.rst +10
-0+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.
Documentation/driver-api/gpio/driver.rst supports more versatile control over electrical properties and can handle · line 269
Quoted 1 line
Documentation/driver-api/gpio/driver.rst +1
-0+ 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
Quoted 11 lines
Documentation/driver-api/gpio/driver.rst +8
-0+ 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 ===========================
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
Hi again,
Quoted 67 lines · Hans de Goede
Hi,
Quoted 22 lines · Andy Shevchenko
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(+)Documentation/driver-api/gpio/driver.rst +5
-0@@ -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.Documentation/driver-api/gpio/driver.rst supports more versatile control over electrical properties and can handle · line 268
Quoted 10 lines
Documentation/driver-api/gpio/driver.rst +10
-0+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 bufferYou 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.
Documentation/driver-api/gpio/driver.rst supports more versatile control over electrical properties and can handle · line 269
Quoted 1 line
Documentation/driver-api/gpio/driver.rst +1
-0+ x Push-Pull Out [cached] output bufferWhy, 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 theget()methods KISS.Actually implementing the behavior you suggest here requires the
get()method to differentiate between push-pull and other mode. This makes theget()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.
Quoted 7 lines
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
Quoted 12 lines
Quoted 11 lines
Documentation/driver-api/gpio/driver.rst +8
-0+ 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 ===========================
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
Quoted 2 lines · Hans de Goede
Quoted 1 line · Hans de Goede
On 11/30/22 16:55, Andy Shevchenko wrote:
...
Quoted 12 lines
Quoted 7 lines
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 valueQuick 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:
Quoted 5 lines
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".
Signature · 2 lines
With Best Regards, Andy Shevchenko
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
In reply to Hans de GoedeQuoted 4 lines · Hans de Goede
Quoted 3 lines · Andy Shevchenko
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.
...
Quoted 22 lines
Quoted 5 lines
Documentation/driver-api/gpio/driver.rst +5
-0+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.Documentation/driver-api/gpio/driver.rst supports more versatile control over electrical properties and can handle · line 268
Quoted 10 lines
Documentation/driver-api/gpio/driver.rst +10
-0+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 bufferYou 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 ?
Quoted 2 lines
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).
Quoted 8 lines
Quoted 1 line
+ 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.
Quoted 4 lines
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 theget()methods KISS.
As you can see, I disagree on this.
Quoted 7 lines
Actually implementing the behavior you suggest here requires the
get()method to differentiate between push-pull and other mode. This makes theget()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.
Quoted 4 lines
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).
Quoted 9 lines
2. Devices does not have an input buffer:
Return last set output-buffer valueQuoted 6 lines
+ Enabled Disabled In input buffer + Enabled OS/OD/etc Bidirectional input buffer+========== ========== =============== =======================
Documentation/driver-api/gpio/driver.rst +3
-0+ +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).
Signature · 2 lines
With Best Regards, Andy Shevchenko
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
Hi,
Quoted 64 lines · Andy Shevchenko
Quoted 4 lines · Hans de Goede
Quoted 3 lines · Andy Shevchenko
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.
...
Quoted 22 lines
Quoted 5 lines
Documentation/driver-api/gpio/driver.rst +5
-0+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.Documentation/driver-api/gpio/driver.rst supports more versatile control over electrical properties and can handle · line 268
Quoted 10 lines
Documentation/driver-api/gpio/driver.rst +10
-0+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 bufferYou 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 ?
Quoted 2 lines
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).
Quoted 8 lines
Quoted 1 line
+ 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.
Quoted 4 lines
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 theget()methods KISS.As you can see, I disagree on this.
Quoted 7 lines
Actually implementing the behavior you suggest here requires the
get()method to differentiate between push-pull and other mode. This makes theget()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.
Quoted 8 lines
Quoted 4 lines
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
Quoted 11 lines
Quoted 10 lines
2. Devices does not have an input buffer:
Return last set output-buffer valueQuoted 6 lines
+ Enabled Disabled In input buffer + Enabled OS/OD/etc Bidirectional input buffer+========== ========== =============== =======================
Documentation/driver-api/gpio/driver.rst +3
-0+ +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).
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
In reply to Andy ShevchenkoDocumentation/driver-api/gpio/driver.rst supports more versatile control over electrical properties and can handle · line 272
Quoted 11 lines · Andy Shevchenko
Documentation/driver-api/gpio/driver.rst +11
-0+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
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
Hi Linus,
Quoted 16 lines · Linus Walleij
Documentation/driver-api/gpio/driver.rst supports more versatile control over electrical properties and can handle · line 272
Quoted 11 lines · Andy Shevchenko
Documentation/driver-api/gpio/driver.rst +11
-0+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
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
In reply to Linus WalleijQuoted 17 lines · Linus Walleij
Documentation/driver-api/gpio/driver.rst supports more versatile control over electrical properties and can handle · line 272
Quoted 11 lines · Andy Shevchenko
Documentation/driver-api/gpio/driver.rst +11
-0+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.
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
Quoted 30 lines · Kent Gibson
Quoted 17 lines · Linus Walleij
Documentation/driver-api/gpio/driver.rst supports more versatile control over electrical properties and can handle · line 272
Quoted 11 lines · Andy Shevchenko
Documentation/driver-api/gpio/driver.rst +11
-0+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.hitself.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.
Quoted 5 lines
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 existingget()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.
Quoted 3 lines
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.
Signature · 2 lines
With Best Regards, Andy Shevchenko
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
Quoted 37 lines · Andy Shevchenko
Quoted 30 lines · Kent Gibson
Quoted 17 lines · Linus Walleij
Documentation/driver-api/gpio/driver.rst supports more versatile control over electrical properties and can handle · line 272
Quoted 11 lines · Andy Shevchenko
Documentation/driver-api/gpio/driver.rst +11
-0+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.hitself.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.
Quoted 5 lines
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 existingget()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.
Quoted 8 lines
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.
Quoted 6 lines
Quoted 3 lines
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.
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
In reply to Kent GibsonQuoted 3 lines · Kent Gibson
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 existingget()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
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
Quoted 10 lines · Linus Walleij
Quoted 3 lines · Kent Gibson
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 existingget()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?
Signature · 2 lines
With Best Regards, Andy Shevchenko
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
Quoted 7 lines · Andy Shevchenko
Quoted 6 lines · Linus Walleij
Quoted 3 lines · Kent Gibson
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 existingget()always return the input buffer.
Quoted 7 lines
Quoted 4 lines
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.
Quoted 4 lines
What would that new API return in that case
and how it would be better withget()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.
Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to return in ->get() callback
In reply to Andy ShevchenkoQuoted 12 lines · Andy Shevchenko
Quoted 10 lines · Linus Walleij
Quoted 3 lines · Kent Gibson
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 existingget()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.
Quoted 4 lines
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
PATCH 3/3 Documentation: gpio: Replace leading TABs by spaces in the code blocks
In reply to Andy ShevchenkoThe 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).
--- Documentation/driver-api/gpio/driver.rst | 28 ++++++++++++------------ 1 file changed, 14 insertions(+), 14 deletions(-)
Documentation/driver-api/gpio/driver.rst +14 -14
@@ -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().
Signature · 1 line
2.35.1
Re: [PATCH v1 3/3] Documentation: gpio: Replace leading TABs by spaces in the code blocks
Quoted 6 lines · Andy Shevchenko
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]>
Yours,
Linus Walleij
Quoted 9 lines · Andy Shevchenko
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]>
Yours,
Linus Walleij
Quoted 9 lines · Linus Walleij
Quoted 6 lines · Andy Shevchenko
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".
Quoted 5 lines
Quoted 3 lines
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?).
Signature · 2 lines
With Best Regards, Andy Shevchenko
Bartosz Golaszewski
AppliedQuoted 15 lines · Andy Shevchenko
Quoted 13 lines · Linus Walleij
Quoted 9 lines · Andy Shevchenko
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]>
Quoted 10 lines
Quoted 1 line
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