[PATCH v2] pinctrl: document semantics vs GPIO

[PATCH v2] pinctrl: document semantics vs GPIO

[Linus Walleij]

From: Linus Walleij <linus.walleij@linaro.org>

The semantics of the interactions between GPIO and pinctrl may be
unclear, e.g. which one do you request first? This amends the
documentation to make this clear.

Reported-by: Domenico Andreoli <cavokz@gmail.com>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
---
ChangeLog v1->v2:
- Reworded a bit in accordance with Stephens feedback.
---
 Documentation/pinctrl.txt | 57 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 55 insertions(+), 2 deletions(-)

diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt
index 1479aca..e2dfc85 100644
--- a/Documentation/pinctrl.txt
+++ b/Documentation/pinctrl.txt
@@ -289,6 +289,11 @@ Interaction with the GPIO subsystem
 The GPIO drivers may want to perform operations of various types on the same
 physical pins that are also registered as pin controller pins.
 
+First and foremost, the two subsystems can be used as completely orthogonal,
+see the section named "pin control requests from drivers" and
+"drivers needing both pin control and GPIOs" below for details. But in some
+situations a cross-subsystem mapping between pins and GPIOs is needed.
+
 Since the pin controller subsystem have its pinspace local to the pin
 controller we need a mapping so that the pin control subsystem can figure out
 which pin controller handles control of a certain GPIO pin. Since a single
@@ -359,6 +364,7 @@ will get an pin number into its handled number range. Further it is also passed
 the range ID value, so that the pin controller knows which range it should
 deal with.
 
+
 PINMUX interfaces
 =================
 
@@ -960,8 +966,8 @@ all get selected, and they all get enabled and disable simultaneously by the
 pinmux core.
 
 
-Pinmux requests from drivers
-============================
+Pin control requests from drivers
+=================================
 
 Generally it is discouraged to let individual drivers get and enable pin
 control. So if possible, handle the pin control in platform code or some other
@@ -969,6 +975,11 @@ place where you have access to all the affected struct device * pointers. In
 some cases where a driver needs to e.g. switch between different mux mappings
 at runtime this is not possible.
 
+A typical case is if a driver needs to switch bias of pins from normal
+operation and going to sleep, moving from the PINCTRL_STATE_DEFAULT to
+PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save
+current in sleep mode.
+
 A driver may request a certain control state to be activated, usually just the
 default state like this:
 
@@ -1058,6 +1069,48 @@ registered. Thus make sure that the error path in your driver gracefully
 cleans up and is ready to retry the probing later in the startup process.
 
 
+Drivers needing both pin control and GPIOs
+==========================================
+
+Again, it is discouraged to let drivers lookup and select pin control states
+themselves, but again sometimes this is unavoidable.
+
+So say that your driver is fetching its resources like this:
+
+#include <linux/pinctrl/consumer.h>
+#include <linux/gpio.h>
+
+struct pinctrl *pinctrl;
+int gpio;
+
+pinctrl = devm_pinctrl_get_select_default(&dev);
+gpio = devm_gpio_request(&dev, 14, "foo");
+
+Here we first request a certain pin state and then request GPIO 14 to be
+used. If you're using the subsystems orthogonally like this, you should
+nominally always get your pinctrl handle and select the desired pinctrl
+state BEFORE requesting the GPIO. This is a semantic convention to avoid
+situations that can be electrically unpleasant, you will certainly want to
+mux in and bias pins in a certain way before the GPIO subsystems starts to
+deal with them.
+
+The above can be hidden: using pinctrl hogs, the pin control driver may be
+setting up the config and muxing for the pins when it is probing,
+nevertheless orthogonal to the GPIO subsystem.
+
+But there are also situations where it makes sense for the GPIO subsystem
+to communicate directly with with the pinctrl subsystem, using the latter
+as a back-end. This is when the GPIO driver may call out to the functions
+described in the section "Pin control interaction with the GPIO subsystem"
+above. This only involves per-pin multiplexing, and will be completely
+hidden behind the gpio_*() function namespace. In this case, the driver
+need not interact with the pin control subsystem at all.
+
+If a pin control driver and a GPIO driver is dealing with the same pins
+and the use cases involve multiplexing, you MUST implement the pin controller
+as a back-end for the GPIO driver like this.
+
+
 System pin control hogging
 ==========================
 
