Commit 4e0edc4b authored by Jonathan Neuschäfer's avatar Jonathan Neuschäfer Committed by Linus Walleij

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: default avatarJonathan Neuschäfer <j.neuschaefer@gmx.net>
Signed-off-by: default avatarLinus Walleij <linus.walleij@linaro.org>
parent 7ee2c130
==================================
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
......
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.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment