[PATCH] gpio: dt-bindings: document the concept of GPIO banks

[PATCH] gpio: dt-bindings: document the concept of GPIO banks

[Linus Walleij]

Cc: devicetree@vger.kernel.org
Cc: Neil Armstrong <narmstrong@baylibre.com>
Cc: Rob Herring <robh@kernel.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
---
 Documentation/devicetree/bindings/gpio/gpio.txt | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
index 069cdf6f9dac..f509ecf03ece 100644
--- a/Documentation/devicetree/bindings/gpio/gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio.txt
@@ -131,6 +131,19 @@ Every GPIO controller node must contain both an empty "gpio-controller"
 property, and a #gpio-cells integer property, which indicates the number of
 cells in a gpio-specifier.
 
+Some system-on-chips (SoCs) use the concept of GPIO banks. A GPIO bank is an
+instance of a hardware IP core on a silicon die, usually exposed to the
+programmer as a coherent range of I/O addresses. Usually each such bank is
+exposed in the device tree as an individual gpio-controller node, reflecting
+the fact that the hardware was synthesized by reusing the same IP block a
+few times over.
+
+A GPIO controller may specify a bank ID. This is a hardware index that
+indicate the logical order of the GPIO controller in the hardware architecture,
+usually in the sequence 0, 1, 2 .. n. The hardware index may be different
+from the order of register ranges and related to the backplane of how this
+one bank is connected to the outside through a pin controller for example.
+
 Optionally, a GPIO controller may have a "ngpios" property. This property
 indicates the number of in-use slots of available slots for GPIOs. The
 typical example is something like this: the hardware register is 32 bits
@@ -152,6 +165,7 @@ gpio-controller@00000000 {
 	reg = <0x00000000 0x1000>;
 	gpio-controller;
 	#gpio-cells = <2>;
+	gpio-bank = <0>;
 	ngpios = <18>;
 }
 
-- 
2.4.3

Re: [PATCH] gpio: dt-bindings: document the concept of GPIO banks

[Rob Herring]

On Thu, Mar 31, 2016 at 4:10 AM, Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org> wrote:
> Cc: devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> Cc: Neil Armstrong <narmstrong-rdvid1DuHRBWk0Htik3J/w@public.gmane.org>
> Cc: Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> Signed-off-by: Linus Walleij <linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>

We generally avoid indexing blocks in DT.

> ---
>  Documentation/devicetree/bindings/gpio/gpio.txt | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
> index 069cdf6f9dac..f509ecf03ece 100644
> --- a/Documentation/devicetree/bindings/gpio/gpio.txt
> +++ b/Documentation/devicetree/bindings/gpio/gpio.txt
> @@ -131,6 +131,19 @@ Every GPIO controller node must contain both an empty "gpio-controller"
>  property, and a #gpio-cells integer property, which indicates the number of
>  cells in a gpio-specifier.
>
> +Some system-on-chips (SoCs) use the concept of GPIO banks. A GPIO bank is an
> +instance of a hardware IP core on a silicon die, usually exposed to the
> +programmer as a coherent range of I/O addresses. Usually each such bank is
> +exposed in the device tree as an individual gpio-controller node, reflecting
> +the fact that the hardware was synthesized by reusing the same IP block a
> +few times over.
> +
> +A GPIO controller may specify a bank ID. This is a hardware index that
> +indicate the logical order of the GPIO controller in the hardware architecture,
> +usually in the sequence 0, 1, 2 .. n. The hardware index may be different
> +from the order of register ranges and related to the backplane of how this
> +one bank is connected to the outside through a pin controller for example.

I still don't understand why do you need to know this? If you need
some mapping of gpio nodes into pin controller, the pin controller
should have a mapping using phandles.

> +
>  Optionally, a GPIO controller may have a "ngpios" property. This property
>  indicates the number of in-use slots of available slots for GPIOs. The
>  typical example is something like this: the hardware register is 32 bits
> @@ -152,6 +165,7 @@ gpio-controller@00000000 {
>         reg = <0x00000000 0x1000>;
>         gpio-controller;
>         #gpio-cells = <2>;
> +       gpio-bank = <0>;
>         ngpios = <18>;
>  }
>
> --
> 2.4.3
>
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] gpio: dt-bindings: document the concept of GPIO banks

[Nicolas Ferre]

