Received-SPF: pass (google.com: domain of linux-kernel+bounces-20929-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3;
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
Message-Id: <20240109135952.77458-1-warthog618@gmail.com>
Precedence: bulk
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

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