-- 
1.7.11.3

Re: [PATCH v2] pinctrl: document semantics vs GPIO

[Domenico Andreoli]

On Fri, Sep 14, 2012 at 03:49:47PM +0200, Linus Walleij wrote:
> From: Linus Walleij <linus.walleij@linaro.org>
> 
> The semantics of the interactions between GPIO and pinctrl may be
> unclear, e.g. which one do you request first? This amends the
> documentation to make this clear.
> 
> Reported-by: Domenico Andreoli <cavokz@gmail.com>
> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> ---
> ChangeLog v1->v2:
> - Reworded a bit in accordance with Stephens feedback.
> ---
>  Documentation/pinctrl.txt | 57 +++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 55 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt
> index 1479aca..e2dfc85 100644
> --- a/Documentation/pinctrl.txt
> +++ b/Documentation/pinctrl.txt
> @@ -289,6 +289,11 @@ Interaction with the GPIO subsystem
>  The GPIO drivers may want to perform operations of various types on the same
>  physical pins that are also registered as pin controller pins.
>  
> +First and foremost, the two subsystems can be used as completely orthogonal,
> +see the section named "pin control requests from drivers" and
> +"drivers needing both pin control and GPIOs" below for details. But in some
> +situations a cross-subsystem mapping between pins and GPIOs is needed.
> +
>  Since the pin controller subsystem have its pinspace local to the pin
>  controller we need a mapping so that the pin control subsystem can figure out
>  which pin controller handles control of a certain GPIO pin. Since a single
> @@ -359,6 +364,7 @@ will get an pin number into its handled number range. Further it is also passed
>  the range ID value, so that the pin controller knows which range it should
>  deal with.
>  
> +
>  PINMUX interfaces
>  =================
>  
> @@ -960,8 +966,8 @@ all get selected, and they all get enabled and disable simultaneously by the
>  pinmux core.
>  
>  
> -Pinmux requests from drivers
> -============================
> +Pin control requests from drivers
> +=================================
>  
>  Generally it is discouraged to let individual drivers get and enable pin
>  control. So if possible, handle the pin control in platform code or some other
> @@ -969,6 +975,11 @@ place where you have access to all the affected struct device * pointers. In
>  some cases where a driver needs to e.g. switch between different mux mappings
>  at runtime this is not possible.
>  
> +A typical case is if a driver needs to switch bias of pins from normal
> +operation and going to sleep, moving from the PINCTRL_STATE_DEFAULT to
> +PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save
> +current in sleep mode.
> +
>  A driver may request a certain control state to be activated, usually just the
>  default state like this:
>  
> @@ -1058,6 +1069,48 @@ registered. Thus make sure that the error path in your driver gracefully
>  cleans up and is ready to retry the probing later in the startup process.
>  
>  
> +Drivers needing both pin control and GPIOs
> +==========================================
> +
> +Again, it is discouraged to let drivers lookup and select pin control states
> +themselves, but again sometimes this is unavoidable.
> +
> +So say that your driver is fetching its resources like this:
> +
> +#include <linux/pinctrl/consumer.h>
> +#include <linux/gpio.h>
> +
> +struct pinctrl *pinctrl;
> +int gpio;
> +
> +pinctrl = devm_pinctrl_get_select_default(&dev);
> +gpio = devm_gpio_request(&dev, 14, "foo");
> +
> +Here we first request a certain pin state and then request GPIO 14 to be
> +used. If you're using the subsystems orthogonally like this, you should
> +nominally always get your pinctrl handle and select the desired pinctrl
> +state BEFORE requesting the GPIO. This is a semantic convention to avoid
> +situations that can be electrically unpleasant, you will certainly want to
> +mux in and bias pins in a certain way before the GPIO subsystems starts to
> +deal with them.
> +
> +The above can be hidden: using pinctrl hogs, the pin control driver may be
> +setting up the config and muxing for the pins when it is probing,
> +nevertheless orthogonal to the GPIO subsystem.
> +
> +But there are also situations where it makes sense for the GPIO subsystem
> +to communicate directly with with the pinctrl subsystem, using the latter
> +as a back-end. This is when the GPIO driver may call out to the functions
> +described in the section "Pin control interaction with the GPIO subsystem"
> +above. This only involves per-pin multiplexing, and will be completely
> +hidden behind the gpio_*() function namespace. In this case, the driver
> +need not interact with the pin control subsystem at all.
> +
> +If a pin control driver and a GPIO driver is dealing with the same pins
> +and the use cases involve multiplexing, you MUST implement the pin controller
> +as a back-end for the GPIO driver like this.
> +
> +
>  System pin control hogging
>  ==========================

