Re: [PATCH 0/8] Move most GPIO documentation to driver-api/gpio/ and ReST

From: Jonathan NeuschÃfer
Date: Sat Mar 10 2018 - 06:18:59 EST


On Fri, Mar 09, 2018 at 10:41:20AM -0700, Jonathan Corbet wrote:
> On Fri, 9 Mar 2018 00:40:16 +0100
> Jonathan NeuschÃfer <j.neuschaefer@xxxxxxx> wrote:
>
> > The aim of this patchset is to move the GPIO subsystem's documentation
> > under Documentation/driver-api/gpio/ such that it is picked up by Sphinx
> > and compiled into HTML. I moved everything except for sysfs.txt, because
> > this file describes the legacy sysfs ABI, and doesn't seem to serve much
> > (non-historical) purpose anymore.
> >
> > There are still some rough edges:
> >
> > * I think the API documentation (kernel-doc) should be moved out of
> > index.rst into more appropriate files.
> > * The headings are arguably wrong, because driver.rst, consumer.rst,
> > etc. use the "document title" style, even though they are part of the
> > GPIO chapter. But the resulting TOC tree is consistent, and I did not
> > want to change almost all headings.
> > * Some of the files could use more :c:func:`...` references and general
> > ReST polish.
> >
> > But I don't want to make this patchset too large.
>
> [For future reference, if you're going to CC me on most of a patch series,
> I'd really rather get the whole thing so I don't have to go looking for
> it.]

Noted.

> From a quick look, it seems like a reasonable RST conversion to me. I do
> wonder if sysfs.txt should just be removed, since it documents something
> we don't want people to use at this point? Historical purposes are well
> served by the repository history.
>
> I'd say changing the headings is worthwhile if it produces a better
> result.

I just tried this on one file (driver.rst) and it made no difference in
the output (neither in the TOC in index.html nor in driver.html).

Thanks,
Jonathan NeuschÃfer


> OTOH I'd be wary of adding too much "polish"; we really want to
> retain the readability of the plain-text files.
>
> Anyway, I'm happy to take these through the docs tree or see them go via
> GPIO; Linus, what's your preference?
>
> Thanks,
>
> jon


----

diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst
index 505ee906d7d9..8eb08005be55 100644
--- a/Documentation/driver-api/gpio/driver.rst
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -1,4 +1,3 @@
-================================
GPIO Descriptor Driver Interface
================================

@@ -13,7 +12,7 @@ the structures used to define a GPIO driver:


Internal Representation of GPIOs
-================================
+--------------------------------

Inside a GPIO driver, individual GPIOs are identified by their hardware number,
which is a unique number between 0 and n, n being the number of GPIOs managed by
@@ -36,7 +35,7 @@ identify GPIOs in a bank of I2C GPIO expanders.


Controller Drivers: gpio_chip
-=============================
+-----------------------------

In the gpiolib framework each GPIO controller is packaged as a "struct
gpio_chip" (see linux/gpio/driver.h for its complete definition) with members
@@ -74,7 +73,7 @@ not be required.


GPIO electrical configuration
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

GPIOs can be configured for several electrical modes of operation by using the
.set_config() callback. Currently this API supports setting debouncing and
@@ -95,7 +94,7 @@ numbers on the pin controller so they can properly cross-reference each other.


GPIOs with debounce support
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~

Debouncing is a configuration set to a pin indicating that it is connected to
a mechanical switch or button, or similar that may bounce. Bouncing means the
@@ -112,7 +111,7 @@ is not configurable.


GPIOs with open drain/source support
-------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Open drain (CMOS) or open collector (TTL) means the line is not actively driven
high: instead you provide the drain/collector as output, so when the transistor
@@ -209,7 +208,7 @@ of actively driving the line low, it is set to input.


GPIO drivers providing IRQs
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is custom that GPIO drivers (GPIO chips) are also providing interrupts,
most often cascaded off a parent interrupt controller, and in some special
cases the GPIO logic is melded with a SoC's primary interrupt controller.
@@ -359,7 +358,7 @@ below exists.


Locking IRQ usage
------------------
+~~~~~~~~~~~~~~~~~
Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
to mark the GPIO as being used as an IRQ::

@@ -378,7 +377,7 @@ When using the gpiolib irqchip helpers, these callback are automatically
assigned.

Real-Time compliance for GPIO IRQ chips
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Any provider of irqchips needs to be carefully tailored to support Real Time
preemption. It is desirable that all irqchips in the GPIO subsystem keep this
@@ -404,7 +403,7 @@ time-compliance:


Requesting self-owned GPIO pins
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sometimes it is useful to allow a GPIO chip driver to request its own GPIO
descriptors through the gpiolib API. Using gpio_request() for this purpose

Attachment: signature.asc
Description: PGP signature