123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272 |
- GPIO Descriptor Driver Interface
- ================================
- This document serves as a guide for GPIO chip drivers writers. Note that it
- describes the new descriptor-based interface. For a description of the
- deprecated integer-based GPIO interface please refer to gpio-legacy.txt.
- Each GPIO controller driver needs to include the following header, which defines
- the structures used to define a GPIO driver:
- #include <linux/gpio/driver.h>
- Internal Representation of GPIOs
- ================================
- Inside a GPIO driver, individual GPIOs are identified by their hardware number,
- which is a unique number between 0 and n, n being the number of GPIOs managed by
- the chip. This number is purely internal: the hardware number of a particular
- GPIO descriptor is never made visible outside of the driver.
- On top of this internal number, each GPIO also need to have a global number in
- the integer GPIO namespace so that it can be used with the legacy GPIO
- interface. Each chip must thus have a "base" number (which can be automatically
- assigned), and for each GPIO the global number will be (base + hardware number).
- Although the integer representation is considered deprecated, it still has many
- users and thus needs to be maintained.
- So for example one platform could use numbers 32-159 for GPIOs, with a
- controller defining 128 GPIOs at a "base" of 32 ; while another platform uses
- numbers 0..63 with one set of GPIO controllers, 64-79 with another type of GPIO
- controller, and on one particular board 80-95 with an FPGA. The numbers need not
- be contiguous; either of those platforms could also use numbers 2000-2063 to
- identify GPIOs in a bank of I2C GPIO expanders.
- Controller Drivers: gpio_chip
- =============================
- In the gpiolib framework each GPIO controller is packaged as a "struct
- gpio_chip" (see linux/gpio/driver.h for its complete definition) with members
- common to each controller of that type:
- - methods to establish GPIO direction
- - methods used to access GPIO values
- - method to return the IRQ number associated to a given GPIO
- - flag saying whether calls to its methods may sleep
- - optional debugfs dump method (showing extra state like pullup config)
- - optional base number (will be automatically assigned if omitted)
- - label for diagnostics and GPIOs mapping using platform data
- The code implementing a gpio_chip should support multiple instances of the
- controller, possibly using the driver model. That code will configure each
- gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be rare;
- use gpiochip_remove() when it is unavoidable.
- Most often a gpio_chip is part of an instance-specific structure with state not
- exposed by the GPIO interfaces, such as addressing, power management, and more.
- Chips such as codecs will have complex non-GPIO state.
- Any debugfs dump method should normally ignore signals which haven't been
- requested as GPIOs. They can use gpiochip_is_requested(), which returns either
- NULL or the label associated with that GPIO when it was requested.
- RT_FULL: GPIO driver should not use spinlock_t or any sleepable APIs
- (like PM runtime) in its gpio_chip implementation (.get/.set and direction
- control callbacks) if it is expected to call GPIO APIs from atomic context
- on -RT (inside hard IRQ handlers and similar contexts). Normally this should
- not be required.
- GPIO drivers providing IRQs
- ---------------------------
- It is custom that GPIO drivers (GPIO chips) are also providing interrupts,
- most often cascaded off a parent interrupt controller, and in some special
- cases the GPIO logic is melded with a SoC's primary interrupt controller.
- The IRQ portions of the GPIO block are implemented using an irqchip, using
- the header <linux/irq.h>. So basically such a driver is utilizing two sub-
- systems simultaneously: gpio and irq.
- RT_FULL: GPIO driver should not use spinlock_t or any sleepable APIs
- (like PM runtime) as part of its irq_chip implementation on -RT.
- - spinlock_t should be replaced with raw_spinlock_t [1].
- - If sleepable APIs have to be used, these can be done from the .irq_bus_lock()
- and .irq_bus_unlock() callbacks, as these are the only slowpath callbacks
- on an irqchip. Create the callbacks if needed [2].
- GPIO irqchips usually fall in one of two categories:
- * CHAINED GPIO irqchips: these are usually the type that is embedded on
- an SoC. This means that there is a fast IRQ handler for the GPIOs that
- gets called in a chain from the parent IRQ handler, most typically the
- system interrupt controller. This means the GPIO irqchip is registered
- using irq_set_chained_handler() or the corresponding
- gpiochip_set_chained_irqchip() helper function, and the GPIO irqchip
- handler will be called immediately from the parent irqchip, while
- holding the IRQs disabled. The GPIO irqchip will then end up calling
- something like this sequence in its interrupt handler:
- static irqreturn_t tc3589x_gpio_irq(int irq, void *data)
- chained_irq_enter(...);
- generic_handle_irq(...);
- chained_irq_exit(...);
- Chained GPIO irqchips typically can NOT set the .can_sleep flag on
- struct gpio_chip, as everything happens directly in the callbacks.
- RT_FULL: Note, chained IRQ handlers will not be forced threaded on -RT.
- As result, spinlock_t or any sleepable APIs (like PM runtime) can't be used
- in chained IRQ handler.
- if required (and if it can't be converted to the nested threaded GPIO irqchip)
- - chained IRQ handler can be converted to generic irq handler and this way
- it will be threaded IRQ handler on -RT and hard IRQ handler on non-RT
- (for example, see [3]).
- Know W/A: The generic_handle_irq() is expected to be called with IRQ disabled,
- so IRQ core will complain if it will be called from IRQ handler wich is forced
- thread. The "fake?" raw lock can be used to W/A this problem:
- raw_spinlock_t wa_lock;
- static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank)
- unsigned long wa_lock_flags;
- raw_spin_lock_irqsave(&bank->wa_lock, wa_lock_flags);
- generic_handle_irq(irq_find_mapping(bank->chip.irqdomain, bit));
- raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags);
- * GENERIC CHAINED GPIO irqchips: these are the same as "CHAINED GPIO irqchips",
- but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is
- performed by generic IRQ handler which is configured using request_irq().
- The GPIO irqchip will then end up calling something like this sequence in
- its interrupt handler:
- static irqreturn_t gpio_rcar_irq_handler(int irq, void *dev_id)
- for each detected GPIO IRQ
- generic_handle_irq(...);
- RT_FULL: Such kind of handlers will be forced threaded on -RT, as result IRQ
- core will complain that generic_handle_irq() is called with IRQ enabled and
- the same W/A as for "CHAINED GPIO irqchips" can be applied.
- * NESTED THREADED GPIO irqchips: these are off-chip GPIO expanders and any
- other GPIO irqchip residing on the other side of a sleeping bus. Of course
- such drivers that need slow bus traffic to read out IRQ status and similar,
- traffic which may in turn incur other IRQs to happen, cannot be handled
- in a quick IRQ handler with IRQs disabled. Instead they need to spawn a
- thread and then mask the parent IRQ line until the interrupt is handled
- by the driver. The hallmark of this driver is to call something like
- this in its interrupt handler:
- static irqreturn_t tc3589x_gpio_irq(int irq, void *data)
- ...
- handle_nested_irq(irq);
- The hallmark of threaded GPIO irqchips is that they set the .can_sleep
- flag on struct gpio_chip to true, indicating that this chip may sleep
- when accessing the GPIOs.
- To help out in handling the set-up and management of GPIO irqchips and the
- associated irqdomain and resource allocation callbacks, the gpiolib has
- some helpers that can be enabled by selecting the GPIOLIB_IRQCHIP Kconfig
- symbol:
- * gpiochip_irqchip_add(): adds an irqchip to a gpiochip. It will pass
- the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks
- need to embed the gpio_chip in its state container and obtain a pointer
- to the container using container_of().
- (See Documentation/driver-model/design-patterns.txt)
- * gpiochip_set_chained_irqchip(): sets up a chained irq handler for a
- gpio_chip from a parent IRQ and passes the struct gpio_chip* as handler
- data. (Notice handler data, since the irqchip data is likely used by the
- parent irqchip!) This is for the chained type of chip. This is also used
- to set up a nested irqchip if NULL is passed as handler.
- To use the helpers please keep the following in mind:
- - Make sure to assign all relevant members of the struct gpio_chip so that
- the irqchip can initialize. E.g. .dev and .can_sleep shall be set up
- properly.
- - Nominally set all handlers to handle_bad_irq() in the setup call and pass
- handle_bad_irq() as flow handler parameter in gpiochip_irqchip_add() if it is
- expected for GPIO driver that irqchip .set_type() callback have to be called
- before using/enabling GPIO IRQ. Then set the handler to handle_level_irq()
- and/or handle_edge_irq() in the irqchip .set_type() callback depending on
- what your controller supports.
- It is legal for any IRQ consumer to request an IRQ from any irqchip no matter
- if that is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and
- irq_chip are orthogonal, and offering their services independent of each
- other.
- gpiod_to_irq() is just a convenience function to figure out the IRQ for a
- certain GPIO line and should not be relied upon to have been called before
- the IRQ is used.
- So always prepare the hardware and make it ready for action in respective
- callbacks from the GPIO and irqchip APIs. Do not rely on gpiod_to_irq() having
- been called first.
- This orthogonality leads to ambiguities that we need to solve: if there is
- competition inside the subsystem which side is using the resource (a certain
- GPIO line and register for example) it needs to deny certain operations and
- keep track of usage inside of the gpiolib subsystem. This is why the API
- below exists.
- Locking IRQ usage
- -----------------
- Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
- to mark the GPIO as being used as an IRQ:
- int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset)
- This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
- is released:
- void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset)
- When implementing an irqchip inside a GPIO driver, these two functions should
- typically be called in the .startup() and .shutdown() callbacks from the
- irqchip.
- Real-Time compliance for GPIO IRQ chips
- ---------------------------------------
- Any provider of irqchips needs to be carefully tailored to support Real Time
- preemption. It is desireable that all irqchips in the GPIO subsystem keep this
- in mind and does the proper testing to assure they are real time-enabled.
- So, pay attention on above " RT_FULL:" notes, please.
- The following is a checklist to follow when preparing a driver for real
- time-compliance:
- - ensure spinlock_t is not used as part irq_chip implementation;
- - ensure that sleepable APIs are not used as part irq_chip implementation.
- If sleepable APIs have to be used, these can be done from the .irq_bus_lock()
- and .irq_bus_unlock() callbacks;
- - Chained GPIO irqchips: ensure spinlock_t or any sleepable APIs are not used
- from chained IRQ handler;
- - Generic chained GPIO irqchips: take care about generic_handle_irq() calls and
- apply corresponding W/A;
- - Chained GPIO irqchips: get rid of chained IRQ handler and use generic irq
- handler if possible :)
- - regmap_mmio: Sry, but you are in trouble :( if MMIO regmap is used as for
- GPIO IRQ chip implementation;
- - Test your driver with the appropriate in-kernel real time test cases for both
- level and edge IRQs.
- Requesting self-owned GPIO pins
- -------------------------------
- Sometimes it is useful to allow a GPIO chip driver to request its own GPIO
- descriptors through the gpiolib API. Using gpio_request() for this purpose
- does not help since it pins the module to the kernel forever (it calls
- try_module_get()). A GPIO driver can use the following functions instead
- to request and free descriptors without being pinned to the kernel forever.
- struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc,
- const char *label)
- void gpiochip_free_own_desc(struct gpio_desc *desc)
- Descriptors requested with gpiochip_request_own_desc() must be released with
- gpiochip_free_own_desc().
- These functions must be used with care since they do not affect module use
- count. Do not use the functions to request gpio descriptors not owned by the
- calling driver.
- [1] http://www.spinics.net/lists/linux-omap/msg120425.html
- [2] https://lkml.org/lkml/2015/9/25/494
- [3] https://lkml.org/lkml/2015/9/25/495
|