diff options
Diffstat (limited to 'Documentation/gpio')
| -rw-r--r-- | Documentation/gpio/00-INDEX | 14 | ||||
| -rw-r--r-- | Documentation/gpio/board.txt | 28 | ||||
| -rw-r--r-- | Documentation/gpio/consumer.txt | 7 | ||||
| -rw-r--r-- | Documentation/gpio/driver.txt | 94 |
4 files changed, 131 insertions, 12 deletions
diff --git a/Documentation/gpio/00-INDEX b/Documentation/gpio/00-INDEX new file mode 100644 index 00000000000..1de43ae46ae --- /dev/null +++ b/Documentation/gpio/00-INDEX @@ -0,0 +1,14 @@ +00-INDEX + - This file +gpio.txt + - Introduction to GPIOs and their kernel interfaces +consumer.txt + - How to obtain and use GPIOs in a driver +driver.txt + - How to write a GPIO driver +board.txt + - How to assign GPIOs to a consumer device and a function +sysfs.txt + - Information about the GPIO sysfs interface +gpio-legacy.txt + - Historical documentation of the deprecated GPIO integer interface diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt index 0d03506f2cc..ba169faad5c 100644 --- a/Documentation/gpio/board.txt +++ b/Documentation/gpio/board.txt @@ -72,10 +72,11 @@ where - chip_label is the label of the gpiod_chip instance providing the GPIO - chip_hwnum is the hardware number of the GPIO within the chip - - dev_id is the identifier of the device that will make use of this GPIO. If - NULL, the GPIO will be available to all devices. + - dev_id is the identifier of the device that will make use of this GPIO. It + can be NULL, in which case it will be matched for calls to gpiod_get() + with a NULL device. - con_id is the name of the GPIO function from the device point of view. It - can be NULL. + can be NULL, in which case it will match any function. - idx is the index of the GPIO within the function. - flags is defined to specify the following properties: * GPIOF_ACTIVE_LOW - to configure the GPIO as active-low @@ -86,18 +87,23 @@ In the future, these flags might be extended to support more properties. Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0. -A lookup table can then be defined as follows: +A lookup table can then be defined as follows, with an empty entry defining its +end: - struct gpiod_lookup gpios_table[] = { - GPIO_LOOKUP_IDX("gpio.0", 15, "foo.0", "led", 0, GPIO_ACTIVE_HIGH), - GPIO_LOOKUP_IDX("gpio.0", 16, "foo.0", "led", 1, GPIO_ACTIVE_HIGH), - GPIO_LOOKUP_IDX("gpio.0", 17, "foo.0", "led", 2, GPIO_ACTIVE_HIGH), - GPIO_LOOKUP("gpio.0", 1, "foo.0", "power", GPIO_ACTIVE_LOW), - }; +struct gpiod_lookup_table gpios_table = { + .dev_id = "foo.0", + .table = { + GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH), + GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH), + GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH), + GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW), + { }, + }, +}; And the table can be added by the board code as follows: - gpiod_add_table(gpios_table, ARRAY_SIZE(gpios_table)); + gpiod_add_lookup_table(&gpios_table); The driver controlling "foo.0" will then be able to obtain its GPIOs as follows: diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index 07c74a3765a..d8abfc31abb 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -38,7 +38,11 @@ device that displays digits), an additional index argument can be specified: const char *con_id, unsigned int idx) Both functions return either a valid GPIO descriptor, or an error code checkable -with IS_ERR(). They will never return a NULL pointer. +with IS_ERR() (they will never return a NULL pointer). -ENOENT will be returned +if and only if no GPIO has been assigned to the device/function/index triplet, +other error codes are used for cases where a GPIO has been assigned but an error +occurred while trying to acquire it. This is useful to discriminate between mere +errors and an absence of GPIO for optional GPIO parameters. Device-managed variants of these functions are also defined: @@ -150,6 +154,7 @@ raw line value: void gpiod_set_raw_value(struct gpio_desc *desc, int value) int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc) void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value) + int gpiod_direction_output_raw(struct gpio_desc *desc, int value) The active-low state of a GPIO can also be queried using the following call: diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index 9da0bfa7478..fa9a0a8b373 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -62,6 +62,96 @@ 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. + +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. + +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. + +* 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. + +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. + +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 @@ -73,3 +163,7 @@ This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock is released: void gpiod_unlock_as_irq(struct gpio_desc *desc) + +When implementing an irqchip inside a GPIO driver, these two functions should +typically be called in the .startup() and .shutdown() callbacks from the +irqchip. |