Re: [libgpiod] libgpiod v2.0 API discussion

[Bartosz Golaszewski <brgl@xxxxxxxx>]

On Thu, Nov 5, 2020 at 2:50 PM Kent Gibson <warthog618@xxxxxxxxx> wrote:
>

[snip]

>
> As I think I've mentioned elsewhere, my preferred approach for
> rethinking the libgpiod API for v2 is to shrink the API to the core
> functions, rethink that set wrt how it maps onto and exposes the
> features available in uAPI v2, and then expand that revised set with
> helpers as appropriate, and then rethink the bindings.
>

What I understood from your previous email is your preference for
going into the direction of exposing more of the underlying kernel API
to users or maybe even: mapping the kernel interface more strictly in
the library. I don't think we should go this way. I want to keep the
<chip, line, set of lines> model which I think is convenient and
represents the underlying hierarchy well. I also want to shield the
library users from ioctls, file descriptors (unless it's to pass them
to poll()) and even HW offsets of GPIO lines as much as possible.

This is why I'd prefer to return pointers to line objects rather than
HW offsets in event structures. Same with line requests: I'm not sure
what the advantage of having a separate request structure would be in
the library (except for representing the file descriptor received from
the kernel upon request - about which the user doesn't need to know
unless using external event loops).

I agree that there's a lot of cruft to remove but I wouldn't be so
quick to remove helpers for simplified use-cases that we have now. For
instance: if we decide to go with an opaque config structure which
needs to be allocated dynamically, then users would most likely
appreciate having helper wrappers allowing them to request lines in a
single call rather than having to deal with resource management.

[snip]

> > > > For config: I believe an opaque request config structure will require
> > > > a lot of getter/setter boiler plate code for not much profit.
> > > >
> > >
> > > The profit being a guarantee of ABI stability and backward compatibility,
> > > while still being free to completely rework the implementation
> > > internally?
> >
> > I think you can gain this profit without opaqueness.  A user can only
> > use those aspects of a config that did exist a the time the code is
> > developed. For that reason, there can be multiple versions of a
> > configuration type and the consumer can use whatever type they happend
> > to see when the code was compiled. The current configuration type can be
> > typedefd to a standard name and only needs to be API compatible with
> > previous config types (i.e. only add new fields with default
> > initializers). In C++, one can leverage function overloads to implement
> > that. In C, you can use symbol versioning or do poor-mans-symbol-
> > versioning by #defineing the consuming function names to versioned ones.
> >
> > The only downside of this seems to be that libgpiod would have to keep
> > the old types and overloads for all eternity.
> >
>
> You underestimate the power of the downside...
>
> How do you go about testing all that?
> And propagating those multiple versions through the bindings?
> And testing those?
>
> I think I'd prefer the boiler plate.
>

The scope of the library is well defined and unlikely to be expanded a
lot. To me it seems that user-facing structures for events and request
config should be fine (as long as we leave some padding for future
extensions). I don't see why would we even need multiple types of
configuration and all this nasty casting Helmut mentions? Frankly: I
don't even understand how it would work. In the end: it's not much
different than the situation with data types used in ioctls - just
have a structure with some space of expansion.

Elsewhere Kent mentioned users providing buffers for opaque event
structures. I think this is the worst of both worlds. Users still need
to know the size of the event structure and its internal
implementation can no longer change arbitrarily because this exported
size would change. Users would never be able to use static buffers
when the size can change from one version of the library to another.
Not to mention the unnecessarily complicated code this approach would
require.

Best Regards,
Bartosz Golaszewski