Support uAPI v2

[hellow554]

torvalds/linux@b53911a introduces the uapi v2 which has slightly different ioctl calls. Also v1 is deprecated from that point on: torvalds/linux@b234d23

[fpagliughi]

I'm on it!

Here's what I'm thinking...

1. Clean up what we have now and bump the version to 1.0 to keep consistent with the kernel versioning. Make a v1.x branch in case we want to maintain some small fixes for it going forward. (Meaning maintain a v1.x Rust crate for a little while)
2. Start developing master toward the new v2 kernel API. When ready, we'll release the crate as version 2.0, again to keep consistent with the kernel numbering.

In addition, I need to add async support for smol/async-std, since my primary customer uses those in their code. I would probably do that first to get it in the v1 branch going forward.

How does that sound?

[eldruin]

Cool to hear!
Regarding the versioning, I would like to propose something different:

1. Keep the versioning of this crate independent from that of the kernel API being used. This is the only way to ensure we can abide by Semantic Versioning in this crate. Otherwise, we would never be able to release a breaking change in the iterface of this crate after 1.0 is out. e.g. which kernel API version does gpio-cdev 3.0 use? Also, releasing breaking changes in a minor version would be a no-go.
2. Implementation-wise, depending on how technically feasible this would be, how about defining 2 modules, one for each kernel API version? With this we could do things like:
   1. If the API version choice can be hidden from the user, we can let the user choose via cargo features but keep the same interface. Alternatively via top-level modules as a sort of "namespace".
   2. If the API version choice cannot be hidden, for example, we could expose only the v2 stuff and keep v1 in a submodule (or viceversa), also even optionally gated on a cargo feature.

What do you think?

[ryankurte]

iiinteresting, i'd echo @eldriun's thoughts, this seems neat but also like a bit of a compatibility problem / not something most users should need to care about... would it be reasonable to detect and abstract this at runtime as the default?

[fpagliughi]

Yeah, looking at it more closely, I think you guys are right.

It seems that, looking at the new header file, mostly v2 types and ioctl's were added rather than modifying the existing API, which I misunderstood when I read up on the new features. So it seems that existing v1 apps still work, although there is the notable difference that the event timestamps are now from the monotonic clock, reporting the number of seconds since the board booted (or so it seems on an RPi) rather than a time_t value.

Given that both API's are still supported side-by-side, then my idea of maintaining separate versions of this crate doesn't make sense.

But keeping with the way it was laid out in the kernel, perhaps we should follow along, and rather than try to abstract the two versions, just add support for v2 and let the application writer decide which to implement.

[fpagliughi]

Apologies for the slow start on this. I ordered a couple Raspberry Pi's to develop/test these new features... and now I have to acknowledge they they will never actually arrive!

I'll see if I can borrow a board from somewhere or seek an alternate target. Any ideas for a board that has a new kernel with v2 out of the box?

[alexferro]

Just as a note from a user of this crate here. I'd appreciate a note in the docs that the timestamps have changed clock base as of v5.7, even with the old v1 ABI as used and documented in the current crate version. While for my purposes (and probably most) CLOCK_MONOTONIC is better than CLOCK_REALTIME anyway, and none of this is your fault, I was very confused today while writing code, and looking for my bug when I kept getting times in 1970 coming out of the string formatting.
Of course, I'm not really sure how updating the docs only works as a crate publisher, so it may have to just be something that's fixed in the version when you also support the v2 ABI.

Also, it looks like v5.11 added a flag to select between the two clocks in the v2 ABI. That might be a useful feature to support.

https://docs.rs/gpio-cdev/latest/gpio_cdev/struct.LineEvent.html#method.timestamp
torvalds/linux@f885020
torvalds/linux@26d060e

On a positive note, I've really liked using this crate over my various hacky uses of the sysfs API I've used in the past, and my current project wouldn't be possible (other than writing my own version, but I learned about the gpio device interface from this crate), as I'm depending on the timestamp without it. So thanks.

As for the delays on supply, I totally feel that, and I wish I had anything spare, but I'm already developing on a borrowed unit myself...

[warthog618]

Hi. I'm the author of the aforementioned GPIO uAPI v2.

On the original point, uAPI v1 is deprecated in that new development should use v2, but v1 will continue to be supported in the kernel for the foreseeable future. But all new features will go on v2.

Wrt hardware support, the gpio-sim module has been added to the kernel recently (5.19) that makes it much easier to mock hardware for testing. The gpio-sim obsoletes the gpio-mockup module that was very difficult to use in practice, and clearly not well known. So GPIO development doesn't require actual hardware. It does require a recent kernel but that isn't a huge issue for a VM. If you need a library to setup and drive the gpio-sim, my gpiosim library provides that.

Wrt the uAPI changes, v2 is essentially v1 with a generalised and simplified object model and with room for future expansion (e,g, we couldn't readily add debounce to v1). Looking at the gpio-cdev API, seamlessly adding support for v2 will be entertaining, if not impossible, as you mirror the v1 uAPI. libgpiod itself is undergoing a complete API change for this reason, in what will be libgpiod v2. Mapping from v2 to v1 is much simpler - v2 being a superset of v1, and that is what my library gpiocdev does. Feel free to use that as a reference, or just to use it for that matter. It provides complete support for both uAPI v2 and v1, and now has support for async.

[fpagliughi]

Hey all. Sincere apologies for never getting to this last year. The open-source work was going to be done in parallel with a paid job that was providing some of the motivation, but the job kept getting pushed back, and back, and back... until now.

But looking at the current state of affairs, I wonder if the work is worth it? @warthog618 's library covers most of what I wanted to add to this one (v2 and async-io support), and the gpiosim is a nice bonus.

But... I have a fair amount of code in production that already uses this library, and would need to see what it would take to validate and then switch it all over.

What do other folks think? Has anyone compared the libraries? Is it worth keeping this one going? Or should we mark it obsolete and recommend the newer library for v2 and beyond?

[alexferro]

I have no real preference here. I am very thankful for the work that has been done on this library, but if the best thing for the ecosystem is to deprecate this and I fix my code the next time I touch the project of mine to use something newer, then so be it. But I also have a very small use case in a tiny application, so take it with the appropriate sized grain of salt.