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 updates the gpio-cdev ABI documentation to reference the
chardev documentation as well as gpio.h.
Patch 3 updates the sysfs-gpio ABI documentation to reference the
gpio-cdev ABI that obsoletes it.
Patch 4 relocates the sysfs API doc to stress its deprecation by
moving it to a new obsolete section, again in userspace-api but
with a similar section in the admin-guide. The obsolete section
also serves as a placeholder for subsequent changes.
Patch 5 updates the sysfs API doc to reference the chardev
documentation rather than gpio.h and make use of reST formatting.
Patch 6 adds documentation for the obsolete v1 version of the
chardev uAPI. It is obsolete, but still useful to have, if
nothing else to help identify the differences between v1 and v2.
Patch 7 capitalizes the title of the admin-guide/gpio to match
the other subsystems and the userspace-api book.
Patch 8 adds an obsolescence note to the gpio-mockup, as it is
obsoleted by the gpio-sim.
Patch 9 moves the gpio-mockup doc into the obsolete 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've sent those separately
to 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.
Changes v1 -> v2:
- add Linus' review tag (patch 1)
- add first added kernel version for APIs, and ioctls where
they were added separately from the API they are part of (patch 1 and 6).
- add note that requesting a line in use is an error (EBUSY),
GPIO_v2_GET_LINE_IOCTL (patch 1), GPIO_GET_LINEEVENT_IOCTL
and GPIO_GET_LINEHANDLE_IOCTL (patch 6).
- add updating gpio-cdev interface doc to reference chardev.rst (patch 2).
- add updating sysfs-gpio interface doc to reference gpio-cdev (patch 3).
- rename deprecated section to obsolete section (patch 4, 6 and 9).
- rework obsolescence warning and abuse note in sysfs.rst to
make use of reST formatting for emphasis, rather than ALL CAPS,
and to note that the interface is to be removed in the future
(patch 5).
- note that the v1 API will be removed in the future (patch 6).
Kent Gibson (9):
Documentation: gpio: add chardev userspace API documentation
Documentation: ABI: update gpio-cdev to reference chardev.rst
Documentation: ABI: update sysfs-gpio to reference gpio-cdev
Documentation: gpio: move sysfs into an obsolete 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 obsolete section
Documentation/ABI/obsolete/sysfs-gpio | 4 +-
Documentation/ABI/testing/gpio-cdev | 9 +-
.../admin-guide/gpio/gpio-mockup.rst | 8 ++
Documentation/admin-guide/gpio/index.rst | 6 +-
Documentation/admin-guide/gpio/obsolete.rst | 13 ++
Documentation/userspace-api/gpio/chardev.rst | 116 ++++++++++++++++
.../userspace-api/gpio/chardev_v1.rst | 131 ++++++++++++++++++
.../userspace-api/gpio/error-codes.rst | 78 +++++++++++
.../gpio/gpio-get-chipinfo-ioctl.rst | 41 ++++++
.../gpio/gpio-get-lineevent-ioctl.rst | 78 +++++++++++
.../gpio/gpio-get-linehandle-ioctl.rst | 86 ++++++++++++
.../gpio/gpio-get-lineinfo-ioctl.rst | 54 ++++++++
.../gpio/gpio-get-lineinfo-unwatch-ioctl.rst | 49 +++++++
.../gpio/gpio-get-lineinfo-watch-ioctl.rst | 74 ++++++++++
.../gpio-handle-get-line-values-ioctl.rst | 56 ++++++++
.../gpio/gpio-handle-set-config-ioctl.rst | 62 +++++++++
.../gpio-handle-set-line-values-ioctl.rst | 48 +++++++
.../gpio/gpio-lineevent-data-read.rst | 84 +++++++++++
.../gpio/gpio-lineinfo-changed-read.rst | 87 ++++++++++++
.../gpio/gpio-v2-get-line-ioctl.rst | 101 ++++++++++++++
.../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 +++
Documentation/userspace-api/gpio/obsolete.rst | 11 ++
.../gpio/sysfs.rst | 27 ++--
Documentation/userspace-api/index.rst | 1 +
31 files changed, 1657 insertions(+), 21 deletions(-)
create mode 100644 Documentation/admin-guide/gpio/obsolete.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/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
create mode 100644 Documentation/userspace-api/gpio/obsolete.rst
rename Documentation/{admin-guide => userspace-api}/gpio/sysfs.rst (89%)
--
2.39.2
