diff mbox

pinctrl: elaborate a bit on arrangements in doc

Message ID 1372169952-22439-1-git-send-email-linus.walleij@stericsson.com
State New
Headers show

Commit Message

Linus Walleij June 25, 2013, 2:19 p.m. UTC 
From: Linus Walleij <linus.walleij@linaro.org>

This elaborates a bit on the pinctrl vs GPIO arangements
in the hardware.

Inspired by some drawings in a mail from Christian
Ruppert.

Cc: Rob Landley <rob@landley.net>
Cc: Christian Ruppert <christian.ruppert@abilis.com>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
---
 Documentation/pinctrl.txt | 37 ++++++++++++++++++++++++++++++++-----
 1 file changed, 32 insertions(+), 5 deletions(-)
diff mbox

Patch

diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt
index 447fd4c..41ecad0 100644
--- a/Documentation/pinctrl.txt
+++ b/Documentation/pinctrl.txt
@@ -784,11 +784,38 @@  special GPIO-handler is registered.
 GPIO mode pitfalls
 ==================
 
-Sometime the developer may be confused by a datasheet talking about a pin
-being possible to set into "GPIO mode". It appears that what hardware
-engineers mean with "GPIO mode" is not necessarily the use case that is
-implied in the kernel interface <linux/gpio.h>: a pin that you grab from
-kernel code and then either listen for input or drive high/low to
+The GPIO portions of a pin and its relation to a certain pin controller
+logic can be constructed in several ways. Here are three examples:
+
+(A)
+
+                                         +- SPI
+     Physical pins --- GPIO --- pinctrl -+- I2C
+                                         +- mmc
+
+(B)
+                    +- GPIO
+     Physical pins -+           +- SPI
+                    +- pinctrl -+- I2C
+                                +- mmc
+
+(C)
+                                +- SPI
+     Physical pins --- pinctrl -+- I2C
+                                +- mmc
+                                +- GPIO
+
+In (A) the GPIO-like functionality of the pin is *always* available.
+For example it is possible to read the GPIO input register to "spy" on
+the SPI, I2C or MMC line while it is being used by the peripheral.
+In (B) the GPIO functionality is orthogonal to any device using the
+pin, and in (C) the GPIO case is the same as "some peripheral".
+
+For this reason the developer may be confused by a datasheet talking
+about a pin being possible to set into "GPIO mode". It appears that what
+hardware engineers mean with "GPIO mode" is not necessarily the use case
+that is implied in the kernel interface <linux/gpio.h>: a pin that you
+grab from kernel code and then either listen for input or drive high/low to
 assert/deassert some external line.
 
 Rather hardware engineers think that "GPIO mode" means that you can