| Message ID | 20240109135952.77458-1-warthog618@gmail.com |
|---|---|
| Headers | show |
| Series | Documentation: gpio: add character device userspace API documentation | expand |
On Wed, Jan 10, 2024 at 01:10:51PM +0200, Andy Shevchenko wrote: > On Wed, Jan 10, 2024 at 10:16 AM Vegard Nossum <vegard.nossum@oracle.com> wrote: > > On 10/01/2024 00:45, Kent Gibson wrote: > > > On Tue, Jan 09, 2024 at 10:00:26PM +0200, Andy Shevchenko wrote: > > >> On Tue, Jan 9, 2024 at 4:00 PM Kent Gibson <warthog618@gmail.com> wrote: > > >> > > >> May we actually state in the documentation that sysfs is subject to > > >> remove at some point? > > > > > > So formally define what "deprecated" means? > > > Is that covered in the higher level documentation somewhere? > > > If so I'm more than happy to provide a reference. > > > > We have a few files that may be relevant here, that I'm aware of: > > > > 1) https://docs.kernel.org/admin-guide/sysfs-rules.html > > > > documents some general assumptions that userspace can make about the > > stability of sysfs and its files > > > > 2) https://docs.kernel.org/admin-guide/abi.html > > > > This is the public-facing, somewhat machine-readable repository of what > > is supposed to be the kernel's ABI/API, including "obsolete" and > > "removed" interfaces. > > > > 3) Documentation/ABI/README > > > > describes the process of deprecating an interface > > Yes and GPIO currently is under obsolete section with also this: > > "This ABI is deprecated and will be removed after 2020. It is replaced > with the GPIO character device." > > https://docs.kernel.org/admin-guide/abi-obsolete.html#symbols-under-sys-class > > So, proposed cleanup series should probably rely on this documentation > among other existing descriptions of sysfs GPIO. > The sysfs doc already references the doc (sysfs-gpio) that generates the HTML that link points to, so not sure what to change. I can't include a direct reference to the HTML, AFAICT, as that HTML is generated using kernel-abi makefile magic so the usual doc path cross-references don't work - you just get the path as plain text. If there is some way to provide a cross-reference that generates to that link then I'll change it, but I don't know how. >>> + - - ``EFAULT`` > Wondering if these constants can be referenced via % and if it makes sense. That would be great and I do want to do that, particularly for the uAPI v1 docs that use a lot of consts rather than enums, but, AFAICT, you can't create cross-references for consts, you can only add formatting[1]. And the % formatting only works in kernel-doc, in rst you have to add it explicitly yourself, hence the ``EFAULT`` . Cheers, Kent. [1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#highlights-and-cross-references
On Tue, Jan 09, 2024 at 09:59:45PM +0800, Kent Gibson wrote: > My new year's resolution was to improve the documentation of the > character device API and gpio in general, so here we are. > > > Patch 2 relocates the sysfs API doc to stress its deprecation by > moving it to a new deprecated section, again in userspace-api but > with a similar section in the admin-guide. The deprecated section > also provides a placeholder for subsequent changes. > While preparing the v2 version of this series, I'm now wondering if this should be changed to "obsolete" rather than "deprecated", to better fit with the interface lifecycle, to indicate there is an alternative, and to emphasise that it is scheduled for removal. i.e. from a userspace perspective "obsolete" is the clearer term. Is that a change worth making? Cheers, Kent.
On Sun, Jan 14, 2024 at 4:47 AM Kent Gibson <warthog618@gmail.com> wrote: > On Tue, Jan 09, 2024 at 09:59:45PM +0800, Kent Gibson wrote: > > My new year's resolution was to improve the documentation of the > > character device API and gpio in general, so here we are. ... > While preparing the v2 version of this series, I'm now wondering > if this should be changed to "obsolete" rather than "deprecated", to > better fit with the interface lifecycle, to indicate there is an > alternative, and to emphasise that it is scheduled for removal. > i.e. from a userspace perspective "obsolete" is the clearer term. > > Is that a change worth making?
On Sun, Jan 14, 2024 at 02:01:29PM +0200, Andy Shevchenko wrote: > On Sun, Jan 14, 2024 at 4:47 AM Kent Gibson <warthog618@gmail.com> wrote: > > On Tue, Jan 09, 2024 at 09:59:45PM +0800, Kent Gibson wrote: > > > My new year's resolution was to improve the documentation of the > > > character device API and gpio in general, so here we are. > > ... > > > While preparing the v2 version of this series, I'm now wondering > > if this should be changed to "obsolete" rather than "deprecated", to > > better fit with the interface lifecycle, to indicate there is an > > alternative, and to emphasise that it is scheduled for removal. > > i.e. from a userspace perspective "obsolete" is the clearer term. > > > > Is that a change worth making? > > From my p.o.v. yes, as it makes it consistent with what we already > have in the sysfs/obsolete. > Ok then, I'll incorporate it into v2. Cheers, Kent.
My new year's resolution was to improve the documentation of the character device API and gpio in general, so here we are. Wrt the formatting and file breakdown, I've taken inspiration from the userspace-api/media documentation. Patch 1 adds documentation for the current chardev uAPI. I've added it to the userspace-api book, as that is the most obvious place a reader would look for it, but have also provided links from the admin-guide book where the gpio docs currently reside. I realise MAINTAINERS should be updated with Documentation/userspace-api/gpio/, but the split out of GPIO UAPI hasn't made it into gpio/for-next yet, so I was unsure of how to handle that. Patch 2 relocates the sysfs API doc to stress its deprecation by moving it to a new deprecated section, again in userspace-api but with a similar section in the admin-guide. The deprecated section also provides a placeholder for subsequent changes. Patch 3 updates the sysfs API doc to reference the chardev documentation rather than gpio.h. Patch 4 adds documentation for the deprecated v1 version of the chardev uAPI. It is deprecated, but still useful to have, if nothing else to help identify the differences between v1 and v2. Patch 5 capitalizes the title of the admin-guide/gpio to match the other subsystems and the userspace-api book. Patch 6 adds a deprecation note to the gpio-mockup, as it is obsoleted by the gpio-sim. Patch 7 moves the gpio-mockup doc into the deprecated section. I've got some minor updates for the kernel doc in gpio.h as well, but they make sense on their own so I'll send those separately keep the cross-posting to a minimum. I realise the only thing less exciting than writing documentation is reviewing it, so my apologies and thanks in advance if you have the fortitude to attempt such a scintillating endeavour. Cheers, Kent. Kent Gibson (7): Documentation: gpio: add chardev userspace API documentation Documentation: gpio: move sysfs into a deprecated section Documentation: gpio: update sysfs documentation to reference new chardev doc Documentation: gpio: add chardev v1 userspace API documentation Documentation: gpio: capitalize GPIO in index title Documentation: gpio: document gpio-mockup as obsoleted by gpio-sim Documentation: gpio: move gpio-mockup into deprecated section Documentation/admin-guide/gpio/deprecated.rst | 13 ++ .../admin-guide/gpio/gpio-mockup.rst | 8 ++ Documentation/admin-guide/gpio/index.rst | 6 +- Documentation/userspace-api/gpio/chardev.rst | 114 ++++++++++++++++ .../userspace-api/gpio/chardev_v1.rst | 129 ++++++++++++++++++ .../userspace-api/gpio/deprecated.rst | 11 ++ .../userspace-api/gpio/error-codes.rst | 78 +++++++++++ .../gpio/gpio-get-chipinfo-ioctl.rst | 41 ++++++ .../gpio/gpio-get-lineevent-ioctl.rst | 76 +++++++++++ .../gpio/gpio-get-linehandle-ioctl.rst | 84 ++++++++++++ .../gpio/gpio-get-lineinfo-ioctl.rst | 54 ++++++++ .../gpio/gpio-get-lineinfo-unwatch-ioctl.rst | 47 +++++++ .../gpio/gpio-get-lineinfo-watch-ioctl.rst | 72 ++++++++++ .../gpio-handle-get-line-values-ioctl.rst | 56 ++++++++ .../gpio/gpio-handle-set-config-ioctl.rst | 60 ++++++++ .../gpio-handle-set-line-values-ioctl.rst | 48 +++++++ .../gpio/gpio-lineevent-data-read.rst | 84 ++++++++++++ .../gpio/gpio-lineinfo-changed-read.rst | 85 ++++++++++++ .../gpio/gpio-v2-get-line-ioctl.rst | 99 ++++++++++++++ .../gpio/gpio-v2-get-lineinfo-ioctl.rst | 50 +++++++ .../gpio/gpio-v2-get-lineinfo-watch-ioctl.rst | 67 +++++++++ .../gpio/gpio-v2-line-event-read.rst | 83 +++++++++++ .../gpio/gpio-v2-line-get-values-ioctl.rst | 51 +++++++ .../gpio/gpio-v2-line-set-config-ioctl.rst | 57 ++++++++ .../gpio/gpio-v2-line-set-values-ioctl.rst | 47 +++++++ .../gpio/gpio-v2-lineinfo-changed-read.rst | 81 +++++++++++ Documentation/userspace-api/gpio/index.rst | 18 +++ .../gpio/sysfs.rst | 10 +- Documentation/userspace-api/index.rst | 1 + 29 files changed, 1621 insertions(+), 9 deletions(-) create mode 100644 Documentation/admin-guide/gpio/deprecated.rst create mode 100644 Documentation/userspace-api/gpio/chardev.rst create mode 100644 Documentation/userspace-api/gpio/chardev_v1.rst create mode 100644 Documentation/userspace-api/gpio/deprecated.rst create mode 100644 Documentation/userspace-api/gpio/error-codes.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst create mode 100644 Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst create mode 100644 Documentation/userspace-api/gpio/index.rst rename Documentation/{admin-guide => userspace-api}/gpio/sysfs.rst (94%)