Documentation: gpio: Move gpiod_* consumer documentation to driver-api

Move gpio/consumer.txt to driver-api/gpio/consumer.rst and make sure it
builds cleanly as ReST.

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

Documentation/gpio/consumer.txt → Documentation/driver-api/gpio/consumer.rst

@@ -1,3 +1,4 @@
+==================================
 GPIO Descriptor Consumer Interface
 ==================================
 
@@ -30,10 +31,10 @@ warnings. These stubs are used for two use cases:
   be met with console warnings that may be perceived as intimidating.
 
 All the functions that work with the descriptor-based GPIO interface are
-prefixed with gpiod_. The gpio_ prefix is used for the legacy interface. No
-other function in the kernel should use these prefixes. The use of the legacy
-functions is strongly discouraged, new code should use <linux/gpio/consumer.h>
-and descriptors exclusively.
+prefixed with ``gpiod_``. The ``gpio_`` prefix is used for the legacy
+interface. No other function in the kernel should use these prefixes. The use
+of the legacy functions is strongly discouraged, new code should use
+<linux/gpio/consumer.h> and descriptors exclusively.
 
 
 Obtaining and Disposing GPIOs
@@ -43,13 +44,13 @@ With the descriptor-based interface, GPIOs are identified with an opaque,
 non-forgeable handler that must be obtained through a call to one of the
 gpiod_get() functions. Like many other kernel subsystems, gpiod_get() takes the
 device that will use the GPIO and the function the requested GPIO is supposed to
-fulfill:
+fulfill::
 
 	struct gpio_desc *gpiod_get(struct device *dev, const char *con_id,
 				    enum gpiod_flags flags)
 
 If a function is implemented by using several GPIOs together (e.g. a simple LED
-device that displays digits), an additional index argument can be specified:
+device that displays digits), an additional index argument can be specified::
 
 	struct gpio_desc *gpiod_get_index(struct device *dev,
 					  const char *con_id, unsigned int idx,
@@ -84,7 +85,7 @@ occurred while trying to acquire it. This is useful to discriminate between mere
 errors and an absence of GPIO for optional GPIO parameters. For the common
 pattern where a GPIO is optional, the gpiod_get_optional() and
 gpiod_get_index_optional() functions can be used. These functions return NULL
-instead of -ENOENT if no GPIO has been assigned to the requested function:
+instead of -ENOENT if no GPIO has been assigned to the requested function::
 
 	struct gpio_desc *gpiod_get_optional(struct device *dev,
 					     const char *con_id,
@@ -101,14 +102,14 @@ This is helpful to driver authors, since they do not need to special case
 -ENOSYS return codes.  System integrators should however be careful to enable
 gpiolib on systems that need it.
 
-For a function using multiple GPIOs all of those can be obtained with one call:
+For a function using multiple GPIOs all of those can be obtained with one call::
 
 	struct gpio_descs *gpiod_get_array(struct device *dev,
 					   const char *con_id,
 					   enum gpiod_flags flags)
 
 This function returns a struct gpio_descs which contains an array of
-descriptors:
+descriptors::
 
 	struct gpio_descs {
 		unsigned int ndescs;
@@ -116,13 +117,13 @@ descriptors:
 	}
 
 The following function returns NULL instead of -ENOENT if no GPIOs have been
-assigned to the requested function:
+assigned to the requested function::
 
 	struct gpio_descs *gpiod_get_array_optional(struct device *dev,
 						    const char *con_id,
 						    enum gpiod_flags flags)
 
-Device-managed variants of these functions are also defined:
+Device-managed variants of these functions are also defined::
 
 	struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id,
 					 enum gpiod_flags flags)
@@ -149,11 +150,11 @@ Device-managed variants of these functions are also defined:
 							 const char *con_id,
 							 enum gpiod_flags flags)
 
-A GPIO descriptor can be disposed of using the gpiod_put() function:
+A GPIO descriptor can be disposed of using the gpiod_put() function::
 
 	void gpiod_put(struct gpio_desc *desc)
 
-For an array of GPIOs this function can be used:
+For an array of GPIOs this function can be used::
 
 	void gpiod_put_array(struct gpio_descs *descs)
 
@@ -161,7 +162,7 @@ It is strictly forbidden to use a descriptor after calling these functions.
 It is also not allowed to individually release descriptors (using gpiod_put())
 from an array acquired with gpiod_get_array().
 
-The device-managed variants are, unsurprisingly:
+The device-managed variants are, unsurprisingly::
 
 	void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)
 
@@ -175,7 +176,7 @@ Setting Direction
 -----------------
 The first thing a driver must do with a GPIO is setting its direction. If no
 direction-setting flags have been given to gpiod_get*(), this is done by
-invoking one of the gpiod_direction_*() functions:
+invoking one of the gpiod_direction_*() functions::
 
 	int gpiod_direction_input(struct gpio_desc *desc)
 	int gpiod_direction_output(struct gpio_desc *desc, int value)
@@ -189,7 +190,7 @@ of early board setup.
 For output GPIOs, the value provided becomes the initial output value. This
 helps avoid signal glitching during system startup.
 
-A driver can also query the current direction of a GPIO:
+A driver can also query the current direction of a GPIO::
 
 	int gpiod_get_direction(const struct gpio_desc *desc)
 
@@ -206,7 +207,7 @@ Most GPIO controllers can be accessed with memory read/write instructions. Those
 don't need to sleep, and can safely be done from inside hard (non-threaded) IRQ
 handlers and similar contexts.
 
-Use the following calls to access GPIOs from an atomic context:
+Use the following calls to access GPIOs from an atomic context::
 
 	int gpiod_get_value(const struct gpio_desc *desc);
 	void gpiod_set_value(struct gpio_desc *desc, int value);
@@ -231,11 +232,11 @@ head of a queue to transmit a command and get its response. This requires
 sleeping, which can't be done from inside IRQ handlers.
 
 Platforms that support this type of GPIO distinguish them from other GPIOs by
-returning nonzero from this call:
+returning nonzero from this call::
 
 	int gpiod_cansleep(const struct gpio_desc *desc)
 
-To access such GPIOs, a different set of accessors is defined:
+To access such GPIOs, a different set of accessors is defined::
 
 	int gpiod_get_value_cansleep(const struct gpio_desc *desc)
 	void gpiod_set_value_cansleep(struct gpio_desc *desc, int value)
@@ -271,23 +272,23 @@ As an example, if the active low property for a dedicated GPIO is set, and the
 gpiod_set_(array)_value_xxx() passes "asserted" ("1"), the physical line level
 will be driven low.
 
-To summarize:
-
-Function (example)                 line property          physical line
-gpiod_set_raw_value(desc, 0);      don't care             low
-gpiod_set_raw_value(desc, 1);      don't care             high
-gpiod_set_value(desc, 0);          default (active high)  low
-gpiod_set_value(desc, 1);          default (active high)  high
-gpiod_set_value(desc, 0);          active low             high
-gpiod_set_value(desc, 1);          active low             low
-gpiod_set_value(desc, 0);          default (active high)  low
-gpiod_set_value(desc, 1);          default (active high)  high
-gpiod_set_value(desc, 0);          open drain             low
-gpiod_set_value(desc, 1);          open drain             high impedance
-gpiod_set_value(desc, 0);          open source            high impedance
-gpiod_set_value(desc, 1);          open source            high
-
-It is possible to override these semantics using the *set_raw/'get_raw functions
+To summarize::
+
+  Function (example)                 line property          physical line
+  gpiod_set_raw_value(desc, 0);      don't care             low
+  gpiod_set_raw_value(desc, 1);      don't care             high
+  gpiod_set_value(desc, 0);          default (active high)  low
+  gpiod_set_value(desc, 1);          default (active high)  high
+  gpiod_set_value(desc, 0);          active low             high
+  gpiod_set_value(desc, 1);          active low             low
+  gpiod_set_value(desc, 0);          default (active high)  low
+  gpiod_set_value(desc, 1);          default (active high)  high
+  gpiod_set_value(desc, 0);          open drain             low
+  gpiod_set_value(desc, 1);          open drain             high impedance
+  gpiod_set_value(desc, 0);          open source            high impedance
+  gpiod_set_value(desc, 1);          open source            high
+
+It is possible to override these semantics using the set_raw/get_raw functions
 but it should be avoided as much as possible, especially by system-agnostic drivers
 which should not need to care about the actual physical line level and worry about
 the logical value instead.
@@ -300,7 +301,7 @@ their device will actually receive, no matter what lies between it and the GPIO
 line.
 
 The following set of calls ignore the active-low or open drain property of a GPIO and
-work on the raw line value:
+work on the raw line value::
 
 	int gpiod_get_raw_value(const struct gpio_desc *desc)
 	void gpiod_set_raw_value(struct gpio_desc *desc, int value)
@@ -308,7 +309,7 @@ work on the raw line value:
 	void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)
 	int gpiod_direction_output_raw(struct gpio_desc *desc, int value)
 
-The active low state of a GPIO can also be queried using the following call:
+The active low state of a GPIO can also be queried using the following call::
 
 	int gpiod_is_active_low(const struct gpio_desc *desc)
 
@@ -318,7 +319,7 @@ should not have to care about the physical line level or open drain semantics.
 
 Access multiple GPIOs with a single function call
 -------------------------------------------------
-The following functions get or set the values of an array of GPIOs:
+The following functions get or set the values of an array of GPIOs::
 
 	int gpiod_get_array_value(unsigned int array_size,
 				  struct gpio_desc **desc_array,
@@ -361,7 +362,7 @@ The functions take three arguments:
 The descriptor array can be obtained using the gpiod_get_array() function
 or one of its variants. If the group of descriptors returned by that function
 matches the desired group of GPIOs, those GPIOs can be accessed by simply using
-the struct gpio_descs returned by gpiod_get_array():
+the struct gpio_descs returned by gpiod_get_array()::
 
 	struct gpio_descs *my_gpio_descs = gpiod_get_array(...);
 	gpiod_set_array_value(my_gpio_descs->ndescs, my_gpio_descs->desc,
@@ -384,7 +385,7 @@ values are stored in value_array rather than passed back as return value.
 GPIOs mapped to IRQs
 --------------------
 GPIO lines can quite often be used as IRQs. You can get the IRQ number
-corresponding to a given GPIO using the following call:
+corresponding to a given GPIO using the following call::
 
 	int gpiod_to_irq(const struct gpio_desc *desc)
 
@@ -424,7 +425,7 @@ Interacting With the Legacy GPIO Subsystem
 Many kernel subsystems still handle GPIOs using the legacy integer-based
 interface. Although it is strongly encouraged to upgrade them to the safer
 descriptor-based API, the following two functions allow you to convert a GPIO
-descriptor into the GPIO integer namespace and vice-versa:
+descriptor into the GPIO integer namespace and vice-versa::
 
 	int desc_to_gpio(const struct gpio_desc *desc)
 	struct gpio_desc *gpio_to_desc(unsigned gpio)

Documentation/driver-api/gpio/index.rst

@@ -9,6 +9,7 @@ Contents:
 
    intro
    driver
+   consumer
    legacy
 
 Core

Documentation/gpio/00-INDEX

@@ -1,7 +1,5 @@
 00-INDEX
 	- This file
-consumer.txt
-	- How to obtain and use GPIOs in a driver
 drivers-on-gpio.txt:
 	- Drivers in other subsystems that can use GPIO to provide more
 	  complex functionality.