Yes, this definitively clarifies the doubts I had on the pinctrl/GPIO
subsystem interaction. Thank you.

Acked-By: Domenico Andreoli <domenico.andreoli@linux.com>

Re: [PATCH v2] pinctrl: document semantics vs GPIO

[Stephen Warren]

On 09/14/2012 07:49 AM, Linus Walleij wrote:
> From: Linus Walleij <linus.walleij@linaro.org>
> 
> The semantics of the interactions between GPIO and pinctrl may be
> unclear, e.g. which one do you request first? This amends the
> documentation to make this clear.

> +If a pin control driver and a GPIO driver is dealing with the same pins
> +and the use cases involve multiplexing, you MUST implement the pin controller
> +as a back-end for the GPIO driver like this.

I might add one caveat to that:

==========
, unless your HW design is such that the GPIO controller can override
the pin controller's mux state, without the need for any such interaction.
==========

... as on Tegra for example, the GPIO controller contains a bit per GPIO
pin which forces the GPIO controller to control the pin, irrespective of
any mux setting in the pinmux controller (although the pin controller's
tri-state config overrides the GPIO controller's output-enable
config!!!). Hence, the exact same semantics can be achieved, without the
GPIO driver actually having to call into the pinctrl subsystem. That
said, Tegra's GPIO driver still does end up calling into
pinctrl_request_gpio()/pinctrl_free_gpio() so that pinctrl debugfs works
for example, just not the pinctrl_gpio_direction_*(), so I guess it's
partially following the MUST above, so perhaps there's no need for the
caveat?

Either way,
Acked-by: Stephen Warren <swarren@wwwdotorg.org>

In the future, I wonder if someone might want the following caveat,

==========
, unless you require that all boards (or device trees) define a system
hog pinmux configuration that muxes all required GPIO signals as desired.
==========

... which might be appropriate for HW where GPIO-vs-special-function
selection is performed in the pinmux controller itself, per-pin. Perhaps
this is the OMAP special case you mentioned before?

Re: [PATCH v2] pinctrl: document semantics vs GPIO

[Linus Walleij]

On Fri, Sep 14, 2012 at 7:16 PM, Stephen Warren <swarren@wwwdotorg.org> wrote:
> On 09/14/2012 07:49 AM, Linus Walleij wrote:

>> +If a pin control driver and a GPIO driver is dealing with the same pins
>> +and the use cases involve multiplexing, you MUST implement the pin controller
>> +as a back-end for the GPIO driver like this.
>
> I might add one caveat to that:
>
> ==========
> , unless your HW design is such that the GPIO controller can override
> the pin controller's mux state, without the need for any such interaction.
> ==========

OK I buy that, so added this paragraph (slightly rephrased) and pused
for next.

> In the future, I wonder if someone might want the following caveat,
>
> ==========
> , unless you require that all boards (or device trees) define a system
> hog pinmux configuration that muxes all required GPIO signals as desired.
> ==========
>
> ... which might be appropriate for HW where GPIO-vs-special-function
> selection is performed in the pinmux controller itself, per-pin. Perhaps
> this is the OMAP special case you mentioned before?

Yeah :-/

I worry about exploding complexity here, so we need to think
about this a bit more...

Linus