Le 31/03/2016 15:22, Rob Herring a écrit :
> On Thu, Mar 31, 2016 at 4:10 AM, Linus Walleij <linus.walleij@linaro.org> wrote:
>> Cc: devicetree@vger.kernel.org
>> Cc: Neil Armstrong <narmstrong@baylibre.com>
>> Cc: Rob Herring <robh@kernel.org>
>> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> 
> We generally avoid indexing blocks in DT.
> 
>> ---
>>  Documentation/devicetree/bindings/gpio/gpio.txt | 14 ++++++++++++++
>>  1 file changed, 14 insertions(+)
>>
>> diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
>> index 069cdf6f9dac..f509ecf03ece 100644
>> --- a/Documentation/devicetree/bindings/gpio/gpio.txt
>> +++ b/Documentation/devicetree/bindings/gpio/gpio.txt
>> @@ -131,6 +131,19 @@ Every GPIO controller node must contain both an empty "gpio-controller"
>>  property, and a #gpio-cells integer property, which indicates the number of
>>  cells in a gpio-specifier.
>>
>> +Some system-on-chips (SoCs) use the concept of GPIO banks. A GPIO bank is an
>> +instance of a hardware IP core on a silicon die, usually exposed to the
>> +programmer as a coherent range of I/O addresses. Usually each such bank is
>> +exposed in the device tree as an individual gpio-controller node, reflecting
>> +the fact that the hardware was synthesized by reusing the same IP block a
>> +few times over.
>> +
>> +A GPIO controller may specify a bank ID. This is a hardware index that
>> +indicate the logical order of the GPIO controller in the hardware architecture,
>> +usually in the sequence 0, 1, 2 .. n. The hardware index may be different
>> +from the order of register ranges and related to the backplane of how this
>> +one bank is connected to the outside through a pin controller for example.
> 
> I still don't understand why do you need to know this? If you need
> some mapping of gpio nodes into pin controller, the pin controller
> should have a mapping using phandles.

We use aliases for this:

aliases {
    gpio0 = &pioA;
    gpio1 = &pioB;
    [..]
};

Bye,

>> +
>>  Optionally, a GPIO controller may have a "ngpios" property. This property
>>  indicates the number of in-use slots of available slots for GPIOs. The
>>  typical example is something like this: the hardware register is 32 bits
>> @@ -152,6 +165,7 @@ gpio-controller@00000000 {
>>         reg = <0x00000000 0x1000>;
>>         gpio-controller;
>>         #gpio-cells = <2>;
>> +       gpio-bank = <0>;
>>         ngpios = <18>;
>>  }
>>
>> --
>> 2.4.3
>>
> --
> To unsubscribe from this list: send the line "unsubscribe devicetree" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 


-- 
Nicolas Ferre
--
To unsubscribe from this list: send the line "unsubscribe linux-gpio" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] gpio: dt-bindings: document the concept of GPIO banks

[Rob Herring]

On Thu, Mar 31, 2016 at 8:30 AM, Nicolas Ferre <nicolas.ferre@atmel.com> wrote:
> Le 31/03/2016 15:22, Rob Herring a écrit :
>> On Thu, Mar 31, 2016 at 4:10 AM, Linus Walleij <linus.walleij@linaro.org> wrote:
>>> Cc: devicetree@vger.kernel.org
>>> Cc: Neil Armstrong <narmstrong@baylibre.com>
>>> Cc: Rob Herring <robh@kernel.org>
>>> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
>>
>> We generally avoid indexing blocks in DT.
>>
>>> ---
>>>  Documentation/devicetree/bindings/gpio/gpio.txt | 14 ++++++++++++++
>>>  1 file changed, 14 insertions(+)
>>>
>>> diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
>>> index 069cdf6f9dac..f509ecf03ece 100644
>>> --- a/Documentation/devicetree/bindings/gpio/gpio.txt
>>> +++ b/Documentation/devicetree/bindings/gpio/gpio.txt
>>> @@ -131,6 +131,19 @@ Every GPIO controller node must contain both an empty "gpio-controller"
>>>  property, and a #gpio-cells integer property, which indicates the number of
>>>  cells in a gpio-specifier.
>>>
>>> +Some system-on-chips (SoCs) use the concept of GPIO banks. A GPIO bank is an
>>> +instance of a hardware IP core on a silicon die, usually exposed to the
>>> +programmer as a coherent range of I/O addresses. Usually each such bank is
>>> +exposed in the device tree as an individual gpio-controller node, reflecting
>>> +the fact that the hardware was synthesized by reusing the same IP block a
>>> +few times over.
>>> +
>>> +A GPIO controller may specify a bank ID. This is a hardware index that
>>> +indicate the logical order of the GPIO controller in the hardware architecture,
>>> +usually in the sequence 0, 1, 2 .. n. The hardware index may be different
>>> +from the order of register ranges and related to the backplane of how this
>>> +one bank is connected to the outside through a pin controller for example.
>>
>> I still don't understand why do you need to know this? If you need
>> some mapping of gpio nodes into pin controller, the pin controller
>> should have a mapping using phandles.
>
> We use aliases for this:
>
> aliases {
>     gpio0 = &pioA;
>     gpio1 = &pioB;
>     [..]
> };

Which is a global number space that might not work in all cases. I
don't think gpio should be using aliases either. If you need to
describe the connections between nodes, then keep that between nodes.

Rob
--
To unsubscribe from this list: send the line "unsubscribe linux-gpio" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] gpio: dt-bindings: document the concept of GPIO banks

[Neil Armstrong]

