GPIO - marking individual pins (not) available in device tree

GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Hi guys,

I'm a little perplexed as to how I would define a GPIO 
controller in a device tree but mark off pins as available or 
not, so users can geek around in their own drivers without 
defining in a device tree exactly what they intend to use it 
for (especially if it's something really weird).

Easiest example - the Efika runs an MPC5200B has 3 GPIO pins 
on the board. It's not much, but they're there for use. All 
the other GPIOs are absolutely out of bounds, off limits and 
probably dangerous to touch, but since each GPIO block has a 
32-bit register to handle them, you can twiddle any bit you 
like with impunity and cause all the damage you want. A simple 
thought comes to mind in that the gpiolib should not allow a 
request for one of these "bad" GPIO pins to succeed.

So, how do we define in a bank of GPIOs, which ones are free 
for use, without them being attached to a device and given as 
a "gpios" property?

Would we suggest a node;

gpio-header {
	compatible = "bplan,efika-gpio";
	gpios = <&gpio-standard 16 0 17 0>;
};

gpio-header2 {
	compatible = "bplan,efika-gpio-wkup";
	gpios = <&gpio-wkup 18 0>;
};

Which a driver can then look for? I would much rather I did 
not have to come up with a special compatible property though, 
after all, MPC5200B GPIO are not special and the Efika does 
not do fancy magic with them :)

My goal is basically to give an entry in the device tree 
whereby (using a forth script) you can pick between IrDA, 
GPIO, a Sleep Switch (for Sylvain's patch for Lite5200 and 
Efika from a year or two ago..), or whatever else you like. 
But a generic GPIO "geek port" is basically then undefined and 
left hanging.

By the way I did notice that none of the GPT timer entries in 
the lite5200b.dts have GPIO references and the GPT GPIO block 
is not defined. Is this because the timers are not exposed on 
the board for GPIO or just no need for it? Each timer has a 
pin it can sample, drive and do PWM on.. this leads me to 
wonder how the PWM driver framework as announced/proposed last 
week would work here, and if the device tree should 
specifically pick which operation works on which timer (after 
all if you have a PWM fan controller on a timer pin, you would 
want to advertise the fact, but having the full 8 timers as a 
"gpio-controller" and "pwm-controller" both at the same time, 
sharing the same reg property but supporting only a subset of 
that controller, needs addressing.

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Mitch Bradley]

You could have the gpio node define an "address space" where each 
"address" is a GPIO pin number.

The node would have one address cell and one size cell, and the 
"decode-unit" and "encode-unit" methods would be the garden-variety 
flavors that just convert integers between binary and ASCII.  Since this 
is not a memory mapped address space, a "ranges" property wouldn't be 
necessary or appropriate.

The node could have an "available" property with address/size pairs 
defining pins that can be freely used.  For example, if pins 4 and 7-9 
were free, the available property would contain

   000000004 00000001   \ 1 pin starting at #4
   000000007 00000003   \ 3 pins starting at 7

This is modeled on the /memory node's "available" property.

Subordinate nodes could represent specific preassigned GPIO functions, 
for example

   /<whatever>/gpio/wakeup@12

As an alternative to the "available" property, you could instead have 
subordinate nodes for the user-assignable GPIOs, e.g.:

  /<whatever>/gpio/usergpio@4
  /<whatever>/gpio/usergpio@7
  ...

That last idea is probably a bit over-the-top, though, especially if 
there are a lot of unassigned GPIOs.

You could adopt the convention that preassigned GPIOs must be 
represented by subordinate nodes, and any GPIO that is not covered by a 
subordinate node's "reg" property is implicitly available.  That's the 
way it works for other address spaces.

Mitch Bradley


> Hi guys,
>
> I'm a little perplexed as to how I would define a GPIO controller in a 
> device tree but mark off pins as available or not, so users can geek 
> around in their own drivers without defining in a device tree exactly 
> what they intend to use it for (especially if it's something really 
> weird).
>
> Easiest example - the Efika runs an MPC5200B has 3 GPIO pins on the 
> board. It's not much, but they're there for use. All the other GPIOs 
> are absolutely out of bounds, off limits and probably dangerous to 
> touch, but since each GPIO block has a 32-bit register to handle them, 
> you can twiddle any bit you like with impunity and cause all the 
> damage you want. A simple thought comes to mind in that the gpiolib 
> should not allow a request for one of these "bad" GPIO pins to succeed.
>
> So, how do we define in a bank of GPIOs, which ones are free for use, 
> without them being attached to a device and given as a "gpios" property?
>
> Would we suggest a node;
>
> gpio-header {
>     compatible = "bplan,efika-gpio";
>     gpios = <&gpio-standard 16 0 17 0>;
> };
>
> gpio-header2 {
>     compatible = "bplan,efika-gpio-wkup";
>     gpios = <&gpio-wkup 18 0>;
> };
>
> Which a driver can then look for? I would much rather I did not have 
> to come up with a special compatible property though, after all, 
> MPC5200B GPIO are not special and the Efika does not do fancy magic 
> with them :)
>
> My goal is basically to give an entry in the device tree whereby 
> (using a forth script) you can pick between IrDA, GPIO, a Sleep Switch 
> (for Sylvain's patch for Lite5200 and Efika from a year or two ago..), 
> or whatever else you like. But a generic GPIO "geek port" is basically 
> then undefined and left hanging.
>
> By the way I did notice that none of the GPT timer entries in the 
> lite5200b.dts have GPIO references and the GPT GPIO block is not 
> defined. Is this because the timers are not exposed on the board for 
> GPIO or just no need for it? Each timer has a pin it can sample, drive 
> and do PWM on.. this leads me to wonder how the PWM driver framework 
> as announced/proposed last week would work here, and if the device 
> tree should specifically pick which operation works on which timer 
> (after all if you have a PWM fan controller on a timer pin, you would 
> want to advertise the fact, but having the full 8 timers as a 
> "gpio-controller" and "pwm-controller" both at the same time, sharing 
> the same reg property but supporting only a subset of that controller, 
> needs addressing.
>
> -- 
> Matt Sealey <matt@genesi-usa.com>
> Genesi, Manager, Developer Relations
> _______________________________________________
> devicetree-discuss mailing list
> devicetree-discuss@ozlabs.org
> https://ozlabs.org/mailman/listinfo/devicetree-discuss

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Mitch Bradley wrote:
[snip]

> You could adopt the convention that preassigned GPIOs must be 
> represented by subordinate nodes, and any GPIO that is not covered by a 
> subordinate node's "reg" property is implicitly available.  That's the 
> way it works for other address spaces.

I like that idea except for the implicitly available bit.

Just summarizing this in my head (also on the list), if we had 
an "available" property in the node marked as a 
gpio-controller, that would easily give gpiolib something to 
parse so that it only gives out allocations for pins that are 
really, really not being multiplexed for something else or 
just not being connected.

There's a GPIO spec in booting-without-of.txt which basically 
defines a controller and a bank, and you can assign a bank of 
GPIO to some other device. Assigning specific GPIO pins should 
be possible.. umm..

http://patchwork.ozlabs.org/patch/5478/

With regards to this patch, how about device usage of pins 
being defined as a range of pins (reusing the standard-ish 
"ranges" property from PCI binding)? That way you have all the 
information you could ever need for each device.

1) where the controller sits ("gpio-controller" property)

2) which pins are available for use (everything not in 
"available" is therefore out of bounds)

3) define banks of gpio for a specific function with "ranges" 
(for instance pins 10, 11 and 15 would be encoded as <10 2> 
and <15 1> and these encapsulate some kind of function be it 
user definable gpio or some control function for a chip)

4) assign "gpio" properties to other nodes which refer to 
banks (see booting-without-of.txt section IX, at the end) 
rather than individual pins.

5) optionally a bank may contain gpio pin node which describes 
EXACTLY what that pin function is (and any lovely properties 
it may well have).

At the moment it's encoded as:

	gpios = <&controller-phandle pin-number pin-flags>

Ad infinitum. Instead of a controller phandle you'd pass in a 
bank (which is a subset of the controller's available pins) 
and then you can give each pin it's little options.

Actually I would also advocate allowing each pin to be 
assigned a node of it's own and a compatible property - after 
all if you have a board where gpios can move around (consider 
an FPGA with a processor core, where positions of lines to use 
are actually reflected by a read-only register or the device 
tree is derived directly from the VHDL source or a constraints 
script?) and don't want to rewrite your driver every time, it 
would be good to be able to find exactly which pin controls 
exactly which line on the peripheral chip?

Therefore you'd get something like this in a DTS; please hit 
me on the head if you think it's getting really unwieldy :D

gpio_1: gpio-controller@1000 {
	#gpio-cells = <2>;
	compatible = "fsl,mpc5200b-gpio";
	reg = <0x1000 0x4>;
	gpio-controller;
	available = <1 10 15 4 30 1>;

	gpio_1_bank_1: gpio-bank {
		\\ 5 pins for some nefarious purpose
		compatible = "gpio-bank";
		ranges = <1 5 0>; \\ start length flags

		gpio_pin@2 {
\\ I guess this address has to be
\\ the global offset and not the offset into the range to make
\\ it easier?
			reg = <2 1>
			compatible = "magic";
		};
	};
}

device@9000 {
	compatible = "somedevice";
	reg = <0x9000 0x18>;
	gpios = <&gpio_1_bank_1>
};

Most implementations won't need the explicit pin definitions 
but it would probably come in handy somewhere if you were 
bitbanging some protocol (SPI, I2C or so) or driving a device 
where you could change this stuff, or even dynamically work 
out if a connector was inserted a certain way (I'm thinking of 
maybe an expansion connector which can run line-reversed like 
PCI Express.. but made out of GPIO. Am I nuts?)

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Mitch Bradley]

>
>
> Mitch Bradley wrote:
> [snip]
>
>> You could adopt the convention that preassigned GPIOs must be 
>> represented by subordinate nodes, and any GPIO that is not covered by 
>> a subordinate node's "reg" property is implicitly available.  That's 
>> the way it works for other address spaces.
>
> I like that idea except for the implicitly available bit.
>
> Just summarizing this in my head (also on the list), if we had an 
> "available" property in the node marked as a gpio-controller, that 
> would easily give gpiolib something to parse so that it only gives out 
> allocations for pins that are really, really not being multiplexed for 
> something else or just not being connected.
>
> There's a GPIO spec in booting-without-of.txt which basically defines 
> a controller and a bank, and you can assign a bank of GPIO to some 
> other device. Assigning specific GPIO pins should be possible.. umm..
>
> http://patchwork.ozlabs.org/patch/5478/
>
> With regards to this patch, how about device usage of pins being 
> defined as a range of pins (reusing the standard-ish "ranges" property 
> from PCI binding)?


Okay, so it looks to me like your "bank" concept is sort of akin to a 
"gpio-to-gpio bridge", with analogy to a pci-to-pci bridge.  Following 
that model, the "name" of your "gpio-bank" would instead be 
"gpio-controller", because its children are GPIO pin nodes that could 
just as well be attached directly to the top-level gpio-controller 
node.  The "compatible" property would be different, reflecting the fact 
that it is a "gpio-to-gpio bridge" instead of an "io-to-gpio bridge" 
(for example).

"ranges" is fully standard.  Its specification is tight enough to permit 
generic address-translation code to walk up a tree and work out how to 
translate addresses through multiple levels, even in the face of 
different address representations at the various levels.  (But the 
chained address spaces must be of the same general flavor, such as 
memory mapped spaces translated through PCI nodes.)  Each "ranges" entry 
defines a subrange of the child address space and the corresponding 
subrange of the parent address space.

So to use "ranges" in the context of "gpio-to-gpio bridge" node, the 
value would be a list of each entries each containing <child-start-pin# 
parent-start-pin# size>.  You could choose whether or not to offset the 
child and parent pin numbers.  If you wrote  <0 5 2>, that would mean 
that child pins 0 and 1 would actually be parent pins 5 and 6 - the 
child "reg" property would have to say, e.g. <0 2>.   If you wrote <5 5 
2>, that would mean no offsetting from child to parent; the child "reg" 
would be <5 2>.  Generic "ranges" handling code wouldn't care.

That said, I'm not sure that the intermediate level ("banks" or "g2g 
bridge", whatever you want to call it) is worth the effort.  There is a 
very good reason for pci-to-pci bridge nodes - they exist in hardware 
and impose a translation on the configuration addresses.  The "g2g" 
intermediate nodes might make it slightly easier to move around chunks 
of GPIO pins, but I'm not sure that it's really that much easier, 
compared to just changing the values in the "reg" property of the 
child.  If a child function requires a group of related GPIO pins, you 
can list all the pins in its reg property, ordered according to their  
purposes.  For example, the first reg entry might be for the "SCL" pin 
and the second for the "SDA" pin.

> That way you have all the information you could ever need for each 
> device.
>
> 1) where the controller sits ("gpio-controller" property)
>
> 2) which pins are available for use (everything not in "available" is 
> therefore out of bounds)
>
> 3) define banks of gpio for a specific function with "ranges" (for 
> instance pins 10, 11 and 15 would be encoded as <10 2> and <15 1> and 
> these encapsulate some kind of function be it user definable gpio or 
> some control function for a chip)

As argued above, I think the grouping should be done directly in the 
child node, listing the pins in the reg property.

>
> 4) assign "gpio" properties to other nodes which refer to banks (see 
> booting-without-of.txt section IX, at the end) rather than individual 
> pins.

I think that's an improvement over the "gpios" formulation in section 
IX.  I'm concerned that the stipulated "gpios" format pushes a lot of 
address-format complexity out into unrelated nodes. 


