Received-SPF: pass (google.com: domain of linux-kernel+bounces-36212-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
Date: Wed, 24 Jan 2024 08:18:45 +0800
From: Kent Gibson <warthog618@gmail.com>
To: Andy Shevchenko <andy.shevchenko@gmail.com>
Cc: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org,
	linux-doc@vger.kernel.org, brgl@bgdev.pl, linus.walleij@linaro.org,
	andy@kernel.org, corbet@lwn.net
Subject: Re: [PATCH] Documentation: gpio: describe uAPI behaviour when
 hardware doesn't support requested config
Message-ID: <20240124001845.GA4578@rigel>
References: <20240123133828.141222-1-warthog618@gmail.com>
 <CAHp75Vd1dipGkCgQBENN3rLeUO+eQfOz9uKzz86eK755smqGag@mail.gmail.com>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <CAHp75Vd1dipGkCgQBENN3rLeUO+eQfOz9uKzz86eK755smqGag@mail.gmail.com>

On Tue, Jan 23, 2024 at 05:44:52PM +0200, Andy Shevchenko wrote:
> On Tue, Jan 23, 2024 at 3:39 PM Kent Gibson <warthog618@gmail.com> wrote:
> >
> > The existing uAPI documentation does not adequately describe how the kernel
> > handles the case where the underlying hardware or driver does not support
> > the requested configuration.
> >
> > Add a Configuration Support section describing that behaviour to both the
> > v1 and v2 documentation, and better document the errors returned where the
> > requested configuration cannot be supported.
>
> ...
>
> > +Bias             best effort
>

This documents the behaviour of the uAPI as it stands, so is your
problem with the documentation or the uAPI?

> So, best effort means that in some cases it won't fail. It reminds me
> of the baud rate setting in serial (TermIOS). The question here is how
> does user space know that it fell in one of such cases? (In termios
> the IOCTL updates the respective fields and then user space can get
> settings to see what has actually been applied.)
>

Best effort means it will try, but if it fails it will continue
regardless.  So the configuration is advisory, not strictly required.

As stated in the docs, userspace cannot currently tell, at least not via
the uAPI.

> Floating line is not good in some cases and user space really wants to
> know that and treat it as an error (if needed). Hence the above Q. I
> believe this needs to be explained in the documentation.
>

Indeed, and I think it is explained in the documentation - worst case it
will float.  And you wont know.  That is the way it is.

This originally came about as setting bias is entangled with
setting direction in gpiod_direction_input(), and it is best effort
there.  The reasoning stated in the doc is what I recall from
conversations at the time.

Adding bias support was the first bit of kernel code I wrote so I wasn't
about to go refactoring the guts of gpiolib - though if I were to do it
now I probably would.

If you consider the current behaviour to be a bug then we can change
that behaviour, e.g. clearing the bias setting in the line info (bascially
the desc flags) if setting fails.
But if it is baked into the ABI then we need to extend the uAPI,
e.g. with a flag requesting that the bias config be mandatory.

Cheers,
Kent.