On 03/31/2016 04:48 PM, Rob Herring wrote:
> On Thu, Mar 31, 2016 at 8:30 AM, Nicolas Ferre <nicolas.ferre@atmel.com> wrote:
>> Le 31/03/2016 15:22, Rob Herring a écrit :
>>> On Thu, Mar 31, 2016 at 4:10 AM, Linus Walleij <linus.walleij@linaro.org> wrote:
>>>> Cc: devicetree@vger.kernel.org
>>>> Cc: Neil Armstrong <narmstrong@baylibre.com>
>>>> Cc: Rob Herring <robh@kernel.org>
>>>> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
>>>
>>> We generally avoid indexing blocks in DT.
>>>
> 
> Which is a global number space that might not work in all cases. I
> don't think gpio should be using aliases either. If you need to
> describe the connections between nodes, then keep that between nodes.
> 
> Rob
> 

Couldn't we use gpio-ranges ?

Neil
--
To unsubscribe from this list: send the line "unsubscribe linux-gpio" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] gpio: dt-bindings: document the concept of GPIO banks

[Linus Walleij]

On Thu, Mar 31, 2016 at 4:52 PM, Neil Armstrong <narmstrong-rdvid1DuHRBWk0Htik3J/w@public.gmane.org> wrote:
> On 03/31/2016 04:48 PM, Rob Herring wrote:

>>>> We generally avoid indexing blocks in DT.
>>
>> Which is a global number space that might not work in all cases. I
>> don't think gpio should be using aliases either. If you need to
>> describe the connections between nodes, then keep that between nodes.
>
> Couldn't we use gpio-ranges ?

GPIO ranges are normally for cross-referencing GPIO blocks to
pin controllers but in essence, yes we *could*.

But what people will do is to use that backwards to calculate
the bank ID.

They would just get the GPIO base offset from the
range and /32 to get the bank ID. All over the place...
Also for GPIO controllers without pin control back-ends.

Yours,
Linus Walleij
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] gpio: dt-bindings: document the concept of GPIO banks

[Linus Walleij]

On Thu, Mar 31, 2016 at 3:22 PM, Rob Herring <robh@kernel.org> wrote:
> On Thu, Mar 31, 2016 at 4:10 AM, Linus Walleij <linus.walleij@linaro.org> wrote:

> We generally avoid indexing blocks in DT.

I am trying to come up with some standard way before I get
even more custom bindings slipping in. We have:

gpio-nmk.txt
   gpio-bank = <n>;

gpio_lpc32xx.txt
   #gpio-cells = <3>; /* bank, pin, flags */

microchip,pic32-gpio.txt
   microchip,gpio-bank = <n>;

The usecase Nicolas describe with aliases used for numbering
the controllers is the same as well.

So we presently have four ways of doing the same thing:

(1) In gpio-controller node:
     gpio-bank = <n>;
     microchip,gpio-bank = <n>;

(2) In the first GPIO specifier cell. (This is a bit special.)

(3) Using alias.

I could also invent something like:

hardware-block-iterator = <n>;
hwid = <n>;
etc

it would have the same effect. Something counting up
from zero.

They could also use (heaven forbid) the order in which
the banks are specified in the device tree. Or, as tz1090
does, the order of bank subnodes in a bigger gpio-controller
node.

>> +A GPIO controller may specify a bank ID. This is a hardware index that
>> +indicate the logical order of the GPIO controller in the hardware architecture,
>> +usually in the sequence 0, 1, 2 .. n.
(...)
> I still don't understand why do you need to know this?

One reason is to (maybe sneakily) get around encoding the
often-proposed linux-gpio-base = <n> property to map the
GPIOs of the bank to the global Linux GPIO numberspace.

By tradition that space begins at 0 and if e.g. each bank
has 32 GPIOs then the driver can calculate
the offset into the global space with:

linux-gpio-base = <gpio-bank> * 32;

So rather than encoding the pointless linux base number,
something less intrusive is encoded: the order of the
banks used when enumerating to a global scope.

Something like this was necessary for DT-ifying some old
systems as they relied on being able to control the
numberspace.

It has some physical counterpart: the pins in a datasheet
are often numbered 0..31, 32..63, 64.. etc corresponding
to the (bank number) * 32 + offset. Also for simple GPIOs
that are not pin control-enabled and not using pin control
as a back-end.

I think many operating systems may be using the same
concept of a fixed numberspace and then they also need
something like this: a hardware index ID starting from zero of
the GPIO bank. It's more neutral, as they can be doing
some other numberspace-slicing if they want.

> If you need
> some mapping of gpio nodes into pin controller, the pin controller
> should have a mapping using phandles.

It actually has the concept of gpio-range that maps a local
GPIO offset on a gpio-controller to a pin offset on a
pin controller, so we have a solution for that.

As Neil Armstrong suggests, it *could* be reused to
enumerate the banks but I'm not too happy about that.

Yours,
Linus Walleij