From: Kent Gibson <warthog618@gmail.com>
To: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org,
linux-doc@vger.kernel.org, brgl@bgdev.pl,
linus.walleij@linaro.org, andy@kernel.org, corbet@lwn.net
Cc: Kent Gibson <warthog618@gmail.com>
Subject: [PATCH 0/7] Documentation: gpio: add character device userspace API documentation
Date: Tue, 9 Jan 2024 21:59:45 +0800 [thread overview]
Message-ID: <20240109135952.77458-1-warthog618@gmail.com> (raw)
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%)
--
2.39.2
next reply other threads:[~2024-01-09 14:00 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-01-09 13:59 Kent Gibson [this message]
2024-01-09 13:59 ` [PATCH 1/7] Documentation: gpio: add chardev userspace API documentation Kent Gibson
2024-01-10 11:40 ` Phil Howard
2024-01-10 12:20 ` Andy Shevchenko
2024-01-10 13:01 ` Kent Gibson
2024-01-10 14:27 ` Linus Walleij
2024-01-10 14:34 ` Kent Gibson
2024-01-10 14:50 ` Linus Walleij
2024-01-10 14:53 ` Kent Gibson
2024-01-09 13:59 ` [PATCH 2/7] Documentation: gpio: move sysfs into a deprecated section Kent Gibson
2024-01-09 13:59 ` [PATCH 3/7] Documentation: gpio: update sysfs documentation to reference new chardev doc Kent Gibson
2024-01-09 13:59 ` [PATCH 4/7] Documentation: gpio: add chardev v1 userspace API documentation Kent Gibson
2024-01-09 13:59 ` [PATCH 5/7] Documentation: gpio: capitalize GPIO in index title Kent Gibson
2024-01-09 13:59 ` [PATCH 6/7] Documentation: gpio: document gpio-mockup as obsoleted by gpio-sim Kent Gibson
2024-01-09 13:59 ` [PATCH 7/7] Documentation: gpio: move gpio-mockup into deprecated section Kent Gibson
2024-01-09 20:00 ` [PATCH 0/7] Documentation: gpio: add character device userspace API documentation Andy Shevchenko
2024-01-09 23:45 ` Kent Gibson
2024-01-10 8:16 ` Vegard Nossum
2024-01-10 11:10 ` Andy Shevchenko
2024-01-12 1:03 ` Kent Gibson
2024-01-14 2:47 ` Kent Gibson
2024-01-14 12:01 ` Andy Shevchenko
2024-01-14 12:55 ` Kent Gibson
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240109135952.77458-1-warthog618@gmail.com \
--to=warthog618@gmail.com \
--cc=andy@kernel.org \
--cc=brgl@bgdev.pl \
--cc=corbet@lwn.net \
--cc=linus.walleij@linaro.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-gpio@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).