Commit 7ee2c130 authored by Jonathan Neuschäfer's avatar Jonathan Neuschäfer Committed by Linus Walleij

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: default avatarJonathan Neuschäfer <j.neuschaefer@gmx.net>
Signed-off-by: default avatarLinus Walleij <linus.walleij@linaro.org>
parent 778ea833
...@@ -9,6 +9,7 @@ Contents: ...@@ -9,6 +9,7 @@ Contents:
intro intro
driver driver
legacy
Core Core
==== ====
...@@ -19,15 +20,6 @@ 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
============ ============
......
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 ...@@ -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 ...@@ -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. ...@@ -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 ...@@ -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 ...@@ -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. ...@@ -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: ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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. ...@@ -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 ...@@ -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 ...@@ -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
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