[PATCH] gpio: mention in DT binding doc that <name>-gpio is also supported

[PATCH] gpio: mention in DT binding doc that <name>-gpio is also supported

[Javier Martinez Canillas]

The GPIO DT binding doc mentions that GPIO are mapped by defining
a <name>-gpios property in the consumer device's node but a -gpio
sufix is also supported after commit:

dd34c37aa3e8 ("gpio: of: Allow -gpio suffix for property names")

Update the DT binding documentation to match the implementation.

Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>

---
Hello,

The GPIO documentation was updated to mention that the -gpio sufix
is also supported in patch https://lkml.org/lkml/2015/9/1/117 that
already landed in Torvalds tree.

I now noticed that the DT binding also only mentions -gpios so I'm
posting this patch that adds -gpio to the DT binding documentation.

Best regards,
Javier

 Documentation/devicetree/bindings/gpio/gpio.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
index 5788d5cf1252..8db8c7bb96c1 100644
--- a/Documentation/devicetree/bindings/gpio/gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio.txt
@@ -13,10 +13,10 @@ properties, each containing a 'gpio-list':
 	gpio-specifier : Array of #gpio-cells specifying specific gpio
 			 (controller specific)
 
-GPIO properties should be named "[<name>-]gpios", with <name> being the purpose
-of this GPIO for the device. While a non-existent <name> is considered valid
-for compatibility reasons (resolving to the "gpios" property), it is not allowed
-for new bindings.
+GPIO properties should be named "[<name>-]gpios" or "[<name>-]gpio" with <name>
+being the purpose of this GPIO for the device. While a non-existent <name> is
+considered valid for compatibility reasons (resolving to the "gpios" property),
+it is not allowed for new bindings.
 
 GPIO properties can contain one or more GPIO phandles, but only in exceptional
 cases should they contain more than one. If your device uses several GPIOs with
-- 
2.4.3

Re: [PATCH] gpio: mention in DT binding doc that <name>-gpio is also supported

[Alexandre Courbot]

On Thu, Sep 17, 2015 at 10:33 AM, Javier Martinez Canillas
<javier@osg.samsung.com> wrote:
> The GPIO DT binding doc mentions that GPIO are mapped by defining
> a <name>-gpios property in the consumer device's node but a -gpio
> sufix is also supported after commit:
>
> dd34c37aa3e8 ("gpio: of: Allow -gpio suffix for property names")
>
> Update the DT binding documentation to match the implementation.
>
> Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
>
> ---
> Hello,
>
> The GPIO documentation was updated to mention that the -gpio sufix
> is also supported in patch https://lkml.org/lkml/2015/9/1/117 that
> already landed in Torvalds tree.
>
> I now noticed that the DT binding also only mentions -gpios so I'm
> posting this patch that adds -gpio to the DT binding documentation.

I think I remember that -gpio is considered obsolete and its use
should thus not be encouraged, which is the reason why the
documentation does not mention it. We could mention it and add a note
saying that it should not be used for new bindings, but all in all
isn't it better to keep the documentation clear of such use cases that
will not be accepted for new patches anyway?

>
> Best regards,
> Javier
>
>  Documentation/devicetree/bindings/gpio/gpio.txt | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
> index 5788d5cf1252..8db8c7bb96c1 100644
> --- a/Documentation/devicetree/bindings/gpio/gpio.txt
> +++ b/Documentation/devicetree/bindings/gpio/gpio.txt
> @@ -13,10 +13,10 @@ properties, each containing a 'gpio-list':
>         gpio-specifier : Array of #gpio-cells specifying specific gpio
>                          (controller specific)
>
> -GPIO properties should be named "[<name>-]gpios", with <name> being the purpose
> -of this GPIO for the device. While a non-existent <name> is considered valid
> -for compatibility reasons (resolving to the "gpios" property), it is not allowed
> -for new bindings.
> +GPIO properties should be named "[<name>-]gpios" or "[<name>-]gpio" with <name>
> +being the purpose of this GPIO for the device. While a non-existent <name> is
> +considered valid for compatibility reasons (resolving to the "gpios" property),
> +it is not allowed for new bindings.
>
>  GPIO properties can contain one or more GPIO phandles, but only in exceptional
>  cases should they contain more than one. If your device uses several GPIOs with
> --
> 2.4.3
>
> --
> 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: mention in DT binding doc that <name>-gpio is also supported

[Javier Martinez Canillas]

Hello Alexandre,

On 09/18/2015 05:44 PM, Alexandre Courbot wrote:
> On Thu, Sep 17, 2015 at 10:33 AM, Javier Martinez Canillas
> <javier@osg.samsung.com> wrote:
>> The GPIO DT binding doc mentions that GPIO are mapped by defining
>> a <name>-gpios property in the consumer device's node but a -gpio
>> sufix is also supported after commit:
>>
>> dd34c37aa3e8 ("gpio: of: Allow -gpio suffix for property names")
>>
>> Update the DT binding documentation to match the implementation.
>>
>> Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
>>
>> ---
>> Hello,
>>
>> The GPIO documentation was updated to mention that the -gpio sufix
>> is also supported in patch https://lkml.org/lkml/2015/9/1/117 that
>> already landed in Torvalds tree.
>>
>> I now noticed that the DT binding also only mentions -gpios so I'm
>> posting this patch that adds -gpio to the DT binding documentation.
> 
> I think I remember that -gpio is considered obsolete and its use
> should thus not be encouraged, which is the reason why the
> documentation does not mention it. We could mention it and add a note
> saying that it should not be used for new bindings, but all in all
> isn't it better to keep the documentation clear of such use cases that
> will not be accepted for new patches anyway?
>

I agree that if that's the case then it should be documented. Currently
by reading the docs there is no way to tell if -gpio was only added to
support old DT bindings and should not be used or if is that the docs
were not updated when <function>-gpio parsing was added to gpiolib.

I can re-spin the patch making it clear that even when the -gpio suffix
is supported, it's only there for compatibility reasons and should not
be used for newer bindings.

And also Documentation/gpio/board.txt has to be updated now since now it
mentions <function>-gpio but does not say that should not be used.

Best regards,
-- 
Javier Martinez Canillas
Open Source Group
Samsung Research America

Re: [PATCH] gpio: mention in DT binding doc that <name>-gpio is also supported

[Alexandre Courbot]

On Sat, Sep 19, 2015 at 2:17 AM, Javier Martinez Canillas
<javier@osg.samsung.com> wrote:
> Hello Alexandre,
>
> On 09/18/2015 05:44 PM, Alexandre Courbot wrote:
>> On Thu, Sep 17, 2015 at 10:33 AM, Javier Martinez Canillas
>> <javier@osg.samsung.com> wrote:
>>> The GPIO DT binding doc mentions that GPIO are mapped by defining
>>> a <name>-gpios property in the consumer device's node but a -gpio
>>> sufix is also supported after commit:
>>>
>>> dd34c37aa3e8 ("gpio: of: Allow -gpio suffix for property names")
>>>
>>> Update the DT binding documentation to match the implementation.
>>>
>>> Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
>>>
>>> ---
>>> Hello,
>>>
>>> The GPIO documentation was updated to mention that the -gpio sufix
>>> is also supported in patch https://lkml.org/lkml/2015/9/1/117 that
>>> already landed in Torvalds tree.
>>>
>>> I now noticed that the DT binding also only mentions -gpios so I'm
>>> posting this patch that adds -gpio to the DT binding documentation.
>>
>> I think I remember that -gpio is considered obsolete and its use
>> should thus not be encouraged, which is the reason why the
>> documentation does not mention it. We could mention it and add a note
>> saying that it should not be used for new bindings, but all in all
>> isn't it better to keep the documentation clear of such use cases that
>> will not be accepted for new patches anyway?
>>
>
> I agree that if that's the case then it should be documented. Currently
> by reading the docs there is no way to tell if -gpio was only added to
> support old DT bindings and should not be used or if is that the docs
> were not updated when <function>-gpio parsing was added to gpiolib.
>
> I can re-spin the patch making it clear that even when the -gpio suffix
> is supported, it's only there for compatibility reasons and should not
> be used for newer bindings.
>
> And also Documentation/gpio/board.txt has to be updated now since now it
> mentions <function>-gpio but does not say that should not be used.

Sounds good. Thanks for taking care of this!