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 v2 0/9] Documentation: gpio: add character device userspace API documentation
Date: Mon, 15 Jan 2024 08:48:38 +0800 [thread overview]
Message-ID: <20240115004847.22369-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 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
next reply other threads:[~2024-01-15 0:49 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-01-15 0:48 Kent Gibson [this message]
2024-01-15 0:48 ` [PATCH v2 1/9] Documentation: gpio: add chardev userspace API documentation Kent Gibson
2024-01-15 1:11 ` Andy Shevchenko
2024-01-15 1:30 ` Kent Gibson
2024-01-15 0:48 ` [PATCH v2 2/9] Documentation: ABI: update gpio-cdev to reference chardev.rst Kent Gibson
2024-01-15 0:48 ` [PATCH v2 3/9] Documentation: ABI: update sysfs-gpio to reference gpio-cdev Kent Gibson
2024-01-15 0:48 ` [PATCH v2 4/9] Documentation: gpio: move sysfs into an obsolete section Kent Gibson
2024-01-15 0:48 ` [PATCH v2 5/9] Documentation: gpio: update sysfs documentation to reference new chardev doc Kent Gibson
2024-01-15 0:48 ` [PATCH v2 6/9] Documentation: gpio: add chardev v1 userspace API documentation Kent Gibson
2024-01-15 0:48 ` [PATCH v2 7/9] Documentation: gpio: capitalize GPIO in index title Kent Gibson
2024-01-15 0:48 ` [PATCH v2 8/9] Documentation: gpio: document gpio-mockup as obsoleted by gpio-sim Kent Gibson
2024-01-15 0:48 ` [PATCH v2 9/9] Documentation: gpio: move gpio-mockup into obsolete section Kent Gibson
2024-01-15 1:20 ` Andy Shevchenko
2024-01-15 1:36 ` Kent Gibson
2024-01-22 9:50 ` [PATCH v2 0/9] Documentation: gpio: add character device userspace API documentation Bartosz Golaszewski
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=20240115004847.22369-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).