summaryrefslogtreecommitdiff
path: root/Documentation/gpio.txt
diff options
context:
space:
mode:
authorDavid Brownell <dbrownell@users.sourceforge.net>2009-04-03 03:57:06 +0400
committerLinus Torvalds <torvalds@linux-foundation.org>2009-04-03 06:04:51 +0400
commit8a0cecffeb52363a57257bbbbd58f4c4537a75bb (patch)
treeee7f754d49a2f2ad75b72ec59e90e6fa2c0753eb /Documentation/gpio.txt
parent926b663ce8215ba448960e1ff6e58b67a2c3b99b (diff)
downloadlinux-8a0cecffeb52363a57257bbbbd58f4c4537a75bb.tar.xz
gpio: gpio_{request,free}() now required (feature removal)
We want to phase out the GPIO "autorequest" mechanism in gpiolib and require all callers to use gpio_request(). - Update feature-removal-schedule - Update the documentation now - Convert the relevant pr_warning() in gpiolib to a WARN() so folk using this mechanism get a noisy stack dump Some drivers and board init code will probably need to change. Implementations not using gpiolib will still be fine; they are already required to implement gpio_{request,free}() stubs. Signed-off-by: David Brownell <dbrownell@users.sourceforge.net> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation/gpio.txt')
-rw-r--r--Documentation/gpio.txt23
1 files changed, 9 insertions, 14 deletions
diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt
index b1b988701247..145c25a170c7 100644
--- a/Documentation/gpio.txt
+++ b/Documentation/gpio.txt
@@ -123,7 +123,10 @@ platform-specific implementation issue.
Using GPIOs
-----------
-One of the first things to do with a GPIO, often in board setup code when
+The first thing a system should do with a GPIO is allocate it, using
+the gpio_request() call; see later.
+
+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:
/* set as input or output, returning 0 or negative errno */
@@ -141,8 +144,8 @@ This helps avoid signal glitching during system startup.
For compatibility with legacy interfaces to GPIOs, setting the direction
of a GPIO implicitly requests that GPIO (see below) if it has not been
-requested already. That compatibility may be removed in the future;
-explicitly requesting GPIOs is strongly preferred.
+requested already. That compatibility is being removed from the optional
+gpiolib framework.
Setting the direction can fail if the GPIO number is invalid, or when
that particular GPIO can't be used in that mode. It's generally a bad
@@ -195,7 +198,7 @@ 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 (which requires a valid GPIO number,
-either explicitly or implicitly requested):
+which should have been previously allocated with gpio_request):
int gpio_cansleep(unsigned gpio);
@@ -212,10 +215,9 @@ for GPIOs that can't be accessed from IRQ handlers, these calls act the
same as the spinlock-safe calls.
-Claiming and Releasing GPIOs (OPTIONAL)
----------------------------------------
+Claiming and Releasing GPIOs
+----------------------------
To help catch system configuration errors, two calls are defined.
-However, many platforms don't currently support this mechanism.
/* request GPIO, returning 0 or negative errno.
* non-null labels may be useful for diagnostics.
@@ -244,13 +246,6 @@ Some platforms may also use knowledge about what GPIOs are active for
power management, such as by powering down unused chip sectors and, more
easily, gating off unused clocks.
-These two calls are optional because not not all current Linux platforms
-offer such functionality in their GPIO support; a valid implementation
-could return success for all gpio_request() calls. Unlike the other calls,
-the state they represent doesn't normally match anything from a hardware
-register; it's just a software bitmap which clearly is not necessary for
-correct operation of hardware or (bug free) drivers.
-
Note that requesting a GPIO does NOT cause it to be configured in any
way; it just marks that GPIO as in use. Separate code must handle any
pin setup (e.g. controlling which pin the GPIO uses, pullup/pulldown).