[PATCH] pinctrl: elaborate a bit on arrangements in doc

[Linus Walleij]

From: Linus Walleij <linus.walleij at 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 at landley.net>
Cc: Christian Ruppert <christian.ruppert at abilis.com>
Signed-off-by: Linus Walleij <linus.walleij at linaro.org>
---
 Documentation/pinctrl.txt | 37 ++++++++++++++++++++++++++++++++-----
 1 file changed, 32 insertions(+), 5 deletions(-)

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
-- 
1.7.11.3