| Message ID | 20210111133426.22040-7-brgl@bgdev.pl |
|---|---|
| State | New |
| Headers | show |
| Series | treewide: remove more cruft and | expand |
On Mon, Jan 11, 2021 at 04:15:21PM +0100, Bartosz Golaszewski wrote: > On Mon, Jan 11, 2021 at 3:45 PM Andy Shevchenko > <andy.shevchenko@gmail.com> wrote: > > > > On Mon, Jan 11, 2021 at 03:06:28PM +0100, Bartosz Golaszewski wrote: > > > On Mon, Jan 11, 2021 at 2:45 PM Andy Shevchenko > > > <andy.shevchenko@gmail.com> wrote: > > > > > > > > On Mon, Jan 11, 2021 at 3:37 PM Bartosz Golaszewski <brgl@bgdev.pl> wrote: > > > > > > > > > > From: Bartosz Golaszewski <bgolaszewski@baylibre.com> > > > > > > > > > > In order to avoid any problems with symbols missing from the host linux > > > > > kernel headers (for example: if current version of libgpiod supports > > > > > features that were added recently to the kernel but the host headers are > > > > > outdated and don't export required symbols) let's add the uapi header to > > > > > the repository and include it instead of the one in /usr/include/linux. > > > > > > > > I doubt this is a good decision. First of all if the host (or rather > > > > target, because host should not influence build of libgpiod) has > > > > > > I meant the host as in: the machine on which you build and which > > > contains the headers for the target as well but I see what you mean. > > > > > > > outdated header it may be for a reason (it runs old kernel). > > > > When you run new library on outdated kernel it might produce various > > > > of interesting errors (in general, I haven't investigated libgpiod > > > > case). > > > > On top of that you make a copy'n'paste source code which is against > > > > the Unix way. > > > > > > > > Sorry, but I'm in favour of dropping this one. > > > > > > > > > > Cc: Thomas > > > > > > This problem has been raised by the buildroot people when we started > > > requiring different versions of kernel headers to build v1.4 and v1.6. > > > It turns out most projects simply package the uapi headers together > > > with their sources (e.g. wpa_supplicant, libnl, iproute2) to avoid > > > complicated dependencies. It's true that now the library can fail at > > > runtime but I'm fine with that. Also: if we add new features between > > > two kernel versions, we still allow to build the new library version > > > except that these new features won't work on older kernels. > > > > I see. > > > > So known ways to solve this are > > - provide a header with source tree (see above) > > - modify code with ifdeffery against specific kernel versions > > - ...something else... ? > > > > Second item is what ALSA used (not sure if they provide a standalone driver > > anymore). Ugly, but won't require header which may be staled. > > > > Any other solutions in mind? > > > > I tried to go the third way and just ignore the problem but I've > received too many emails about that. :) > > I don't like the ifdef hell so I prefer to bundle the header. I'm open > to other suggestions, although I can't come up with anything else. > Going off on a bit of a tangent, but I'm trying to add support for decoding the GPIO ioctls into strace and am running up against a similar issue. The way strace does it is to check the uAPI header on the host and use it if possible. To handle where it may be stale, local types are defined that mirror any types that may have been added since the header was originally released. If the corresponding type is available in the linux header then it is used, else the local type. This obviously creates a lot of pointless boilerplate code and preprocessor chicanery so I floated the idea of just including the latest header in the strace tree, as you are doing here for libgpiod. But that raised the issue of licencing, specifically if you copy the linux/gpio.h into a source tree does that mean that the whole project becomes GPL 2.0? That is an issue for strace as it is LGPL 2.1 - as is libgpiod. The Linux uAPI headers are under the GPL-2.0 WITH Linux-syscall-note, which is also not totally clear on this point[1]. My gut feeling was that using and even copying API headers doesn't constitute a derived work, as per the FSF view quoted in [1], and ethically might even be less of a violation than copying and re-defining individual types, but I'd rather not rely on a gut feeling. Is there some clear opinion or precedent on this point? i.e. are libgpiod and strace in legal licence jeopardy if they include gpio.h in their source tree? Cheers, Kent. [1] https://lkml.org/lkml/2020/2/21/2193
On Mon, Jan 25, 2021 at 7:55 AM Kent Gibson <warthog618@gmail.com> wrote: > On Mon, Jan 11, 2021 at 04:15:21PM +0100, Bartosz Golaszewski wrote: > > On Mon, Jan 11, 2021 at 3:45 PM Andy Shevchenko > > <andy.shevchenko@gmail.com> wrote: > > > On Mon, Jan 11, 2021 at 03:06:28PM +0100, Bartosz Golaszewski wrote: > > > > On Mon, Jan 11, 2021 at 2:45 PM Andy Shevchenko > > > > <andy.shevchenko@gmail.com> wrote: > > > > > On Mon, Jan 11, 2021 at 3:37 PM Bartosz Golaszewski <brgl@bgdev.pl> wrote: > > > > > > > > > > > > From: Bartosz Golaszewski <bgolaszewski@baylibre.com> > > > > > > > > > > > > In order to avoid any problems with symbols missing from the host linux > > > > > > kernel headers (for example: if current version of libgpiod supports > > > > > > features that were added recently to the kernel but the host headers are > > > > > > outdated and don't export required symbols) let's add the uapi header to > > > > > > the repository and include it instead of the one in /usr/include/linux. > > > > > > > > > > I doubt this is a good decision. First of all if the host (or rather > > > > > target, because host should not influence build of libgpiod) has > > > > > > > > I meant the host as in: the machine on which you build and which > > > > contains the headers for the target as well but I see what you mean. > > > > > > > > > outdated header it may be for a reason (it runs old kernel). > > > > > When you run new library on outdated kernel it might produce various > > > > > of interesting errors (in general, I haven't investigated libgpiod > > > > > case). > > > > > On top of that you make a copy'n'paste source code which is against > > > > > the Unix way. > > > > > > > > > > Sorry, but I'm in favour of dropping this one. > > > > > > > > > > > > > Cc: Thomas > > > > > > > > This problem has been raised by the buildroot people when we started > > > > requiring different versions of kernel headers to build v1.4 and v1.6. > > > > It turns out most projects simply package the uapi headers together > > > > with their sources (e.g. wpa_supplicant, libnl, iproute2) to avoid > > > > complicated dependencies. It's true that now the library can fail at > > > > runtime but I'm fine with that. Also: if we add new features between > > > > two kernel versions, we still allow to build the new library version > > > > except that these new features won't work on older kernels. > > > > > > I see. > > > > > > So known ways to solve this are > > > - provide a header with source tree (see above) > > > - modify code with ifdeffery against specific kernel versions > > > - ...something else... ? > > > > > > Second item is what ALSA used (not sure if they provide a standalone driver > > > anymore). Ugly, but won't require header which may be staled. > > > > > > Any other solutions in mind? > > > > > > > I tried to go the third way and just ignore the problem but I've > > received too many emails about that. :) > > > > I don't like the ifdef hell so I prefer to bundle the header. I'm open > > to other suggestions, although I can't come up with anything else. > > > > Going off on a bit of a tangent, but I'm trying to add support for > decoding the GPIO ioctls into strace and am running up against a similar > issue. > > The way strace does it is to check the uAPI header on the host and use > it if possible. To handle where it may be stale, local types are > defined that mirror any types that may have been added since the header > was originally released. If the corresponding type is available in the > linux header then it is used, else the local type. > > This obviously creates a lot of pointless boilerplate code and > preprocessor chicanery so I floated the idea of just including the latest > header in the strace tree, as you are doing here for libgpiod. > But that raised the issue of licencing, specifically if you copy the > linux/gpio.h into a source tree does that mean that the whole project > becomes GPL 2.0? That is an issue for strace as it is LGPL 2.1 - as is > libgpiod. Very good point! > The Linux uAPI headers are under the GPL-2.0 WITH Linux-syscall-note, > which is also not totally clear on this point[1]. > > My gut feeling was that using and even copying API headers doesn't > constitute a derived work, as per the FSF view quoted in [1], and > ethically might even be less of a violation than copying and re-defining > individual types, but I'd rather not rely on a gut feeling. This reminds me of the Google vs. Oracle case where they pointed out the header files (IIRC!). > Is there some clear opinion or precedent on this point? > i.e. are libgpiod and strace in legal licence jeopardy if they include > gpio.h in their source tree? > [1] https://lkml.org/lkml/2020/2/21/2193 -- With Best Regards, Andy Shevchenko
On Mon, Jan 25, 2021 at 6:55 AM Kent Gibson <warthog618@gmail.com> wrote: > [snip!] > > > > I don't like the ifdef hell so I prefer to bundle the header. I'm open > > to other suggestions, although I can't come up with anything else. > > > > Going off on a bit of a tangent, but I'm trying to add support for > decoding the GPIO ioctls into strace and am running up against a similar > issue. > > The way strace does it is to check the uAPI header on the host and use > it if possible. To handle where it may be stale, local types are > defined that mirror any types that may have been added since the header > was originally released. If the corresponding type is available in the > linux header then it is used, else the local type. > > This obviously creates a lot of pointless boilerplate code and > preprocessor chicanery so I floated the idea of just including the latest > header in the strace tree, as you are doing here for libgpiod. > But that raised the issue of licencing, specifically if you copy the > linux/gpio.h into a source tree does that mean that the whole project > becomes GPL 2.0? That is an issue for strace as it is LGPL 2.1 - as is > libgpiod. > > The Linux uAPI headers are under the GPL-2.0 WITH Linux-syscall-note, > which is also not totally clear on this point[1]. > > My gut feeling was that using and even copying API headers doesn't > constitute a derived work, as per the FSF view quoted in [1], and > ethically might even be less of a violation than copying and re-defining > individual types, but I'd rather not rely on a gut feeling. > > Is there some clear opinion or precedent on this point? > i.e. are libgpiod and strace in legal licence jeopardy if they include > gpio.h in their source tree? > > Cheers, > Kent. > > [1] https://lkml.org/lkml/2020/2/21/2193 Thanks for pointing that out. I lack the legal knowledge to have an opinion of my own on this. Cc'ing Greg KH for help. Greg: do you know if it's fine to bundle a 'GPL-2.0 WITH Linux-syscall-note' uAPI header together with an LGPL-v2.1-or-later user-space shared library? Best Regards, Bartosz Golaszewski
On Tue, Jan 26, 2021 at 04:07:47PM +0100, Bartosz Golaszewski wrote: > On Mon, Jan 25, 2021 at 6:55 AM Kent Gibson <warthog618@gmail.com> wrote: > > > > [snip!] > > > > > > > I don't like the ifdef hell so I prefer to bundle the header. I'm open > > > to other suggestions, although I can't come up with anything else. > > > > > > > Going off on a bit of a tangent, but I'm trying to add support for > > decoding the GPIO ioctls into strace and am running up against a similar > > issue. > > > > The way strace does it is to check the uAPI header on the host and use > > it if possible. To handle where it may be stale, local types are > > defined that mirror any types that may have been added since the header > > was originally released. If the corresponding type is available in the > > linux header then it is used, else the local type. > > > > This obviously creates a lot of pointless boilerplate code and > > preprocessor chicanery so I floated the idea of just including the latest > > header in the strace tree, as you are doing here for libgpiod. > > But that raised the issue of licencing, specifically if you copy the > > linux/gpio.h into a source tree does that mean that the whole project > > becomes GPL 2.0? That is an issue for strace as it is LGPL 2.1 - as is > > libgpiod. > > > > The Linux uAPI headers are under the GPL-2.0 WITH Linux-syscall-note, > > which is also not totally clear on this point[1]. > > > > My gut feeling was that using and even copying API headers doesn't > > constitute a derived work, as per the FSF view quoted in [1], and > > ethically might even be less of a violation than copying and re-defining > > individual types, but I'd rather not rely on a gut feeling. > > > > Is there some clear opinion or precedent on this point? > > i.e. are libgpiod and strace in legal licence jeopardy if they include > > gpio.h in their source tree? > > > > Cheers, > > Kent. > > > > [1] https://lkml.org/lkml/2020/2/21/2193 > > Thanks for pointing that out. I lack the legal knowledge to have an > opinion of my own on this. > > Cc'ing Greg KH for help. > > Greg: do you know if it's fine to bundle a 'GPL-2.0 WITH > Linux-syscall-note' uAPI header together with an LGPL-v2.1-or-later > user-space shared library? How would you "bundle" such a thing as that is not what is in the kernel source tree? If you are going to copy files out of the kernel and do other things with them, well, I recommend asking a lawyer as I am not one :) good luck! greg k-h
On Tue, Jan 26, 2021 at 6:11 PM Greg Kroah-Hartman <gregkh@linuxfoundation.org> wrote: > > On Tue, Jan 26, 2021 at 04:07:47PM +0100, Bartosz Golaszewski wrote: > > On Mon, Jan 25, 2021 at 6:55 AM Kent Gibson <warthog618@gmail.com> wrote: > > > > > > > [snip!] > > > > > > > > > > I don't like the ifdef hell so I prefer to bundle the header. I'm open > > > > to other suggestions, although I can't come up with anything else. > > > > > > > > > > Going off on a bit of a tangent, but I'm trying to add support for > > > decoding the GPIO ioctls into strace and am running up against a similar > > > issue. > > > > > > The way strace does it is to check the uAPI header on the host and use > > > it if possible. To handle where it may be stale, local types are > > > defined that mirror any types that may have been added since the header > > > was originally released. If the corresponding type is available in the > > > linux header then it is used, else the local type. > > > > > > This obviously creates a lot of pointless boilerplate code and > > > preprocessor chicanery so I floated the idea of just including the latest > > > header in the strace tree, as you are doing here for libgpiod. > > > But that raised the issue of licencing, specifically if you copy the > > > linux/gpio.h into a source tree does that mean that the whole project > > > becomes GPL 2.0? That is an issue for strace as it is LGPL 2.1 - as is > > > libgpiod. > > > > > > The Linux uAPI headers are under the GPL-2.0 WITH Linux-syscall-note, > > > which is also not totally clear on this point[1]. > > > > > > My gut feeling was that using and even copying API headers doesn't > > > constitute a derived work, as per the FSF view quoted in [1], and > > > ethically might even be less of a violation than copying and re-defining > > > individual types, but I'd rather not rely on a gut feeling. > > > > > > Is there some clear opinion or precedent on this point? > > > i.e. are libgpiod and strace in legal licence jeopardy if they include > > > gpio.h in their source tree? > > > > > > Cheers, > > > Kent. > > > > > > [1] https://lkml.org/lkml/2020/2/21/2193 > > > > Thanks for pointing that out. I lack the legal knowledge to have an > > opinion of my own on this. > > > > Cc'ing Greg KH for help. > > > > Greg: do you know if it's fine to bundle a 'GPL-2.0 WITH > > Linux-syscall-note' uAPI header together with an LGPL-v2.1-or-later > > user-space shared library? > > How would you "bundle" such a thing as that is not what is in the kernel > source tree? If you are going to copy files out of the kernel and do > other things with them, well, I recommend asking a lawyer as I am not > one :) > > good luck! > > greg k-h By "bundling" I mean - copying the kernel uAPI header verbatim from the kernel tree into the project repository. The reason for that is the fact that always relying on the toolchain kernel headers leads to build issues if we want to support more recent kernel features in the library while the supplied headers don't define all required symbols. We can either make the latest supported version of linux headers a hard requirement for building (I did that and buildroot folks yelled at me because two stable versions of the library had different kernel headers requirements) or redefine certain symbols (new symbols since the oldest supported kernel version) or - and this is preferred unless it's against the linux license - include the kernel headers in the source tarball of the library. I hope this is not a stupid question but obviously I don't know any lawyer well versed in software copyright: can we direct this question to anyone at the Linux Foundation maybe? Bartosz
On Tue, Jan 26, 2021 at 08:08:01PM +0100, Bartosz Golaszewski wrote: > On Tue, Jan 26, 2021 at 6:11 PM Greg Kroah-Hartman > <gregkh@linuxfoundation.org> wrote: > > > > On Tue, Jan 26, 2021 at 04:07:47PM +0100, Bartosz Golaszewski wrote: > > > On Mon, Jan 25, 2021 at 6:55 AM Kent Gibson <warthog618@gmail.com> wrote: > > > > > > > > > > [snip!] > > > > > > > > > > > > > I don't like the ifdef hell so I prefer to bundle the header. I'm open > > > > > to other suggestions, although I can't come up with anything else. > > > > > > > > > > > > > Going off on a bit of a tangent, but I'm trying to add support for > > > > decoding the GPIO ioctls into strace and am running up against a similar > > > > issue. > > > > > > > > The way strace does it is to check the uAPI header on the host and use > > > > it if possible. To handle where it may be stale, local types are > > > > defined that mirror any types that may have been added since the header > > > > was originally released. If the corresponding type is available in the > > > > linux header then it is used, else the local type. > > > > > > > > This obviously creates a lot of pointless boilerplate code and > > > > preprocessor chicanery so I floated the idea of just including the latest > > > > header in the strace tree, as you are doing here for libgpiod. > > > > But that raised the issue of licencing, specifically if you copy the > > > > linux/gpio.h into a source tree does that mean that the whole project > > > > becomes GPL 2.0? That is an issue for strace as it is LGPL 2.1 - as is > > > > libgpiod. > > > > > > > > The Linux uAPI headers are under the GPL-2.0 WITH Linux-syscall-note, > > > > which is also not totally clear on this point[1]. > > > > > > > > My gut feeling was that using and even copying API headers doesn't > > > > constitute a derived work, as per the FSF view quoted in [1], and > > > > ethically might even be less of a violation than copying and re-defining > > > > individual types, but I'd rather not rely on a gut feeling. > > > > > > > > Is there some clear opinion or precedent on this point? > > > > i.e. are libgpiod and strace in legal licence jeopardy if they include > > > > gpio.h in their source tree? > > > > > > > > Cheers, > > > > Kent. > > > > > > > > [1] https://lkml.org/lkml/2020/2/21/2193 > > > > > > Thanks for pointing that out. I lack the legal knowledge to have an > > > opinion of my own on this. > > > > > > Cc'ing Greg KH for help. > > > > > > Greg: do you know if it's fine to bundle a 'GPL-2.0 WITH > > > Linux-syscall-note' uAPI header together with an LGPL-v2.1-or-later > > > user-space shared library? > > > > How would you "bundle" such a thing as that is not what is in the kernel > > source tree? If you are going to copy files out of the kernel and do > > other things with them, well, I recommend asking a lawyer as I am not > > one :) > > > > good luck! > > > > greg k-h > > By "bundling" I mean - copying the kernel uAPI header verbatim from > the kernel tree into the project repository. The reason for that is > the fact that always relying on the toolchain kernel headers leads to > build issues if we want to support more recent kernel features in the > library while the supplied headers don't define all required symbols. > > We can either make the latest supported version of linux headers a > hard requirement for building (I did that and buildroot folks yelled > at me because two stable versions of the library had different kernel > headers requirements) or redefine certain symbols (new symbols since > the oldest supported kernel version) or - and this is preferred unless > it's against the linux license - include the kernel headers in the > source tarball of the library. > > I hope this is not a stupid question but obviously I don't know any > lawyer well versed in software copyright: can we direct this question > to anyone at the Linux Foundation maybe? Ok, first off, I am not a lawyer so don't take legal advice from me. But, if you copy the .h file directly, and keep the same license on the file, that should be fine as you would be using it under the "GPLv2 with syscall note" license for your userspace program, right? So there shouldn't be an issue there that I can determine, as we want userspace programs to be free to use those headers to interact with the kernel. It's come up in the past that we might want to somehow make this much more obvious, and we have talked about this with the legal community, but that's only in the context of making it more obvious that we want people to write programs of any license to talk to the kernel, not that we would want to keep anyone from doing that :) thanks, greg k-h
On Wed, Jan 27, 2021 at 12:43:25PM +0100, Greg Kroah-Hartman wrote: > On Tue, Jan 26, 2021 at 08:08:01PM +0100, Bartosz Golaszewski wrote: > > On Tue, Jan 26, 2021 at 6:11 PM Greg Kroah-Hartman > > <gregkh@linuxfoundation.org> wrote: > > > > > > On Tue, Jan 26, 2021 at 04:07:47PM +0100, Bartosz Golaszewski wrote: > > > > On Mon, Jan 25, 2021 at 6:55 AM Kent Gibson <warthog618@gmail.com> wrote: > > > > > > > > > > > > > [snip!] > > > > > > > > > > > > > > > > I don't like the ifdef hell so I prefer to bundle the header. I'm open > > > > > > to other suggestions, although I can't come up with anything else. > > > > > > > > > > > > > > > > Going off on a bit of a tangent, but I'm trying to add support for > > > > > decoding the GPIO ioctls into strace and am running up against a similar > > > > > issue. > > > > > > > > > > The way strace does it is to check the uAPI header on the host and use > > > > > it if possible. To handle where it may be stale, local types are > > > > > defined that mirror any types that may have been added since the header > > > > > was originally released. If the corresponding type is available in the > > > > > linux header then it is used, else the local type. > > > > > > > > > > This obviously creates a lot of pointless boilerplate code and > > > > > preprocessor chicanery so I floated the idea of just including the latest > > > > > header in the strace tree, as you are doing here for libgpiod. > > > > > But that raised the issue of licencing, specifically if you copy the > > > > > linux/gpio.h into a source tree does that mean that the whole project > > > > > becomes GPL 2.0? That is an issue for strace as it is LGPL 2.1 - as is > > > > > libgpiod. > > > > > > > > > > The Linux uAPI headers are under the GPL-2.0 WITH Linux-syscall-note, > > > > > which is also not totally clear on this point[1]. > > > > > > > > > > My gut feeling was that using and even copying API headers doesn't > > > > > constitute a derived work, as per the FSF view quoted in [1], and > > > > > ethically might even be less of a violation than copying and re-defining > > > > > individual types, but I'd rather not rely on a gut feeling. > > > > > > > > > > Is there some clear opinion or precedent on this point? > > > > > i.e. are libgpiod and strace in legal licence jeopardy if they include > > > > > gpio.h in their source tree? > > > > > > > > > > Cheers, > > > > > Kent. > > > > > > > > > > [1] https://lkml.org/lkml/2020/2/21/2193 > > > > > > > > Thanks for pointing that out. I lack the legal knowledge to have an > > > > opinion of my own on this. > > > > > > > > Cc'ing Greg KH for help. > > > > > > > > Greg: do you know if it's fine to bundle a 'GPL-2.0 WITH > > > > Linux-syscall-note' uAPI header together with an LGPL-v2.1-or-later > > > > user-space shared library? > > > > > > How would you "bundle" such a thing as that is not what is in the kernel > > > source tree? If you are going to copy files out of the kernel and do > > > other things with them, well, I recommend asking a lawyer as I am not > > > one :) > > > > > > good luck! > > > > > > greg k-h > > > > By "bundling" I mean - copying the kernel uAPI header verbatim from > > the kernel tree into the project repository. The reason for that is > > the fact that always relying on the toolchain kernel headers leads to > > build issues if we want to support more recent kernel features in the > > library while the supplied headers don't define all required symbols. > > > > We can either make the latest supported version of linux headers a > > hard requirement for building (I did that and buildroot folks yelled > > at me because two stable versions of the library had different kernel > > headers requirements) or redefine certain symbols (new symbols since > > the oldest supported kernel version) or - and this is preferred unless > > it's against the linux license - include the kernel headers in the > > source tarball of the library. > > > > I hope this is not a stupid question but obviously I don't know any > > lawyer well versed in software copyright: can we direct this question > > to anyone at the Linux Foundation maybe? > > Ok, first off, I am not a lawyer so don't take legal advice from me. > > But, if you copy the .h file directly, and keep the same license on the > file, that should be fine as you would be using it under the "GPLv2 with > syscall note" license for your userspace program, right? > > So there shouldn't be an issue there that I can determine, as we want > userspace programs to be free to use those headers to interact with the > kernel. > > It's come up in the past that we might want to somehow make this much > more obvious, and we have talked about this with the legal community, > but that's only in the context of making it more obvious that we want > people to write programs of any license to talk to the kernel, not that > we would want to keep anyone from doing that :) > > thanks, > > greg k-h Including Dmitry as he orignally raised the issue and has an interest in its resolution. Greg: thanks for providing your view. You may not be a lawyer (which is a very good thing, btw), but your opinion carries a lot of weight, and combined with what we already knew I think we're on very solid ground distributing the kernel headers in the libgpiod and strace repositories. Bart and Dmitry: I submit that we are good to copy the headers into the repositories, but we should take a few steps just to make clear that we are in full compliance with the GPL v2. Firstly, we are distributing the headers under Section 1 (distribution) of the GPL, so we should keep the headers in a separate directory that contains its own COPYING file as well as the GPL v2 and Linux syscall note - unless they are already available elsewhere in the repo. The headers must be copied verbatim so as to not trigger Section 2 (modification). And it is probably good to include in the commit comment what kernel version or commit they were drawn from so that can be easily confirmed. Section 3 still doesn't apply, as any resulting object code or executables are no more a derived work due to the availability of the header than they were previously. And I don't think anyone is claiming that the repo itself is a derived work - in this context it is just a distribution medium. The COPYING file, or equivalent, for the project should explicitly exclude any claim on the kernel header directory to make clear we are not trying to sublicense the headers as LGPL - which could breach Section 4. Other than those points, I don't see anywhere we may be in breach. As with Greg, IANAL so this is not legal advice. Feel free to disregard any or all of the above if you still consider the legal standing uncertain or too risky. Cheers, Kent.
On Thu, Jan 28, 2021 at 11:26:41AM +0800, Kent Gibson wrote: > Bart and Dmitry: I submit that we are good to copy the headers into the > repositories, but we should take a few steps just to make clear that we > are in full compliance with the GPL v2. > > Firstly, we are distributing the headers under Section 1 (distribution) > of the GPL, so we should keep the headers in a separate directory that > contains its own COPYING file as well as the GPL v2 and Linux syscall note > - unless they are already available elsewhere in the repo. > > The headers must be copied verbatim so as to not trigger Section 2 > (modification). And it is probably good to include in the commit > comment what kernel version or commit they were drawn from so that can > be easily confirmed. > > Section 3 still doesn't apply, as any resulting object code or > executables are no more a derived work due to the availability of the > header than they were previously. And I don't think anyone is claiming > that the repo itself is a derived work - in this context it is just a > distribution medium. > > The COPYING file, or equivalent, for the project should explicitly > exclude any claim on the kernel header directory to make clear we are > not trying to sublicense the headers as LGPL - which could breach > Section 4. > > Other than those points, I don't see anywhere we may be in breach. That looks good, you should also consider following the REUSE specification: https://reuse.software/ which recommends using a LICENSES/ directory for the different licenses in your project and use SPDX lines at the top of your files to make everything explicit. The `reuse lint` command line tool should give you lots of hints on good things to fix up in this area. Good luck! greg k-h
diff --git a/configure.ac b/configure.ac index ddb9dc2..f6db096 100644 --- a/configure.ac +++ b/configure.ac @@ -93,16 +93,10 @@ AC_CHECK_HEADERS([getopt.h], [], [HEADER_NOT_FOUND_LIB([getopt.h])]) AC_CHECK_HEADERS([dirent.h], [], [HEADER_NOT_FOUND_LIB([dirent.h])]) AC_CHECK_HEADERS([sys/poll.h], [], [HEADER_NOT_FOUND_LIB([sys/poll.h])]) AC_CHECK_HEADERS([sys/sysmacros.h], [], [HEADER_NOT_FOUND_LIB([sys/sysmacros.h])]) -AC_CHECK_HEADERS([linux/gpio.h], [], [HEADER_NOT_FOUND_LIB([linux/gpio.h])]) AC_CHECK_HEADERS([linux/version.h], [], [HEADER_NOT_FOUND_LIB([linux/version.h])]) - -AC_COMPILE_IFELSE([AC_LANG_SOURCE( -#include <linux/version.h> -#if LINUX_VERSION_CODE < KERNEL_VERSION(5, 10, 0) -#error -#endif -)], -[], [AC_MSG_ERROR(["libgpiod needs linux headers version >= v5.10.0"])]) +AC_CHECK_HEADERS([linux/const.h], [], [HEADER_NOT_FOUND_LIB([linux/const.h])]) +AC_CHECK_HEADERS([linux/ioctl.h], [], [HEADER_NOT_FOUND_LIB([linux/ioctl.h])]) +AC_CHECK_HEADERS([linux/types.h], [], [HEADER_NOT_FOUND_LIB([linux/types.h])]) AC_ARG_ENABLE([tools], [AS_HELP_STRING([--enable-tools],[enable libgpiod command-line tools [default=no]])], diff --git a/lib/Makefile.am b/lib/Makefile.am index 43ebf76..fb0dae9 100644 --- a/lib/Makefile.am +++ b/lib/Makefile.am @@ -7,7 +7,7 @@ # lib_LTLIBRARIES = libgpiod.la -libgpiod_la_SOURCES = core.c helpers.c misc.c +libgpiod_la_SOURCES = core.c helpers.c misc.c uapi/gpio.h libgpiod_la_CFLAGS = -Wall -Wextra -g -std=gnu89 libgpiod_la_CFLAGS += -fvisibility=hidden -I$(top_srcdir)/include/ libgpiod_la_CFLAGS += -include $(top_builddir)/config.h diff --git a/lib/core.c b/lib/core.c index 9629a4f..5e19c67 100644 --- a/lib/core.c +++ b/lib/core.c @@ -11,7 +11,6 @@ #include <fcntl.h> #include <gpiod.h> #include <limits.h> -#include <linux/gpio.h> #include <poll.h> #include <stdint.h> #include <stdio.h> @@ -22,6 +21,8 @@ #include <sys/types.h> #include <unistd.h> +#include "uapi/gpio.h" + #define LINE_REQUEST_MAX_LINES 64 enum { diff --git a/lib/uapi/gpio.h b/lib/uapi/gpio.h new file mode 100644 index 0000000..b8d2687 --- /dev/null +++ b/lib/uapi/gpio.h @@ -0,0 +1,522 @@ +/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ +/* + * <linux/gpio.h> - userspace ABI for the GPIO character devices + * + * Copyright (C) 2016 Linus Walleij + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 as published by + * the Free Software Foundation. + */ +#ifndef _GPIO_H_ +#define _GPIO_H_ + +#include <linux/const.h> +#include <linux/ioctl.h> +#include <linux/types.h> + +/* + * The maximum size of name and label arrays. + * + * Must be a multiple of 8 to ensure 32/64-bit alignment of structs. + */ +#define GPIO_MAX_NAME_SIZE 32 + +/** + * struct gpiochip_info - Information about a certain GPIO chip + * @name: the Linux kernel name of this GPIO chip + * @label: a functional name for this GPIO chip, such as a product + * number, may be empty (i.e. label[0] == '\0') + * @lines: number of GPIO lines on this chip + */ +struct gpiochip_info { + char name[GPIO_MAX_NAME_SIZE]; + char label[GPIO_MAX_NAME_SIZE]; + __u32 lines; +}; + +/* + * Maximum number of requested lines. + * + * Must be no greater than 64, as bitmaps are restricted here to 64-bits + * for simplicity, and a multiple of 2 to ensure 32/64-bit alignment of + * structs. + */ +#define GPIO_V2_LINES_MAX 64 + +/* + * The maximum number of configuration attributes associated with a line + * request. + */ +#define GPIO_V2_LINE_NUM_ATTRS_MAX 10 + +/** + * enum gpio_v2_line_flag - &struct gpio_v2_line_attribute.flags values + * @GPIO_V2_LINE_FLAG_USED: line is not available for request + * @GPIO_V2_LINE_FLAG_ACTIVE_LOW: line active state is physical low + * @GPIO_V2_LINE_FLAG_INPUT: line is an input + * @GPIO_V2_LINE_FLAG_OUTPUT: line is an output + * @GPIO_V2_LINE_FLAG_EDGE_RISING: line detects rising (inactive to active) + * edges + * @GPIO_V2_LINE_FLAG_EDGE_FALLING: line detects falling (active to + * inactive) edges + * @GPIO_V2_LINE_FLAG_OPEN_DRAIN: line is an open drain output + * @GPIO_V2_LINE_FLAG_OPEN_SOURCE: line is an open source output + * @GPIO_V2_LINE_FLAG_BIAS_PULL_UP: line has pull-up bias enabled + * @GPIO_V2_LINE_FLAG_BIAS_PULL_DOWN: line has pull-down bias enabled + * @GPIO_V2_LINE_FLAG_BIAS_DISABLED: line has bias disabled + */ +enum gpio_v2_line_flag { + GPIO_V2_LINE_FLAG_USED = _BITULL(0), + GPIO_V2_LINE_FLAG_ACTIVE_LOW = _BITULL(1), + GPIO_V2_LINE_FLAG_INPUT = _BITULL(2), + GPIO_V2_LINE_FLAG_OUTPUT = _BITULL(3), + GPIO_V2_LINE_FLAG_EDGE_RISING = _BITULL(4), + GPIO_V2_LINE_FLAG_EDGE_FALLING = _BITULL(5), + GPIO_V2_LINE_FLAG_OPEN_DRAIN = _BITULL(6), + GPIO_V2_LINE_FLAG_OPEN_SOURCE = _BITULL(7), + GPIO_V2_LINE_FLAG_BIAS_PULL_UP = _BITULL(8), + GPIO_V2_LINE_FLAG_BIAS_PULL_DOWN = _BITULL(9), + GPIO_V2_LINE_FLAG_BIAS_DISABLED = _BITULL(10), +}; + +/** + * struct gpio_v2_line_values - Values of GPIO lines + * @bits: a bitmap containing the value of the lines, set to 1 for active + * and 0 for inactive. + * @mask: a bitmap identifying the lines to get or set, with each bit + * number corresponding to the index into &struct + * gpio_v2_line_request.offsets. + */ +struct gpio_v2_line_values { + __aligned_u64 bits; + __aligned_u64 mask; +}; + +/** + * enum gpio_v2_line_attr_id - &struct gpio_v2_line_attribute.id values + * identifying which field of the attribute union is in use. + * @GPIO_V2_LINE_ATTR_ID_FLAGS: flags field is in use + * @GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUES: values field is in use + * @GPIO_V2_LINE_ATTR_ID_DEBOUNCE: debounce_period_us field is in use + */ +enum gpio_v2_line_attr_id { + GPIO_V2_LINE_ATTR_ID_FLAGS = 1, + GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUES = 2, + GPIO_V2_LINE_ATTR_ID_DEBOUNCE = 3, +}; + +/** + * struct gpio_v2_line_attribute - a configurable attribute of a line + * @id: attribute identifier with value from &enum gpio_v2_line_attr_id + * @padding: reserved for future use and must be zero filled + * @flags: if id is %GPIO_V2_LINE_ATTR_ID_FLAGS, the flags for the GPIO + * line, with values from &enum gpio_v2_line_flag, such as + * %GPIO_V2_LINE_FLAG_ACTIVE_LOW, %GPIO_V2_LINE_FLAG_OUTPUT etc, added + * together. This overrides the default flags contained in the &struct + * gpio_v2_line_config for the associated line. + * @values: if id is %GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUES, a bitmap + * containing the values to which the lines will be set, with each bit + * number corresponding to the index into &struct + * gpio_v2_line_request.offsets. + * @debounce_period_us: if id is %GPIO_V2_LINE_ATTR_ID_DEBOUNCE, the + * desired debounce period, in microseconds + */ +struct gpio_v2_line_attribute { + __u32 id; + __u32 padding; + union { + __aligned_u64 flags; + __aligned_u64 values; + __u32 debounce_period_us; + }; +}; + +/** + * struct gpio_v2_line_config_attribute - a configuration attribute + * associated with one or more of the requested lines. + * @attr: the configurable attribute + * @mask: a bitmap identifying the lines to which the attribute applies, + * with each bit number corresponding to the index into &struct + * gpio_v2_line_request.offsets. + */ +struct gpio_v2_line_config_attribute { + struct gpio_v2_line_attribute attr; + __aligned_u64 mask; +}; + +/** + * struct gpio_v2_line_config - Configuration for GPIO lines + * @flags: flags for the GPIO lines, with values from &enum + * gpio_v2_line_flag, such as %GPIO_V2_LINE_FLAG_ACTIVE_LOW, + * %GPIO_V2_LINE_FLAG_OUTPUT etc, added together. This is the default for + * all requested lines but may be overridden for particular lines using + * @attrs. + * @num_attrs: the number of attributes in @attrs + * @padding: reserved for future use and must be zero filled + * @attrs: the configuration attributes associated with the requested + * lines. Any attribute should only be associated with a particular line + * once. If an attribute is associated with a line multiple times then the + * first occurrence (i.e. lowest index) has precedence. + */ +struct gpio_v2_line_config { + __aligned_u64 flags; + __u32 num_attrs; + /* Pad to fill implicit padding and reserve space for future use. */ + __u32 padding[5]; + struct gpio_v2_line_config_attribute attrs[GPIO_V2_LINE_NUM_ATTRS_MAX]; +}; + +/** + * struct gpio_v2_line_request - Information about a request for GPIO lines + * @offsets: an array of desired lines, specified by offset index for the + * associated GPIO chip + * @consumer: a desired consumer label for the selected GPIO lines such as + * "my-bitbanged-relay" + * @config: requested configuration for the lines. + * @num_lines: number of lines requested in this request, i.e. the number + * of valid fields in the %GPIO_V2_LINES_MAX sized arrays, set to 1 to + * request a single line + * @event_buffer_size: a suggested minimum number of line events that the + * kernel should buffer. This is only relevant if edge detection is + * enabled in the configuration. Note that this is only a suggested value + * and the kernel may allocate a larger buffer or cap the size of the + * buffer. If this field is zero then the buffer size defaults to a minimum + * of @num_lines * 16. + * @padding: reserved for future use and must be zero filled + * @fd: if successful this field will contain a valid anonymous file handle + * after a %GPIO_GET_LINE_IOCTL operation, zero or negative value means + * error + */ +struct gpio_v2_line_request { + __u32 offsets[GPIO_V2_LINES_MAX]; + char consumer[GPIO_MAX_NAME_SIZE]; + struct gpio_v2_line_config config; + __u32 num_lines; + __u32 event_buffer_size; + /* Pad to fill implicit padding and reserve space for future use. */ + __u32 padding[5]; + __s32 fd; +}; + +/** + * struct gpio_v2_line_info - Information about a certain GPIO line + * @name: the name of this GPIO line, such as the output pin of the line on + * the chip, a rail or a pin header name on a board, as specified by the + * GPIO chip, may be empty (i.e. name[0] == '\0') + * @consumer: a functional name for the consumer of this GPIO line as set + * by whatever is using it, will be empty if there is no current user but + * may also be empty if the consumer doesn't set this up + * @offset: the local offset on this GPIO chip, fill this in when + * requesting the line information from the kernel + * @num_attrs: the number of attributes in @attrs + * @flags: flags for the GPIO lines, with values from &enum + * gpio_v2_line_flag, such as %GPIO_V2_LINE_FLAG_ACTIVE_LOW, + * %GPIO_V2_LINE_FLAG_OUTPUT etc, added together. + * @attrs: the configuration attributes associated with the line + * @padding: reserved for future use + */ +struct gpio_v2_line_info { + char name[GPIO_MAX_NAME_SIZE]; + char consumer[GPIO_MAX_NAME_SIZE]; + __u32 offset; + __u32 num_attrs; + __aligned_u64 flags; + struct gpio_v2_line_attribute attrs[GPIO_V2_LINE_NUM_ATTRS_MAX]; + /* Space reserved for future use. */ + __u32 padding[4]; +}; + +/** + * enum gpio_v2_line_changed_type - &struct gpio_v2_line_changed.event_type + * values + * @GPIO_V2_LINE_CHANGED_REQUESTED: line has been requested + * @GPIO_V2_LINE_CHANGED_RELEASED: line has been released + * @GPIO_V2_LINE_CHANGED_CONFIG: line has been reconfigured + */ +enum gpio_v2_line_changed_type { + GPIO_V2_LINE_CHANGED_REQUESTED = 1, + GPIO_V2_LINE_CHANGED_RELEASED = 2, + GPIO_V2_LINE_CHANGED_CONFIG = 3, +}; + +/** + * struct gpio_v2_line_info_changed - Information about a change in status + * of a GPIO line + * @info: updated line information + * @timestamp_ns: estimate of time of status change occurrence, in nanoseconds + * @event_type: the type of change with a value from &enum + * gpio_v2_line_changed_type + * @padding: reserved for future use + */ +struct gpio_v2_line_info_changed { + struct gpio_v2_line_info info; + __aligned_u64 timestamp_ns; + __u32 event_type; + /* Pad struct to 64-bit boundary and reserve space for future use. */ + __u32 padding[5]; +}; + +/** + * enum gpio_v2_line_event_id - &struct gpio_v2_line_event.id values + * @GPIO_V2_LINE_EVENT_RISING_EDGE: event triggered by a rising edge + * @GPIO_V2_LINE_EVENT_FALLING_EDGE: event triggered by a falling edge + */ +enum gpio_v2_line_event_id { + GPIO_V2_LINE_EVENT_RISING_EDGE = 1, + GPIO_V2_LINE_EVENT_FALLING_EDGE = 2, +}; + +/** + * struct gpio_v2_line_event - The actual event being pushed to userspace + * @timestamp_ns: best estimate of time of event occurrence, in nanoseconds. + * The @timestamp_ns is read from %CLOCK_MONOTONIC and is intended to allow + * the accurate measurement of the time between events. It does not provide + * the wall-clock time. + * @id: event identifier with value from &enum gpio_v2_line_event_id + * @offset: the offset of the line that triggered the event + * @seqno: the sequence number for this event in the sequence of events for + * all the lines in this line request + * @line_seqno: the sequence number for this event in the sequence of + * events on this particular line + * @padding: reserved for future use + */ +struct gpio_v2_line_event { + __aligned_u64 timestamp_ns; + __u32 id; + __u32 offset; + __u32 seqno; + __u32 line_seqno; + /* Space reserved for future use. */ + __u32 padding[6]; +}; + +/* + * ABI v1 + * + * This version of the ABI is deprecated. + * Use the latest version of the ABI, defined above, instead. + */ + +/* Informational flags */ +#define GPIOLINE_FLAG_KERNEL (1UL << 0) /* Line used by the kernel */ +#define GPIOLINE_FLAG_IS_OUT (1UL << 1) +#define GPIOLINE_FLAG_ACTIVE_LOW (1UL << 2) +#define GPIOLINE_FLAG_OPEN_DRAIN (1UL << 3) +#define GPIOLINE_FLAG_OPEN_SOURCE (1UL << 4) +#define GPIOLINE_FLAG_BIAS_PULL_UP (1UL << 5) +#define GPIOLINE_FLAG_BIAS_PULL_DOWN (1UL << 6) +#define GPIOLINE_FLAG_BIAS_DISABLE (1UL << 7) + +/** + * struct gpioline_info - Information about a certain GPIO line + * @line_offset: the local offset on this GPIO device, fill this in when + * requesting the line information from the kernel + * @flags: various flags for this line + * @name: the name of this GPIO line, such as the output pin of the line on the + * chip, a rail or a pin header name on a board, as specified by the gpio + * chip, may be empty (i.e. name[0] == '\0') + * @consumer: a functional name for the consumer of this GPIO line as set by + * whatever is using it, will be empty if there is no current user but may + * also be empty if the consumer doesn't set this up + * + * Note: This struct is part of ABI v1 and is deprecated. + * Use &struct gpio_v2_line_info instead. + */ +struct gpioline_info { + __u32 line_offset; + __u32 flags; + char name[GPIO_MAX_NAME_SIZE]; + char consumer[GPIO_MAX_NAME_SIZE]; +}; + +/* Maximum number of requested handles */ +#define GPIOHANDLES_MAX 64 + +/* Possible line status change events */ +enum { + GPIOLINE_CHANGED_REQUESTED = 1, + GPIOLINE_CHANGED_RELEASED, + GPIOLINE_CHANGED_CONFIG, +}; + +/** + * struct gpioline_info_changed - Information about a change in status + * of a GPIO line + * @info: updated line information + * @timestamp: estimate of time of status change occurrence, in nanoseconds + * @event_type: one of %GPIOLINE_CHANGED_REQUESTED, + * %GPIOLINE_CHANGED_RELEASED and %GPIOLINE_CHANGED_CONFIG + * @padding: reserved for future use + * + * The &struct gpioline_info embedded here has 32-bit alignment on its own, + * but it works fine with 64-bit alignment too. With its 72 byte size, we can + * guarantee there are no implicit holes between it and subsequent members. + * The 20-byte padding at the end makes sure we don't add any implicit padding + * at the end of the structure on 64-bit architectures. + * + * Note: This struct is part of ABI v1 and is deprecated. + * Use &struct gpio_v2_line_info_changed instead. + */ +struct gpioline_info_changed { + struct gpioline_info info; + __u64 timestamp; + __u32 event_type; + __u32 padding[5]; /* for future use */ +}; + +/* Linerequest flags */ +#define GPIOHANDLE_REQUEST_INPUT (1UL << 0) +#define GPIOHANDLE_REQUEST_OUTPUT (1UL << 1) +#define GPIOHANDLE_REQUEST_ACTIVE_LOW (1UL << 2) +#define GPIOHANDLE_REQUEST_OPEN_DRAIN (1UL << 3) +#define GPIOHANDLE_REQUEST_OPEN_SOURCE (1UL << 4) +#define GPIOHANDLE_REQUEST_BIAS_PULL_UP (1UL << 5) +#define GPIOHANDLE_REQUEST_BIAS_PULL_DOWN (1UL << 6) +#define GPIOHANDLE_REQUEST_BIAS_DISABLE (1UL << 7) + +/** + * struct gpiohandle_request - Information about a GPIO handle request + * @lineoffsets: an array of desired lines, specified by offset index for the + * associated GPIO device + * @flags: desired flags for the desired GPIO lines, such as + * %GPIOHANDLE_REQUEST_OUTPUT, %GPIOHANDLE_REQUEST_ACTIVE_LOW etc, added + * together. Note that even if multiple lines are requested, the same flags + * must be applicable to all of them, if you want lines with individual + * flags set, request them one by one. It is possible to select + * a batch of input or output lines, but they must all have the same + * characteristics, i.e. all inputs or all outputs, all active low etc + * @default_values: if the %GPIOHANDLE_REQUEST_OUTPUT is set for a requested + * line, this specifies the default output value, should be 0 (low) or + * 1 (high), anything else than 0 or 1 will be interpreted as 1 (high) + * @consumer_label: a desired consumer label for the selected GPIO line(s) + * such as "my-bitbanged-relay" + * @lines: number of lines requested in this request, i.e. the number of + * valid fields in the above arrays, set to 1 to request a single line + * @fd: if successful this field will contain a valid anonymous file handle + * after a %GPIO_GET_LINEHANDLE_IOCTL operation, zero or negative value + * means error + * + * Note: This struct is part of ABI v1 and is deprecated. + * Use &struct gpio_v2_line_request instead. + */ +struct gpiohandle_request { + __u32 lineoffsets[GPIOHANDLES_MAX]; + __u32 flags; + __u8 default_values[GPIOHANDLES_MAX]; + char consumer_label[GPIO_MAX_NAME_SIZE]; + __u32 lines; + int fd; +}; + +/** + * struct gpiohandle_config - Configuration for a GPIO handle request + * @flags: updated flags for the requested GPIO lines, such as + * %GPIOHANDLE_REQUEST_OUTPUT, %GPIOHANDLE_REQUEST_ACTIVE_LOW etc, added + * together + * @default_values: if the %GPIOHANDLE_REQUEST_OUTPUT is set in flags, + * this specifies the default output value, should be 0 (low) or + * 1 (high), anything else than 0 or 1 will be interpreted as 1 (high) + * @padding: reserved for future use and should be zero filled + * + * Note: This struct is part of ABI v1 and is deprecated. + * Use &struct gpio_v2_line_config instead. + */ +struct gpiohandle_config { + __u32 flags; + __u8 default_values[GPIOHANDLES_MAX]; + __u32 padding[4]; /* padding for future use */ +}; + +/** + * struct gpiohandle_data - Information of values on a GPIO handle + * @values: when getting the state of lines this contains the current + * state of a line, when setting the state of lines these should contain + * the desired target state + * + * Note: This struct is part of ABI v1 and is deprecated. + * Use &struct gpio_v2_line_values instead. + */ +struct gpiohandle_data { + __u8 values[GPIOHANDLES_MAX]; +}; + +/* Eventrequest flags */ +#define GPIOEVENT_REQUEST_RISING_EDGE (1UL << 0) +#define GPIOEVENT_REQUEST_FALLING_EDGE (1UL << 1) +#define GPIOEVENT_REQUEST_BOTH_EDGES ((1UL << 0) | (1UL << 1)) + +/** + * struct gpioevent_request - Information about a GPIO event request + * @lineoffset: the desired line to subscribe to events from, specified by + * offset index for the associated GPIO device + * @handleflags: desired handle flags for the desired GPIO line, such as + * %GPIOHANDLE_REQUEST_ACTIVE_LOW or %GPIOHANDLE_REQUEST_OPEN_DRAIN + * @eventflags: desired flags for the desired GPIO event line, such as + * %GPIOEVENT_REQUEST_RISING_EDGE or %GPIOEVENT_REQUEST_FALLING_EDGE + * @consumer_label: a desired consumer label for the selected GPIO line(s) + * such as "my-listener" + * @fd: if successful this field will contain a valid anonymous file handle + * after a %GPIO_GET_LINEEVENT_IOCTL operation, zero or negative value + * means error + * + * Note: This struct is part of ABI v1 and is deprecated. + * Use &struct gpio_v2_line_request instead. + */ +struct gpioevent_request { + __u32 lineoffset; + __u32 handleflags; + __u32 eventflags; + char consumer_label[GPIO_MAX_NAME_SIZE]; + int fd; +}; + +/* + * GPIO event types + */ +#define GPIOEVENT_EVENT_RISING_EDGE 0x01 +#define GPIOEVENT_EVENT_FALLING_EDGE 0x02 + +/** + * struct gpioevent_data - The actual event being pushed to userspace + * @timestamp: best estimate of time of event occurrence, in nanoseconds + * @id: event identifier + * + * Note: This struct is part of ABI v1 and is deprecated. + * Use &struct gpio_v2_line_event instead. + */ +struct gpioevent_data { + __u64 timestamp; + __u32 id; +}; + +/* + * v1 and v2 ioctl()s + */ +#define GPIO_GET_CHIPINFO_IOCTL _IOR(0xB4, 0x01, struct gpiochip_info) +#define GPIO_GET_LINEINFO_UNWATCH_IOCTL _IOWR(0xB4, 0x0C, __u32) + +/* + * v2 ioctl()s + */ +#define GPIO_V2_GET_LINEINFO_IOCTL _IOWR(0xB4, 0x05, struct gpio_v2_line_info) +#define GPIO_V2_GET_LINEINFO_WATCH_IOCTL _IOWR(0xB4, 0x06, struct gpio_v2_line_info) +#define GPIO_V2_GET_LINE_IOCTL _IOWR(0xB4, 0x07, struct gpio_v2_line_request) +#define GPIO_V2_LINE_SET_CONFIG_IOCTL _IOWR(0xB4, 0x0D, struct gpio_v2_line_config) +#define GPIO_V2_LINE_GET_VALUES_IOCTL _IOWR(0xB4, 0x0E, struct gpio_v2_line_values) +#define GPIO_V2_LINE_SET_VALUES_IOCTL _IOWR(0xB4, 0x0F, struct gpio_v2_line_values) + +/* + * v1 ioctl()s + * + * These ioctl()s are deprecated. Use the v2 equivalent instead. + */ +#define GPIO_GET_LINEINFO_IOCTL _IOWR(0xB4, 0x02, struct gpioline_info) +#define GPIO_GET_LINEHANDLE_IOCTL _IOWR(0xB4, 0x03, struct gpiohandle_request) +#define GPIO_GET_LINEEVENT_IOCTL _IOWR(0xB4, 0x04, struct gpioevent_request) +#define GPIOHANDLE_GET_LINE_VALUES_IOCTL _IOWR(0xB4, 0x08, struct gpiohandle_data) +#define GPIOHANDLE_SET_LINE_VALUES_IOCTL _IOWR(0xB4, 0x09, struct gpiohandle_data) +#define GPIOHANDLE_SET_CONFIG_IOCTL _IOWR(0xB4, 0x0A, struct gpiohandle_config) +#define GPIO_GET_LINEINFO_WATCH_IOCTL _IOWR(0xB4, 0x0B, struct gpioline_info) + +#endif /* _GPIO_H_ */