>
> 5) optionally a bank may contain gpio pin node which describes EXACTLY 
> what that pin function is (and any lovely properties it may well have).
>
> At the moment it's encoded as:
>
>     gpios = <&controller-phandle pin-number pin-flags>
>
> Ad infinitum. Instead of a controller phandle you'd pass in a bank 
> (which is a subset of the controller's available pins) and then you 
> can give each pin it's little options.

How about
     gpios = <&controller-child-phandle0 &controller-child-phandle1 ...>

The flags, if any, should be properties of the child node.

One might argue that the code to process the "new" gpios will need 
additional complexity to deal with addressing issues at the target child 
nodes.  I would counter that it is probably actually easier, because 
instead of needing code to handle "#gpio-cells", you instead re-use 
existing code to handle "#address-cells" in the child/parent context.

>
> Actually I would also advocate allowing each pin to be assigned a node 
> of it's own and a compatible property - after all if you have a board 
> where gpios can move around (consider an FPGA with a processor core, 
> where positions of lines to use are actually reflected by a read-only 
> register or the device tree is derived directly from the VHDL source 
> or a constraints script?) and don't want to rewrite your driver every 
> time, it would be good to be able to find exactly which pin controls 
> exactly which line on the peripheral chip?

Yep.  The existing OFW addressing framework was designed to solve 
exactly this sort of problem, with its abstraction of the notion of an 
"address" and its ability to change the interpretation of "addresses" as 
you move around in the tree.


>
> Therefore you'd get something like this in a DTS; please hit me on the 
> head if you think it's getting really unwieldy :D
>
> gpio_1: gpio-controller@1000 {
>     #gpio-cells = <2>;

"#gpio-cells" is unnecessary if the "gpios" property is just a list of 
phandles.  But you do need "#address-cells = <1>" and "#size-cells = 
<1>", because this node defines a proper subordinate address space.

>     compatible = "fsl,mpc5200b-gpio";
>     reg = <0x1000 0x4>;
>     gpio-controller;
>     available = <1 10 15 4 30 1>;
>
>     gpio_1_bank_1: gpio-bank {
>         \\ 5 pins for some nefarious purpose
>         compatible = "gpio-bank";
>         ranges = <1 5 0>; \\ start length flags

As stated, I'd forego this intermediate level.


>
>         gpio_pin@2 {

The name here should reflect the purpose of the pin, i.e. what it does 
(perhaps "NAME,magic"), not the fact that is is GPIO pin.  By analogy, 
an ethernet controller's node name is "ethernet", not "pci-card".  The 
fact that the node represents one or more gpio pins is implicit and 
obvious - all children of a gpio-controller node are gpio pin(s).  All 
children of a scsi node are SCSI devices, ad nauseum.

> \\ I guess this address has to be
> \\ the global offset and not the offset into the range to make
> \\ it easier?

Eliminating the intermediate level moots this question.

>             reg = <2 1>
>             compatible = "magic";
>         };
>     };
> }
>
> device@9000 {
>     compatible = "somedevice";
>     reg = <0x9000 0x18>;
>     gpios = <&gpio_1_bank_1>

gpios = <&NAME,magic>

> };
>
> Most implementations won't need the explicit pin definitions but it 
> would probably come in handy somewhere if you were bitbanging some 
> protocol (SPI, I2C or so) or driving a device where you could change 
> this stuff, or even dynamically work out if a connector was inserted a 
> certain way (I'm thinking of maybe an expansion connector which can 
> run line-reversed like PCI Express.. but made out of GPIO. Am I nuts?)

It has been my experience that full explicit descriptions are usually a 
win in the long run.  (Which is not to say that I've always done the 
right thing, but when I have it has often been worthwhile.)


>
> -- 
> Matt Sealey <matt@genesi-usa.com>
> Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[David Gibson]

On Thu, Oct 23, 2008 at 02:52:18PM -1000, Mitch Bradley wrote:
>>
>>
>> Mitch Bradley wrote:
>> [snip]
>>
>>> You could adopt the convention that preassigned GPIOs must be  
>>> represented by subordinate nodes, and any GPIO that is not covered by 
>>> a subordinate node's "reg" property is implicitly available.  That's  
>>> the way it works for other address spaces.
>>
>> I like that idea except for the implicitly available bit.
>>
>> Just summarizing this in my head (also on the list), if we had an  
>> "available" property in the node marked as a gpio-controller, that  
>> would easily give gpiolib something to parse so that it only gives out  
>> allocations for pins that are really, really not being multiplexed for  
>> something else or just not being connected.
>>
>> There's a GPIO spec in booting-without-of.txt which basically defines  
>> a controller and a bank, and you can assign a bank of GPIO to some  
>> other device. Assigning specific GPIO pins should be possible.. umm..
>>
>> http://patchwork.ozlabs.org/patch/5478/
>>
>> With regards to this patch, how about device usage of pins being  
>> defined as a range of pins (reusing the standard-ish "ranges" property  
>> from PCI binding)?
>
>
> Okay, so it looks to me like your "bank" concept is sort of akin to a  
> "gpio-to-gpio bridge", with analogy to a pci-to-pci bridge.  Following  
> that model, the "name" of your "gpio-bank" would instead be  
> "gpio-controller", because its children are GPIO pin nodes that could  
> just as well be attached directly to the top-level gpio-controller node.  
> The "compatible" property would be different, reflecting the fact that it 
> is a "gpio-to-gpio bridge" instead of an "io-to-gpio bridge" (for 
> example).

No, no, no, no, no.  Making complex multi-level representations of
nested things for gpios is just insanity.  Just use the same encoded
format as we already use for gpio descriptors in 'gpios' properties
(which is gpio controller specific, with length defined by
#gpio-cells).

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

Re: GPIO - marking individual pins (not) available in device tree

[Mitch Bradley]

>
> No, no, no, no, no.  Making complex multi-level representations of
> nested things for gpios is just insanity. 


You know, I don't find this "argument" particularly compelling.  But it 
certainly is strongly worded.

>  Just use the same encoded
> format as we already use for gpio descriptors in 'gpios' properties
> (which is gpio controller specific, with length defined by
> #gpio-cells).

http://en.wikipedia.org/wiki/Proof_by_assertion

Re: GPIO - marking individual pins (not) available in device tree

[David Gibson]

On Thu, Oct 23, 2008 at 06:17:45PM -1000, Mitch Bradley wrote:
>>
>> No, no, no, no, no.  Making complex multi-level representations of
>> nested things for gpios is just insanity. 
>
>
> You know, I don't find this "argument" particularly compelling.  But it  
> certainly is strongly worded.
>
>>  Just use the same encoded
>> format as we already use for gpio descriptors in 'gpios' properties
>> (which is gpio controller specific, with length defined by
>> #gpio-cells).
>
> http://en.wikipedia.org/wiki/Proof_by_assertion

Don't be patronising.

There is an existing address space defined by the gpio binding.
Defining another one is pointless redundancy.  This is standard good
ideas in computer science, no further argument necessary.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

David Gibson wrote:
> Don't be patronising.
> 
> There is an existing address space defined by the gpio binding.
> Defining another one is pointless redundancy.  This is standard good
> ideas in computer science, no further argument necessary.

The existing address space, and the patches Anton etc. just submitted
which I started this discussion to address, don't fulfil certain needs.

You could do better than call it insane, by describing how you would
define a gpio bank that used 3 seperate pins which are NOT together
in a register, using a base address (reg) and base property (offset
of first pin) with the current system?

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[David Gibson]

On Fri, Oct 24, 2008 at 05:14:26PM -0500, Matt Sealey wrote:
>
>
> David Gibson wrote:
>> Don't be patronising.
>>
>> There is an existing address space defined by the gpio binding.
>> Defining another one is pointless redundancy.  This is standard good
>> ideas in computer science, no further argument necessary.
>
> The existing address space, and the patches Anton etc. just submitted
> which I started this discussion to address, don't fulfil certain
> needs.

Such as what?  Apparently none, since elsewhere in this thread you
seem to be happy with the suggestion of using a gpio-header node,
which does use the same address space.

> You could do better than call it insane, by describing how you would
> define a gpio bank that used 3 seperate pins which are NOT together
> in a register, using a base address (reg) and base property (offset
> of first pin) with the current system?

Um.. I can't actually follow what you're getting at there, sorry.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

David Gibson wrote:

> Um.. I can't actually follow what you're getting at there, sorry.

Imagine in your head that you have a GPIO controller that has a
32-bit register potentially controlling 32 pins on the chip.

Imagine that rather than being able to allocate 6 GPIO pins
*right next to each other* in the register and saying that
you start at "pin" 15 and use the next 6 "pins", you have to
spread it around and use pin 1, pin 8, pin 9, pin 11, pin 15,
pin 30, to make up this peripheral.

As far as I can tell there is no way at all to specify a set of
GPIO pins which are NOT consecutive because the current GPIO
spec stops after specifying a controller bank (the 32-bit
register).

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Anton Vorontsov]

On Mon, Oct 27, 2008 at 10:40:12AM -0500, Matt Sealey wrote:
>
>
> David Gibson wrote:
>
>> Um.. I can't actually follow what you're getting at there, sorry.
>
> Imagine in your head that you have a GPIO controller that has a
> 32-bit register potentially controlling 32 pins on the chip.
>
> Imagine that rather than being able to allocate 6 GPIO pins
> *right next to each other* in the register and saying that
> you start at "pin" 15 and use the next 6 "pins", you have to
> spread it around and use pin 1, pin 8, pin 9, pin 11, pin 15,
> pin 30, to make up this peripheral.

Isn't this some implementation detail of a gpio controller?

gpio: gpio-controller@... {
	#gpio-cells = <2>;
	compatible = "gpio-bank-with-funny-mapping"; <- notice this
	reg = <123 4>;
	gpio-controller;
}

device {
	gpios = <&gpio 0 0 &gpio 1 0 &gpio 2 0>;
}

^^ Three gpios, 0, 1, 2. Based on a compatible entry Linux can
   translate them in any way.

   For example GPIO0 - bit 15, GPIO1 - bit 20, GPIO2 - bit 1.

> As far as I can tell there is no way at all to specify a set of
> GPIO pins which are NOT consecutive because the current GPIO
> spec stops after specifying a controller bank (the 32-bit
> register).

The GPIO spec doesn't specify a controller bank. It says

- - - -
gpio-specifier may encode: bank, pin position inside the bank,
whether pin is open-drain and whether pin is logically inverted.
- - - -

May encode. Or may not encode. FYI, for most (all) SOC GPIO
controllers we don't use "bank" encoding in the gpio-specifier.

-- 
Anton Vorontsov
email: cbouatmailru@gmail.com
irc://irc.freenode.net/bd2

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Anton Vorontsov wrote:
> The GPIO spec doesn't specify a controller bank. It says
> 
> - - - -
> gpio-specifier may encode: bank, pin position inside the bank,
> whether pin is open-drain and whether pin is logically inverted.
> - - - -
> 
> May encode. Or may not encode. FYI, for most (all) SOC GPIO
> controllers we don't use "bank" encoding in the gpio-specifier.

This is exactly 100% precisely why I asked about it, there should at
least be a binding for each specific controller where this is
relevant, but since there is very little variation on "use pin 15
please with these flags" (only what "pin 15" means is undefined
so far, and left to the driver/controller variation) there must
be a generic way to specify groups of IO pins which may not be
consecutive.

I don't get your example;

 > device {
 >	gpios = <&gpio 0 0 &gpio 1 0 &gpio 2 0>;
 > }
 >
 > ^^ Three gpios, 0, 1, 2. Based on a compatible entry Linux can
 >   translate them in any way.
 >
 >   For example GPIO0 - bit 15, GPIO1 - bit 20, GPIO2 - bit 1.

This kind of defeats the object. While the pin numbering may well
be board-specific, it makes sense to maintain it as it relates to
offsets into a register or offsets into a bank of registers the
same way that interrupt mappings on the MPC5200B are ripped out of a
table in the MPC5200B documentation.

What the above example does is give a completely arbitrary
number which only maps to a real pin or offset *inside the driver*
meaning 10 boards with the same chip all have to have different
drivers, gpio_chip libraries to allocate the pins - the driver
to note which pin is for which purpose, and gpiolib to make sure
some driver accessing them has not been loaded twice.

Right?

Even if I have my Efika sitting here I want to share my GPIO
library code between it and the lite5200b - be that making the
"sleep switch" code look for a certain gpio pin marker in the
device tree so it knows what to allocate (so the number isn't
hardcoded into the driver as a compile-time switch or a check
for the /soc node model)

The current model seems to me like it is not getting any benefit
whatsoever from being defined in a device tree, in fact it is
making certain GPIO functionality go back to the hardcoded-per-board
stuff we used to have in arch/ppc.

This is just proving the point that nobody is forward-thinking
about this stuff, and is just implementing hack over hack over
hack to get something to work, and refining it later. We're
already running kernels which need to be specially built for
specially built U-Boot versions, special options for the dtc,
and device trees which change every other week. Specifying the
bare minimum here for the functionality a single user uses
defeats the object of having a descriptive device tree.

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Anton Vorontsov]

On Mon, Oct 27, 2008 at 01:56:03PM -0500, Matt Sealey wrote:
> Anton Vorontsov wrote:
>> The GPIO spec doesn't specify a controller bank. It says
>>
>> - - - -
>> gpio-specifier may encode: bank, pin position inside the bank,
>> whether pin is open-drain and whether pin is logically inverted.
>> - - - -
>>
>> May encode. Or may not encode. FYI, for most (all) SOC GPIO
>> controllers we don't use "bank" encoding in the gpio-specifier.
>
> This is exactly 100% precisely why I asked about it, there should at
> least be a binding for each specific controller where this is
> relevant, but since there is very little variation on "use pin 15
> please with these flags" (only what "pin 15" means is undefined
> so far, and left to the driver/controller variation) there must
> be a generic way to specify groups of IO pins which may not be
> consecutive.
>
> I don't get your example;
>
> > device {
> >	gpios = <&gpio 0 0 &gpio 1 0 &gpio 2 0>;
> > }
> >
> > ^^ Three gpios, 0, 1, 2. Based on a compatible entry Linux can
> >   translate them in any way.
> >
> >   For example GPIO0 - bit 15, GPIO1 - bit 20, GPIO2 - bit 1.
>
> This kind of defeats the object. While the pin numbering may well
> be board-specific, it makes sense to maintain it as it relates to
> offsets into a register or offsets into a bank of registers the
> same way that interrupt mappings on the MPC5200B are ripped out of a
> table in the MPC5200B documentation.
>
> What the above example does is give a completely arbitrary
> number which only maps to a real pin or offset *inside the driver*
> meaning 10 boards with the same chip all have to have different
> drivers, gpio_chip libraries to allocate the pins - the driver
> to note which pin is for which purpose, and gpiolib to make sure
> some driver accessing them has not been loaded twice.
>
> Right?
>
> Even if I have my Efika sitting here I want to share my GPIO
> library code between it and the lite5200b - be that making the
> "sleep switch" code look for a certain gpio pin marker in the
> device tree so it knows what to allocate (so the number isn't
> hardcoded into the driver as a compile-time switch or a check
> for the /soc node model)
>
> The current model seems to me like it is not getting any benefit
> whatsoever from being defined in a device tree, in fact it is
> making certain GPIO functionality go back to the hardcoded-per-board
> stuff we used to have in arch/ppc.
>
> This is just proving the point that nobody is forward-thinking
> about this stuff, and is just implementing hack over hack over
> hack to get something to work, and refining it later. We're
> already running kernels which need to be specially built for
> specially built U-Boot versions, special options for the dtc,
> and device trees which change every other week. Specifying the
> bare minimum here for the functionality a single user uses
> defeats the object of having a descriptive device tree.

Sorry, your mail doesn't make any sense to me.
That makes me think that you you didn't understand the whole
GPIO thing... Or maybe I misunderstood you completely.

Can you _simply_ describe the problem you're trying to solve,
w/o that much emotions? Can you give examples of what
you've tried, and describe why you don't like it?

Am I understand correctly that some 52xx boards have an
external GPIOs header, and you need to describe it, and
maybe write some driver to do something with a device called
_GPIO header_ with a _pin_ named "wakeup" that connects to
a CPU _pin_ that pinmuxed to a _GPIO_ that can wakeup the CPU?

I remember I purposed the solution to this problem, what was
wrong with it?

-- 
Anton Vorontsov
email: cbouatmailru@gmail.com
irc://irc.freenode.net/bd2

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Anton Vorontsov wrote:
> Can you _simply_ describe the problem you're trying to solve,
> w/o that much emotions? Can you give examples of what
> you've tried, and describe why you don't like it?

I've not tried anything because I don't feel confident that the
documentation or device tree examples explain the situation at
all.

Here's the basic premise;

MPC5200B has three GPIO banks, one for standard, one for wakeups,
one for timer GPIO. They're all implemented as 32-bit registers
(but each bank does not necessarily have 32 pins escaping the
chip). Several of the GPIO are multiplexed with other devices
which can and does leave gaping holes of GPIO in the 32-bit
register where anything up to 7 pins are given over to another
device and therefore are no longer GPIO (this example is held
up by the implementation of ethernet on the MPC5200B).

Given GPIO functionality where you need more pins than a single
device mux can offer, and some device muxing making those holes
splitting up a contiguous allocation of pins that can be defined
by a base pin number and a count of pins to assign, you may have
to allocate several GPIO pins out of the register which are NOT
contiguous.

So in a 32-bit register, let's say 0 is a GPIO we don't need (or
available but used for some other GPIO peripheral), and X is a
GPIO muxed to another device (therefore not GPIO anymore) and 1
is one we do want to use:

00011XXXXXXX111XX1111XXX00000XX1

