[PATCH v2] Documentation: gpio: consumer: describe the con_id parameter

[PATCH v2] Documentation: gpio: consumer: describe the con_id parameter

[Dirk Behme]

The con_id parameter has to match the GPIO description and is automatically
extended by the GPIO suffix if not NULL. I had to look into the code to
understand this and properly find the GPIO I've been looking for, so document
this.

Signed-off-by: Dirk Behme <dirk.behme@gmail.com>
Acked-by: Alexandre Courbot <acourbot@nvidia.com>
---
Changes in v2: Incorporate the review comments from Alexandre.

 Documentation/gpio/consumer.txt | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt
index 75542b9..5f7437b 100644
--- a/Documentation/gpio/consumer.txt
+++ b/Documentation/gpio/consumer.txt
@@ -39,6 +39,19 @@ device that displays digits), an additional index argument can be specified:
 					  const char *con_id, unsigned int idx,
 					  enum gpiod_flags flags)
 
+The con_id string parameter has to be either NULL or the prefix of the GPIO
+suffixes ("gpios" or "gpio", automatically looked up by the gpiod functions
+internally):
+
+* If the GPIO description is just named with one of the GPIO suffixes
+  ("gpios" or "gpio"), use NULL.
+* If the GPIO description is prefixed with anything, e.g. "reset-gpios", use the
+  prefix without the "-" as con_id parameter (in this example "reset").
+
+In case con_id is not NULL, the GPIO subsystem prefixes the GPIO suffix
+("gpios" or "gpio") with the string passed in con_id to get the resulting string
+(snprintf(... "%s-%s", con_id, gpio_suffixes[]).
+
 The flags parameter is used to optionally specify a direction and initial value
 for the GPIO. Values can be:
 
-- 
2.4.6

Re: [PATCH v2] Documentation: gpio: consumer: describe the con_id parameter

[Alexandre Courbot]

On Sat, Jul 18, 2015 at 3:24 PM, Dirk Behme <dirk.behme@gmail.com> wrote:
> The con_id parameter has to match the GPIO description and is automatically
> extended by the GPIO suffix if not NULL. I had to look into the code to
> understand this and properly find the GPIO I've been looking for, so document
> this.
>
> Signed-off-by: Dirk Behme <dirk.behme@gmail.com>
> Acked-by: Alexandre Courbot <acourbot@nvidia.com>
> ---
> Changes in v2: Incorporate the review comments from Alexandre.
>
>  Documentation/gpio/consumer.txt | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
>
> diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt
> index 75542b9..5f7437b 100644
> --- a/Documentation/gpio/consumer.txt
> +++ b/Documentation/gpio/consumer.txt
> @@ -39,6 +39,19 @@ device that displays digits), an additional index argument can be specified:
>                                           const char *con_id, unsigned int idx,
>                                           enum gpiod_flags flags)
>
> +The con_id string parameter has to be either NULL or the prefix of the GPIO
> +suffixes ("gpios" or "gpio", automatically looked up by the gpiod functions
> +internally):
> +
> +* If the GPIO description is just named with one of the GPIO suffixes
> +  ("gpios" or "gpio"), use NULL.
> +* If the GPIO description is prefixed with anything, e.g. "reset-gpios", use the
> +  prefix without the "-" as con_id parameter (in this example "reset").
> +
> +In case con_id is not NULL, the GPIO subsystem prefixes the GPIO suffix
> +("gpios" or "gpio") with the string passed in con_id to get the resulting string
> +(snprintf(... "%s-%s", con_id, gpio_suffixes[]).

Ah, there is still an issue with this description. It is correct as
far as GPIOs are assigned by the device tree ; but it turns out that
we have two other ways of assigning GPIOs: ACPI and platform data.
Have a look at the board.txt file which describes how this works. And
actually, instead of repeating the same stuff in consumer.txt, maybe
we can just redirect the reader to the other file?

Re: [PATCH v2] Documentation: gpio: consumer: describe the con_id parameter

[Dirk Behme]

On 21.07.2015 07:12, Alexandre Courbot wrote:
> On Sat, Jul 18, 2015 at 3:24 PM, Dirk Behme <dirk.behme@gmail.com> wrote:
>> The con_id parameter has to match the GPIO description and is automatically
>> extended by the GPIO suffix if not NULL. I had to look into the code to
>> understand this and properly find the GPIO I've been looking for, so document
>> this.
>>
>> Signed-off-by: Dirk Behme <dirk.behme@gmail.com>
>> Acked-by: Alexandre Courbot <acourbot@nvidia.com>
>> ---
>> Changes in v2: Incorporate the review comments from Alexandre.
>>
>>   Documentation/gpio/consumer.txt | 13 +++++++++++++
>>   1 file changed, 13 insertions(+)
>>
>> diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt
>> index 75542b9..5f7437b 100644
>> --- a/Documentation/gpio/consumer.txt
>> +++ b/Documentation/gpio/consumer.txt
>> @@ -39,6 +39,19 @@ device that displays digits), an additional index argument can be specified:
>>                                            const char *con_id, unsigned int idx,
>>                                            enum gpiod_flags flags)
>>
>> +The con_id string parameter has to be either NULL or the prefix of the GPIO
>> +suffixes ("gpios" or "gpio", automatically looked up by the gpiod functions
>> +internally):
>> +
>> +* If the GPIO description is just named with one of the GPIO suffixes
>> +  ("gpios" or "gpio"), use NULL.
>> +* If the GPIO description is prefixed with anything, e.g. "reset-gpios", use the
>> +  prefix without the "-" as con_id parameter (in this example "reset").
>> +
>> +In case con_id is not NULL, the GPIO subsystem prefixes the GPIO suffix
>> +("gpios" or "gpio") with the string passed in con_id to get the resulting string
>> +(snprintf(... "%s-%s", con_id, gpio_suffixes[]).
>
> Ah, there is still an issue with this description. It is correct as
> far as GPIOs are assigned by the device tree ; but it turns out that
> we have two other ways of assigning GPIOs: ACPI and platform data.
> Have a look at the board.txt file which describes how this works. And
> actually, instead of repeating the same stuff in consumer.txt, maybe
> we can just redirect the reader to the other file?


Please have a look to

http://article.gmane.org/gmane.linux.kernel.gpio/9816

http://article.gmane.org/gmane.linux.kernel.gpio/9815

They should replace this patch, then.

Best regards

Dirk