Patchwork [RESEND,4/5] Documentation: add the Marvell Berlin pinctrl documentation

login
register
mail settings
Submitter Antoine Ténart
Date April 10, 2014, 1:07 p.m.
Message ID <1397135274-10764-5-git-send-email-antoine.tenart@free-electrons.com>
Download mbox | patch
Permalink /patch/338243/
State New
Headers show

Comments

Antoine Ténart - April 10, 2014, 1:07 p.m.
Signed-off-by: Antoine Ténart <antoine.tenart@free-electrons.com>
---
 .../bindings/pinctrl/marvell,berlin-pinctrl.txt    | 43 ++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/pinctrl/marvell,berlin-pinctrl.txt
Jisheng Zhang - April 11, 2014, 6:33 a.m.
On Thu, 10 Apr 2014 06:07:53 -0700
Antoine Ténart <antoine.tenart@free-electrons.com> wrote:

> Signed-off-by: Antoine Ténart <antoine.tenart@free-electrons.com>
> ---
>  .../bindings/pinctrl/marvell,berlin-pinctrl.txt    | 43
> ++++++++++++++++++++++ 1 file changed, 43 insertions(+)
>  create mode 100644
> Documentation/devicetree/bindings/pinctrl/marvell,berlin-pinctrl.txt
> 
> diff --git
> a/Documentation/devicetree/bindings/pinctrl/marvell,berlin-pinctrl.txt
> b/Documentation/devicetree/bindings/pinctrl/marvell,berlin-pinctrl.txt new
> file mode 100644 index 000000000000..e21538a37734 --- /dev/null
> +++ b/Documentation/devicetree/bindings/pinctrl/marvell,berlin-pinctrl.txt
> @@ -0,0 +1,43 @@
> +* Pinctrl driver for the Marvell Berlin SoCs
> +
> +The pins controlled by the Marvell Berlin controller are organized in
> groups. +Configuration is done by group, so no actual pin information is
> needed. +
> +Required properties:
> +- compatible:	"marvell-berlin2cd-pinctrl",
> +		"marvell-berlin2-pinctrl",
> +		"marvell-berlin2q-pinctrl"
> +- reg: registers physical addresses and lengths of the pin controller.
> +- reg-names: name of the register regions.
> +
> +Please refer to pinctrl-bindings.txt in this directory for details of the
> +common pinctrl bindings used by client devices.
> +
> +A pinctrl should contains subnodes representing the pinctrl pin group
> +configurations, one per group. Each subnode has the group name and the
> muxing +function used.
> +
> +Required subnode-properties:
> +- berlin,group: a string describing the group's name.
> +- berlin,function: the function used to mux the group.

Would it be better to s/function/mode? Because in mrvl internal technology
discussion and docs, we usually say "set pinmux Gy as mode z".


Thanks,
Jisheng
Antoine Ténart - April 11, 2014, 8:12 a.m.
Hi Jisheng,

On Fri, Apr 11, 2014 at 02:33:18PM +0800, Jisheng Zhang wrote:
> On Thu, 10 Apr 2014 06:07:53 -0700
> Antoine Ténart <antoine.tenart@free-electrons.com> wrote:
> > +Required subnode-properties:
> > +- berlin,group: a string describing the group's name.
> > +- berlin,function: the function used to mux the group.
> 
> Would it be better to s/function/mode? Because in mrvl internal technology
> discussion and docs, we usually say "set pinmux Gy as mode z".

The pinctrl framework uses 'function', so I guess it's better not to introduce
an other keyword that may confuse people. But I agree this is not what's used in
the Marvell's docs. What do you think about we mention it in this documentation ?

Thanks for the feedback !

Antoine
Jisheng Zhang - April 11, 2014, 8:18 a.m.
Hi Antoine,

On Fri, 11 Apr 2014 01:12:59 -0700
Antoine Ténart <antoine.tenart@free-electrons.com> wrote:

> Hi Jisheng,
> 
> On Fri, Apr 11, 2014 at 02:33:18PM +0800, Jisheng Zhang wrote:
> > On Thu, 10 Apr 2014 06:07:53 -0700
> > Antoine Ténart <antoine.tenart@free-electrons.com> wrote:
> > > +Required subnode-properties:
> > > +- berlin,group: a string describing the group's name.
> > > +- berlin,function: the function used to mux the group.
> > 
> > Would it be better to s/function/mode? Because in mrvl internal technology
> > discussion and docs, we usually say "set pinmux Gy as mode z".
> 
> The pinctrl framework uses 'function', so I guess it's better not to
> introduce an other keyword that may confuse people. But I agree this is not
> what's used in the Marvell's docs. What do you think about we mention it in
> this documentation ?

That's a good idea.

Thanks,
Jisheng
Andrew Lunn - April 11, 2014, 8:22 a.m.
On Fri, Apr 11, 2014 at 10:12:59AM +0200, Antoine Ténart wrote:
> Hi Jisheng,
> 
> On Fri, Apr 11, 2014 at 02:33:18PM +0800, Jisheng Zhang wrote:
> > On Thu, 10 Apr 2014 06:07:53 -0700
> > Antoine Ténart <antoine.tenart@free-electrons.com> wrote:
> > > +Required subnode-properties:
> > > +- berlin,group: a string describing the group's name.
> > > +- berlin,function: the function used to mux the group.
> > 
> > Would it be better to s/function/mode? Because in mrvl internal technology
> > discussion and docs, we usually say "set pinmux Gy as mode z".
> 
> The pinctrl framework uses 'function', so I guess it's better not to introduce
> an other keyword that may confuse people.

Agreed. DT is a standard, Marvell datasheets are just datasheets.

> But I agree this is not what's used in the Marvell's docs. What do
> you think about we mention it in this documentation ?

Or ask for the datahsheet to be changed :-)

   Andrew
Sebastian Hesselbarth - April 11, 2014, 9:13 a.m.
On 04/10/2014 03:07 PM, Antoine Ténart wrote:

Missing commit message.

> Signed-off-by: Antoine Ténart <antoine.tenart@free-electrons.com>
> ---
>   .../bindings/pinctrl/marvell,berlin-pinctrl.txt    | 43 ++++++++++++++++++++++
>   1 file changed, 43 insertions(+)
>   create mode 100644 Documentation/devicetree/bindings/pinctrl/marvell,berlin-pinctrl.txt
>
> diff --git a/Documentation/devicetree/bindings/pinctrl/marvell,berlin-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/marvell,berlin-pinctrl.txt
> new file mode 100644
> index 000000000000..e21538a37734
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/pinctrl/marvell,berlin-pinctrl.txt
> @@ -0,0 +1,43 @@
> +* Pinctrl driver for the Marvell Berlin SoCs
> +
> +The pins controlled by the Marvell Berlin controller are organized in groups.
> +Configuration is done by group, so no actual pin information is needed.
> +
> +Required properties:
> +- compatible:	"marvell-berlin2cd-pinctrl",
> +		"marvell-berlin2-pinctrl",
> +		"marvell-berlin2q-pinctrl"

s/marvell-/marvell,/g

Also, you can add at least some prosa like
"compatible: should be one of"...

> +- reg: registers physical addresses and lengths of the pin controller.
> +- reg-names: name of the register regions.
> +
> +Please refer to pinctrl-bindings.txt in this directory for details of the
> +common pinctrl bindings used by client devices.
> +
> +A pinctrl should contains subnodes representing the pinctrl pin group

s/pinctrl/pin-controller/g
s/contains/contain

> +configurations, one per group. Each subnode has the group name and the muxing
> +function used.
> +
> +Required subnode-properties:
> +- berlin,group: a string describing the group's name.
> +- berlin,function: the function used to mux the group.
> +	0: function 0
> +	1: function 1
> +	...

s/berlin,/marvell,/

And I also prefer either DT binding includes for each function (even if
the proper name is not known).

> +
> +Example:
> +
> +pinctrl: pinctrl@0 {

I looked at ePAPR recommended node names yesterday. It uses
foo-controller for all listed examples. Also, with the idea
of splitting both pin-controllers into separate nodes the
above (with broken unit-address) will become:

soc_pinctrl: pin-controller@ea0000 {
	compatible = "marvell,berlin2q-soc-pinctrl";
	reg = <0xea0000 0x08>;
};

and

sm_pinctrl: pin-controller@fc0000 {
	compatible = "marvell,berlin2q-sysmgr-pinctrl";
	reg = <0xfc0000 0x44>;
};

Sebastian

> +	compatible = "marvell,berlin2q-pinctrl";
> +	reg = <0xea0000 0x08>, <0xfc0000 0x44>;
> +	reg-names = "global_base", "sm_base";
> +
> +	uart0_pmux: uart0-pmux {
> +		berlin,group = "GSM12";
> +		berlin,function = <0>;
> +	};
> +}
> +
> +&uart0 {
> +	pinctrl-0 = <&uart0_pmux>;
> +	pinctrl-names = "default";
> +};
>

Patch

diff --git a/Documentation/devicetree/bindings/pinctrl/marvell,berlin-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/marvell,berlin-pinctrl.txt
new file mode 100644
index 000000000000..e21538a37734
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/marvell,berlin-pinctrl.txt
@@ -0,0 +1,43 @@ 
+* Pinctrl driver for the Marvell Berlin SoCs
+
+The pins controlled by the Marvell Berlin controller are organized in groups.
+Configuration is done by group, so no actual pin information is needed.
+
+Required properties:
+- compatible:	"marvell-berlin2cd-pinctrl",
+		"marvell-berlin2-pinctrl",
+		"marvell-berlin2q-pinctrl"
+- reg: registers physical addresses and lengths of the pin controller.
+- reg-names: name of the register regions.
+
+Please refer to pinctrl-bindings.txt in this directory for details of the
+common pinctrl bindings used by client devices.
+
+A pinctrl should contains subnodes representing the pinctrl pin group
+configurations, one per group. Each subnode has the group name and the muxing
+function used.
+
+Required subnode-properties:
+- berlin,group: a string describing the group's name.
+- berlin,function: the function used to mux the group.
+	0: function 0
+	1: function 1
+	...
+
+Example:
+
+pinctrl: pinctrl@0 {
+	compatible = "marvell,berlin2q-pinctrl";
+	reg = <0xea0000 0x08>, <0xfc0000 0x44>;
+	reg-names = "global_base", "sm_base";
+
+	uart0_pmux: uart0-pmux {
+		berlin,group = "GSM12";
+		berlin,function = <0>;
+	};
+}
+
+&uart0 {
+	pinctrl-0 = <&uart0_pmux>;
+	pinctrl-names = "default";
+};