[RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[Sascha Hauer]

Most iomux controllers allow a configuration per pin. These currently
have no common device tree binding. There are many different SoC
specific bindings for this class of iomux controllers. Some controllers
artificially group pins together where in hardware no groups exist (for
example lantiq). Other controllers just put each pin into a separate
group which explodes to many many strings to parse (Tegra30).


A pin controller has n pins, each muxable to m different positions.
There exists a logical numbering for all pins, for most SoCs this will
be defined by the register ordering so that the pin number can directly
be translated to a register offset without the need of tables in the
driver. The register usually takes m different numbers to specify the
function the pin should have. Both the pin and its function can be
described as a single 32bit number:

#define PINMUX_PIN(no, fn) (((no) & 0xffffff) << 8) | (fn) & 0xff)

This allows to put multiple pins into a single device tree property
which is very efficiently parsable by the driver (or the pinmux core).
We suggest to name this property 'pins' and to put it next to the
generic pinconf binding.  This allows to describe multiple pins with the
same pinconf settings in a single device tree node. Multiple of these
nodes can be grouped under a pinctrl state node. This allows to put pins
with different pinconf settings to a single state.

Example:

	uart2 {
		uart2_default_mode: uart2_default {
			pins1 {
				pins = <PINMUX_PIN(127, 3), PINMUX_PIN(128, 3)>;
				drive-push-pull;
			};
			pins2 {
				pins = <PINMUX_PIN(129, 2), PINMUX_PIN(130, 2)>;
				drive-strength = <20>;
			};
		};
	};

This binding is efficient to write and to parse and covers all (per-)pin
controllers we are aware of. Further convenience can be added using
defines which specify the pin and function names. A SoC might want to
use defines for pin numbers, or even for a combination of pin number and
function:

#define PIN_W23				127
#define PIN_W23__UART2_RXD		PINMUX_PIN(PIN_W23, 3)

Defines like this make it a straight forward task to write down all
possible combinations of pins and functions, thus creating a full
documentation without writing documentation. Looking at current binding
documentation this is indeed a problem since often the different mux
groups and the different function names are described, but not which
combinations are valid in hardware. Sometimes the documentation does not
even describe which pins and functions exist (Allwinner, Renesas), so
strings like "mmc0_data8_0" have to be made up from the driver source.

So from our view we see the following advantages of such a binding:

- Easy to transfer schematics or the output of a vendor iomux tool or
  excel sheet to a valid device tree. These are often the base for porting
  to a new board.
- The simple case when all pins of a state have the same pinconf setting
  requires only a single device tree node.
- No string matching required. String matching is expensive in terms of
  CPU cycles, device tree binary size and kernel binary size.
- Less creativity needed for writing drivers. Many drivers and bindings
  look very different, although all implement the same muxing pattern.
- makes a common device tree parser possible.
- No artificial limitations in the binding, do not force groups when there
  are none in hardware. Grouping pins in the driver means that the original
  author must get it right, splitting up groups later and using pins
  individually is difficult.


Sascha Hauer, Lucas Stach

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

[RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[Sascha Hauer]

Most iomux controllers allow a configuration per pin. These currently
have no common device tree binding. There are many different SoC
specific bindings for this class of iomux controllers. Some controllers
artificially group pins together where in hardware no groups exist (for
example lantiq). Other controllers just put each pin into a separate
group which explodes to many many strings to parse (Tegra30).


A pin controller has n pins, each muxable to m different positions.
There exists a logical numbering for all pins, for most SoCs this will
be defined by the register ordering so that the pin number can directly
be translated to a register offset without the need of tables in the
driver. The register usually takes m different numbers to specify the
function the pin should have. Both the pin and its function can be
described as a single 32bit number:

#define PINMUX_PIN(no, fn) (((no) & 0xffffff) << 8) | (fn) & 0xff)

This allows to put multiple pins into a single device tree property
which is very efficiently parsable by the driver (or the pinmux core).
We suggest to name this property 'pins' and to put it next to the
generic pinconf binding.  This allows to describe multiple pins with the
same pinconf settings in a single device tree node. Multiple of these
nodes can be grouped under a pinctrl state node. This allows to put pins
with different pinconf settings to a single state.

Example:

	uart2 {
		uart2_default_mode: uart2_default {
			pins1 {
				pins = <PINMUX_PIN(127, 3), PINMUX_PIN(128, 3)>;
				drive-push-pull;
			};
			pins2 {
				pins = <PINMUX_PIN(129, 2), PINMUX_PIN(130, 2)>;
				drive-strength = <20>;
			};
		};
	};

This binding is efficient to write and to parse and covers all (per-)pin
controllers we are aware of. Further convenience can be added using
defines which specify the pin and function names. A SoC might want to
use defines for pin numbers, or even for a combination of pin number and
function:

#define PIN_W23				127
#define PIN_W23__UART2_RXD		PINMUX_PIN(PIN_W23, 3)

Defines like this make it a straight forward task to write down all
possible combinations of pins and functions, thus creating a full
documentation without writing documentation. Looking at current binding
documentation this is indeed a problem since often the different mux
groups and the different function names are described, but not which
combinations are valid in hardware. Sometimes the documentation does not
even describe which pins and functions exist (Allwinner, Renesas), so
strings like "mmc0_data8_0" have to be made up from the driver source.

So from our view we see the following advantages of such a binding:

- Easy to transfer schematics or the output of a vendor iomux tool or
  excel sheet to a valid device tree. These are often the base for porting
  to a new board.
- The simple case when all pins of a state have the same pinconf setting
  requires only a single device tree node.
- No string matching required. String matching is expensive in terms of
  CPU cycles, device tree binary size and kernel binary size.
- Less creativity needed for writing drivers. Many drivers and bindings
  look very different, although all implement the same muxing pattern.
- makes a common device tree parser possible.
- No artificial limitations in the binding, do not force groups when there
  are none in hardware. Grouping pins in the driver means that the original
  author must get it right, splitting up groups later and using pins
  individually is difficult.


Sascha Hauer, Lucas Stach

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[Sascha Hauer]

Most iomux controllers allow a configuration per pin. These currently
have no common device tree binding. There are many different SoC
specific bindings for this class of iomux controllers. Some controllers
artificially group pins together where in hardware no groups exist (for
example lantiq). Other controllers just put each pin into a separate
group which explodes to many many strings to parse (Tegra30).


A pin controller has n pins, each muxable to m different positions.
There exists a logical numbering for all pins, for most SoCs this will
be defined by the register ordering so that the pin number can directly
be translated to a register offset without the need of tables in the
driver. The register usually takes m different numbers to specify the
function the pin should have. Both the pin and its function can be
described as a single 32bit number:

#define PINMUX_PIN(no, fn) (((no) & 0xffffff) << 8) | (fn) & 0xff)

This allows to put multiple pins into a single device tree property
which is very efficiently parsable by the driver (or the pinmux core).
We suggest to name this property 'pins' and to put it next to the
generic pinconf binding.  This allows to describe multiple pins with the
same pinconf settings in a single device tree node. Multiple of these
nodes can be grouped under a pinctrl state node. This allows to put pins
with different pinconf settings to a single state.

Example:

	uart2 {
		uart2_default_mode: uart2_default {
			pins1 {
				pins = <PINMUX_PIN(127, 3), PINMUX_PIN(128, 3)>;
				drive-push-pull;
			};
			pins2 {
				pins = <PINMUX_PIN(129, 2), PINMUX_PIN(130, 2)>;
				drive-strength = <20>;
			};
		};
	};

This binding is efficient to write and to parse and covers all (per-)pin
controllers we are aware of. Further convenience can be added using
defines which specify the pin and function names. A SoC might want to
use defines for pin numbers, or even for a combination of pin number and
function:

#define PIN_W23				127
#define PIN_W23__UART2_RXD		PINMUX_PIN(PIN_W23, 3)

Defines like this make it a straight forward task to write down all
possible combinations of pins and functions, thus creating a full
documentation without writing documentation. Looking at current binding
documentation this is indeed a problem since often the different mux
groups and the different function names are described, but not which
combinations are valid in hardware. Sometimes the documentation does not
even describe which pins and functions exist (Allwinner, Renesas), so
strings like "mmc0_data8_0" have to be made up from the driver source.

So from our view we see the following advantages of such a binding:

- Easy to transfer schematics or the output of a vendor iomux tool or
  excel sheet to a valid device tree. These are often the base for porting
  to a new board.
- The simple case when all pins of a state have the same pinconf setting
  requires only a single device tree node.
- No string matching required. String matching is expensive in terms of
  CPU cycles, device tree binary size and kernel binary size.
- Less creativity needed for writing drivers. Many drivers and bindings
  look very different, although all implement the same muxing pattern.
- makes a common device tree parser possible.
- No artificial limitations in the binding, do not force groups when there
  are none in hardware. Grouping pins in the driver means that the original
  author must get it right, splitting up groups later and using pins
  individually is difficult.


Sascha Hauer, Lucas Stach

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

Re: [RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[Linus Walleij]

On Thu, Oct 23, 2014 at 3:23 PM, Sascha Hauer <s.hauer@pengutronix.de> wrote:

> Most iomux controllers allow a configuration per pin. These currently
> have no common device tree binding. There are many different SoC
> specific bindings for this class of iomux controllers. Some controllers
> artificially group pins together where in hardware no groups exist (for
> example lantiq). Other controllers just put each pin into a separate
> group which explodes to many many strings to parse (Tegra30).

So I'd specifically like Stephen Warrens comments on this proposal,
as well as from everyone else doing per-pin device tree configs.

Yours,
Linus Walleij

Re: [RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[Linus Walleij]

On Thu, Oct 23, 2014 at 3:23 PM, Sascha Hauer <s.hauer@pengutronix.de> wrote:

> Most iomux controllers allow a configuration per pin. These currently
> have no common device tree binding. There are many different SoC
> specific bindings for this class of iomux controllers. Some controllers
> artificially group pins together where in hardware no groups exist (for
> example lantiq). Other controllers just put each pin into a separate
> group which explodes to many many strings to parse (Tegra30).

So I'd specifically like Stephen Warrens comments on this proposal,
as well as from everyone else doing per-pin device tree configs.

Yours,
Linus Walleij

[RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[Linus Walleij]

On Thu, Oct 23, 2014 at 3:23 PM, Sascha Hauer <s.hauer@pengutronix.de> wrote:

> Most iomux controllers allow a configuration per pin. These currently
> have no common device tree binding. There are many different SoC
> specific bindings for this class of iomux controllers. Some controllers
> artificially group pins together where in hardware no groups exist (for
> example lantiq). Other controllers just put each pin into a separate
> group which explodes to many many strings to parse (Tegra30).

So I'd specifically like Stephen Warrens comments on this proposal,
as well as from everyone else doing per-pin device tree configs.

Yours,
Linus Walleij

Re: [RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[Stephen Warren]

On 10/23/2014 07:23 AM, Sascha Hauer wrote:
> Most iomux controllers allow a configuration per pin. These currently
> have no common device tree binding. There are many different SoC
> specific bindings for this class of iomux controllers. Some controllers
> artificially group pins together where in hardware no groups exist (for
> example lantiq). Other controllers just put each pin into a separate
> group which explodes to many many strings to parse (Tegra30).
> 
> 
> A pin controller has n pins, each muxable to m different positions.

I assume that sentence is meant to say something more specific:

This binding is intended to apply to pin controllers where each pin has
an independently selectable mux function.

"A pin controller ..." sounds like a general statement that is intended
to apply to any pin controller. If that were intended, the statement you
made certainly wouldn't be true.

> There exists a logical numbering for all pins, for most SoCs this will
> be defined by the register ordering so that the pin number can directly
> be translated to a register offset without the need of tables in the
> driver. The register usually takes m different numbers to specify the
> function the pin should have. Both the pin and its function can be
> described as a single 32bit number:
> 
> #define PINMUX_PIN(no, fn) (((no) & 0xffffff) << 8) | (fn) & 0xff)
> 
> This allows to put multiple pins into a single device tree property
> which is very efficiently parsable by the driver (or the pinmux core).
> We suggest to name this property 'pins' and to put it next to the
> generic pinconf binding.  This allows to describe multiple pins with the
> same pinconf settings in a single device tree node. Multiple of these
> nodes can be grouped under a pinctrl state node. This allows to put pins
> with different pinconf settings to a single state.
> 
> Example:
> 
> 	uart2 {
> 		uart2_default_mode: uart2_default {
> 			pins1 {
> 				pins = <PINMUX_PIN(127, 3), PINMUX_PIN(128, 3)>;

Within each of the nodes, the binding for pinmux is defined
independently by each pin controller. I don't have any /strong/
objection to any particular pin controller using this binding, or even
it being re-used across many similar pin controllers, or even being
the/a default binding style for new pin controllers.

I'm not totally sure whether blending the pin ID and mux function ID
into the same value is a good idea. That said, it does have advantages
as you state, and shouldn't cause any significant issues. In any case
where it would be a bad idea, the binding for the pin controller in
question can still choose to use some more appropriate binding, so
allowing this binding for some controllers won't force issues onto other
controllers. So, it seems fine.

Note however that we can't change existing bindings. Well, I suppose
certain bindings could be enhanced to support either a string-based or
an integer-base binding, but I don't think that'd be a good idea.

Re: [RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[Stephen Warren]

On 10/23/2014 07:23 AM, Sascha Hauer wrote:
> Most iomux controllers allow a configuration per pin. These currently
> have no common device tree binding. There are many different SoC
> specific bindings for this class of iomux controllers. Some controllers
> artificially group pins together where in hardware no groups exist (for
> example lantiq). Other controllers just put each pin into a separate
> group which explodes to many many strings to parse (Tegra30).
> 
> 
> A pin controller has n pins, each muxable to m different positions.

I assume that sentence is meant to say something more specific:

This binding is intended to apply to pin controllers where each pin has
an independently selectable mux function.

"A pin controller ..." sounds like a general statement that is intended
to apply to any pin controller. If that were intended, the statement you
made certainly wouldn't be true.

> There exists a logical numbering for all pins, for most SoCs this will
> be defined by the register ordering so that the pin number can directly
> be translated to a register offset without the need of tables in the
> driver. The register usually takes m different numbers to specify the
> function the pin should have. Both the pin and its function can be
> described as a single 32bit number:
> 
> #define PINMUX_PIN(no, fn) (((no) & 0xffffff) << 8) | (fn) & 0xff)
> 
> This allows to put multiple pins into a single device tree property
> which is very efficiently parsable by the driver (or the pinmux core).
> We suggest to name this property 'pins' and to put it next to the
> generic pinconf binding.  This allows to describe multiple pins with the
> same pinconf settings in a single device tree node. Multiple of these
> nodes can be grouped under a pinctrl state node. This allows to put pins
> with different pinconf settings to a single state.
> 
> Example:
> 
> 	uart2 {
> 		uart2_default_mode: uart2_default {
> 			pins1 {
> 				pins = <PINMUX_PIN(127, 3), PINMUX_PIN(128, 3)>;

Within each of the nodes, the binding for pinmux is defined
independently by each pin controller. I don't have any /strong/
objection to any particular pin controller using this binding, or even
it being re-used across many similar pin controllers, or even being
the/a default binding style for new pin controllers.

I'm not totally sure whether blending the pin ID and mux function ID
into the same value is a good idea. That said, it does have advantages
as you state, and shouldn't cause any significant issues. In any case
where it would be a bad idea, the binding for the pin controller in
question can still choose to use some more appropriate binding, so
allowing this binding for some controllers won't force issues onto other
controllers. So, it seems fine.

Note however that we can't change existing bindings. Well, I suppose
certain bindings could be enhanced to support either a string-based or
an integer-base binding, but I don't think that'd be a good idea.
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[Stephen Warren]

On 10/23/2014 07:23 AM, Sascha Hauer wrote:
> Most iomux controllers allow a configuration per pin. These currently
> have no common device tree binding. There are many different SoC
> specific bindings for this class of iomux controllers. Some controllers
> artificially group pins together where in hardware no groups exist (for
> example lantiq). Other controllers just put each pin into a separate
> group which explodes to many many strings to parse (Tegra30).
> 
> 
> A pin controller has n pins, each muxable to m different positions.

I assume that sentence is meant to say something more specific:

This binding is intended to apply to pin controllers where each pin has
an independently selectable mux function.

"A pin controller ..." sounds like a general statement that is intended
to apply to any pin controller. If that were intended, the statement you
made certainly wouldn't be true.

> There exists a logical numbering for all pins, for most SoCs this will
> be defined by the register ordering so that the pin number can directly
> be translated to a register offset without the need of tables in the
> driver. The register usually takes m different numbers to specify the
> function the pin should have. Both the pin and its function can be
> described as a single 32bit number:
> 
> #define PINMUX_PIN(no, fn) (((no) & 0xffffff) << 8) | (fn) & 0xff)
> 
> This allows to put multiple pins into a single device tree property
> which is very efficiently parsable by the driver (or the pinmux core).
> We suggest to name this property 'pins' and to put it next to the
> generic pinconf binding.  This allows to describe multiple pins with the
> same pinconf settings in a single device tree node. Multiple of these
> nodes can be grouped under a pinctrl state node. This allows to put pins
> with different pinconf settings to a single state.
> 
> Example:
> 
> 	uart2 {
> 		uart2_default_mode: uart2_default {
> 			pins1 {
> 				pins = <PINMUX_PIN(127, 3), PINMUX_PIN(128, 3)>;

Within each of the nodes, the binding for pinmux is defined
independently by each pin controller. I don't have any /strong/
objection to any particular pin controller using this binding, or even
it being re-used across many similar pin controllers, or even being
the/a default binding style for new pin controllers.

I'm not totally sure whether blending the pin ID and mux function ID
into the same value is a good idea. That said, it does have advantages
as you state, and shouldn't cause any significant issues. In any case
where it would be a bad idea, the binding for the pin controller in
question can still choose to use some more appropriate binding, so
allowing this binding for some controllers won't force issues onto other
controllers. So, it seems fine.

Note however that we can't change existing bindings. Well, I suppose
certain bindings could be enhanced to support either a string-based or
an integer-base binding, but I don't think that'd be a good idea.

Re: [RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[Sascha Hauer]

Hi Stephen,

On Wed, Oct 29, 2014 at 10:05:40PM -0600, Stephen Warren wrote:
> On 10/23/2014 07:23 AM, Sascha Hauer wrote:
> > Most iomux controllers allow a configuration per pin. These currently
> > have no common device tree binding. There are many different SoC
> > specific bindings for this class of iomux controllers. Some controllers
> > artificially group pins together where in hardware no groups exist (for
> > example lantiq). Other controllers just put each pin into a separate
> > group which explodes to many many strings to parse (Tegra30).
> > 
> > 
> > A pin controller has n pins, each muxable to m different positions.
> 
> I assume that sentence is meant to say something more specific:
> 
> This binding is intended to apply to pin controllers where each pin has
> an independently selectable mux function.

Yes.

> 
> "A pin controller ..." sounds like a general statement that is intended
> to apply to any pin controller. If that were intended, the statement you
> made certainly wouldn't be true.

Right.

> 
> > There exists a logical numbering for all pins, for most SoCs this will
> > be defined by the register ordering so that the pin number can directly
> > be translated to a register offset without the need of tables in the
> > driver. The register usually takes m different numbers to specify the
> > function the pin should have. Both the pin and its function can be
> > described as a single 32bit number:
> > 
> > #define PINMUX_PIN(no, fn) (((no) & 0xffffff) << 8) | (fn) & 0xff)
> > 
> > This allows to put multiple pins into a single device tree property
> > which is very efficiently parsable by the driver (or the pinmux core).
> > We suggest to name this property 'pins' and to put it next to the
> > generic pinconf binding.  This allows to describe multiple pins with the
> > same pinconf settings in a single device tree node. Multiple of these
> > nodes can be grouped under a pinctrl state node. This allows to put pins
> > with different pinconf settings to a single state.
> > 
> > Example:
> > 
> > 	uart2 {
> > 		uart2_default_mode: uart2_default {
> > 			pins1 {
> > 				pins = <PINMUX_PIN(127, 3), PINMUX_PIN(128, 3)>;
> 
> Within each of the nodes, the binding for pinmux is defined
> independently by each pin controller. I don't have any /strong/
> objection to any particular pin controller using this binding, or even
> it being re-used across many similar pin controllers, or even being
> the/a default binding style for new pin controllers.
> 
> I'm not totally sure whether blending the pin ID and mux function ID
> into the same value is a good idea. That said, it does have advantages
> as you state, and shouldn't cause any significant issues. In any case
> where it would be a bad idea, the binding for the pin controller in
> question can still choose to use some more appropriate binding, so
> allowing this binding for some controllers won't force issues onto other
> controllers. So, it seems fine.
> 
> Note however that we can't change existing bindings. Well, I suppose
> certain bindings could be enhanced to support either a string-based or
> an integer-base binding, but I don't think that'd be a good idea.

I'm only talking about new bindings, no need to change existing
bindings. For new bindings it surely has benefits when we can just point
to a well established binding. Right now the existing bindings for the
pin controllers which independently control each pin differ a lot.

The next step should be to integrate the above into the pinctrl
documentation.

Sascha

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

Re: [RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[Sascha Hauer]

Hi Stephen,

On Wed, Oct 29, 2014 at 10:05:40PM -0600, Stephen Warren wrote:
> On 10/23/2014 07:23 AM, Sascha Hauer wrote:
> > Most iomux controllers allow a configuration per pin. These currently
> > have no common device tree binding. There are many different SoC
> > specific bindings for this class of iomux controllers. Some controllers
> > artificially group pins together where in hardware no groups exist (for
> > example lantiq). Other controllers just put each pin into a separate
> > group which explodes to many many strings to parse (Tegra30).
> > 
> > 
> > A pin controller has n pins, each muxable to m different positions.
> 
> I assume that sentence is meant to say something more specific:
> 
> This binding is intended to apply to pin controllers where each pin has
> an independently selectable mux function.

Yes.

> 
> "A pin controller ..." sounds like a general statement that is intended
> to apply to any pin controller. If that were intended, the statement you
> made certainly wouldn't be true.

Right.

> 
> > There exists a logical numbering for all pins, for most SoCs this will
> > be defined by the register ordering so that the pin number can directly
> > be translated to a register offset without the need of tables in the
> > driver. The register usually takes m different numbers to specify the
> > function the pin should have. Both the pin and its function can be
> > described as a single 32bit number:
> > 
> > #define PINMUX_PIN(no, fn) (((no) & 0xffffff) << 8) | (fn) & 0xff)
> > 
> > This allows to put multiple pins into a single device tree property
> > which is very efficiently parsable by the driver (or the pinmux core).
> > We suggest to name this property 'pins' and to put it next to the
> > generic pinconf binding.  This allows to describe multiple pins with the
> > same pinconf settings in a single device tree node. Multiple of these
> > nodes can be grouped under a pinctrl state node. This allows to put pins
> > with different pinconf settings to a single state.
> > 
> > Example:
> > 
> > 	uart2 {
> > 		uart2_default_mode: uart2_default {
> > 			pins1 {
> > 				pins = <PINMUX_PIN(127, 3), PINMUX_PIN(128, 3)>;
> 
> Within each of the nodes, the binding for pinmux is defined
> independently by each pin controller. I don't have any /strong/
> objection to any particular pin controller using this binding, or even
> it being re-used across many similar pin controllers, or even being
> the/a default binding style for new pin controllers.
> 
> I'm not totally sure whether blending the pin ID and mux function ID
> into the same value is a good idea. That said, it does have advantages
> as you state, and shouldn't cause any significant issues. In any case
> where it would be a bad idea, the binding for the pin controller in
> question can still choose to use some more appropriate binding, so
> allowing this binding for some controllers won't force issues onto other
> controllers. So, it seems fine.
> 
> Note however that we can't change existing bindings. Well, I suppose
> certain bindings could be enhanced to support either a string-based or
> an integer-base binding, but I don't think that'd be a good idea.

I'm only talking about new bindings, no need to change existing
bindings. For new bindings it surely has benefits when we can just point
to a well established binding. Right now the existing bindings for the
pin controllers which independently control each pin differ a lot.

The next step should be to integrate the above into the pinctrl
documentation.

Sascha

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[RFC] pinctrl: Provide a generic device tree binding for per-pin pin controllers

[Sascha Hauer]

Hi Stephen,

On Wed, Oct 29, 2014 at 10:05:40PM -0600, Stephen Warren wrote:
> On 10/23/2014 07:23 AM, Sascha Hauer wrote:
> > Most iomux controllers allow a configuration per pin. These currently
> > have no common device tree binding. There are many different SoC
> > specific bindings for this class of iomux controllers. Some controllers
> > artificially group pins together where in hardware no groups exist (for
> > example lantiq). Other controllers just put each pin into a separate
> > group which explodes to many many strings to parse (Tegra30).
> > 
> > 
> > A pin controller has n pins, each muxable to m different positions.
> 
> I assume that sentence is meant to say something more specific:
> 
> This binding is intended to apply to pin controllers where each pin has
> an independently selectable mux function.

Yes.

> 
> "A pin controller ..." sounds like a general statement that is intended
> to apply to any pin controller. If that were intended, the statement you
> made certainly wouldn't be true.

Right.

> 
> > There exists a logical numbering for all pins, for most SoCs this will
> > be defined by the register ordering so that the pin number can directly
> > be translated to a register offset without the need of tables in the
> > driver. The register usually takes m different numbers to specify the
> > function the pin should have. Both the pin and its function can be
> > described as a single 32bit number:
> > 
> > #define PINMUX_PIN(no, fn) (((no) & 0xffffff) << 8) | (fn) & 0xff)
> > 
> > This allows to put multiple pins into a single device tree property
> > which is very efficiently parsable by the driver (or the pinmux core).
> > We suggest to name this property 'pins' and to put it next to the
> > generic pinconf binding.  This allows to describe multiple pins with the
> > same pinconf settings in a single device tree node. Multiple of these
> > nodes can be grouped under a pinctrl state node. This allows to put pins
> > with different pinconf settings to a single state.
> > 
> > Example:
> > 
> > 	uart2 {
> > 		uart2_default_mode: uart2_default {
> > 			pins1 {
> > 				pins = <PINMUX_PIN(127, 3), PINMUX_PIN(128, 3)>;
> 
> Within each of the nodes, the binding for pinmux is defined
> independently by each pin controller. I don't have any /strong/
> objection to any particular pin controller using this binding, or even
> it being re-used across many similar pin controllers, or even being
> the/a default binding style for new pin controllers.
> 
> I'm not totally sure whether blending the pin ID and mux function ID
> into the same value is a good idea. That said, it does have advantages
> as you state, and shouldn't cause any significant issues. In any case
> where it would be a bad idea, the binding for the pin controller in
> question can still choose to use some more appropriate binding, so
> allowing this binding for some controllers won't force issues onto other
> controllers. So, it seems fine.
> 
> Note however that we can't change existing bindings. Well, I suppose
> certain bindings could be enhanced to support either a string-based or
> an integer-base binding, but I don't think that'd be a good idea.

I'm only talking about new bindings, no need to change existing
bindings. For new bindings it surely has benefits when we can just point
to a well established binding. Right now the existing bindings for the
pin controllers which independently control each pin differ a lot.

The next step should be to integrate the above into the pinctrl
documentation.

Sascha

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |