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.

[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 at 12

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

/<whatever>/gpio/usergpio at 4
/<whatever>/gpio/usergpio at 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

Post by 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 at genesi-usa.com>
Genesi, Manager, Developer Relations
_______________________________________________
devicetree-discuss mailing list
devicetree-discuss at ozlabs.org
https://ozlabs.org/mailman/listinfo/devicetree-discuss

[Matt Sealey]

Mitch Bradley wrote:
[snip]

Post by Mitch Bradley
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 at 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 at 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 at 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?)

[Mitch Bradley]

Post by Matt Sealey
[snip]

Post by Mitch Bradley
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.

Post by Matt Sealey
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.

Post by Matt Sealey
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.

Post by Matt Sealey
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).
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.

Post by Matt Sealey
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.

Post by Matt Sealey
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 at 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.

Post by Matt Sealey
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.

Post by Matt Sealey
gpio_pin at 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.

Post by Matt Sealey
\\ 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.

Post by Matt Sealey
reg = <2 1>
compatible = "magic";
};
};
}
device at 9000 {
compatible = "somedevice";
reg = <0x9000 0x18>;
gpios = <&gpio_1_bank_1>

gpios = <&NAME,magic>

Post by Matt Sealey
};
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.)

Post by Matt Sealey
--
Matt Sealey <matt at genesi-usa.com>
Genesi, Manager, Developer Relations

[David Gibson]

Post by Mitch Bradley

Post by Matt Sealey
[snip]

Post by Mitch Bradley
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).

[Mitch Bradley]

Post by David Gibson
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.

Post by David Gibson
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

[David Gibson]

Post by Mitch Bradley

Post by David Gibson
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.

Post by David Gibson
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.

[Matt Sealey]

Post by David Gibson
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?

[David Gibson]

Post by Matt Sealey

Post by David Gibson
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.

Post by Matt Sealey
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.

[Matt Sealey]

Post by David Gibson
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).

[Anton Vorontsov]

Post by Matt Sealey

Post by David Gibson
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 at ... {
#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.

Post by Matt Sealey
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.

[Matt Sealey]

Post by Anton Vorontsov
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;

Post by Anton Vorontsov
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.

[Anton Vorontsov]

Post by Matt Sealey

Post by Anton Vorontsov
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;

Post by Anton Vorontsov
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?

[Matt Sealey]

Post by Anton Vorontsov
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.

[Anton Vorontsov]

Post by Matt Sealey

Post by Anton Vorontsov
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
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)
* 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.

Post by Matt Sealey
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.

Post by Matt Sealey
(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 */
...>;
}

Post by Matt Sealey
* 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.

Post by Matt Sealey
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>;
}

Post by Matt Sealey
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.

Post by Matt Sealey
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?

Post by Matt Sealey
At the very least it needs documenting better,

Feel free to write a better documentation.

Post by Matt Sealey
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.

Post by Matt Sealey
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?

Post by Matt Sealey
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.

Post by Matt Sealey
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]

On Tue, Oct 28, 2008 at 02:12:21AM +0300, Anton Vorontsov wrote:
[...]

Post by Matt Sealey
* 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.

[Matt Sealey]

Post by Anton Vorontsov
[...]

Post by Matt Sealey
* 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.

Post by Anton Vorontsov
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]

Post by Anton Vorontsov

Post by Matt Sealey
* 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.

Post by Anton Vorontsov

Post by Matt Sealey
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..

Post by Anton Vorontsov
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

Post by Anton Vorontsov
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>;
}

Post by Matt Sealey
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.

Post by Anton Vorontsov

Post by Matt Sealey
* 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.

Post by Anton Vorontsov

Post by Matt Sealey
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

Post by Anton Vorontsov

Post by Matt Sealey
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.

Post by Anton Vorontsov
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.

Post by Anton Vorontsov

Post by Matt Sealey
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.

[Anton Vorontsov]

Post by Matt Sealey

Post by Anton Vorontsov

Post by Matt Sealey
* 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?

Post by Matt Sealey

Post by Anton Vorontsov

Post by Matt Sealey
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.

Post by Matt Sealey

Post by Anton Vorontsov
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.

Post by Matt Sealey
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.

Post by Matt Sealey

Post by Anton Vorontsov
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>;
}

Post by Matt Sealey
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.

Post by Matt Sealey
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.

Post by Matt Sealey
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"?

[...]

Post by Matt Sealey

Post by Anton Vorontsov

Post by Matt Sealey
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. ;-)

[...]

Post by Matt Sealey

Post by Anton Vorontsov
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?

Post by Matt Sealey
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.

Post by Matt Sealey

Post by Anton Vorontsov

Post by Matt Sealey
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... ;-)

[Matt Sealey]

Post by Anton Vorontsov

Post by Matt Sealey

Post by Anton Vorontsov

Post by Matt Sealey
* 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 :)

Post by Anton Vorontsov
- 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*

Post by Anton Vorontsov
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.

Post by Anton Vorontsov

Post by Matt Sealey
Comments don't get compiled..

If you _really_ want to complicate things, you can write gpios for
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).

Post by Anton Vorontsov

Post by Matt Sealey
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)

Post by Anton Vorontsov

Post by Matt Sealey
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?)

Post by Anton Vorontsov
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

Post by Anton Vorontsov

Post by Matt Sealey
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.

Post by Anton Vorontsov
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.

Post by Anton Vorontsov
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.