(imagine them routed to a 12-pin connector with VCC and GND
and 10 data pins. This may be an LCD display controller such
as you can buy from Sparkfun or CrystalFontz, if you need a
physical example)

A bunch of things spring to mind:

*   How do you define a GPIO bank in a device tree, not a controller
     but a grouping of pins which fit that pattern, of which there
     may be multiple groupings for multiple peripheral functions

(for instance an LED controller, and an IR receiver, and a bitbang
SPI implemented using these GPIO pins)?

*   How do you stop GPIOLIB from blindly approving requests to use
     pins marked X, without making it "controller-specific"? GPIOLIB
     can be as controller-specific as it likes, but having 20 different
     ways to define "X pins" or "available pins" complicates a
     device tree unnecessarily.

(I've been implementing a "gpio-mask" property in MY device trees
because I thought of this problem ages ago but just never had any
reason to make use of it. But it's very controller-specific, and
therefore pretty useless (and actually on other GPIO controllers
which use a register-per-pin is not actually any use at all, but
the question above remains!))

*   Since we're looking at an example where we interface a fairly
     complex device which is technically a bus, with a subordinate
     device which may or may not be probe-able, could you define
     that GPIO configuration in such a way that it is a device node
     of it's own, that the pins are marked for their purpose

(on such an LCD example, 8 data pins in a group, 1 for r/w selection
and 1 for data/control selection, it would be nice for the
software to know which pin is which and, slightly unrelated,
which way around the data pins went - MSB first or LSB first
- from the device tree, as this is a BOARD LEVEL DESIGN DECISION
which is what the device tree is meant to abstract - in the same
way we define i2c controllers and clients?)

*   At the end of the day the GPIO device tree binding is barely
     20 lines at the bottom of a file that has been superceded by
     the ePAPR standard now, so where do we stand on this anyway?

(I will ask that same last question of the i2c guys, I have never
seen the Linux i2c device binding in the tree - maybe I am not
looking hard enough - and the Sun binding seems to be a secret
that only special people are allowed to see)


I don't feel the current spec actually takes this into account
and the patch submission the other day from Wolfgang made me
think that if a "base" register is the obvious solution to some
problem, then it either can't be that clear to others (i.e. it
is not just me being stupid) or it is simply not possible under
the current binding.

At the very least it needs documenting better, worst case is
it needs a damn good rethink taking into account a set of
controllers which comprise a representative number of GPIO
controller types and potential uses. I actually saw the voltage
controller framework go into 2.6.27 and they have designed it
around the operation of two PMUI chips which are pretty much
the industry standard. GPIO device tree does not seem to have
gotten the same amount of attention.

Yes, your idea, Mitch's discussion was great, I just don't think
anything will get done about it (emotional moment) as usual.

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Anton Vorontsov]

On Mon, Oct 27, 2008 at 04:56:57PM -0500, Matt Sealey wrote:
> Anton Vorontsov wrote:
>> Can you _simply_ describe the problem you're trying to solve,
>> w/o that much emotions? Can you give examples of what
>> you've tried, and describe why you don't like it?
>
> I've not tried anything because I don't feel confident that the
> documentation or device tree examples explain the situation at
> all.
>
> Here's the basic premise;
>
> MPC5200B has three GPIO banks, one for standard, one for wakeups,
> one for timer GPIO. They're all implemented as 32-bit registers
> (but each bank does not necessarily have 32 pins escaping the
> chip). Several of the GPIO are multiplexed with other devices
> which can and does leave gaping holes of GPIO in the 32-bit
> register where anything up to 7 pins are given over to another
> device and therefore are no longer GPIO (this example is held
> up by the implementation of ethernet on the MPC5200B).
>
> Given GPIO functionality where you need more pins than a single
> device mux can offer, and some device muxing making those holes
> splitting up a contiguous allocation of pins that can be defined
> by a base pin number and a count of pins to assign, you may have
> to allocate several GPIO pins out of the register which are NOT
> contiguous.
>
> So in a 32-bit register, let's say 0 is a GPIO we don't need (or
> available but used for some other GPIO peripheral), and X is a
> GPIO muxed to another device (therefore not GPIO anymore) and 1
> is one we do want to use:
>
> 00011XXXXXXX111XX1111XXX00000XX1
>
> (imagine them routed to a 12-pin connector with VCC and GND
> and 10 data pins. This may be an LCD display controller such
> as you can buy from Sparkfun or CrystalFontz, if you need a
> physical example)
>
> A bunch of things spring to mind:
>
> *   How do you define a GPIO bank in a device tree, not a controller

Not a controller? What do you mean by "bank"? There is no such
thing. There are GPIO controllers, and _maybe_ _their_ banks of
GPIOs.

>     but a grouping of pins which fit that pattern, of which there
>     may be multiple groupings for multiple peripheral functions

Why do you need this, _exactly_? What problem this would solve? But
see below, this is still possible to implement.

> (for instance an LED controller, and an IR receiver, and a bitbang
> SPI implemented using these GPIO pins)?

So you need indirect GPIOs to use with devices? I.e. you want
to reference a GPIO header's GPIOs? Don't see any point in this
(other than just introducing the indirectness), but anyway this
will look like this:

cpu_pio: cpu-gpio-controller {
	#gpio-cells = <2>;
	gpio-controller;
};

header_pio: gpio-header {
	/*
	 * This controller defines a group of GPIOs wired to a
	 * external header. The header enumerates pins from 1
	 * to 12. So gpio-spec "&header_pio 4 0" will reference
	 * the 5-th pin, no matter what underlaying GPIO controller
	 * provides it.
	 */
	#gpio-cells = <2>;
	gpio-controller;
	gpios = <&cpu_pio 12 0
		 &cpu_pio 21 0
		 &i2c_controller 2 0
		 ...>
}

spi-controller {
	/* We want to _not_ care what underlaying GPIOs there are,
	 * we reference the header pins instead. */
	gpios = <&header_pio 0 0 /* MISO */
		 &header_pio 1 0 /* MOSI */
		 ...
		 &header_pio 11 0 /* CS0 */
		 ...>;
}

> *   How do you stop GPIOLIB from blindly approving requests to use
>     pins marked X, without making it "controller-specific"?

Driver can implement a .request() hook, and check for compatible
entries for this specific gpio controller. If this particular
gpio controller doesn't provide some pin it can return -ENODEV.

But I still wonder what problem exactly you're trying to solve
here? Prevent requesting reserved gpios? I don't see any point
in this, really.

>     GPIOLIB
>     can be as controller-specific as it likes, but having 20 different
>     ways to define "X pins" or "available pins" complicates a
>     device tree unnecessarily.
>
> (I've been implementing a "gpio-mask" property in MY device trees
> because I thought of this problem ages ago but just never had any
> reason to make use of it. But it's very controller-specific, and
> therefore pretty useless (and actually on other GPIO controllers
> which use a register-per-pin is not actually any use at all, but
> the question above remains!))
>
> *   Since we're looking at an example where we interface a fairly
>     complex device which is technically a bus, with a subordinate
>     device which may or may not be probe-able, could you define
>     that GPIO configuration in such a way that it is a device node
>     of it's own, that the pins are marked for their purpose
>
> (on such an LCD example, 8 data pins in a group, 1 for r/w selection

No problem. Define bindings for "8 GPIOs data group".

/* 8bit Parallel I/O port using arbitrary gpios */
byte_pio: byte-pio {
	compatible = "byte-pio";
	gpios = <&controller1 0 1   /* data line 0 */
		 &controller2 12 0  /* data line 1 */
		 ...>;
};

lcd-controller {
	/* the lcd controller can simply use the pio_out_8(),
	 * pio_in_8() API. The API is easily implemented. */
	lcd-data-port = <&byte_pio>;
}

> and 1 for data/control selection, it would be nice for the
> software to know which pin is which and, slightly unrelated,
> which way around the data pins went - MSB first or LSB first
> - from the device tree, as this is a BOARD LEVEL DESIGN DECISION
> which is what the device tree is meant to abstract - in the same
> way we define i2c controllers and clients?)

> *   At the end of the day the GPIO device tree binding is barely
>     20 lines at the bottom of a file that has been superceded by
>     the ePAPR standard now, so where do we stand on this anyway?
>
> (I will ask that same last question of the i2c guys, I have never
> seen the Linux i2c device binding in the tree - maybe I am not
> looking hard enough - and the Sun binding seems to be a secret
> that only special people are allowed to see)

Please don't mix threads. Start a new thread for i2c guys.

> I don't feel the current spec actually takes this into account
> and the patch submission the other day from Wolfgang made me
> think that if a "base" register is the obvious solution to some
> problem, then it either can't be that clear to others (i.e. it
> is not just me being stupid) or it is simply not possible under
> the current binding.

Wolfgang's patch proved to be unnecessary, you haven't seen
the solution?

> At the very least it needs documenting better,

Feel free to write a better documentation.

> worst case is
> it needs a damn good rethink taking into account a set of
> controllers which comprise a representative number of GPIO
> controller types and potential uses.

The proposal is.. quite vague.

> I actually saw the voltage
> controller framework go into 2.6.27 and they have designed it
> around the operation of two PMUI chips which are pretty much
> the industry standard.

Good for them. How does it relate to this GPIO discussion?

> GPIO device tree does not seem to have
> gotten the same amount of attention.

I don't know how did you come to these conclusions. Pretty much
people were involved into the gpio bindings discussion.

> Yes, your idea, Mitch's discussion was great, I just don't think
> anything will get done about it (emotional moment) as usual.

Hm. If idea looks ok, then it is matter of implementation. And
the gpio-header case is quite easy to implement, really.

-- 
Anton Vorontsov
email: cbouatmailru@gmail.com
irc://irc.freenode.net/bd2

Re: GPIO - marking individual pins (not) available in device tree

[Anton Vorontsov]

On Tue, Oct 28, 2008 at 02:12:21AM +0300, Anton Vorontsov wrote:
[...]
> > *   How do you stop GPIOLIB from blindly approving requests to use
> >     pins marked X, without making it "controller-specific"?

Btw, as for pins marked X... If the gpio controller has some register
that specify which pins are not available to use as GPIOs, then just read
that register, check its value and return -ENODEV from the .request()
gpiolib callback.

This is easily doable for QE/CPM gpio controllers (they have option
registers), but nobody cares to check them.

-- 
Anton Vorontsov
email: cbouatmailru@gmail.com
irc://irc.freenode.net/bd2

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Anton Vorontsov wrote:
> On Tue, Oct 28, 2008 at 02:12:21AM +0300, Anton Vorontsov wrote:
> [...]
>>> *   How do you stop GPIOLIB from blindly approving requests to use
>>>     pins marked X, without making it "controller-specific"?
> 
> Btw, as for pins marked X... If the gpio controller has some register
> that specify which pins are not available to use as GPIOs, then just read
> that register, check its value and return -ENODEV from the .request()
> gpiolib callback.

It doesn't. At least not close by.

> This is easily doable for QE/CPM gpio controllers (they have option
> registers), but nobody cares to check them.

There are plenty of examples where this information is encoded somewhere
else in the chip and Ben Herrenschmidt et al. have recommended that it
be put in the device tree so that drivers do not have to go and check
registers in other units to get that information.

However there is no standard way to expose it. And people just grab a
pin they "know" is free on their particular board.

Are you sure you do NOT see any shortcomings here?

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Anton Vorontsov wrote:
> On Mon, Oct 27, 2008 at 04:56:57PM -0500, Matt Sealey wrote:
>>
>> A bunch of things spring to mind:
>>
>> *   How do you define a GPIO bank in a device tree, not a controller
> 
> Not a controller? What do you mean by "bank"? There is no such
> thing. There are GPIO controllers, and _maybe_ _their_ banks of
> GPIOs.

I don't know what you want to call it, I don't know what the official
Linux term might be for a grouped bunch of GPIO used for a peripheral.

>>     but a grouping of pins which fit that pattern, of which there
>>     may be multiple groupings for multiple peripheral functions
> 
> Why do you need this, _exactly_? What problem this would solve? But
> see below, this is still possible to implement.

I made a pretty good example with the lcd controller, I thought..

> But I still wonder what problem exactly you're trying to solve
> here? Prevent requesting reserved gpios? I don't see any point
> in this, really.

There's plenty of reason for it, it's totally wrong to be able
to request a GPIO which has been multiplexed to another device
in the SoC, and probably completely undefined behaviour if you
start toggling a pin that's been assigned to an internal
controller.

Since you have no way of knowing except intimate board design
knowledge in the driver.. well, that defeats the purpose of the
device tree in general and is a step back into hardcoded information
in board support from arch/ppc days etc..

This information SHOULD be in the device tree specifically because
there is one very popular chip here which has GPIO multiplexed with
other very-often-used peripherals, and I can think of at least 5
other chips which also have device trees and GPIO potential (4 of
which we have designed boards around) which fit the same model and
would have the same requirement.

There are two ways you can do it; implicit and explicit. If a
pin is not defined for a peripheral in the device tree, it is
not requestable from GPIOLIB. Or, you make sure that you specify


> No problem. Define bindings for "8 GPIOs data group".
> 
> /* 8bit Parallel I/O port using arbitrary gpios */
> byte_pio: byte-pio {
> 	compatible = "byte-pio";
> 	gpios = <&controller1 0 1   /* data line 0 */
> 		 &controller2 12 0  /* data line 1 */
> 		 ...>;
> };
> 
> lcd-controller {
> 	/* the lcd controller can simply use the pio_out_8(),
> 	 * pio_in_8() API. The API is easily implemented. */
> 	lcd-data-port = <&byte_pio>;
> }
> 
>> and 1 for data/control selection, it would be nice for the
>> software to know which pin is which and, slightly unrelated,
>> which way around the data pins went - MSB first or LSB first
>> - from the device tree, as this is a BOARD LEVEL DESIGN DECISION
>> which is what the device tree is meant to abstract - in the same
>> way we define i2c controllers and clients?)

And this? What about the other two control lines? Do they just get
set in the gpios property of the lcd-controller? How do you determine
which is which? Comments don't get compiled.. and a driver will have
to be written FROM the comments, hardcoding the pins into it, again.

I refer you to the little discussion about Xilinx cores and GPIO
which may change from build to build due to pin mapping requirements
and autofitting. There are plenty of cases where you'd implement
some board design where you do not want to rewrite and recompile a
driver after you've just revised your FPGA design for some reason.

>> *   At the end of the day the GPIO device tree binding is barely
>>     20 lines at the bottom of a file that has been superceded by
>>     the ePAPR standard now, so where do we stand on this anyway?
>>
>> (I will ask that same last question of the i2c guys, I have never
>> seen the Linux i2c device binding in the tree - maybe I am not
>> looking hard enough - and the Sun binding seems to be a secret
>> that only special people are allowed to see)
> 
> Please don't mix threads. Start a new thread for i2c guys.

It's simply a reference to a similar problem.

>> I don't feel the current spec actually takes this into account
>> and the patch submission the other day from Wolfgang made me
>> think that if a "base" register is the obvious solution to some
>> problem, then it either can't be that clear to others (i.e. it
>> is not just me being stupid) or it is simply not possible under
>> the current binding.
> 
> Wolfgang's patch proved to be unnecessary, you haven't seen
> the solution?

Wolfgang's patch would never have been considered by Wolfgang
if the solution wasn't more obvious... this is why I started
the thread :D

>> At the very least it needs documenting better,
> 
> Feel free to write a better documentation.

I'm more confused now about how this is meant to be done than
I was when I started.

Device tree authors may as well just make shit up on the spot
at this point... write an entirely specific driver for their
effort, and it will still get in, and everyone will be using
that hack as an example of what is right.

That happens too often by my book.

