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
