linux-kernel - Re: [PATCH v2 0/9] Documentation: gpio: add character device userspace API documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <CAMRc=MegMkgyBmanxTAvQwcGJ1_doNdqUAhCu-MECePZ=-_KrA@mail.gmail.com>
Date: Mon, 22 Jan 2024 10:50:02 +0100
From: Bartosz Golaszewski <brgl@...ev.pl>
To: Kent Gibson <warthog618@...il.com>
Cc: linux-kernel@...r.kernel.org, linux-gpio@...r.kernel.org, 
	linux-doc@...r.kernel.org, linus.walleij@...aro.org, andy@...nel.org, 
	corbet@....net
Subject: Re: [PATCH v2 0/9] Documentation: gpio: add character device
 userspace API documentation

On Mon, Jan 15, 2024 at 1:49 AM Kent Gibson <warthog618@...il.com> wrote:
>
> 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.
>

Not all heroes wear capes. Thanks for doing this Kent!

Queued the series for v6.9.

[snip]