> I don't know how did you come to these conclusions. Pretty much
> people were involved into the gpio bindings discussion.

I was watching the threads and I expected a little more than 20
lines of documentation and a couple LED drivers would come out
of it.

GPIOLIB excited me when I talked to the original author about
it, now that there has to be a device tree behind it that is
an absolutely undefined, gpio-controller-specific implementation
for every chip or even every board with significant information
hardcoded into drivers, I am considerably less enthused.

>> Yes, your idea, Mitch's discussion was great, I just don't think
>> anything will get done about it (emotional moment) as usual.
> 
> Hm. If idea looks ok, then it is matter of implementation. And
> the gpio-header case is quite easy to implement, really.

Okay. I think I am understanding this enough that I could write
a bit more comprehensive documentation for it that would
encompass the result of this discussion and some other things
going on right now...

As for implementation, since the only hardware I have here to
test is a) broken b) only has 3 GPIO pins or b) working but
such a horrid design I wouldn't use it as a doorstop, I don't
think I am really qualified to put it into action..

The premise draws from some discussions a long while ago with
users about using GPIO in Linux (before GPIOLIB happened) and
from my current work trying to get a framework for students to
do their senior design projects in mechatronics - mostly with
CPLDs but also using boards like the Efika and similar (but with
GPIO to spare) as control. We can't assume these students know
how to program the kernel so the very easiest way to define it
is in the device tree with a more generic driver, something
we could even drop sysfs/GUI tools on top. We simply can't
have them all join the clique kernel hacker society for it.

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Anton Vorontsov]

On Mon, Oct 27, 2008 at 08:11:12PM -0500, Matt Sealey wrote:
> Anton Vorontsov wrote:
>> On Mon, Oct 27, 2008 at 04:56:57PM -0500, Matt Sealey wrote:
>>>
>>> A bunch of things spring to mind:
>>>
>>> *   How do you define a GPIO bank in a device tree, not a controller
>>
>> Not a controller? What do you mean by "bank"? There is no such
>> thing. There are GPIO controllers, and _maybe_ _their_ banks of
>> GPIOs.
>
> I don't know what you want to call it, I don't know what the official
> Linux term might be for a grouped bunch of GPIO used for a peripheral.

You don't know this term because there isn't any. There is no term
for "bunch of GPIO used for a peripheral".

But there are:

- gpio controllers;
- devices that use some gpios;
- gpios = <>; property that is used to denote which gpios the device
  is using.

What's so hard about that?

>>>     but a grouping of pins which fit that pattern, of which there
>>>     may be multiple groupings for multiple peripheral functions
>>
>> Why do you need this, _exactly_? What problem this would solve? But
>> see below, this is still possible to implement.
>
> I made a pretty good example with the lcd controller, I thought..

Yes, thanks for the example. And I don't see any problems with
describing the lcd controller.

>> But I still wonder what problem exactly you're trying to solve
>> here? Prevent requesting reserved gpios? I don't see any point
>> in this, really.
>
> There's plenty of reason for it, it's totally wrong to be able
> to request a GPIO which has been multiplexed to another device
> in the SoC, and probably completely undefined behaviour if you
> start toggling a pin that's been assigned to an internal
> controller.

Then just don't specify the wrong GPIO in the gpios = <>! It is
that simple.

You don't specify the SOC's peripheral memory in the /memory node,
do you? I bet you don't. Can you? Yes. Bad things will happen? Sure.

You may bring the gpio sysfs example. But I can answer back with the
/dev/mem example. There are plenty of things you can do bad things
with, even being in the userspace.

> Since you have no way of knowing except intimate board design
> knowledge in the driver.. well, that defeats the purpose of the
> device tree in general and is a step back into hardcoded information
> in board support from arch/ppc days etc..
> 
> This information SHOULD be in the device tree specifically because
> there is one very popular chip here which has GPIO multiplexed with
> other very-often-used peripherals, and I can think of at least 5
> other chips which also have device trees and GPIO potential (4 of
> which we have designed boards around) which fit the same model and
> would have the same requirement.
>
> There are two ways you can do it; implicit and explicit. If a
> pin is not defined for a peripheral in the device tree, it is
> not requestable from GPIOLIB. Or, you make sure that you specify

This is doable and _maybe_ a good idea. Though I don't see much
value in this.

>> No problem. Define bindings for "8 GPIOs data group".
>>
>> /* 8bit Parallel I/O port using arbitrary gpios */
>> byte_pio: byte-pio {
>> 	compatible = "byte-pio";
>> 	gpios = <&controller1 0 1   /* data line 0 */
>> 		 &controller2 12 0  /* data line 1 */
>> 		 ...>;
>> };
>>
>> lcd-controller {
>> 	/* the lcd controller can simply use the pio_out_8(),
>> 	 * pio_in_8() API. The API is easily implemented. */
>> 	lcd-data-port = <&byte_pio>;
>> }
>>
>>> and 1 for data/control selection, it would be nice for the
>>> software to know which pin is which and, slightly unrelated,
>>> which way around the data pins went - MSB first or LSB first
>>> - from the device tree, as this is a BOARD LEVEL DESIGN DECISION
>>> which is what the device tree is meant to abstract - in the same
>>> way we define i2c controllers and clients?)
>
> And this? What about the other two control lines? Do they just get
> set in the gpios property of the lcd-controller? How do you determine
> which is which?

This depends on how will you write the bindings.

> Comments don't get compiled..

If you _really_ want to complicate things, you can write gpios for
devices like this:

device {
	data0-gpio = <&controller1 1 1>;
	...
	rw-gpio = <&controller1 2 1>;
}

This _will_ get compiled in. This is insane, but this is more friendly
to a device tree reader, if you like.

> and a driver will have
> to be written FROM the comments, hardcoding the pins into it, again.

What do you mean by "hardcoding"? Let's see: interrupts = <33 32>;
and then extracting them via
of_irq_to_resource(node, 0, &tx_irq),
of_irq_to_resource(node, 1, &rx_irq).

Does this mean "hard-coding"?

[...]
>>> I don't feel the current spec actually takes this into account
>>> and the patch submission the other day from Wolfgang made me
>>> think that if a "base" register is the obvious solution to some
>>> problem, then it either can't be that clear to others (i.e. it
>>> is not just me being stupid) or it is simply not possible under
>>> the current binding.
>>
>> Wolfgang's patch proved to be unnecessary, you haven't seen
>> the solution?
>
> Wolfgang's patch would never have been considered by Wolfgang
> if the solution wasn't more obvious... this is why I started
> the thread :D

Oh, device tree/correct bindings/proper ways to solve things
aren't always obvious? It's news to me. ;-)

[...]
>> I don't know how did you come to these conclusions. Pretty much
>> people were involved into the gpio bindings discussion.
>
> I was watching the threads and I expected a little more than 20
> lines of documentation and a couple LED drivers would come out
> of it.
>
> GPIOLIB excited me when I talked to the original author about
> it, now that there has to be a device tree behind it that is
> an absolutely undefined, gpio-controller-specific implementation
> for every chip

You seem to disagree with the whole device tree idea and the OF
in general. Interrupts are so controller-specific stuff that
we should reconsider using it, right?

> or even every board with significant information
> hardcoded into drivers, I am considerably less enthused.

What's so bad about board-specific drivers for board-specific
devices? If a gpio-header is board-specific, then we have to
write a board-specific driver for it. To make things better
we can write the driver in a such way that the driver could be
easily adopted/extended for similar boards/setups.

OR we can write bindings that could fully describe the gpio
header, and then just use the universal driver for it.

Both solutions are doable.

>>> Yes, your idea, Mitch's discussion was great, I just don't think
>>> anything will get done about it (emotional moment) as usual.
>>
>> Hm. If idea looks ok, then it is matter of implementation. And
>> the gpio-header case is quite easy to implement, really.
>
> Okay. I think I am understanding this enough that I could write
> a bit more comprehensive documentation for it that would
> encompass the result of this discussion and some other things
> going on right now...
>
> As for implementation, since the only hardware I have here to
> test is a) broken b) only has 3 GPIO pins or b) working but
> such a horrid design I wouldn't use it as a doorstop, I don't
> think I am really qualified to put it into action..

Yeah, there are always excuses when it comes to send patches... ;-)

-- 
Anton Vorontsov
email: cbouatmailru@gmail.com
irc://irc.freenode.net/bd2

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Anton Vorontsov wrote:
> On Mon, Oct 27, 2008 at 08:11:12PM -0500, Matt Sealey wrote:
>> Anton Vorontsov wrote:
>>> On Mon, Oct 27, 2008 at 04:56:57PM -0500, Matt Sealey wrote:
>>>> A bunch of things spring to mind:
>>>>
>>>> *   How do you define a GPIO bank in a device tree, not a controller
>>> Not a controller? What do you mean by "bank"? There is no such
>>> thing. There are GPIO controllers, and _maybe_ _their_ banks of
>>> GPIOs.
>> I don't know what you want to call it, I don't know what the official
>> Linux term might be for a grouped bunch of GPIO used for a peripheral.
> 
> You don't know this term because there isn't any. There is no term
> for "bunch of GPIO used for a peripheral".

There should be so we didn't have that conversation just now about
what a "bank" is supposed to mean :)

> But there are:
> 
> - gpio controllers;
> - devices that use some gpios;
> - gpios = <>; property that is used to denote which gpios the device
>   is using.
> 
> What's so hard about that?

*shrug*

> You don't specify the SOC's peripheral memory in the /memory node,
> do you? I bet you don't. Can you? Yes. Bad things will happen? Sure.

You could put SRAM in there and that wouldn't cause any problems. I
don't figure why SRAM is treated differently except that it would
be unlikely and unfortunate for Linux to use it as a generic pool of
RAM. There was a big discussion about whether the device_type should
be "memory" or "sram"... I personally prefer the latter.

>> Comments don't get compiled..
> 
> If you _really_ want to complicate things, you can write gpios for
> devices like this:
> 
> device {
> 	data0-gpio = <&controller1 1 1>;
> 	...
> 	rw-gpio = <&controller1 2 1>;
> }
> 
> This _will_ get compiled in. This is insane, but this is more friendly
> to a device tree reader, if you like.

Is it still possible to perhaps create a node under lcd-controller which
describes the pin groupings? Maybe we should call it a gpio-group.

That way lcd-controller looks like

lcd-controller {
	compatible = "crystalfontz,something-gpio";
	data-bus {
		compatible - "gpio-group";
		gpios = <gpioc 1 gpioc 8 gpioc 42 ... >
	}
	rw-ctrl {
		compatible = "gpio-group";
		gpios = <gpioc 2>
	}
	cmd-ctrl {
		...
	}
};

At least a driver for a particular lcd display geared for GPIO
output can then simply check the device tree for some known
compatibles. With a user header this is not required, just list
out the GPIOs ready for use. With a device where the function is
literally too obvious (it has 8 pins on an 8-bit data bus so how
hard can it be, and the order would be implicit in the gpios
property?) it is also kind of useless.

I definitely think that while possibly overly verbose for some
or even most functionality it would come in handy. The driver
would be able to detect which pins are for which purpose, rather
than what could be a very generic driver for multiple bus types
and platforms being hardcoded to work only on a specific board
(imagine 10 boards with the same LCD controller, all having a
list of which GPIO pins are which, when they are configured ever
so slightly differently).

>> and a driver will have
>> to be written FROM the comments, hardcoding the pins into it, again.
> 
> What do you mean by "hardcoding"? Let's see: interrupts = <33 32>;
> and then extracting them via
> of_irq_to_resource(node, 0, &tx_irq),
> of_irq_to_resource(node, 1, &rx_irq).
> 
> Does this mean "hard-coding"?

No. If you have an array of GPIO pins (gpios property) then how do you
determine which is for data and which is some control pin? Do you
associate these numbers in the driver somehow? Maybe a matchlist or
an array? Given pins A B C D E F G H I J where does the data bus
start and the control pins live? A and B? A and J? I and J?

It would be definitely frivolous to define a whole device tree binding
for the *order in which you MUST specify the gpios for this particular
device*. There is obviously an implicit ordering of the GPIOs to make
up the data bus (you'd expect an order from MSB to LSB.. or perhaps
LSB to MSB... that might be better defined than undefined)

>> GPIOLIB excited me when I talked to the original author about
>> it, now that there has to be a device tree behind it that is
>> an absolutely undefined, gpio-controller-specific implementation
>> for every chip
> 
> You seem to disagree with the whole device tree idea and the OF
> in general.

Actually I love Open Firmware, if I had a nickel for every time I had
nagged the guys at bplan to port it to one of these Freescale dev
boards so I didn't have to crawl through U-Boot every time I booted,
I would be able to fund the port myself.

The device tree, I guess I am a die-hard. I don't think shoehorning
a device tree into U-Boot is a great idea (I don't see why you can't
have a real OF!) and if Firmworks can port OF to OLPC and have it be
a success, what on earth is the point of U-Boot?

I love being able to "boot" anything that is bootable, and not have
to use a specific filesystem load command (ext2load, tftp etc.)
because the information and software to decode that booting process
is contained in the device tree and client interface, and not some
esoteric script command. I love the abstraction and the OPPORTUNITY
for abstraction and not just description.

What I don't so much agree with is the arbitrary definitions we had
to deal with when we made the Efika. The MPC5200B binding was in
flux (and for a chip Freescale do not encourage for new designs, the
device tree is still moving around. In 5 years nobody fixed it down?)
and we had arguments over "memory" or "sram" and stupid things like
"the node with all the SoC peripherals in *MUST* be device_type "soc"
and have name "soc"!!!! (we call it "builtin", it's compatible
property has always been "mpc5200b" though, so how can you have a problem
detecting that?)

 > Interrupts are so controller-specific stuff that
> we should reconsider using it, right?

No, because while controller specific, interrupt controllers have
well-defined layouts with interrupt-parent, cascading and the
connection of certain pins to certain interrupt hosts (PCI INTA,
B, C, D) is all explicit in the device tree. If you have an MPC5200B
interrupt in a device tree node, you know the 3 numbers are
encoded as TYPE NUMBER LEVEL (type being critital, main or
peripheral or "bestcomm", number being encoded as an offset into
a register, and the level being 0-3 for edge, blah blah) because
the bindings say so. But when you allocate an IRQ using the device
tree as input, you do not even need to know what these things mean,
just hope that someone used the right one in the device tree. The
binding does not affect the driver, it actually works to make the
driver MUCH simpler here, and far more generic and maintainable
and promotes shared code.

GPIO does not have this explicit layout option, only a randomly
ordered list of gpios which are hooked to a device which do not
have any "purpose" assigned to them. Rather than specific ways
to define a GPIO data it's not specific. So one device may encode
the purpose of the pin as a flag. These flags change per-chip.
And at the end of the day if you go down that route you risk
being clobbered by a new standard which defines a new flag right
over the one you wanted to use for your "this is a data pin and
this is a control pin" flag.

While I see a device binding that says that the encoding of the
gpios field and the gpio-cells is arbitrary per controller and
if flags are specified, these flags are controller-specific, I
do not see any definition of what they are for a SPECIFIC
CONTROLLER. What do I use for flags with the MPC5200B? Which
ones are spare? :D

>> or even every board with significant information
>> hardcoded into drivers, I am considerably less enthused.
> 
> What's so bad about board-specific drivers for board-specific
> devices?

I doubt you will only see one LCD controller kind on one board
any time soon.

That LCD controller may be able to be driven over a couple of
methods - be that one bus or another or a GPIO method, in the
same way you can use MII or a 7-wire ethernet controller on
the same chip. 99.9% of the driver is the same except the
abstraction to how it communicates with the PHY.

