2

Update at 2020/10/31

Thanks for 0andriy asking the question on mailing list. And Alexandre Courbot aka Gunurou answered my question!

I have to thank 0andriy again! Your are the true hero behind this question.


Old Question:

This question seems like typo in documentation, but I want to double check.

My question is the last two paragraphs in the last section of GPIO Descriptor Consumer Interface.

the following two functions allow you to convert a GPIO descriptor into the GPIO integer namespace and vice-versa:

int desc_to_gpio(const struct gpio_desc *desc)
struct gpio_desc *gpio_to_desc(unsigned gpio)

The GPIO number returned by desc_to_gpio() can be safely used as long as the GPIO descriptor has not been freed. All the same, a GPIO number passed to gpio_to_desc() must have been properly acquired, and usage of the returned GPIO descriptor is only possible after the GPIO number has been released.

Freeing a GPIO obtained by one API with the other API is forbidden and an unchecked error.

My understanding for each sentence

The GPIO number returned by desc_to_gpio() can be safely used as long as the GPIO descriptor has not been freed.

Any GPIO pin could be use before gpiod_put() free the descriptor. Following is pseudo code for my understanding.

struct gpio_desc desc = gpiod_get(...);
gpio pin = desc_to_gpio(desc);

// operation here

gpiod_put(desc);

All the same, a GPIO number passed to gpio_to_desc() must have been properly acquired, and usage of the returned GPIO descriptor is only possible after the GPIO number has been released.

I'm confused with "All the same" and "usage of the returned GPIO descriptor is only possible after the GPIO number has been released".

If "All the same" applies, I presume gpio_desc could be used before gpio_free(). But "usage of the returned GPIO descriptor is only possible after the GPIO number has been released" makes me think I have to gpio_free() before using gpio_desc returned from gpio_to_desc().

To re-state my question, which of the following code snippet should be correct usage of gpio_to_desc()? I presume "usage of the returned GPIO descriptor" means the gpio_desc return from gpio_to_desc().

I thought second one should be incorrect, but I'd like to be confirmed with any documentation or example for it.

  1. Use gpio_desc before free.
    gpio pin = gpio_request( ... );
    struct gpio_desc desc = gpio_to_desc(pin);
    
    // gpiod operation here, before free
    
    gpio_free(gpio_desc)
  1. Using gpio_desc AFTER free.
    gpio pin = gpio_request( ... );
    struct gpio_desc desc = gpio_to_desc(pin);
    gpio_free(gpio_desc)
    
    // gpiod operation here, after free

In other words, should

"usage of the returned GPIO descriptor is only possible after the GPIO number has been released"

be changed to

"usage of the returned GPIO descriptor is only possible before the GPIO number has been released"?


Side question

According to this sentence.

Freeing a GPIO obtained by one API with the other API is forbidden and an unchecked error.

Should I NOT release the gpio_desc with gpiod_put() returned by gpio_to_desc()?


Keywords on Google.

  • gpio_to_desc() must gpio_free() first

    No offical articles mention about it.

  • gpio_to_desc() gpiod_put()

    I found header files. However it doesn't explain it.

6
  • Thanks @0andriy, let me delete my comments before they cause more confusion! Oct 21, 2020 at 13:10
  • 1
    @MarcoBonelli, Louis, to be on cnstructrive side I have dug into the Git history. So it was a ~1 year period of time when this chapter used to be correct. But world is changing... Some details in the thread: lore.kernel.org/linux-gpio/… Sorry for misleading.
    – 0andriy
    Oct 29, 2020 at 17:34
  • @0andriy oh you actually asked on the GPIO mailing list, nice! That makes more sense now. You should turn that into an answer :) Oct 29, 2020 at 17:39
  • @0andriy Thanks for asking the question! Your work deserves an answer :)
    – Louis Go
    Oct 30, 2020 at 0:35
  • 1
    @MarcoBonelli, you got the answer by the author of that documentation :-)
    – 0andriy
    Oct 30, 2020 at 14:43

2 Answers 2

3

The short answer to this question is don't ever call these functions. They have been obsolete since 2014 and there should be no reason for new code to use them. New code should only rely on the gpiod_*() family of functions, and never work with GPIO numbers.

If you deal with old code, the safest thing to do is to convert it to use the gpiod interface first thing.

Now if you absolutely need to work with these functions, my recollection is that the following usages are valid (copied from your question):

struct gpio_desc desc = gpiod_get(...);
gpio pin = desc_to_gpio(desc);

// operation here

gpiod_put(desc);
gpio pin = gpio_request( ... );
struct gpio_desc desc = gpio_to_desc(pin);
   
// gpiod operation here, before free
  
gpio_free(gpio_desc)

That's because the gpio_*() family of functions are built on top of the gpiod interface, as you can see in drivers/gpio/gpiolib-legacy.c. So the descriptor corresponding to the GPIO number you requested will have been acquired by gpiod_request(), and thus is guaranteed to remain valid until gpio_free() (which really just calls gpiod_free() is invoked.

As for your side question:

Should I NOT release the gpio_desc with gpiod_put() returned by gpio_to_desc()?

That's correct, you should never do that. At the moment the APIs are built in such a way that doing so might work, but there is no guarantee they will not diverge in the future. Also if you acquired a descriptor, there is no reason why you could not keep it around to free it using the correct API.

But again, the best thing to do is assume that these functions do not exist, and use gpiod everywhere you can.

0

All the same, a GPIO number passed to gpio_to_desc() must have been properly acquired, and usage of the returned GPIO descriptor is only possible after the GPIO number has been released.

Shouldn't after be changed to before?

Probably neither of them. I guess that the sentence wants to express not to mix legacy gpio_XXX and modern gpiod_XXX APIs. E.g. to release gpio resources before working with gpiod ones.

You are right, that using the descriptor after gpio_free() is wrong.

In practice, the kernel violates the stated sentence itself because nearly every gpio operation uses gpio_to_desc(). E.g.

void gpio_free(unsigned gpio)
{
    gpiod_free(gpio_to_desc(gpio));
}

or

static inline void __gpio_set_value(unsigned gpio, int value)
{
    return gpiod_set_raw_value(gpio_to_desc(gpio), value);
}

Both gpio_to_desc() and desc_to_gpio() do not acquire resources but return pointers to existing objects:

struct gpio_desc *gpio_to_desc(unsigned gpio)
{
  ...
            return &gdev->descs[gpio - gdev->base];
}
int desc_to_gpio(const struct gpio_desc *desc)
{
    return desc->gdev->base + (desc - &desc->gdev->descs[0]);
}
3
  • I thought "usage of the returned GPIO descriptor" means the return gpio_desc from gpio_to_desc and "GPIO number has been released." means the argument of gpio_to_desc. After your explaination, I presume the latter sentence "Freeing..." should be taken into account when reading "All the same...".
    – Louis Go
    Oct 22, 2020 at 0:20
  • @0andry: no; gpio_free() calls gpiod_free() which can render the information within the descriptor invalid (e.g. it does a module_put(desc->gdev->owner))
    – ensc
    Oct 22, 2020 at 10:46
  • I would argue that if the intended usage of the API is to first free() and then use the object, then it's completely insane. I would not expect Linus to approve something like this. Oct 22, 2020 at 14:25

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.