Documentation: gpio: Move legacy documentation to driver-api
Move gpio/gpio-legacy.txt to driver-api/gpio/legacy.rst and make sure it builds cleanly as ReST. Also move the legacy API reference from index.rst to legacy.rst. Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
This commit is contained in:
parent
778ea833c5
commit
7ee2c13080
|
@ -9,6 +9,7 @@ Contents:
|
||||||
|
|
||||||
intro
|
intro
|
||||||
driver
|
driver
|
||||||
|
legacy
|
||||||
|
|
||||||
Core
|
Core
|
||||||
====
|
====
|
||||||
|
@ -19,15 +20,6 @@ Core
|
||||||
.. kernel-doc:: drivers/gpio/gpiolib.c
|
.. kernel-doc:: drivers/gpio/gpiolib.c
|
||||||
:export:
|
:export:
|
||||||
|
|
||||||
Legacy API
|
|
||||||
==========
|
|
||||||
|
|
||||||
The functions listed in this section are deprecated. The GPIO descriptor based
|
|
||||||
API described above should be used in new code.
|
|
||||||
|
|
||||||
.. kernel-doc:: drivers/gpio/gpiolib-legacy.c
|
|
||||||
:export:
|
|
||||||
|
|
||||||
ACPI support
|
ACPI support
|
||||||
============
|
============
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,6 @@
|
||||||
GPIO Interfaces
|
======================
|
||||||
|
Legacy GPIO Interfaces
|
||||||
|
======================
|
||||||
|
|
||||||
This provides an overview of GPIO access conventions on Linux.
|
This provides an overview of GPIO access conventions on Linux.
|
||||||
|
|
||||||
|
@ -129,7 +131,7 @@ The first thing a system should do with a GPIO is allocate it, using
|
||||||
the gpio_request() call; see later.
|
the gpio_request() call; see later.
|
||||||
|
|
||||||
One of the next things to do with a GPIO, often in board setup code when
|
One of the next things to do with a GPIO, often in board setup code when
|
||||||
setting up a platform_device using the GPIO, is mark its direction:
|
setting up a platform_device using the GPIO, is mark its direction::
|
||||||
|
|
||||||
/* set as input or output, returning 0 or negative errno */
|
/* set as input or output, returning 0 or negative errno */
|
||||||
int gpio_direction_input(unsigned gpio);
|
int gpio_direction_input(unsigned gpio);
|
||||||
|
@ -164,7 +166,7 @@ Those don't need to sleep, and can safely be done from inside hard
|
||||||
(nonthreaded) IRQ handlers and similar contexts.
|
(nonthreaded) IRQ handlers and similar contexts.
|
||||||
|
|
||||||
Use the following calls to access such GPIOs,
|
Use the following calls to access such GPIOs,
|
||||||
for which gpio_cansleep() will always return false (see below):
|
for which gpio_cansleep() will always return false (see below)::
|
||||||
|
|
||||||
/* GPIO INPUT: return zero or nonzero */
|
/* GPIO INPUT: return zero or nonzero */
|
||||||
int gpio_get_value(unsigned gpio);
|
int gpio_get_value(unsigned gpio);
|
||||||
|
@ -201,11 +203,11 @@ This requires sleeping, which can't be done from inside IRQ handlers.
|
||||||
|
|
||||||
Platforms that support this type of GPIO distinguish them from other GPIOs
|
Platforms that support this type of GPIO distinguish them from other GPIOs
|
||||||
by returning nonzero from this call (which requires a valid GPIO number,
|
by returning nonzero from this call (which requires a valid GPIO number,
|
||||||
which should have been previously allocated with gpio_request):
|
which should have been previously allocated with gpio_request)::
|
||||||
|
|
||||||
int gpio_cansleep(unsigned gpio);
|
int gpio_cansleep(unsigned gpio);
|
||||||
|
|
||||||
To access such GPIOs, a different set of accessors is defined:
|
To access such GPIOs, a different set of accessors is defined::
|
||||||
|
|
||||||
/* GPIO INPUT: return zero or nonzero, might sleep */
|
/* GPIO INPUT: return zero or nonzero, might sleep */
|
||||||
int gpio_get_value_cansleep(unsigned gpio);
|
int gpio_get_value_cansleep(unsigned gpio);
|
||||||
|
@ -222,27 +224,27 @@ Other than the fact that these accessors might sleep, and will work
|
||||||
on GPIOs that can't be accessed from hardIRQ handlers, these calls act
|
on GPIOs that can't be accessed from hardIRQ handlers, these calls act
|
||||||
the same as the spinlock-safe calls.
|
the same as the spinlock-safe calls.
|
||||||
|
|
||||||
** IN ADDITION ** calls to setup and configure such GPIOs must be made
|
**IN ADDITION** calls to setup and configure such GPIOs must be made
|
||||||
from contexts which may sleep, since they may need to access the GPIO
|
from contexts which may sleep, since they may need to access the GPIO
|
||||||
controller chip too: (These setup calls are usually made from board
|
controller chip too (These setup calls are usually made from board
|
||||||
setup or driver probe/teardown code, so this is an easy constraint.)
|
setup or driver probe/teardown code, so this is an easy constraint.)::
|
||||||
|
|
||||||
gpio_direction_input()
|
gpio_direction_input()
|
||||||
gpio_direction_output()
|
gpio_direction_output()
|
||||||
gpio_request()
|
gpio_request()
|
||||||
|
|
||||||
## gpio_request_one()
|
## gpio_request_one()
|
||||||
## gpio_request_array()
|
## gpio_request_array()
|
||||||
## gpio_free_array()
|
## gpio_free_array()
|
||||||
|
|
||||||
gpio_free()
|
gpio_free()
|
||||||
gpio_set_debounce()
|
gpio_set_debounce()
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Claiming and Releasing GPIOs
|
Claiming and Releasing GPIOs
|
||||||
----------------------------
|
----------------------------
|
||||||
To help catch system configuration errors, two calls are defined.
|
To help catch system configuration errors, two calls are defined::
|
||||||
|
|
||||||
/* request GPIO, returning 0 or negative errno.
|
/* request GPIO, returning 0 or negative errno.
|
||||||
* non-null labels may be useful for diagnostics.
|
* non-null labels may be useful for diagnostics.
|
||||||
|
@ -296,7 +298,7 @@ Also note that it's your responsibility to have stopped using a GPIO
|
||||||
before you free it.
|
before you free it.
|
||||||
|
|
||||||
Considering in most cases GPIOs are actually configured right after they
|
Considering in most cases GPIOs are actually configured right after they
|
||||||
are claimed, three additional calls are defined:
|
are claimed, three additional calls are defined::
|
||||||
|
|
||||||
/* request a single GPIO, with initial configuration specified by
|
/* request a single GPIO, with initial configuration specified by
|
||||||
* 'flags', identical to gpio_request() wrt other arguments and
|
* 'flags', identical to gpio_request() wrt other arguments and
|
||||||
|
@ -347,7 +349,7 @@ to make the pin LOW. The pin is make to HIGH by driving value 1 in output mode.
|
||||||
In the future, these flags can be extended to support more properties.
|
In the future, these flags can be extended to support more properties.
|
||||||
|
|
||||||
Further more, to ease the claim/release of multiple GPIOs, 'struct gpio' is
|
Further more, to ease the claim/release of multiple GPIOs, 'struct gpio' is
|
||||||
introduced to encapsulate all three fields as:
|
introduced to encapsulate all three fields as::
|
||||||
|
|
||||||
struct gpio {
|
struct gpio {
|
||||||
unsigned gpio;
|
unsigned gpio;
|
||||||
|
@ -355,7 +357,7 @@ introduced to encapsulate all three fields as:
|
||||||
const char *label;
|
const char *label;
|
||||||
};
|
};
|
||||||
|
|
||||||
A typical example of usage:
|
A typical example of usage::
|
||||||
|
|
||||||
static struct gpio leds_gpios[] = {
|
static struct gpio leds_gpios[] = {
|
||||||
{ 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* default to ON */
|
{ 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* default to ON */
|
||||||
|
@ -380,7 +382,7 @@ GPIOs mapped to IRQs
|
||||||
--------------------
|
--------------------
|
||||||
GPIO numbers are unsigned integers; so are IRQ numbers. These make up
|
GPIO numbers are unsigned integers; so are IRQ numbers. These make up
|
||||||
two logically distinct namespaces (GPIO 0 need not use IRQ 0). You can
|
two logically distinct namespaces (GPIO 0 need not use IRQ 0). You can
|
||||||
map between them using calls like:
|
map between them using calls like::
|
||||||
|
|
||||||
/* map GPIO numbers to IRQ numbers */
|
/* map GPIO numbers to IRQ numbers */
|
||||||
int gpio_to_irq(unsigned gpio);
|
int gpio_to_irq(unsigned gpio);
|
||||||
|
@ -446,12 +448,12 @@ A GPIO controller on a SOC might be tightly coupled with the pinctrl
|
||||||
subsystem, in the sense that the pins can be used by other functions
|
subsystem, in the sense that the pins can be used by other functions
|
||||||
together with an optional gpio feature. We have already covered the
|
together with an optional gpio feature. We have already covered the
|
||||||
case where e.g. a GPIO controller need to reserve a pin or set the
|
case where e.g. a GPIO controller need to reserve a pin or set the
|
||||||
direction of a pin by calling any of:
|
direction of a pin by calling any of::
|
||||||
|
|
||||||
pinctrl_gpio_request()
|
pinctrl_gpio_request()
|
||||||
pinctrl_gpio_free()
|
pinctrl_gpio_free()
|
||||||
pinctrl_gpio_direction_input()
|
pinctrl_gpio_direction_input()
|
||||||
pinctrl_gpio_direction_output()
|
pinctrl_gpio_direction_output()
|
||||||
|
|
||||||
But how does the pin control subsystem cross-correlate the GPIO
|
But how does the pin control subsystem cross-correlate the GPIO
|
||||||
numbers (which are a global business) to a certain pin on a certain
|
numbers (which are a global business) to a certain pin on a certain
|
||||||
|
@ -565,7 +567,7 @@ If neither of these options are selected, the platform does not support
|
||||||
GPIOs through GPIO-lib and the code cannot be enabled by the user.
|
GPIOs through GPIO-lib and the code cannot be enabled by the user.
|
||||||
|
|
||||||
Trivial implementations of those functions can directly use framework
|
Trivial implementations of those functions can directly use framework
|
||||||
code, which always dispatches through the gpio_chip:
|
code, which always dispatches through the gpio_chip::
|
||||||
|
|
||||||
#define gpio_get_value __gpio_get_value
|
#define gpio_get_value __gpio_get_value
|
||||||
#define gpio_set_value __gpio_set_value
|
#define gpio_set_value __gpio_set_value
|
||||||
|
@ -731,7 +733,7 @@ the correct GPIO number to use for a given signal.
|
||||||
Exporting from Kernel code
|
Exporting from Kernel code
|
||||||
--------------------------
|
--------------------------
|
||||||
Kernel code can explicitly manage exports of GPIOs which have already been
|
Kernel code can explicitly manage exports of GPIOs which have already been
|
||||||
requested using gpio_request():
|
requested using gpio_request()::
|
||||||
|
|
||||||
/* export the GPIO to userspace */
|
/* export the GPIO to userspace */
|
||||||
int gpio_export(unsigned gpio, bool direction_may_change);
|
int gpio_export(unsigned gpio, bool direction_may_change);
|
||||||
|
@ -756,3 +758,13 @@ After the GPIO has been exported, gpio_export_link() allows creating
|
||||||
symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can
|
symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can
|
||||||
use this to provide the interface under their own device in sysfs with
|
use this to provide the interface under their own device in sysfs with
|
||||||
a descriptive name.
|
a descriptive name.
|
||||||
|
|
||||||
|
|
||||||
|
API Reference
|
||||||
|
=============
|
||||||
|
|
||||||
|
The functions listed in this section are deprecated. The GPIO descriptor based
|
||||||
|
API should be used in new code.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/gpio/gpiolib-legacy.c
|
||||||
|
:export:
|
|
@ -9,5 +9,3 @@ board.txt
|
||||||
- How to assign GPIOs to a consumer device and a function
|
- How to assign GPIOs to a consumer device and a function
|
||||||
sysfs.txt
|
sysfs.txt
|
||||||
- Information about the GPIO sysfs interface
|
- Information about the GPIO sysfs interface
|
||||||
gpio-legacy.txt
|
|
||||||
- Historical documentation of the deprecated GPIO integer interface
|
|
||||||
|
|
Loading…
Reference in a new issue