Without some purposeful definition in the device tree, the
layout of the gpios property has to be defined, maintained
and extracted by the driver using intimate knowledge of the
board, extracted from a comment or a document, possibly
extended from the one for the controller if you need "more
flags".

Let's be honest, using the flags field in "gpios" is not
very human readable, and if we're using device tree examples
as documentation, this just makes it harder on the developer
as well as a user browsing the device tree on their device.

> If a gpio-header is board-specific, then we have to
> write a board-specific driver for it. To make things better
> we can write the driver in a such way that the driver could be
> easily adopted/extended for similar boards/setups.

Indeed.

> OR we can write bindings that could fully describe the gpio
> header, and then just use the universal driver for it.

Sure. This is what I mean.

> Both solutions are doable.
> 
>> Okay. I think I am understanding this enough that I could write
>> a bit more comprehensive documentation for it that would
>> encompass the result of this discussion and some other things
>> going on right now...
>>
>> As for implementation, since the only hardware I have here to
>> test is a) broken b) only has 3 GPIO pins or b) working but
>> such a horrid design I wouldn't use it as a doorstop, I don't
>> think I am really qualified to put it into action..
> 
> Yeah, there are always excuses when it comes to send patches... ;-)

That and I am busy, yes. I need to document it first though.

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Grant Likely]

On Tue, Oct 28, 2008 at 10:53 AM, Matt Sealey <matt@genesi-usa.com> wrote:
> Is it still possible to perhaps create a node under lcd-controller which
> describes the pin groupings? Maybe we should call it a gpio-group.
>
> That way lcd-controller looks like
>
> lcd-controller {
>        compatible = "crystalfontz,something-gpio";
>        data-bus {
>                compatible - "gpio-group";
>                gpios = <gpioc 1 gpioc 8 gpioc 42 ... >
>        }
>        rw-ctrl {
>                compatible = "gpio-group";
>                gpios = <gpioc 2>
>        }

At this level, the 'compatible = "gpio-group";' is completely
irrelevant.  The binding for "crystalfontz,something-gpio" must
specify that there are two subnodes; one named data-bus and one named
rw-ctrl.  The driver, which binds against compatible in the parent
node, would know to go looking for those child nodes and to use the
gpios property inside them.  Simple.

>> Does this mean "hard-coding"?
>
> No. If you have an array of GPIO pins (gpios property) then how do you
> determine which is for data and which is some control pin? Do you
> associate these numbers in the driver somehow? Maybe a matchlist or
> an array? Given pins A B C D E F G H I J where does the data bus
> start and the control pins live? A and B? A and J? I and J?

You know because you document it in the binding.

> It would be definitely frivolous to define a whole device tree binding
> for the *order in which you MUST specify the gpios for this particular
> device*. There is obviously an implicit ordering of the GPIOs to make
> up the data bus (you'd expect an order from MSB to LSB.. or perhaps
> LSB to MSB... that might be better defined than undefined)

Why is it frivolous?  We do this all the time for reg and irqs.

g.

-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Grant Likely wrote:

> At this level, the 'compatible = "gpio-group";' is completely
> irrelevant.  The binding for "crystalfontz,something-gpio" must
> specify that there are two subnodes; one named data-bus and one named
> rw-ctrl.  The driver, which binds against compatible in the parent
> node, would know to go looking for those child nodes and to use the
> gpios property inside them.  Simple.

Point taken.

>>> Does this mean "hard-coding"?
>> No. If you have an array of GPIO pins (gpios property) then how do you
>> determine which is for data and which is some control pin? Do you
>> associate these numbers in the driver somehow? Maybe a matchlist or
>> an array? Given pins A B C D E F G H I J where does the data bus
>> start and the control pins live? A and B? A and J? I and J?
> 
> You know because you document it in the binding.

I think having a working device tree and a seperate binding document
sometimes slows things down. If it is not patently obvious what you
mean from a device tree, in order to write a new driver, the device
tree is not doing it's job..

Where the binding must take it's cue from established documentation,
and follows existing procedures and semantics, the binding is important
(for instance there are a few ways to check an interrupt fired on
MPC5200B, and Linux/dts encodes them per ONE table in the docs, this
must be referenced somewhere at least)

>> It would be definitely frivolous to define a whole device tree binding
>> for the *order in which you MUST specify the gpios for this particular
>> device*. There is obviously an implicit ordering of the GPIOs to make
>> up the data bus (you'd expect an order from MSB to LSB.. or perhaps
>> LSB to MSB... that might be better defined than undefined)
> 
> Why is it frivolous?  We do this all the time for reg and irqs.

See above. Does every driver require a ratified device tree binding
which is collaborated and agreed upon even though it may be in use on
one or two boards which actually may never see the light of day (I
bet none of you will ever see the CPLD core I'm sitting in front of
right now..)

I think it should be obvious both from the tree and inside the driver
what magical little sections of code do without cross-referencing, I
do far too much cross-referencing in Linux as it is, and it's one thing
I'm a little sore to see keep reoccurring, that I have to have 3 windows
open to understand the intent of a 10 line snippet in a driver..

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[David Gibson]

On Mon, Oct 27, 2008 at 10:40:12AM -0500, Matt Sealey wrote:
>
>
> David Gibson wrote:
>
>> Um.. I can't actually follow what you're getting at there, sorry.
>
> Imagine in your head that you have a GPIO controller that has a
> 32-bit register potentially controlling 32 pins on the chip.
>
> Imagine that rather than being able to allocate 6 GPIO pins
> *right next to each other* in the register and saying that
> you start at "pin" 15 and use the next 6 "pins", you have to
> spread it around and use pin 1, pin 8, pin 9, pin 11, pin 15,
> pin 30, to make up this peripheral.
>
> As far as I can tell there is no way at all to specify a set of
> GPIO pins which are NOT consecutive because the current GPIO
> spec stops after specifying a controller bank (the 32-bit
> register).

Uh.. no.  The gpio specifier has a format that's gpio controller
specific, but it must include the actual pin number, although exactly
how it's encoded might vary.

So, you use
	gpios = <&controller pin1-specifier &controller pin8-specifier
		 &controller pin9-specifier &controller pin11-specifier
		 &controller pin15-specifier &controller pin30-specifier>;

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

David Gibson wrote:
> On Mon, Oct 27, 2008 at 10:40:12AM -0500, Matt Sealey wrote:
> 
> Uh.. no.  The gpio specifier has a format that's gpio controller
> specific, but it must include the actual pin number, although exactly
> how it's encoded might vary.
> 
> So, you use
> 	gpios = <&controller pin1-specifier &controller pin8-specifier
> 		 &controller pin9-specifier &controller pin11-specifier
> 		 &controller pin15-specifier &controller pin30-specifier>;

Okay that makes some more sense to me.

So now my qualm is back to the beginning of the discussion. How do
we encode the purpose of those pins reliably and within some
standard framework, without getting *driver* specific?

Take the example of an LCD controller with an 8-bit bus and two
control pins, if you put all 10 into a gpios property, explicit
knowledge of the purpose of those pins is lost. It must then be
encoded directly into the driver..

I liked Anton's suggestion of grouping them and creating new nodes,
but you didn't like it when it was suggested before, so, I'm
wondering if there's a middle ground..

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[David Gibson]

On Mon, Oct 27, 2008 at 07:51:23PM -0500, Matt Sealey wrote:
>
>
> David Gibson wrote:
>> On Mon, Oct 27, 2008 at 10:40:12AM -0500, Matt Sealey wrote:
>>
>> Uh.. no.  The gpio specifier has a format that's gpio controller
>> specific, but it must include the actual pin number, although exactly
>> how it's encoded might vary.
>>
>> So, you use
>> 	gpios = <&controller pin1-specifier &controller pin8-specifier
>> 		 &controller pin9-specifier &controller pin11-specifier
>> 		 &controller pin15-specifier &controller pin30-specifier>;
>
> Okay that makes some more sense to me.
>
> So now my qualm is back to the beginning of the discussion. How do
> we encode the purpose of those pins reliably and within some
> standard framework, without getting *driver* specific?

Um.. I fail to see how the purpose of a pin can be not driver
specific.

> Take the example of an LCD controller with an 8-bit bus and two
> control pins, if you put all 10 into a gpios property, explicit
> knowledge of the purpose of those pins is lost. It must then be
> encoded directly into the driver..

Yes, this is normal.  Just as the driver for a device must know the
function of each entry in 'reg' for its specific device, and what each
interrupt in 'interrupts' is used for.

> I liked Anton's suggestion of grouping them and creating new nodes,
> but you didn't like it when it was suggested before, so, I'm
> wondering if there's a middle ground..

I have no problem with the suggestion of gpio_header nodes, if that's
what you're referring to (although I do suspect occasions on which
they are useful would be limited).

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

Re: GPIO - marking individual pins (not) available in device tree

[Grant Likely]

On Mon, Oct 27, 2008 at 6:51 PM, Matt Sealey <matt@genesi-usa.com> wrote:
>
>
> David Gibson wrote:
>>
>> On Mon, Oct 27, 2008 at 10:40:12AM -0500, Matt Sealey wrote:
>>
>> So, you use
>>        gpios = <&controller pin1-specifier &controller pin8-specifier
>>                 &controller pin9-specifier &controller pin11-specifier
>>                 &controller pin15-specifier &controller pin30-specifier>;
>
> Okay that makes some more sense to me.
>
> So now my qualm is back to the beginning of the discussion. How do
> we encode the purpose of those pins reliably and within some
> standard framework, without getting *driver* specific?
>
> Take the example of an LCD controller with an 8-bit bus and two
> control pins, if you put all 10 into a gpios property, explicit
> knowledge of the purpose of those pins is lost. It must then be
> encoded directly into the driver..

I disagree.  With the approach we've been following the meaning of
those 10 gpio pins is not lost because we make a point of documenting
it (granted in the Linux kernel tree at the moment which is far from
ideal).  The knowledge of what those GPIOs are for is all bound up
with the documented binding attached to the compatible value.

> I liked Anton's suggestion of grouping them and creating new nodes,
> but you didn't like it when it was suggested before, so, I'm
> wondering if there's a middle ground..

I've got no problem with this myself, but I don't think it really adds
much in terms of additional information because users still need to
refer to binding documentation to figure out what it actually means.

g.

-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Mitch Bradley wrote:

>>         gpio_pin@2 {
> 
> The name here should reflect the purpose of the pin, i.e. what it does 
> (perhaps "NAME,magic"), not the fact that is is GPIO pin.  By analogy, 
> an ethernet controller's node name is "ethernet", not "pci-card".  The 
> fact that the node represents one or more gpio pins is implicit and 
> obvious - all children of a gpio-controller node are gpio pin(s).  All 
> children of a scsi node are SCSI devices, ad nauseum.

Right. I had a similar discussion about this the other day with Anton (I
think he forwarded it here but I wasn't subscribed at that point..). The
current ideology for device trees is to get rid of device_type for new
trees that aren't OF-based. I think it's relevant to give nodes fancy
names (i.e. not "timer" or even "ethernet") since the name property is
entirely descriptive in nature. I also think it's relevant that device_type
still exists because since the name is totally irrelevant except from a
user-friendliness point of view, marking a device as a generic type is
quite important (device_type = serial, ethernet, rtc, keyboard) where
compatible properties are usually wildly over-specific.

This reminded me of a discussion I had a long time back that encoding
the manufacturer and chip name into EVERY child node was bordering on
the insane (and if the dt wasn't compressed in the first place, wasting
space) - if you have /soc/usb and they have compatible="fsl,mpc5200b"
and "fsl,mpc5200b-usb-ohci" respectively, isn't that encoding redundant
information? Someone I think proposed assigning a couple of quirk
properties to notify drivers that fsl,mpc5200b-usb-ohci did things
differently because of the chip revision, and I was shot down when I
asked if the driver could just check it's parent node instead.

Apparently current ideology there is to have every node self-contained
(however the current practise in the Linux kernel, for example with
some PCI quirks, is to search for the parent PCI southbridge and check
off some values or disable features there, which I don't think is that
much different..)

Anyway back to the actual discussion, yes, I should have given it a
much fancier name than "gpio_pin" but at the time I wasn't thinking of
any particular use and didn't want to confuse by giving it a fancy
name like "sleep-controller-wakeup-pin".

> It has been my experience that full explicit descriptions are usually a 
> win in the long run.  (Which is not to say that I've always done the 
> right thing, but when I have it has often been worthwhile.)

In my view, having an overly descriptive and unwieldy device tree is
only bad when you type "ls" on the forth prompt and it scrolls off
the screen 8 times. At the driver level

One thing I had a crazy dream about was a GUI-based device tree builder
for platforms. Instead of editing them manually and passing them
through the compiler, wouldn't it be fun to drag and drop system
components (and build new ones) into something like a DirectX Filter
Graph Builder (or the GStreamer one for that matter) or those GUI
SQL database builders, so that you could build a tree and have it
output all the craziness and connect phandles to range properties
etc.

That way dropping a bunch of pins on a GPIO bank, or i2c devices
on an i2c bus (I have a board here with an i2c bus with 8 devices
on it, I suppose you could have more than 100 if you got your
addresses right) and having a device tree that goes on for 8
screens would not be so bad to maintain.

And no, I did NOT just volunteer to write one, I'm happy coding my
device tree updates in Forth :)

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

RE: GPIO - marking individual pins (not) available in device tree

[Stephen Neuendorffer]

> One thing I had a crazy dream about was a GUI-based device tree
builder
> for platforms. Instead of editing them manually and passing them
> through the compiler, wouldn't it be fun to drag and drop system
> components (and build new ones) into something like a DirectX Filter
> Graph Builder (or the GStreamer one for that matter) or those GUI
> SQL database builders, so that you could build a tree and have it
> output all the craziness and connect phandles to range properties
> etc.
> =

> That way dropping a bunch of pins on a GPIO bank, or i2c devices
> on an i2c bus (I have a board here with an i2c bus with 8 devices
> on it, I suppose you could have more than 100 if you got your
> addresses right) and having a device tree that goes on for 8
> screens would not be so bad to maintain.
> =

> And no, I did NOT just volunteer to write one, I'm happy coding my
> device tree updates in Forth :)
> =

> --
> Matt Sealey <matt@genesi-usa.com>
> Genesi, Manager, Developer Relations

Why is this crazy?  This is essentially what we do today with PowerPC
and Microblaze processors in Xilinx FPGAs.  Even for ASIC SOCs, there
are several commercial 'connect-your-IP on the bus' tools that could (if
SOC providers thought it was important) generate the 'canonical' device
tree automagically.

I think the real question is: if part of the device tree describes
'hardware' (either in the SOC or on the board that, more or less,
doesn't change) and part represents 'hardware configuration' (e.g. My
board has my one-off hardware hanging off the gpio bank connected to the
40 pin header), then how do we separate the two so that the hardware can
be in a canonical form separate from the configuration.  Or perhaps
there are even three device tree fragments: one provided by an SOC
provider, one by a board provider, and one by the user, which can all be
nicely separated once the great device tree update happens... :)

Steve


This email and any attachments are intended for the sole use of the named r=
ecipient(s) and contain(s) confidential information that may be proprietary=
, privileged or copyrighted under applicable law. If you are not the intend=
ed recipient, do not read, copy, or forward this email message or any attac=
hments. Delete this email message and any attachments immediately.

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Stephen Neuendorffer wrote:
>> One thing I had a crazy dream about was a GUI-based device tree
>> builder for platforms.
> 
> Why is this crazy?  This is essentially what we do today with PowerPC
> and Microblaze processors in Xilinx FPGAs.  Even for ASIC SOCs, there
> are several commercial 'connect-your-IP on the bus' tools that could (if
> SOC providers thought it was important) generate the 'canonical' device
> tree automagically.

Indeed I have to sit in front of Quartus all day at the moment and the
BDF window, pin planner etc. and the constraints scripts for the megacores
just seemed to me to be a great way to spit out a device tree without
doing any real work.

> I think the real question is: if part of the device tree describes
> 'hardware' (either in the SOC or on the board that, more or less,
> doesn't change) and part represents 'hardware configuration' (e.g. My
> board has my one-off hardware hanging off the gpio bank connected to the
> 40 pin header), then how do we separate the two so that the hardware can
> be in a canonical form separate from the configuration.

Personally, I think that goes against the whole point of the device
tree specification anyway. Or at least the greatest benefit - which is
to allow hardware designers to present to software developers a
reasonable description of what can and usually is an esoteric design
decision (which port goes where and what undetectable hardware is
used for X and Y) without exposing the software developer to the
programming model of each individual device (contrast any other system
where you might have a huge list of registers and positions, and use
a rom monitor to manually poke at certain registers, and need the
board schematics to get anywhere you can't read a chip name off the
board to use)

The definition of the binding defines what every peripheral should
look like if it's present - if the peripheral is multiplexed inside
the chip, then you can just copy-paste one feature and not use the
other. A difference in PHY for something is one thing you just can't
detect sometimes; on different boards, this will be different, but
it is all part of the hardware configuration, and not much to do with
the hardware itself (if you have 12 serial controllers but USB and
ethernet usage means you lose 5 of them to multiplexing, or a SerDes
shared between PCI Express, SATA or RapidIO but only one can be
active.. or a configurable clock module for internal devices which
would have the same quirks as an interrupt controller.. or even an
interrupt controller configured to cascade or slaved to something
else)

> there are even three device tree fragments: one provided by an SOC
> provider, one by a board provider, and one by the user, which can all be
> nicely separated once the great device tree update happens... :)

If you have an SoC provider device tree fragment does it entertain
every possibility in the chip, or just the most common? Does the
board provider dt fragment then allow "disable" certain features in
the previous fragments? See examples above where defining 12 serial ports
on the SoC dts AND usb and ethernet functionality, just can't work,
and the board configuration of these devices is entirely relevant.

Updating a device tree at the user end is very useful but I do not
think that there is any fundamental difference between the hardware
itself and the board configuration from a DT point of view, except
that you need a binding or an example (but not a canonical device
tree excerpt) to base your final tree from. What is inside the SoC
rarely matches what is escaped from the chip, so a premade
fragment you could just load becomes rather redundant. Just a
useful reference would be better and that's what we have already.

As for user fragments we have that on OpenFirmware already* and
the idea that we may actually standardize on this kind of stuff
sort of excites me as it validates the point to remove all the
device tree fixups from Pegasos and Efika in prom_init.c and use
something a little less of the order of "you have to recompile
your kernel every time". Be it a dtb fragment for U-Boot or a
Forth script for real OF, this is such a great idea, I don't
know why it's not already there :)

* http://www.powerdeveloper.org/platforms/efika/devicetree

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Mitch Bradley]

> Right. I had a similar discussion about this the other day with Anton (I
> think he forwarded it here but I wasn't subscribed at that point..). The
> current ideology for device trees is to get rid of device_type for new
> trees that aren't OF-based. I think it's relevant to give nodes fancy
> names (i.e. not "timer" or even "ethernet") since the name property is
> entirely descriptive in nature. I also think it's relevant that 
> device_type
> still exists because since the name is totally irrelevant except from a
> user-friendliness point of view, marking a device as a generic type is
> quite important (device_type = serial, ethernet, rtc, keyboard) where
> compatible properties are usually wildly over-specific.

I don't use device_type much, if at all, anymore.  Generic name + compatible
just works better than device_type + specific name.  When I write code that
has to find a node that is suitable for a given purpose, I look for the 
existence
of suitable methods and perhaps other properties.  I was just too hard to
keep the list of device_type values properly synchronized with all the 
possible
things that you might want to infer from that set of names.

device_type is one of those things that seemed like a good idea at the time,
but didn't work out as well as I had hoped.

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Mitch Bradley wrote:
> 
> I don't use device_type much, if at all, anymore.  Generic name + 
> compatible just works better than device_type + specific name.  When
 > I write code that has to find a node that is suitable for a given purpose,
 > I look for the existence of suitable methods and perhaps other properties.
 > I was just too hard to keep the list of device_type values properly
 > synchronized with all the possible things that you might want to infer
 > from that set of names.

The simple problem comes when you define a device_type for everything,
I do agree it's best not to add any *MORE* that aren't in the IEEE1275
or CHRP etc. bindings, but for those that still exist and are well
defined (serial port probably the best, but network devices too) I
think we should keep using them where possible and where relevant.

> device_type is one of those things that seemed like a good idea at the 
> time, but didn't work out as well as I had hoped.

I can imagine a scenario where you would want to perhaps have a serial
port, where you want to say a) that is is a serial port, b) that it is
for a specific purpose without creating some new standard or proprietary
property set and c) tell the world what kind of serial port it is.

How about name = "debug" or "modem" or something else, which gives you
a pretty name for what the port is for (and maybe matches the markings
on the outside of a case) but the device_type would always be "serial",
and compatible would give you "mpc5200b-psc-uart" or so. You can find
all the serial ports, you can find the serial port that is assigned to
the modem or debug (this may actually allow the driver to be informed
not to do anything crazy - if you've ever connected a modem to a port
that gets set up to output firmware debug data or whatever, you'll know
sometimes it's kind of difficult to bring the modem back out of it's
funk from being hammered with data for the duration of boot), and you
know which driver to attach to it.

I personally think while deprecate and shouldn't be used for new
definitions, the old ones work really well for devices it encompasses.
On the MPC8641D board I have here there are 4 network ports; in the
device tree they're all called ethernet, device_type "network",
compatible "gianfar" and have a model "TSEC" - in a real OF
implementation you shouldn't have to check for a "ping" method to
make sure it's ACTUALLY a network device :D

(I'd advocate all those ports being renamed to eTSEC{n} since that
matches the board documentation, for example, and while cell-index
tells you which port is is on the back of the board, this is not
user friendly (a simple "boot eTSEC0 tftpboot/kernel" is more
intuitive than cd /boot/ethernet@24000, .properties, backing out
if it wasn't the one you were looking for.. or assuming that the
lowest numbered "reg" is the first port on the back of the chassis
and finding out that is not how it's connected :)

I'm really big on descriptive device trees that I can just browse
and know what I am looking at without delving. There is already
too much needless cross-referencing in Linux as it is.

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[David Gibson]

On Sun, Oct 26, 2008 at 04:13:26PM -0500, Matt Sealey wrote:
>
>
> Mitch Bradley wrote:
>>
>> I don't use device_type much, if at all, anymore.  Generic name +  
>> compatible just works better than device_type + specific name.  When
> > I write code that has to find a node that is suitable for a given purpose,
> > I look for the existence of suitable methods and perhaps other properties.
> > I was just too hard to keep the list of device_type values properly
> > synchronized with all the possible things that you might want to infer
> > from that set of names.
>
> The simple problem comes when you define a device_type for everything,
> I do agree it's best not to add any *MORE* that aren't in the IEEE1275
> or CHRP etc. bindings, but for those that still exist and are well
> defined (serial port probably the best, but network devices too) I
> think we should keep using them where possible and where relevant.

device_type in 1275 defines the runtime method interface.  It's *not*
for declaring the general class of the device, although it often
matches that in practice.  Drivers which attempt to use it this way
are buggy.

So, in the  case of a real OF implementation,  yes, you should include
device_type values as specified by 1275.  Assuming of course that your
implementation  really  does  implement  the OF  method  binding  that
matches the stated device_type.  However, flattened trees clearly
can't provide the method interface, and so shouldn't declare the
device_type.

In practice, we do suggest including device_type in certain, limited,
circumstances precisely because there are a whole bunch of buggy
drivers out there which match (at least partly) on device_type.  We
don't want to break these gratuitously, but neither do we want to
encourage any further spread of using device_type incorrectly for
driver matching.  Hence the current policy.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

David Gibson wrote:
> On Sun, Oct 26, 2008 at 04:13:26PM -0500, Matt Sealey wrote:
>>
>> Mitch Bradley wrote:
> 
> device_type in 1275 defines the runtime method interface.  It's *not*
> for declaring the general class of the device, although it often
> matches that in practice.

It *is* for declaring the general class of the device, even if it's
purpose is to make it known that it implements all the required
methods and therefore acts in a certain predefined way when those
methods are used; it's not a necessary property but it is a USEFUL
property:

~~
It is not necessary for every node to have a “device_type” property. If a
particular device is not useful for any Open Firmware function (e.g., booting,
console, probing) then it need not have a device type. For example, Open
Firmware has no use for a FAX modem, so such a device does not need a device
type. However, there is no restriction preventing it from having a device type
so long as its device type is not the same as one of the standard types
(i.e., a device should not claim to be something that it is not).
~~

I'm all for it being legacy and optional but marking ethernet ports as
network, and serial ports as serial, is a wonderfully good idea especially
if they were used in ANY firmware environment to bring up the console,
drag in the boot files, or provide a framebuffer display.

It's quite possible that a generic framebuffer driver be written that
only needs to know that it is a "display", read a property to find out
where the memory starts, and gain some rudimentary information about
the dimensions. Oh, wait, it already exists, it's offb.c (if you strip
out the ATI hacks, it'll work on *a n y* framebuffer that is defined
as such, and needn't have any specific compatible to do it)

> Drivers which attempt to use it this way are buggy.

I'm more concerned about code that lives specifically outside of the
driver itself - examples;

http://www.mail-archive.com/linuxppc-dev@ozlabs.org/msg11772.html
http://www.mail-archive.com/linuxppc-dev@ozlabs.org/msg11773.html

When you're about to take control of the system and do your board
setup, it is usually a great idea to use what the firmware was
using, you do not want to go through and find out that you were
using a serial console but Linux has inited a display and expects
a keyboard on a framebuffer console, because that is what "most
people get" when they boot Linux.

(I will concede that using "serial" as the VGA textmode console
is, while a semi-accurate abstraction of an ANSI-capable terminal
with no framebuffer, is kind of braindead when it comes to giving
the OS accurate information about which devices are in use)

> matches the stated device_type.  However, flattened trees clearly
> can't provide the method interface, and so shouldn't declare the
> device_type.

Even if they are used in the firmware environment for console, booting
or probing? :D

> In practice, we do suggest including device_type in certain, limited,
> circumstances precisely because there are a whole bunch of buggy
> drivers out there which match (at least partly) on device_type.
 > We don't want to break these gratuitously,

Oh that's rich. If you were that concerned you'd rip the device_type
out and fix all the drivers in a huge patch, like everyone else does
when they change the ABI.

> driver matching.  Hence the current policy.

I might say that the policy on device trees has changed by the month
for the last 2 years and ePAPR didn't fix down a single concern that
wasn't already documented in the original IEEE 1275 specification.

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Scott Wood]

Matt Sealey wrote:
> I'm all for it being legacy and optional but marking ethernet ports as
> network, and serial ports as serial, is a wonderfully good idea especially
> if they were used in ANY firmware environment to bring up the console,
> drag in the boot files, or provide a framebuffer display.

Nobody is saying that device_type should not be used in real OF when an 
appropriate method interface exists.  What we're saying is that flat 
device trees, which are incapable of providing a method interface, 
should not lie and claim that they have one.

As for "ANY firmware environment", I'd suggest that any new method 
interfaces, where backwards compatibility isn't an issue, use some 
relevant compatible rather than device_type, so that multiple supported 
interfaces can be listed.  What do you have against vendor namespaces 
(don't make the device binding guess which firmware type it's on) and 
multiple interfaces per node?

>> matches the stated device_type.  However, flattened trees clearly
>> can't provide the method interface, and so shouldn't declare the
>> device_type.
> 
> Even if they are used in the firmware environment for console, booting
> or probing? :D

Define "they", "used", and "firmware environment".  Obviously u-boot may 
use the serial port for its console, but there's no method interface 
defined by the device tree, nor is there any firmware resident at all 
after starting the kernel.

>> In practice, we do suggest including device_type in certain, limited,
>> circumstances precisely because there are a whole bunch of buggy
>> drivers out there which match (at least partly) on device_type.
>  > We don't want to break these gratuitously,
> 
> Oh that's rich. If you were that concerned you'd rip the device_type
> out and fix all the drivers in a huge patch, like everyone else does
> when they change the ABI.

This isn't internal ABI, it's an external interface with firmware.

>> driver matching.  Hence the current policy.
> 
> I might say that the policy on device trees has changed by the month
> for the last 2 years and ePAPR didn't fix down a single concern that
> wasn't already documented in the original IEEE 1275 specification.

It fixes three primary concerns:

1. The 1275 documentation is scattered in many places, some of which are 
not easily accessible to the general public (just look at the i2c mess).

2. 1275 did not appear to be actively maintained and updated.

3. It standardized the flattened device tree interface, which did not 
exist in 1275.

-Scott

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Scott Wood wrote:
> Matt Sealey wrote:
> 
> Nobody is saying that device_type should not be used in real OF when an 
> appropriate method interface exists.  What we're saying is that flat 
> device trees, which are incapable of providing a method interface, 
> should not lie and claim that they have one.
> 
> As for "ANY firmware environment", I'd suggest that any new method 
> interfaces, where backwards compatibility isn't an issue, use some 
> relevant compatible rather than device_type, so that multiple supported 
> interfaces can be listed.  What do you have against vendor namespaces 
> (don't make the device binding guess which firmware type it's on) and 
> multiple interfaces per node?

I say ANY firmware environment because at the end of the day what methods
the OF implements, or even if the firmware (like a U-Boot modification)
"lies" about it being device_type serial or device_type network, Linux
completely f**ks over the client interface at the first opportunity it
gets and does not call ANY appreciable method anyway.

So, it is not a lie to say it's a certain device_type, and I really
do focus here on the between-the-lines reading of the OF spec where
devices which ARE useful for booting, console and probing (for instance
marking detected disks as "block", ethernet as "network", serial
consoles as "serial" and displays and keyboards are present in the
tree if they are present on the machine) is more relevant here than
the Open Firmware client interface methods which Linux is steadfastly
resolved never to use anyway.

Other operating systems might be a little less pleased about the lack
of methods but we've been pushing them to ignore the CI for a long,
long time as it causes way too many problems with differences in MMU
mapping (even in virtual-mode) when booting the system, to try and
access a disk through the client interface or use a polled ethernet
driver which has to go through an egregious context switch to load
significant amounts of data.

So let's just take the basic premise of the device_type and not the
literal truth of it (hey, the world wasn't created in 7 days
after all, who'd have thunk?) and use it to the advantage of the
Linux kernel instead of ditching it as legacy.

> Define "they", "used", and "firmware environment".  Obviously u-boot may 
> use the serial port for its console, but there's no method interface 
> defined by the device tree, nor is there any firmware resident at all 
> after starting the kernel.

However it is a serial port, and when it boots it says "input: serial"
and "output: serial" - or it could be netconsole or so. Or even screen
and keyboard! These are put into /chosen/stdin and /chosen/stdout when
the system is booted with the device tree.

Should a platform be extremely specific and check compatible properties
for every kind of serial port it could ever support (including PCI, ISA/LPC,
and otherwise connected GPIO implementations or crazy designs) just so
that it can carry over the firmware choices reported in the device tree
to the booting system, or should it simply be looking for those generic
device classes?

A simple way to check what is in use and what basic sort of peripheral it
is, without knowing the ultimate specifics of the device (since you would
not be in a driver, early_init is too early of course in the examples, but
I could probably think of a bunch of othe reasons you'd want to check some
of the /chosen nodes or make a quick check if the device was purposed by
the firmware for some reason)

> It fixes three primary concerns:
> 
> 1. The 1275 documentation is scattered in many places, some of which are 
> not easily accessible to the general public (just look at the i2c mess).

To be honest I didn't know i2c had ever been defined at all, so I see
your point there.

> 2. 1275 did not appear to be actively maintained and updated.

But, it did not suddenly break in the last 14 years, did it?

This simply exposes the endemic problem of Linux developers subscribing
to the Not Invented Here philosophy and making subtle yet intrusive
changes to suit themselves and brighten their name in lights while, in
the end, ignoring their own statements to whit the benefits and reasons
why they wanted to change something.

I am still kind of sore that the policy swung from "the firmware is
responsible" to "we will accept any crazy patch for prom_init.c which
will fix up a device even though there is an easy way to fix it from
the firmware side and not clutter Linux, and even though the patch
doesn't ACTUALLY work" and many other 180's in the history of the
device tree specifications and the support Linux implements.

ePAPR doesn't resolve a single thing we didn't already know, and
considering it was written by the IBM and Freescale engineers who
implemented and maintain the support and the firmware.. I wonder
how much thought went into it besides how to format it as a PDF.
Don't get me started on how useless and ineffectual Power.org
technical subcommittees are.. there is no reason why PAPR and
ePAPR couldn't have been the same specification. When you start
thinking about U-Boot with RTAS or the IBM Hypervisor this is
going to kick you in the backside.

> 3. It standardized the flattened device tree interface, which did not 
> exist in 1275.

This is about all it did but it is not like we've not been using
flattened device trees for the past 2 or so years *anyway*. They did
always work. The real sore points here are device bindings and
a grand total of nothing changed between OF and now with that.

The assertion in ePAPR that device_type is deprecated and ignored
because ePAPR doesn't support FCode is naive at best.

To be honest I've lost the will to actually contribute to the
discussion because it's just reminding me of why we got a refund
from Power.org and why we stopped submitting patches to mainline.

Thanks for your input, Mitch, at least. It was very helpful.

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Scott Wood]

Matt Sealey wrote:
> I say ANY firmware environment because at the end
> of the day what methods the OF implements, or even if the firmware
> (like a U-Boot modification) "lies" about it being device_type serial
> or device_type network, Linux completely f**ks over the client
> interface at the first opportunity it gets and does not call ANY
> appreciable method anyway.

That's Linux's choice; what does that have to do with how the firmware
expresses the functionality it provides?

> So, it is not a lie to say it's a certain device_type,

It's not a lie because Linux doesn't care that it's a lie?

> and I really do focus here on the between-the-lines reading of the OF
> spec where devices which ARE useful for booting, console and probing
> (for instance marking detected disks as "block", ethernet as
> "network", serial consoles as "serial" and displays and keyboards are
> present in the tree if they are present on the machine) is more
> relevant here than the Open Firmware client interface methods which
> Linux is steadfastly resolved never to use anyway.

If you're not going to use the method interface, then what *do* you use 
device_type for?

> So let's just take the basic premise of the device_type and not the 
> literal truth of it (hey, the world wasn't created in 7 days after
> all, who'd have thunk?) and use it to the advantage of the Linux
> kernel instead of ditching it as legacy.

What advantage would that be?

>> Define "they", "used", and "firmware environment".  Obviously
>> u-boot may use the serial port for its console, but there's no
>> method interface defined by the device tree, nor is there any
>> firmware resident at all after starting the kernel.
> 
> However it is a serial port, and when it boots it says "input:
> serial" and "output: serial" - or it could be netconsole or so. Or
> even screen and keyboard! These are put into /chosen/stdin and
> /chosen/stdout when the system is booted with the device tree.

And how, exactly, do /chosen/stdin and /chosen/stdout depend on device_type?

> Should a platform be extremely specific and check compatible
> properties for every kind of serial port it could ever support

Of course it should check compatible -- how else would it know how to 
drive the thing?

> (including PCI, ISA/LPC, and otherwise connected GPIO implementations
> or crazy designs) just so that it can carry over the firmware choices
> reported in the device tree to the booting system, or should it
> simply be looking for those generic device classes?

And what do you propose it do with a generic "serial" in the absence of 
a method interface?  Just assume it's ns16550?

> A simple way to check what is in use and what basic sort of
> peripheral it is, without knowing the ultimate specifics of the
> device (since you would not be in a driver, early_init is too early
> of course in the examples, but I could probably think of a bunch of
> othe reasons you'd want to check some of the /chosen nodes or make a
> quick check if the device was purposed by the firmware for some
> reason)

-EPARSE

>> 2. 1275 did not appear to be actively maintained and updated.
> 
> But, it did not suddenly break in the last 14 years, did it?

New hardware came along that is not described.  Details that fall out of 
the use of flat trees are not addressed (no ihandles, phandles as 
properties, etc).

> ePAPR doesn't resolve a single thing we didn't already know,

The primary intent was to codify existing practice.

> Don't
> get me started on how useless and ineffectual Power.org technical
> subcommittees are.. there is no reason why PAPR and ePAPR couldn't
> have been the same specification. When you start thinking about
> U-Boot with RTAS or the IBM Hypervisor this is going to kick you in
> the backside.

Agreed; that's more of a political issue than a technical one.

>> 3. It standardized the flattened device tree interface, which did
>> not exist in 1275.
> 
> This is about all it did but it is not like we've not been using 
> flattened device trees for the past 2 or so years *anyway*.

...in Linux and u-boot.  ePAPR gives us a self-contained document that 
we can point other firmware and OS developers to.

> They did 
> always work. The real sore points here are device bindings and a
> grand total of nothing changed between OF and now with that.
> 
> The assertion in ePAPR that device_type is deprecated and ignored 
> because ePAPR doesn't support FCode is naive at best.

It's deprecated *in the context of flat device trees*.  Anything not 
using flat device trees is out-of-scope with respect to ePAPR.

-Scott

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Scott Wood wrote:
>
>> They did always work. The real sore points here are device bindings and a
>> grand total of nothing changed between OF and now with that.
>>
>> The assertion in ePAPR that device_type is deprecated and ignored 
>> because ePAPR doesn't support FCode is naive at best.
> 
> It's deprecated *in the context of flat device trees*.  Anything not 
> using flat device trees is out-of-scope with respect to ePAPR.

Isn't the beauty of a device tree that every firmware no matter what
type can present it in whatever form it chooses, but still be describing
the same hardware in the same way?

Designing a tree for OF and one for U-Boot should be an absolutely
identical process, internal firmware methodologies notwithstanding
be it pure Forth in Firmworks, C API in Codegen, or output of dtc
for U-Boot, the exact same tree should be output, device_type and
all, within reason. I don't think "it's not real Open Firmware" is
a valid reason. Not as valid as "our firmware doesn't support this
hardware yet so we can't probe or initialize, only describe the bus",
for example (USB on Efika is filled out, USB on U-Boot for Lite5200B
is not).

I'm curious, is it the remit of the ePAPR TSC to publish and act as
a registration authority for device tree bindings for specific SoCs
or is that devolved to the SoC maker itself (be they a member of
Power.org or not) and, more prudent, two other questions; where are
Freescale and IBM publishing these if it is their responsibility,
are things like the mysterious i2c binding going to be published
under this TSC?

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Scott Wood]

Matt Sealey wrote:
> Scott Wood wrote:
>> It's deprecated *in the context of flat device trees*.  Anything not 
>> using flat device trees is out-of-scope with respect to ePAPR.
> 
> Isn't the beauty of a device tree that every firmware no matter what
> type can present it in whatever form it chooses, but still be describing
> the same hardware in the same way?

When run-time services are not involved, yes.  device_type was used by 
1275 in the context of run-time services, which we don't have, so we 
didn't copy that property over (except for memory and cpu, to avoid 
gratuitous divergence).

> I'm curious, is it the remit of the ePAPR TSC to publish and act as
> a registration authority for device tree bindings for specific SoCs
> or is that devolved to the SoC maker itself (be they a member of
> Power.org or not) and, more prudent, two other questions; where are
> Freescale and IBM publishing these if it is their responsibility,
> are things like the mysterious i2c binding going to be published
> under this TSC?

There has been talk about setting up such a repository, but I'm not sure 
what the status of it is.

-Scott

Re: GPIO - marking individual pins (not) available in device tree

[David Gibson]

On Mon, Oct 27, 2008 at 12:54:15PM -0500, Scott Wood wrote:
> Matt Sealey wrote:
>> Scott Wood wrote:
>>> It's deprecated *in the context of flat device trees*.  Anything not  
>>> using flat device trees is out-of-scope with respect to ePAPR.
>>
>> Isn't the beauty of a device tree that every firmware no matter what
>> type can present it in whatever form it chooses, but still be describing
>> the same hardware in the same way?
>
> When run-time services are not involved, yes.  device_type was used by  
> 1275 in the context of run-time services, which we don't have, so we  
> didn't copy that property over (except for memory and cpu, to avoid  
> gratuitous divergence).
>
>> I'm curious, is it the remit of the ePAPR TSC to publish and act as
>> a registration authority for device tree bindings for specific SoCs
>> or is that devolved to the SoC maker itself (be they a member of
>> Power.org or not) and, more prudent, two other questions; where are
>> Freescale and IBM publishing these if it is their responsibility,
>> are things like the mysterious i2c binding going to be published
>> under this TSC?
>
> There has been talk about setting up such a repository, but I'm not sure  
> what the status of it is.

Progressing intermittently when people get small packets of time to
actually do something about it.  We do really want this, it's just
no-one's yet had the spare cycles to make it happen.

At the moment things are published in the kernel documentation
(booting-without-of.txt, although I think it's now been split up into
multiple files), which is far from ideal, but better than nothing.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

Re: GPIO - marking individual pins (not) available in device tree

[David Gibson]

On Mon, Oct 27, 2008 at 11:12:07AM -0500, Matt Sealey wrote:
>
>
> David Gibson wrote:
>> On Sun, Oct 26, 2008 at 04:13:26PM -0500, Matt Sealey wrote:
>>>
>>> Mitch Bradley wrote:
>>
>> device_type in 1275 defines the runtime method interface.  It's *not*
>> for declaring the general class of the device, although it often
>> matches that in practice.
>
> It *is* for declaring the general class of the device, even if it's
> purpose is to make it known that it implements all the required
> methods and therefore acts in a certain predefined way when those
> methods are used; it's not a necessary property but it is a USEFUL
> property:

No, it's really not.  There are only two ways device class information
can be useful:
	- for human readability.  For this purpose the node name with
the generic names convention suffices.
	- for manipulating the device without having a driver specific
to the device.  This works *only* if there is a class-defined protocol
for doing this manipulation.  Clearly, this can't exist unless the
firmware provides some sort of runtime service to abstract away
differences between devices.  Flat trees cannot of themselves provide
such a thing, and so should not advertise that they can with
device_type.

Even if a firmware did provide run time services, but they weren't in
the form of the OF defined method interface, they should not use
device_type, but some other property to advertise their own particular
brand of runtime service interface.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

Re: GPIO - marking individual pins (not) available in device tree

[David Gibson]

On Thu, Oct 23, 2008 at 06:05:19PM -0500, Matt Sealey wrote:
>
>
> Mitch Bradley wrote:
> [snip]
>
>> You could adopt the convention that preassigned GPIOs must be  
>> represented by subordinate nodes, and any GPIO that is not covered by a 
>> subordinate node's "reg" property is implicitly available.  That's the  
>> way it works for other address spaces.

[snip]
> At the moment it's encoded as:
>
> 	gpios = <&controller-phandle pin-number pin-flags>

Actually, it's not.  The gpios property is:
	<controller-phandle gpio-descriptor ...>

The "gpio-descriptor" (like an interrupt descriptor from IEEE1275) is
a blob with number of cells equal to #gpio-cells from the controller.
The internal layout of the descriptor is specific to the gpio
controller.  Typically it includes a pin number and flags/mode.
However, it could be, and sometimes is, encoded as bank-number /
pin-number / flags.  Or even something more involved still, if that's
useful for the specific gpio controller in question.  Or it could
simply be pin number if it's associated with a really simple gpio
controller where all pins have the same behaviour.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

Re: GPIO - marking individual pins (not) available in device tree

[David Gibson]

On Thu, Oct 23, 2008 at 12:22:03PM -1000, Mitch Bradley wrote:
> You could have the gpio node define an "address space" where each  
> "address" is a GPIO pin number.
>
> The node would have one address cell and one size cell, and the  

Not necessarily.  If you were to have such an address space, the only
sane way of encoding it would be using the same "gpio descriptor"
format as is used in 'gpios' properties.  Which would mean the gpio
controller would in this situation have #address-cells == #gpio-cells.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

Re: GPIO - marking individual pins (not) available in device tree

[Anton Vorontsov]

On Thu, Oct 23, 2008 at 04:32:49PM -0500, Matt Sealey wrote:
> Hi guys,
>
> I'm a little perplexed as to how I would define a GPIO controller in a 
> device tree but mark off pins as available or not, so users can geek 
> around in their own drivers without defining in a device tree exactly 
> what they intend to use it for (especially if it's something really 
> weird).
>
> Easiest example - the Efika runs an MPC5200B has 3 GPIO pins on the 
> board. It's not much, but they're there for use. All the other GPIOs are 
> absolutely out of bounds, off limits and probably dangerous to touch, but 
> since each GPIO block has a 32-bit register to handle them, you can 
> twiddle any bit you like with impunity and cause all the damage you want. 
> A simple thought comes to mind in that the gpiolib should not allow a  
> request for one of these "bad" GPIO pins to succeed.

Well, the same applies to the IRQ controllers. I bet you can request a
reserved IRQ on some particular board/CPU, but results would be
unpredictable (the driver would touch reserved bits etc). The device
tree should be sane for this particular platform and not specify bogus
gpios/irqs/regs/sizes/etc.

> So, how do we define in a bank of GPIOs, which ones are free for use, 
> without them being attached to a device and given as a "gpios" property?
>
> Would we suggest a node;
>
> gpio-header {
> 	compatible = "bplan,efika-gpio";
> 	gpios = <&gpio-standard 16 0 17 0>;
> };
>
> gpio-header2 {
> 	compatible = "bplan,efika-gpio-wkup";
> 	gpios = <&gpio-wkup 18 0>;
> };

IMO this looks very reasonable. You properly describe the hardware:
physical device (header) and its resources.

-- 
Anton Vorontsov
email: cbouatmailru@gmail.com
irc://irc.freenode.net/bd2

Re: GPIO - marking individual pins (not) available in device tree

[Anton Vorontsov]

On Fri, Oct 24, 2008 at 08:41:20PM +0400, Anton Vorontsov wrote:
[...]
> > So, how do we define in a bank of GPIOs, which ones are free for use, 
> > without them being attached to a device and given as a "gpios" property?
> >
> > Would we suggest a node;
> >
> > gpio-header {
> > 	compatible = "bplan,efika-gpio";
> > 	gpios = <&gpio-standard 16 0 17 0>;
> > };
> >
> > gpio-header2 {
> > 	compatible = "bplan,efika-gpio-wkup";
> > 	gpios = <&gpio-wkup 18 0>;
> > };
>
> IMO this looks very reasonable. You properly describe the hardware:
> physical device (header) and its resources.

If there are actually two headers, that is. If you use two nodes
just to specify which gpio is wkup, that is's a bit ugly... Why not

gpio-header {
	compatible = "bplan,<board>-gpio-header";
	gpios = <&standard 16 0
		 &standard 17 0
		 &wakeup 18 0>;
}