Post by Anton Vorontsov
Both solutions are doable.

Post by Matt Sealey
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.

[Grant Likely]

Post by Matt Sealey
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.

Post by Matt Sealey

Post by Anton Vorontsov
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.

Post by Matt Sealey
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.

[Matt Sealey]

Post by Grant Likely
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.

Post by Grant Likely

Post by Matt Sealey

Post by Anton Vorontsov
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)

Post by Grant Likely

Post by Matt Sealey
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..

[David Gibson]

Post by Matt Sealey

Post by David Gibson
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>;

[Matt Sealey]

Post by David Gibson
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..

[David Gibson]

Post by Matt Sealey

Post by David Gibson
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.

Post by Matt Sealey
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.

Post by Matt Sealey
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).

[Grant Likely]

Post by Matt Sealey

Post by David Gibson
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.

Post by Matt Sealey
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.

[Matt Sealey]

Post by Mitch Bradley

Post by Matt Sealey
gpio_pin at 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".

Post by Mitch Bradley
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 :)

[Stephen Neuendorffer]

Post by Matt Sealey
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 at 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 recipient(s) and contain(s) confidential information that may be proprietary, privileged or copyrighted under applicable law. If you are not the intended recipient, do not read, copy, or forward this email message or any attachments. Delete this email message and any attachments immediately.

[Matt Sealey]

Post by Stephen Neuendorffer

Post by Matt Sealey
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.

Post by Stephen Neuendorffer
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)

Post by Stephen Neuendorffer
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

[Mitch Bradley]

Post by Matt Sealey
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.

[Matt Sealey]

Post by Mitch Bradley
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.

Post by Mitch Bradley
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 at 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.

[David Gibson]

Post by Matt Sealey

Post by Mitch Bradley
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.

[Matt Sealey]

Post by David Gibson
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)

Post by David Gibson
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 at ozlabs.org/msg11772.html
http://www.mail-archive.com/linuxppc-dev at 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)

Post by David Gibson
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

Post by David Gibson
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.

Post by David Gibson
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.

[Scott Wood]

Post by Matt Sealey
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?

Post by Matt Sealey

Post by David Gibson
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.

Post by Matt Sealey

Post by David Gibson
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.

Post by Matt Sealey

Post by David Gibson
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

[Matt Sealey]

Post by Scott Wood
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.

Post by Scott Wood
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)

Post by Scott Wood
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.

Post by Scott Wood
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.

Post by Scott Wood
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.

[Scott Wood]

Post by Matt Sealey
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?

Post by Matt Sealey
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?

Post by Matt Sealey
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?

Post by Matt Sealey
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?

Post by Matt Sealey

Post by Scott Wood
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.

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?

Post by Matt Sealey
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?

Post by Matt Sealey
(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?

Post by Matt Sealey
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

Post by Matt Sealey

Post by Scott Wood
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).

Post by Matt Sealey
ePAPR doesn't resolve a single thing we didn't already know,

The primary intent was to codify existing practice.

Post by Matt Sealey
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.

Post by Matt Sealey

Post by Scott Wood
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.

Post by Matt Sealey
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

[Matt Sealey]

Post by Scott Wood

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?

[Scott Wood]

Post by Matt Sealey

Post by Scott Wood
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).

Post by Matt Sealey
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

[David Gibson]

Post by Scott Wood

Post by Matt Sealey

Post by Scott Wood
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).

Post by Matt Sealey
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]

Post by Matt Sealey

Post by David Gibson
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

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]

Post by Matt Sealey
[snip]

Post by Mitch Bradley
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]

Post by Matt Sealey
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]

Post by 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

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.

[Anton Vorontsov]

Post by 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.

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.

Post by Matt Sealey
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]

On Fri, Oct 24, 2008 at 08:41:20PM +0400, Anton Vorontsov wrote:
[...]

Post by Anton Vorontsov

Post by Matt Sealey
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>;
};

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?

[Matt Sealey]

Post by Anton Vorontsov
[...]

Post by Anton Vorontsov

Post by Matt Sealey
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>;
};

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? :/

[Anton Vorontsov]

Post by Matt Sealey

Post by Anton Vorontsov
[...]

Post by Anton Vorontsov

Post by Matt Sealey
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>;
};

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

;-)

Post by Matt Sealey
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 at 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 at 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).

[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

Post by David Gibson

Post by Matt Sealey
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

[Anton Vorontsov]

Post by Konstantinos Margaritis
Pardon my intrusion in the conversation, but I just couldn't not comment on
On Tue, 28 Oct 2008 12:50:03 +1100, David Gibson

Post by David Gibson

Post by Matt Sealey
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/. ;-)

[Grant Likely]

On Tue, Oct 28, 2008 at 7:31 AM, Konstantinos Margaritis

Post by Konstantinos Margaritis
Pardon my intrusion in the conversation, but I just couldn't not comment on
On Tue, 28 Oct 2008 12:50:03 +1100, David Gibson

Post by David Gibson

Post by Matt Sealey
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.

[Matt Sealey]

Post by Grant Likely
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

[Grant Likely]

Post by Matt Sealey
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.

Post by Matt Sealey
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.

[David Gibson]

Post by Konstantinos Margaritis
Pardon my intrusion in the conversation, but I just couldn't not comment on
On Tue, 28 Oct 2008 12:50:03 +1100, David Gibson

Post by David Gibson

Post by Matt Sealey
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.