Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <8a53e88b-1e74-bf34-62a1-780a1b29bcbc@redhat.com>
Date:   Wed, 30 Nov 2022 17:12:13 +0100
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.5.0
Subject: Re: [PATCH v1 2/3] Documentation: gpio: Add a section on what to
 return in ->get() callback
Content-Language: en-US, nl
To:     Andy Shevchenko <andriy.shevchenko@linux.intel.com>,
        Marc Zyngier <maz@kernel.org>, linux-gpio@vger.kernel.org,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Cc:     Linus Walleij <linus.walleij@linaro.org>,
        Bartosz Golaszewski <brgl@bgdev.pl>,
        Jonathan Corbet <corbet@lwn.net>
References: <20221130155519.20362-1-andriy.shevchenko@linux.intel.com>
 <20221130155519.20362-2-andriy.shevchenko@linux.intel.com>
From:   Hans de Goede <hdegoede@redhat.com>
In-Reply-To: <20221130155519.20362-2-andriy.shevchenko@linux.intel.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

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 <andriy.shevchenko@linux.intel.com>
> ---
>  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
>  ===========================
>