And the driver whould know that on this particular <board>
third gpio is the wakeup one?

-- 
Anton Vorontsov
email: cbouatmailru@gmail.com
irc://irc.freenode.net/bd2

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Anton Vorontsov wrote:
> On Fri, Oct 24, 2008 at 08:41:20PM +0400, Anton Vorontsov wrote:
> [...]
>>> Would we suggest a node;
>>>
>>> gpio-header {
>>> 	compatible = "bplan,efika-gpio";
>>> 	gpios = <&gpio-standard 16 0 17 0>;
>>> };
>>>
>>> gpio-header2 {
>>> 	compatible = "bplan,efika-gpio-wkup";
>>> 	gpios = <&gpio-wkup 18 0>;
>>> };
>> IMO this looks very reasonable. You properly describe the hardware:
>> physical device (header) and its resources.
> 
> If there are actually two headers, that is. If you use two nodes
> just to specify which gpio is wkup, that is's a bit ugly... Why not
> 
> gpio-header {
> 	compatible = "bplan,<board>-gpio-header";
> 	gpios = <&standard 16 0
> 		 &standard 17 0
> 		 &wakeup 18 0>;
> }
> 
> And the driver whould know that on this particular <board>
> third gpio is the wakeup one?

Good point, I concede to your much better plan :D

Back to the other discussion, where we give individual GPIOs some
names so they are detectable and not just programmable as a bank,
do you have any ideas about that? :/

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Anton Vorontsov]

On Fri, Oct 24, 2008 at 05:17:42PM -0500, Matt Sealey wrote:
> Anton Vorontsov wrote:
>> On Fri, Oct 24, 2008 at 08:41:20PM +0400, Anton Vorontsov wrote:
>> [...]
>>>> Would we suggest a node;
>>>>
>>>> gpio-header {
>>>> 	compatible = "bplan,efika-gpio";
>>>> 	gpios = <&gpio-standard 16 0 17 0>;
>>>> };
>>>>
>>>> gpio-header2 {
>>>> 	compatible = "bplan,efika-gpio-wkup";
>>>> 	gpios = <&gpio-wkup 18 0>;
>>>> };
>>> IMO this looks very reasonable. You properly describe the hardware:
>>> physical device (header) and its resources.
>>
>> If there are actually two headers, that is. If you use two nodes
>> just to specify which gpio is wkup, that is's a bit ugly... Why not
>>
>> gpio-header {
>> 	compatible = "bplan,<board>-gpio-header";
>> 	gpios = <&standard 16 0
>> 		 &standard 17 0
>> 		 &wakeup 18 0>;
>> }
>>
>> And the driver whould know that on this particular <board>
>> third gpio is the wakeup one?
>
> Good point, I concede to your much better plan :D

;-)

> Back to the other discussion, where we give individual GPIOs some
> names so they are detectable and not just programmable as a bank,
> do you have any ideas about that? :/

Pure GPIOs don't have names. But when you use bindings they
automatically translate to names. For example FHCI bindings:

                usb@6c0 {
                        compatible = "fsl,mpc8360-qe-usb",
                                     "fsl,mpc8323-qe-usb";
                        reg = <0x6c0 0x40 0x8b00 0x100>;
                        interrupts = <11>;
                        interrupt-parent = <&qeic>;
                        fsl,fullspeed-clock = "clk21";
                        fsl,lowspeed-clock = "brg9";
                        gpios = <&qe_pio_b  2 0   /* USBOE */
                                 &qe_pio_b  3 0   /* USBTP */
                                 &qe_pio_b  8 0   /* USBTN */
                                 &qe_pio_b  9 0   /* USBRP */
                                 &qe_pio_b 11 0   /* USBRN */
                                 &bcsr13    5 0   /* SPEED */
                                 &bcsr13    4 1>; /* POWER */
                };

The bindings specify that gpios[0] (here qe_pio_b 2) is USBOE,
gpios[1] (here qe_pin_b 3) is USBTP, and so on.

There is nothing new in this. You can see the reg = <> property in
these bindings. It specify two regions: 0x6c0 0x40 - USB Regs
and 0x8b00 0x100 - USB parameter ram. Pure addresses don't have
names until bindings applied.

The same is for interrupts. Device may specify several interrupts:

                enet0: ethernet@24000 {
                        cell-index = <0>;
                        device_type = "network";
                        model = "TSEC";
                        compatible = "gianfar";
                        reg = <0x24000 0x1000>;
                        local-mac-address = [ 00 00 00 00 00 00 ];
                        interrupts = <32 0x8 33 0x8 34 0x8>;
                        interrupt-parent = <&ipic>;
                        phy-handle = <&phy1c>;
                        linux,network-index = <0>;
                };

IRQ 32 is tx interrupt, IRQ33 is rx interrupt, and IRQ34 is
error-reporting interrupt.

But w/o any bindings nobody can tell what does IRQ33 mean (well,
actually we can tell it for ipic on this particular processor,
since it has hard-coded "SOC device<->irq" mapping. But it might
be not true for other controllers, or even ipic's external
interrupts).

-- 
Anton Vorontsov
email: cbouatmailru@gmail.com
irc://irc.freenode.net/bd2

Re: GPIO - marking individual pins (not) available in device tree

[Konstantinos Margaritis]

Pardon my intrusion in the conversation, but I just couldn't not comment on
this:

On Tue, 28 Oct 2008 12:50:03 +1100, David Gibson
<david@gibson.dropbear.id.au> wrote:
>> So now my qualm is back to the beginning of the discussion. How do
>> we encode the purpose of those pins reliably and within some
>> standard framework, without getting *driver* specific?
>
> Um.. I fail to see how the purpose of a pin can be not driver
> specific.

GPIO stands for _General_ Purpose IO. The driver should just expose that
info to user space and it should be up to the userspace application to
decide what to do with that. The programmer should require absolutely
no other intervention to the driver whatsoever.
Anyone that has worked on data mining scientific equipment -eg.
particle/photon scanners on VME boards with lots of GPIO pins- will tell
you that meddling with kernel coding is totally unneeded, in fact it's
stupid to require the student to do so. Usually some Windows API is given
and the students write the programs on Windows to collect the data and
control the device. I guess GPIOLIB and the new framework would have
similar application in Linux -ie, requiring the programmer to write only
a userspace to access the GPIO pins. From my understanding of the
conversation, there are some people who fail to see the necessity of
doing extra work to abstract this information away from the driver. A walk
to a nearby experimental physicists lab with students working on such
devices will convince you of the right way to do it actually.

PS. I am of physics background myself, though a theoritical one and not 
experimental. But I did have many friends experimentalists, in
particular I remember two that did exactly what I described. Neither did
have any particular kernel/driver knowledge and neither did have to do
anything extremely low-level to acquire the data. Both used windows 
user-level programming, though that was ~8years ago so don't expect me
to remember the exact VME boards or APIs used...

Konstantinos Margaritis
Codex
http://www.codex.gr

Re: GPIO - marking individual pins (not) available in device tree

[Anton Vorontsov]

On Tue, Oct 28, 2008 at 02:31:29PM +0100, Konstantinos Margaritis wrote:
> 
> Pardon my intrusion in the conversation, but I just couldn't not comment on
> this:
> 
> On Tue, 28 Oct 2008 12:50:03 +1100, David Gibson
> <david@gibson.dropbear.id.au> wrote:
> >> So now my qualm is back to the beginning of the discussion. How do
> >> we encode the purpose of those pins reliably and within some
> >> standard framework, without getting *driver* specific?
> >
> > Um.. I fail to see how the purpose of a pin can be not driver
> > specific.
> 
> GPIO stands for _General_ Purpose IO. The driver should just expose that
> info to user space and it should be up to the userspace application to
> decide what to do with that. The programmer should require absolutely
> no other intervention to the driver whatsoever.
> Anyone that has worked on data mining scientific equipment -eg.
> particle/photon scanners on VME boards with lots of GPIO pins- will tell
> you that meddling with kernel coding is totally unneeded, in fact it's
> stupid to require the student to do so. Usually some Windows API is given
> and the students write the programs on Windows to collect the data and
> control the device. I guess GPIOLIB and the new framework would have
> similar application in Linux -ie, requiring the programmer to write only
> a userspace to access the GPIO pins. From my understanding of the
> conversation, there are some people who fail to see the necessity of
> doing extra work to abstract this information away from the driver.

Heh. You _have_ the API to work with the GPIOs. In-kernel and userland
APIs. What you don't have in the _device tree_ is:

1. The mapping of invalid GPIOs. Though again, this can be easily
   implemented, just nobody bothers with it since there are million
   of other ways to do bad things with the hardware resources.

2. The mapping of board's external pins to gpio-controller's GPIOs. This
   is also can be trivially implemented. Sometimes this mapping could
   make some sense, and could be useful. You just need describe the
   board's headers in the device tree. You don't even need the driver
   for this, your userspace application can just look into the
   /proc/device-tree directly, and find out which GPIOs are wired
   to the board's headers.

See? You _can_ use the GPIOs. If you don't believe me, just find
some PPC board for which we support some GPIO controller, and compile
the kernel with CONFIG_GPIO_SYSFS=y, then look into the
/sys/class/gpio/. ;-)

-- 
Anton Vorontsov
email: cbouatmailru@gmail.com
irc://irc.freenode.net/bd2

Re: GPIO - marking individual pins (not) available in device tree

[Grant Likely]

On Tue, Oct 28, 2008 at 7:31 AM, Konstantinos Margaritis
<markos@codex.gr> wrote:
>
> Pardon my intrusion in the conversation, but I just couldn't not comment on
> this:
>
> On Tue, 28 Oct 2008 12:50:03 +1100, David Gibson
> <david@gibson.dropbear.id.au> wrote:
>>> So now my qualm is back to the beginning of the discussion. How do
>>> we encode the purpose of those pins reliably and within some
>>> standard framework, without getting *driver* specific?
>>
>> Um.. I fail to see how the purpose of a pin can be not driver
>> specific.
>
> GPIO stands for _General_ Purpose IO. The driver should just expose that
> info to user space and it should be up to the userspace application to
> decide what to do with that. The programmer should require absolutely
> no other intervention to the driver whatsoever.
> Anyone that has worked on data mining scientific equipment -eg.
> particle/photon scanners on VME boards with lots of GPIO pins- will tell
> you that meddling with kernel coding is totally unneeded, in fact it's
> stupid to require the student to do so. Usually some Windows API is given
> and the students write the programs on Windows to collect the data and
> control the device. I guess GPIOLIB and the new framework would have
> similar application in Linux -ie, requiring the programmer to write only
> a userspace to access the GPIO pins. From my understanding of the
> conversation, there are some people who fail to see the necessity of
> doing extra work to abstract this information away from the driver. A walk
> to a nearby experimental physicists lab with students working on such
> devices will convince you of the right way to do it actually.

All this already exists.   All GPIO pins using GPIOLIB are exportable
and usable from userspace with no kernel coding whatsoever.  However,
some of those GPIO pins are also used by in-kernel driver to implement
things like i2c, spi, mdio and jtag which use in-kernel
infrastructure, so it is critical to support both kernel and user
space users.

As far as David's comment about pins being driver specific; that
really is true.  Once a GPIO pin is wired to something it becomes
specific purpose which is device/board/connection specific, regardless
of if the driver is in kernel or a user space application (Just
because it is user space code doesn't mean it isn't a device driver).
If the driver willfully uses the wrong GPIO pins then things simply
won't work and it is critical for the device tree to contain valid
data about GPIO connections.

For Matt's purposes, I think he wants to describe which GPIO pins are
available to be used, but are not yet connected to anything.  In such
a case I think it does make sense to add a node for available GPIO
pins and give it a gpios property with a list of the pins wired to the
header.

Thanks for the comments.

g.

-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.

Re: GPIO - marking individual pins (not) available in device tree

[Matt Sealey]

Grant Likely wrote:
> 
> For Matt's purposes, I think he wants to describe which GPIO pins are
> available to be used, but are not yet connected to anything.  In such
> a case I think it does make sense to add a node for available GPIO
> pins and give it a gpios property with a list of the pins wired to the
> header.

Yes, the two problems I saw were there is only an implicit definition
of which gpios are available for use (GPIOLIB will happily give
you an unavailable pin if you ask for it, because there is no
definition except for "gpios" property as hooked up to a device).

I liked Mitch's idea about the available property and re-using already
existing standards and parsing to get it done.

(this allows some syntax/lint checking of a device tree too since if
you put a pin in a gpios property which you marked as unavailable,
you can flag it :)

The other problem was defining pins which most definitely ARE
connected to something (as GPIO) but could well be in an ill-defined
order or for no defined purpose with regards to the peripheral. A
lot of GPIO drivers right now (bitbang SPI, I2C) will just allocate
one pin as one thing and the other as another - if you say pin 15
and 16 for bitbang-i2c, then it may assumes pin 15 is clock and 16
is data. For SPI, you get another pin, which order is it (the
middle one may be correct but the outer ones could be swapped).

Is this even defined? Shouldn't it be? And therein lies the
question :)

Exposing it to userspace is a good idea. While grouping them up
would break the existing sysfs ABI there's no reason you can't
have all of the GPIOs dumped into sysfs as it is now, and then
new directories named after the gpio-group, which symlink back
to the sysfs pins in the parent directory? That would really
rock as it's bringing the abstraction and description of the
device tree back into userspace, where let's be honest, they do
not give a crap about device tree bindings, only what pin does
what action :D

-- 
Matt Sealey <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: GPIO - marking individual pins (not) available in device tree

[Grant Likely]

On Tue, Oct 28, 2008 at 11:06 AM, Matt Sealey <matt@genesi-usa.com> wrote:
> The other problem was defining pins which most definitely ARE
> connected to something (as GPIO) but could well be in an ill-defined
> order or for no defined purpose with regards to the peripheral. A
> lot of GPIO drivers right now (bitbang SPI, I2C) will just allocate
> one pin as one thing and the other as another - if you say pin 15
> and 16 for bitbang-i2c, then it may assumes pin 15 is clock and 16
> is data. For SPI, you get another pin, which order is it (the
> middle one may be correct but the outer ones could be swapped).

Yes, order is important, and yes it should be defined.  That is what
the binding documentation must specify.  It is no different from the
ordering of multiple ranges in the reg property or multiple
interrupts.

> Is this even defined? Shouldn't it be? And therein lies the
> question :)

Yes and yes.  It all hangs off the value of compatible and the
documentation of what the compatible value means.

g.

-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.

Re: GPIO - marking individual pins (not) available in device tree

[David Gibson]

On Tue, Oct 28, 2008 at 02:31:29PM +0100, Konstantinos Margaritis wrote:
> 
> Pardon my intrusion in the conversation, but I just couldn't not comment on
> this:
> 
> On Tue, 28 Oct 2008 12:50:03 +1100, David Gibson
> <david@gibson.dropbear.id.au> wrote:
> >> So now my qualm is back to the beginning of the discussion. How do
> >> we encode the purpose of those pins reliably and within some
> >> standard framework, without getting *driver* specific?
> >
> > Um.. I fail to see how the purpose of a pin can be not driver
> > specific.
> 
> GPIO stands for _General_ Purpose IO. The driver should just expose that
> info to user space and it should be up to the userspace application to
> decide what to do with that. The programmer should require absolutely
> no other intervention to the driver whatsoever.

Yes, which is exactly why the purpose of the pin is driver specific.
That's the driver for the user of the pin, not the gpio controller.
In some cases that's another kernel driver, where some device needs
gpio access, in your case it's the userspace application.  But in
either case it's this driver that must know what gpio line to use, and
how to use it.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson