gpio api
GPIO API
Motivation: On many of the little Linux devices I've seen, there are multiple chips providing GPIO and in many cases GPIO pins from one chip are used to control unrelated functions. The first approach I took to solving this problem was to implement a per-function framework. I wrote the first version of the lcd_device and backlight_device framework to separate out the platform-specific parts of a framebuffer video driver from the framebuffer chip parts. (That framework was finished by Andrew Zabolotny and has been accepted into the main kernel tree.) However, such a framework is quite a bit of overhead for very simple controls, so I think it would be worthwhile to have a generic GPIO API.
My initial thought was to provide a synchronous API for configuring GPIO mode and setting and getting values. However, GPIOs are sometimes implemented by chips on slow buses such as I2C and SPI, so an asynchronous interface should be provided. For example, a bus extender such as the MAX7317 provides a set of GPIO pins accessible via SPI. There are similar I2C parts. Since SPI and I2C are much slower than CPU speeds, it seems best to treat operations on those GPIO pins as asynchronous. The SPI bus used to reach the MAX7317 could in turn be implemented by other onchip GPIO pins. The next question is to separate the sync and async APIs or combine them. I have a feeling that if two separate sets of calls are provided that people using boards with async GPIOs will end up having to rewrite drivers.
This proposal provides an async interface via a callback registered via request_gpio. If a driver supports async operations, it should provide flags GPIOF_SYNC|GPIOF_ASYNC, a non-NULL callback. This will work for both sync and async gpios. If a driver only supports sync GPIOs, then it should only provide the GPIOF_SYNC flag and a NULL callback. If at runtime the requested gpio is async, then request_gpio will return -EINVAL. It is a BUG to go ahead and call set_gpio_mode, set_gpio_value, or get_gpio_value on an async gpio without registering a callback.
Platform GPIO Resource
In order to use platform_device to specify the GPIOs used by a device, we need a definition of IORESOURCE_GPIO.
#define IORESOURCE_GPIO 0x08000000
An alternative is to reuse IORESOURCE_IRQ with a flag set.
#define IORESOURCE_IRQ_GPIO (1<<4)
SYFS Interface to GPIOs
For debugging purposes and for one-off gpio uses, it is very useful to have a userspace interface to particular gpios. However, exposing all gpios this way is a grave security (denial of service) and possibly safety risk. The implementation will include an optional sysfs interface that exposes unrequested GPIOs that have their GPIOF_SYSFS flag set.
One of the flags could enable a gpio sysfs module to expose the GPIO to user space. I am in favor of a sysfs module that only has access to explicitly exposed GPIOs, as you did in your driver.
GPIO Client Driver API
The first two calls are analogous to request_irq/free_irq, so that driver can ensure that they have exclusive access to a GPIO and can specify asynchronous or synchronous access. I have run into problems due to out-of-date or misconfigured drivers that would be prevented by the use of these calls.
#define GPIOF_SYNC (1 << 0) #define GPIOF_ASYNC (1 << 1) #define GPIOF_SYSFS (1 << 2) #define GPIOF_VALID (1 << 3)
int request_gpio(int gpio_num, const char *name,
void (*callback)(int gpionum, void *devid), int flags, void *devid);
void free_gpio(int gpio_num, void *devid);
It is a BUG to supply a NULL callback if GPIO is successfully requested with GPIOF_ASYNCH set. [Alternatively, split into sync and async calls and consider it a BUG to use the synchronous calls on a GPIO requested with GPIOF_ASYNC set.]
int set_gpio_mode(int gpionum, int modeflags); int set_gpio_value(int gpionum, int value); int get_gpio_value(int gpionum);
GPIO Provider API
struct gpiochip {
int (*set)(struct gpiochip *chip, void *context, int value);
int (*get)(struct gpiochip *chip void *context);
int (*mode)(struct gpiochip *chip, void *context, int modeflags);
};GPIOs are associated with gpiochip instances by calling set_gpio_chip. If the -1 is provided as the gpionum, then the next free gpionum is returned. If a positive gpionum is provided and it is already allocated, then -EINVAL is returned. If there are no free gpionums, then -ENOMEM is returned.
int set_gpio_chip(int gpionum, struct gpiochip *chip, void *context,
int flags);
int free_gpio_chip(int gpionum);
=end-of-proposal=
Quoted 14 lines · Jamey Hicks
GPIO Client Driver API
The first two calls are analogous to request_irq/free_irq, so that driver can ensure that they have exclusive access to a GPIO and can specify asynchronous or synchronous access. I have run into problems due to out-of-date or misconfigured drivers that would be prevented by the use of these calls.
#define GPIOF_SYNC (1 << 0) #define GPIOF_ASYNC (1 << 1) #define GPIOF_SYSFS (1 << 2) #define GPIOF_VALID (1 << 3)
Quoted 8 lines
int request_gpio(int
gpio_num, const char *name,void (*callback)(int gpionum, void *devid), int flags, void *devid);void
free_gpio(int gpio_num, void *devid);It is a BUG to supply a NULL callback if GPIO is successfully requested with
GPIOF_ASYNCHset. [Alternatively, split into sync and async calls and consider it a BUG to use the synchronous calls on a GPIO requested withGPIOF_ASYNCset.]
Don't split the interface. BUG_ON((flags&GPIOF_ASYNC) && !callback) might be a good idea, but most likely there are valid reasons for NULL callbacks as well.
Also, it's not unusual to request several pins at one. If the requester can simply provide a bitmask, the calling code is *much* simpler.
Quoted 3 lines
int set_gpio_mode(int gpionum, int modeflags); int set_gpio_value(int gpionum, int value); int get_gpio_value(int gpionum);
These functions either lack a struct gpiochip argument or could be omitted completely.
Quoted 7 lines
GPIO Provider API
struct gpiochip { int (*set)(struct gpiochip *chip, void *context, int value); int (*get)(struct gpiochip *chip void *context); int (*mode)(struct gpiochip *chip, void *context, int modeflags); };
A private structure is surely needed, no?
Overall, I like the idea. Having a standard interface for gpio drivers makes life somewhat easier when writing a driver, and a *lot* easier when using one. With every driver having their own custom interface, some *will* end up broken and unusable.
Jörn
Signature · 2 lines
He that composes himself is wiser than he that composes a book. -- B. Franklin
I think that implementing a GPIO interface is a must-have. And I also think that your proposal is awesome. I work with GPIOs a lot, and I hate not doing it in a cross-platform way.
I generally agree with your proposal but I see some missing behaviours.
Configuration that should be done on GPIOs.
- GPIO direction (input/output)
- GPIO modes (standard CMOS / open drain).
- GPIO interruption generation (by level or edge, high, low, raising, falling)
The GPIOs requesting and numbering should be done by specifying the chip, the port and the pin. We should be able to manipulate easily a GPIO from one of 3 I2C chips and another one from our microprocessor.
We should be able to change several pins on the same port simultaneously (if the driver of the port allows it). Maybe, all the operations should be done by port (and not by pin), so that we can change several ports simultaneously. We should be able to register several pins of a port, and write and read from the port.
I'd like some comments about these features.
Signature · 1 line
Asier Llano Palacios <[email protected]>
Quoted 3 lines · Asier Llano Palacios
The GPIOs requesting and numbering should be done by specifying the chip, the port and the pin. We should be able to manipulate easily a GPIO from one of 3 I2C chips and another one from our microprocessor.
I think there's a problem with this approach:
- I2C chips require you to talk to them via a relatively slow bus. The I2C subsystem takes a semaphore, so it can be used from interrupt context.
- You may wish to use GPIOs (especially on-chip GPIOs) from interrupt context.
Therefore, you don't have a clear locking model for a GPIO subsystem. You'll probably be in the situation where some GPIOs may be locked by spinlocks (which are fine to manipulate from interrupt context) and others which are locked by semaphores - so you don't actually know what's going on beneath the GPIO API.
This is real bad news in terms of ensuring correctness and being able to review.
Signature · 1 line
Russell King
Quoted 5 lines · On Mon, 21 Feb 2005 11:02:24 +0100 Asier Llano Palacios <[email protected]>…
I think that implementing a GPIO interface is a must-have. And I also think that your proposal is awesome. I work with GPIOs a lot, and I hate not doing it in a cross-platform way.
I generally agree with your proposal but I see some missing behaviours.
me too,
Quoted 3 lines
Configuration that should be done on GPIOs.
- GPIO direction (input/output)
- GPIO modes (standard CMOS / open drain).
I also need pull-up/pull-down.
Quoted 2 lines
- GPIO interruption generation (by level or edge, high, low, raising, falling)
We also need a method that GPIO cascade to IRQ.
Yoichi