[PATCH] dt: pinctrl: Document device tree binding

[Stephen Warren]

On 03/13/2012 03:14 AM, Linus Walleij wrote:
> On Fri, Mar 9, 2012 at 7:14 PM, Stephen Warren <swarren at wwwdotorg.org> wrote:
> 
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
>> @@ -0,0 +1,118 @@
>> +== Introduction ==
>> +
>> +Hardware modules that control pin multiplexing or configuration parameters
>> +such as pull-up/down, tri-state, drive-strength etc are designated as pin
>> +controllers. Each pin controller must be represented as a node in device tree,
>> +just like any other hardware module.
> 
> Maybe put in a reference to Documentation/pinctrl.txt for in-depth
> discussion? Also some stuff may be moved over there as generic
> information. A lot of the text here does not seem to be about the
> device tree ...
> 
> However maybe the use case is outside the Linux kernel too
> and in that case I'm happy with it.

Yes, the idea is that the bindings are OS-independent as much as
possible. That's why it's a little redundant w.r.t. the existing Linux
pinctrl documentation.

>> +For a client device to operate correctly, certain pin controllers must
>> +set up certain specific pin configurations. Some client devices need a
>> +single static pin configuration, e.g. set up during initialization. Others
>> +need to reconfigure pins at run-time, for example to tri-state pins when the
>> +device is inactive. Hence, each client device can define a set of named
>> +states. The number and names of those states is defined by the client device's
>> +own binding.
> 
> Just so I understand: is "pin configuration" here strictly what we
> handle in pinconf.c or does it include multiplexing (pinmux.c)?
> 
> I guess it's not multiplexing, just making sure.
>
> Maybe state explicitly that multiplexing is not part of pin config,
> else someone will invariably get confused.

No, it's intended to cover any aspect at all of pin control hardware,
including muxing. I'm not sure why you would expect pin muxing /not/ to
be represented by these bindings?

>> +Note that pin controllers themselves may also be client devices of themselves.
> 
> Insert something about this being known as config hogging.

I think that's Linux-specific terminology, hence not appropriate for a
generic document. (And as an aside, I don't really like the name
"hogging", or even treating it as some kind of special-case).

> The rest I barely understand so I leave it for the others to discuss...

Hmm. That's unfortunate. It'd be very useful if you could fully digest
this aspect of pinctrl.