similarity index 89%
rename from Documentation/gpio/consumer.txt
rename to 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)
@@ -9,6 +9,7 @@ Contents:
intro
driver
+ consumer
legacy
Core
@@ -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.
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> --- .../consumer.txt => driver-api/gpio/consumer.rst} | 85 +++++++++++----------- Documentation/driver-api/gpio/index.rst | 1 + Documentation/gpio/00-INDEX | 2 - 3 files changed, 44 insertions(+), 44 deletions(-) rename Documentation/{gpio/consumer.txt => driver-api/gpio/consumer.rst} (89%)