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

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

[Linus Walleij]

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

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

[Stephen Warren]

On 06/25/2013 08:19 AM, Linus Walleij wrote:
> 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.

> diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt

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

I'm not really sure quite what these diagrams are attempting to convey
within the context of this document.

> +In (A) the GPIO-like functionality of the pin is *always* available.

Well, that can't really be true.

It may be possible that you can always read the physical pin's value via
a GPIO input register.

However, you obviously can't always write to a GPIO output register to
set the pin's value. If you could, the pin would simply be a GPIO, and
never serve any other function.

If you're saying that it's always possible to put the pin into a mode
where you can use the GPIO output register to driver the pin value, well
then that's just regular pin-muxing, so I'm not sure why it's worth
mentioning.

In (a) there are really two levels of pinmux configuration, one in the
GPIO HW block (GPIO-vs-whatever-pinctrl-selects).

In (b) there is another level of pinmux configuration; some block has to
exist between the physical pins and both GPIO/pinctrl HW modules; it
simply isn't drawn in the diagram

Diagram (c) appears complete.

In all cases though, this is just attempting to enumerate different HW
designs for pin-muxing I think. Isn't it better to just let each SoC's
datasheet specify exactly how things are hooked up?

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

[Linus Walleij]

On Tue, Jun 25, 2013 at 11:16 PM, Stephen Warren <swarren@wwwdotorg.org> wrote:
> On 06/25/2013 08:19 AM, Linus Walleij wrote:
>> 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.
(...)
> I'm not really sure quite what these diagrams are attempting to convey
> within the context of this document.

I am trying to help pinctrl kernel developers understand hardware
terminology.

>> +In (A) the GPIO-like functionality of the pin is *always* available.
>
> Well, that can't really be true.
>
> It may be possible that you can always read the physical pin's value via
> a GPIO input register.
>
> However, you obviously can't always write to a GPIO output register to
> set the pin's value. If you could, the pin would simply be a GPIO, and
> never serve any other function.

This is possible on the U300. What happens in practice is
that what you send out on the output from e.g. the I2C block is
OR:ed with the GPIO output, so if that is not zero, you jam it to 1.

> If you're saying that it's always possible to put the pin into a mode
> where you can use the GPIO output register to driver the pin value, well
> then that's just regular pin-muxing, so I'm not sure why it's worth
> mentioning.

That's not really the case. It can drive the pin at the same time.

> In (a) there are really two levels of pinmux configuration, one in the
> GPIO HW block (GPIO-vs-whatever-pinctrl-selects).
>
> In (b) there is another level of pinmux configuration; some block has to
> exist between the physical pins and both GPIO/pinctrl HW modules; it
> simply isn't drawn in the diagram

I've redrawn these a bit to reflect the cases I know exist.
Check the v2 patch.

> In all cases though, this is just attempting to enumerate different HW
> designs for pin-muxing I think. Isn't it better to just let each SoC's
> datasheet specify exactly how things are hooked up?

The intention of this is to understand the datasheet from a kernel
point of view.

Yours,
Linus Walleij

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

[Christian Ruppert]

On Tue, Jun 25, 2013 at 04:19:12PM +0200, Linus Walleij wrote:
> 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 --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

In my experience, in hardware engineering terminology, GPIO/General
Purpose I/O just means a physical pad macro cell which can be
dynamically configured in different modes, e.g. as an input or as an
output, as an open drain driver etc. This configuration is done through
hardware signals and controlled by digital logic. This logic might
either be a GPIO controller or some other hardware block, e.g. an I2C
controller block.

Hardware GPIOs have nothing to do with the concept of GPIOs from the
Linux kernel point of view where a GPIO is a swoftware controllable pin
with a similar configuration space as "hardware GPIOs". To put it
simple, a software GPIO is a hardware GPIO plus some digital logic which
implements a register interface to drive all the hardware GPIO's control
lines from software.

In some cases, both modes are combined, e.g. one can imagine an SPI
interface where the output levels are driven from an SPI controller
hardware block and other parameters such as the drive strength or
integrated pull-up/pull-down resistors are controlled through some
independent mechanism. The parameters controlled through that
independent mechanism are sometimes referred to as the GPIO mode of the
pin.

-- 
  Christian Ruppert              ,          <christian.ruppert@abilis.com>
                                /|
  Tel: +41/(0)22 816 19-42     //|                 3, Chemin du Pr?-Fleuri
                             _// | bilis Systems   CH-1228 Plan-les-Ouates

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

[Linus Walleij]

On Wed, Jun 26, 2013 at 3:15 PM, Christian Ruppert
<christian.ruppert@abilis.com> wrote:

> In my experience, in hardware engineering terminology, GPIO/General
> Purpose I/O just means a physical pad macro cell which can be
> dynamically configured in different modes, e.g. as an input or as an
> output, as an open drain driver etc. This configuration is done through
> hardware signals and controlled by digital logic. This logic might
> either be a GPIO controller or some other hardware block, e.g. an I2C
> controller block.

This is what this patch is trying to hash out. Have you seen this
presentation I did a while back?
http://www.df.lth.se/~triad/papers/pincontrol.pdf

> Hardware GPIOs have nothing to do with the concept of GPIOs from the
> Linux kernel point of view

That is unfortunately a bit of HW engineering terminology problem.
It took some months before we came up with the three non-overlapping
(well) sets of "GPIO", "pin configuration" and "pin multiplexing" to sort
these things into three different buckets.

And this entire section in Documentation/pinctrl.txt is trying to explain
this to the kernel developer.

> In some cases, both modes are combined, e.g. one can imagine an SPI
> interface where the output levels are driven from an SPI controller
> hardware block and other parameters such as the drive strength or
> integrated pull-up/pull-down resistors are controlled through some
> independent mechanism.

This is the case on the Nomadik and I think many other pin controllers.

But on the U300, the output line is controlled by two things at the
time!

> The parameters controlled through that
> independent mechanism are sometimes referred to as the GPIO mode of the
> pin.

Yes...

Yours,
Linus Walleij