[PATCH 1/2] pinctrl: clean up pinconfig-generic documentation

From: Stephen Warren <redacted>

Reword the section of pinctrl-bindings.txt that describes generic
properties that pinctrl bindings may use. The aim is to make the text
clearer, and more explicitly call out the responsibility of individual
bindings that use the generic properties to define which of the
properties are used, and how.

Signed-off-by: Stephen Warren <redacted>
---
LinusW, Laxman, this is the binding doc cleanup I mentioned I was going
to send when reviewing Laxman's Palmas pinctrl driver.

 .../bindings/pinctrl/pinctrl-bindings.txt          | 25 +++++++++-------------
 1 file changed, 10 insertions(+), 15 deletions(-)

diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
index aeb3c99..31b0cb9 100644
--- a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
+++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt

@@ -127,20 +127,16 @@ whether there is any interaction between the child and intermediate parent
 nodes, is again defined entirely by the binding for the individual pin
 controller device.
 
-== Using generic pinconfig options ==
+== Generic pin configuration node content ==
 
-Generic pinconfig parameters can be used by defining a separate node containing
-the applicable parameters (and optional values), like:
+Many data items that are represented in a pin configuration node are common
+and generic. Pin control bindings should use the properties defined below
+where they are applicable; not all of these properties are relevant or useful
+for all hardware or binding structures. Each individual binding document
+should state which of these generic properties, if any, are used, and the
+structure of the DT nodes that contain these properties.
 
-pcfg_pull_up: pcfg_pull_up {
-	bias-pull-up;
-	drive-strength = <20>;
-};
-
-This node should then be referenced in the appropriate pinctrl node as a phandle
-and parsed in the driver using the pinconf_generic_parse_dt_config function.
-
-Supported configuration parameters are:
+Supported generic properties are:
 
 bias-disable		- disable any pin bias
 bias-high-impedance	- high impedance mode ("third-state", "floating")

@@ -160,7 +156,8 @@ low-power-disable	- disable low power mode
 output-low		- set the pin to output mode with low level
 output-high		- set the pin to output mode with high level
 
-Arguments for parameters:
+Some of the generic properties take arguments. For those that do, the
+arguments are described below.
 
 - bias-pull-up, -down and -pin-default take as optional argument on hardware
   supporting it the pull strength in Ohm. bias-disable will disable the pull.

@@ -170,7 +167,5 @@ Arguments for parameters:
 - input-debounce takes the debounce time in usec as argument
   or 0 to disable debouncing
 
-All parameters not listed here, do not take an argument.
-
 More in-depth documentation on these parameters can be found in
 <include/linux/pinctrl/pinconfig-generic.h>

-- 
1.8.1.5

From: Stephen Warren <redacted>

pinctrl bindings can benefit from generic property names that define
which pins a "pin configuration node" affects, and which mux function
to select onto those pins. Document new properties for this purpose so
that other bindings may refer to them.

Signed-off-by: Stephen Warren <redacted>
---
 Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
index 31b0cb9..237823a 100644
--- a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
+++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt

@@ -138,6 +138,9 @@ structure of the DT nodes that contain these properties.
 
 Supported generic properties are:
 
+pins			- the list of pins that properties in the node
+			  apply to
+function		- the mux function to select
 bias-disable		- disable any pin bias
 bias-high-impedance	- high impedance mode ("third-state", "floating")
 bias-bus-hold		- latch weakly

-- 
1.8.1.5

On Mon, Aug 05, 2013 at 10:56:00PM +0100, Stephen Warren wrote:

I assume the type of these properties must be described in the more
specific binding?

Mark.

 bias-disable		- disable any pin bias
 bias-high-impedance	- high impedance mode ("third-state", "floating")
 bias-bus-hold		- latch weakly
-- 
1.8.1.5

On 08/06/2013 02:41 AM, Mark Rutland wrote:

On Mon, Aug 05, 2013 at 10:56:00PM +0100, Stephen Warren wrote:

quoted

From: Stephen Warren <redacted>

pinctrl bindings can benefit from generic property names that define
which pins a "pin configuration node" affects, and which mux function
to select onto those pins. Document new properties for this purpose so
that other bindings may refer to them.

Signed-off-by: Stephen Warren <redacted>
---
 Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
index 31b0cb9..237823a 100644
--- a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
+++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt

@@ -138,6 +138,9 @@ structure of the DT nodes that contain these properties.
 
 Supported generic properties are:
 
+pins			- the list of pins that properties in the node
+			  apply to
+function		- the mux function to select

I assume the type of these properties must be described in the more
specific binding?

Yes, I think so. I guess I should also add entries into the section
right below this list which describes the values for each of the
properties that has values.

On Mon, Aug 5, 2013 at 11:55 PM, Stephen Warren [off-list ref] wrote:

From: Stephen Warren <redacted>

Reword the section of pinctrl-bindings.txt that describes generic
properties that pinctrl bindings may use. The aim is to make the text
clearer, and more explicitly call out the responsibility of individual
bindings that use the generic properties to define which of the
properties are used, and how.

Signed-off-by: Stephen Warren <redacted>
---
LinusW, Laxman, this is the binding doc cleanup I mentioned I was going
to send when reviewing Laxman's Palmas pinctrl driver.

Looks good to me.
Patch applied.

Yours,
Linus Walleij

On 08/07/2013 01:32 PM, Linus Walleij wrote:

On Mon, Aug 5, 2013 at 11:55 PM, Stephen Warren [off-list ref] wrote:

quoted

From: Stephen Warren <redacted>

Reword the section of pinctrl-bindings.txt that describes generic
properties that pinctrl bindings may use. The aim is to make the text
clearer, and more explicitly call out the responsibility of individual
bindings that use the generic properties to define which of the
properties are used, and how.

Signed-off-by: Stephen Warren <redacted>
---
LinusW, Laxman, this is the binding doc cleanup I mentioned I was going
to send when reviewing Laxman's Palmas pinctrl driver.

Looks good to me.
Patch applied.

I assume just patch 1? There was a v2 of patch 2.

On Wed, Aug 7, 2013 at 9:41 PM, Stephen Warren [off-list ref] wrote:

On 08/07/2013 01:32 PM, Linus Walleij wrote:

quoted

On Mon, Aug 5, 2013 at 11:55 PM, Stephen Warren [off-list ref] wrote:

quoted

From: Stephen Warren <redacted>

Reword the section of pinctrl-bindings.txt that describes generic
properties that pinctrl bindings may use. The aim is to make the text
clearer, and more explicitly call out the responsibility of individual
bindings that use the generic properties to define which of the
properties are used, and how.

Signed-off-by: Stephen Warren <redacted>
---
LinusW, Laxman, this is the binding doc cleanup I mentioned I was going
to send when reviewing Laxman's Palmas pinctrl driver.

Looks good to me.
Patch applied.

I assume just patch 1? There was a v2 of patch 2.

Yes ... I haven't found that v2 of patch 2 yet.

Yours,
Linus Walleij