^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) GPIO Driver Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) This document serves as a guide for writers of GPIO chip drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Each GPIO controller driver needs to include the following header, which defines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) the structures used to define a GPIO driver::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) #include <linux/gpio/driver.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) Internal Representation of GPIOs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) ================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) A GPIO chip handles one or more GPIO lines. To be considered a GPIO chip, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) lines must conform to the definition: General Purpose Input/Output. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) line is not general purpose, it is not GPIO and should not be handled by a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) GPIO chip. The use case is the indicative: certain lines in a system may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) called GPIO but serve a very particular purpose thus not meeting the criteria
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) of a general purpose I/O. On the other hand a LED driver line may be used as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) GPIO and should therefore still be handled by a GPIO chip driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) Inside a GPIO driver, individual GPIO lines are identified by their hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) number, sometime also referred to as ``offset``, which is a unique number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) between 0 and n-1, n being the number of GPIOs managed by the chip.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) The hardware GPIO number should be something intuitive to the hardware, for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) example if a system uses a memory-mapped set of I/O-registers where 32 GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) lines are handled by one bit per line in a 32-bit register, it makes sense to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) use hardware offsets 0..31 for these, corresponding to bits 0..31 in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) register.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) This number is purely internal: the hardware number of a particular GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) line is never made visible outside of the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) On top of this internal number, each GPIO line also needs to have a global
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) number in the integer GPIO namespace so that it can be used with the legacy GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) interface. Each chip must thus have a "base" number (which can be automatically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) assigned), and for each GPIO line the global number will be (base + hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) number). Although the integer representation is considered deprecated, it still
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) has many users and thus needs to be maintained.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) So for example one platform could use global numbers 32-159 for GPIOs, with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) controller defining 128 GPIOs at a "base" of 32 ; while another platform uses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) global numbers 0..63 with one set of GPIO controllers, 64-79 with another type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) of GPIO controller, and on one particular board 80-95 with an FPGA. The legacy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) numbers need not be contiguous; either of those platforms could also use numbers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) 2000-2063 to identify GPIO lines in a bank of I2C GPIO expanders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) Controller Drivers: gpio_chip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) In the gpiolib framework each GPIO controller is packaged as a "struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) gpio_chip" (see <linux/gpio/driver.h> for its complete definition) with members
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) common to each controller of that type, these should be assigned by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) driver code:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) - methods to establish GPIO line direction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) - methods used to access GPIO line values
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) - method to set electrical configuration for a given GPIO line
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) - method to return the IRQ number associated to a given GPIO line
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) - flag saying whether calls to its methods may sleep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) - optional line names array to identify lines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) - optional debugfs dump method (showing extra state information)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) - optional base number (will be automatically assigned if omitted)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) - optional label for diagnostics and GPIO chip mapping using platform data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) The code implementing a gpio_chip should support multiple instances of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) controller, preferably using the driver model. That code will configure each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) gpio_chip and issue gpiochip_add(), gpiochip_add_data(), or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) devm_gpiochip_add_data(). Removing a GPIO controller should be rare; use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) gpiochip_remove() when it is unavoidable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) Often a gpio_chip is part of an instance-specific structure with states not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) exposed by the GPIO interfaces, such as addressing, power management, and more.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) Chips such as audio codecs will have complex non-GPIO states.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) Any debugfs dump method should normally ignore lines which haven't been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) requested. They can use gpiochip_is_requested(), which returns either
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) NULL or the label associated with that GPIO line when it was requested.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) Realtime considerations: the GPIO driver should not use spinlock_t or any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) sleepable APIs (like PM runtime) in its gpio_chip implementation (.get/.set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) and direction control callbacks) if it is expected to call GPIO APIs from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) atomic context on realtime kernels (inside hard IRQ handlers and similar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) contexts). Normally this should not be required.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) GPIO electrical configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) GPIO lines can be configured for several electrical modes of operation by using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) the .set_config() callback. Currently this API supports setting:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) - Debouncing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) - Single-ended modes (open drain/open source)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) - Pull up and pull down resistor enablement
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) These settings are described below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) The .set_config() callback uses the same enumerators and configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) semantics as the generic pin control drivers. This is not a coincidence: it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) possible to assign the .set_config() to the function gpiochip_generic_config()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) which will result in pinctrl_gpio_set_config() being called and eventually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) ending up in the pin control back-end "behind" the GPIO controller, usually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) closer to the actual pins. This way the pin controller can manage the below
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) listed GPIO configurations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) If a pin controller back-end is used, the GPIO controller or hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) description needs to provide "GPIO ranges" mapping the GPIO line offsets to pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) numbers on the pin controller so they can properly cross-reference each other.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) GPIO lines with debounce support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Debouncing is a configuration set to a pin indicating that it is connected to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) a mechanical switch or button, or similar that may bounce. Bouncing means the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) line is pulled high/low quickly at very short intervals for mechanical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) reasons. This can result in the value being unstable or irqs fireing repeatedly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) unless the line is debounced.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) Debouncing in practice involves setting up a timer when something happens on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) the line, wait a little while and then sample the line again, so see if it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) still has the same value (low or high). This could also be repeated by a clever
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) state machine, waiting for a line to become stable. In either case, it sets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) a certain number of milliseconds for debouncing, or just "on/off" if that time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) is not configurable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) GPIO lines with open drain/source support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) -----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) Open drain (CMOS) or open collector (TTL) means the line is not actively driven
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) high: instead you provide the drain/collector as output, so when the transistor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) is not open, it will present a high-impedance (tristate) to the external rail::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) CMOS CONFIGURATION TTL CONFIGURATION
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) ||--- out +--- out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) in ----|| |/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) ||--+ in ----|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) | |\
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) GND GND
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) This configuration is normally used as a way to achieve one of two things:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) - Level-shifting: to reach a logical level higher than that of the silicon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) where the output resides.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) - Inverse wire-OR on an I/O line, for example a GPIO line, making it possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) for any driving stage on the line to drive it low even if any other output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) to the same line is simultaneously driving it high. A special case of this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) is driving the SCL and SDA lines of an I2C bus, which is by definition a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) wire-OR bus.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) Both use cases require that the line be equipped with a pull-up resistor. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) resistor will make the line tend to high level unless one of the transistors on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) the rail actively pulls it down.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) The level on the line will go as high as the VDD on the pull-up resistor, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) may be higher than the level supported by the transistor, achieving a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) level-shift to the higher VDD.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) Integrated electronics often have an output driver stage in the form of a CMOS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) "totem-pole" with one N-MOS and one P-MOS transistor where one of them drives
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) the line high and one of them drives the line low. This is called a push-pull
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) output. The "totem-pole" looks like so::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) VDD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) OD ||--+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) +--/ ---o|| P-MOS-FET
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) | ||--+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) IN --+ +----- out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) | ||--+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) +--/ ----|| N-MOS-FET
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) OS ||--+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) GND
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) The desired output signal (e.g. coming directly from some GPIO output register)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) arrives at IN. The switches named "OD" and "OS" are normally closed, creating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) a push-pull circuit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) Consider the little "switches" named "OD" and "OS" that enable/disable the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) P-MOS or N-MOS transistor right after the split of the input. As you can see,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) either transistor will go totally numb if this switch is open. The totem-pole
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) is then halved and give high impedance instead of actively driving the line
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) high or low respectively. That is usually how software-controlled open
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) drain/source works.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) Some GPIO hardware come in open drain / open source configuration. Some are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) hard-wired lines that will only support open drain or open source no matter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) what: there is only one transistor there. Some are software-configurable:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) by flipping a bit in a register the output can be configured as open drain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) or open source, in practice by flicking open the switches labeled "OD" and "OS"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) in the drawing above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) By disabling the P-MOS transistor, the output can be driven between GND and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) high impedance (open drain), and by disabling the N-MOS transistor, the output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) can be driven between VDD and high impedance (open source). In the first case,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) a pull-up resistor is needed on the outgoing rail to complete the circuit, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) in the second case, a pull-down resistor is needed on the rail.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) Hardware that supports open drain or open source or both, can implement a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) special callback in the gpio_chip: .set_config() that takes a generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) pinconf packed value telling whether to configure the line as open drain,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) open source or push-pull. This will happen in response to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) GPIO_OPEN_DRAIN or GPIO_OPEN_SOURCE flag set in the machine file, or coming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) from other hardware descriptions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) If this state can not be configured in hardware, i.e. if the GPIO hardware does
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) not support open drain/open source in hardware, the GPIO library will instead
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) use a trick: when a line is set as output, if the line is flagged as open
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) drain, and the IN output value is low, it will be driven low as usual. But
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) if the IN output value is set to high, it will instead *NOT* be driven high,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) instead it will be switched to input, as input mode is high impedance, thus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) achieveing an "open drain emulation" of sorts: electrically the behaviour will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) be identical, with the exception of possible hardware glitches when switching
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) the mode of the line.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) For open source configuration the same principle is used, just that instead
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) of actively driving the line low, it is set to input.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) GPIO lines with pull up/down resistor support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) ---------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) A GPIO line can support pull-up/down using the .set_config() callback. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) means that a pull up or pull-down resistor is available on the output of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) GPIO line, and this resistor is software controlled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) In discrete designs, a pull-up or pull-down resistor is simply soldered on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) the circuit board. This is not something we deal with or model in software. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) most you will think about these lines is that they will very likely be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) configured as open drain or open source (see the section above).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) The .set_config() callback can only turn pull up or down on and off, and will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) no have any semantic knowledge about the resistance used. It will only say
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) switch a bit in a register enabling or disabling pull-up or pull-down.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) If the GPIO line supports shunting in different resistance values for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) pull-up or pull-down resistor, the GPIO chip callback .set_config() will not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) suffice. For these complex use cases, a combined GPIO chip and pin controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) need to be implemented, as the pin config interface of a pin controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) supports more versatile control over electrical properties and can handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) different pull-up or pull-down resistance values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) GPIO drivers providing IRQs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) It is custom that GPIO drivers (GPIO chips) are also providing interrupts,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) most often cascaded off a parent interrupt controller, and in some special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) cases the GPIO logic is melded with a SoC's primary interrupt controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) The IRQ portions of the GPIO block are implemented using an irq_chip, using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) the header <linux/irq.h>. So this combined driver is utilizing two sub-
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) systems simultaneously: gpio and irq.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) It is legal for any IRQ consumer to request an IRQ from any irqchip even if it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) irq_chip are orthogonal, and offering their services independent of each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) other.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) gpiod_to_irq() is just a convenience function to figure out the IRQ for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) certain GPIO line and should not be relied upon to have been called before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) the IRQ is used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) Always prepare the hardware and make it ready for action in respective
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) callbacks from the GPIO and irq_chip APIs. Do not rely on gpiod_to_irq() having
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) been called first.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) We can divide GPIO irqchips in two broad categories:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) - CASCADED INTERRUPT CHIPS: this means that the GPIO chip has one common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) interrupt output line, which is triggered by any enabled GPIO line on that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) chip. The interrupt output line will then be routed to an parent interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) controller one level up, in the most simple case the systems primary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) interrupt controller. This is modeled by an irqchip that will inspect bits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) inside the GPIO controller to figure out which line fired it. The irqchip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) part of the driver needs to inspect registers to figure this out and it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) will likely also need to acknowledge that it is handling the interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) by clearing some bit (sometime implicitly, by just reading a status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) register) and it will often need to set up the configuration such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) edge sensitivity (rising or falling edge, or high/low level interrupt for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) example).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) - HIERARCHICAL INTERRUPT CHIPS: this means that each GPIO line has a dedicated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) irq line to a parent interrupt controller one level up. There is no need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) to inquire the GPIO hardware to figure out which line has fired, but it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) may still be necessary to acknowledge the interrupt and set up configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) such as edge sensitivity.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) Realtime considerations: a realtime compliant GPIO driver should not use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) spinlock_t or any sleepable APIs (like PM runtime) as part of its irqchip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) implementation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) - spinlock_t should be replaced with raw_spinlock_t.[1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) - If sleepable APIs have to be used, these can be done from the .irq_bus_lock()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) and .irq_bus_unlock() callbacks, as these are the only slowpath callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) on an irqchip. Create the callbacks if needed.[2]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) Cascaded GPIO irqchips
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) Cascaded GPIO irqchips usually fall in one of three categories:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) - CHAINED CASCADED GPIO IRQCHIPS: these are usually the type that is embedded on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) an SoC. This means that there is a fast IRQ flow handler for the GPIOs that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) gets called in a chain from the parent IRQ handler, most typically the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) system interrupt controller. This means that the GPIO irqchip handler will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) be called immediately from the parent irqchip, while holding the IRQs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) disabled. The GPIO irqchip will then end up calling something like this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) sequence in its interrupt handler::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) static irqreturn_t foo_gpio_irq(int irq, void *data)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) chained_irq_enter(...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) generic_handle_irq(...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) chained_irq_exit(...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) Chained GPIO irqchips typically can NOT set the .can_sleep flag on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) struct gpio_chip, as everything happens directly in the callbacks: no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) slow bus traffic like I2C can be used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) Realtime considerations: Note that chained IRQ handlers will not be forced
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) threaded on -RT. As a result, spinlock_t or any sleepable APIs (like PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) runtime) can't be used in a chained IRQ handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) If required (and if it can't be converted to the nested threaded GPIO irqchip,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) see below) a chained IRQ handler can be converted to generic irq handler and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) this way it will become a threaded IRQ handler on -RT and a hard IRQ handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) on non-RT (for example, see [3]).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) The generic_handle_irq() is expected to be called with IRQ disabled,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) so the IRQ core will complain if it is called from an IRQ handler which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) forced to a thread. The "fake?" raw lock can be used to work around this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) problem::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) raw_spinlock_t wa_lock;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) unsigned long wa_lock_flags;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) raw_spin_lock_irqsave(&bank->wa_lock, wa_lock_flags);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) generic_handle_irq(irq_find_mapping(bank->chip.irq.domain, bit));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) - GENERIC CHAINED GPIO IRQCHIPS: these are the same as "CHAINED GPIO irqchips",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) performed by generic IRQ handler which is configured using request_irq().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) The GPIO irqchip will then end up calling something like this sequence in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) its interrupt handler::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) static irqreturn_t gpio_rcar_irq_handler(int irq, void *dev_id)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) for each detected GPIO IRQ
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) generic_handle_irq(...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) Realtime considerations: this kind of handlers will be forced threaded on -RT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) and as result the IRQ core will complain that generic_handle_irq() is called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) with IRQ enabled and the same work-around as for "CHAINED GPIO irqchips" can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) be applied.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) - NESTED THREADED GPIO IRQCHIPS: these are off-chip GPIO expanders and any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) other GPIO irqchip residing on the other side of a sleeping bus such as I2C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) or SPI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) Of course such drivers that need slow bus traffic to read out IRQ status and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) similar, traffic which may in turn incur other IRQs to happen, cannot be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) handled in a quick IRQ handler with IRQs disabled. Instead they need to spawn
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) a thread and then mask the parent IRQ line until the interrupt is handled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) by the driver. The hallmark of this driver is to call something like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) this in its interrupt handler::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) static irqreturn_t foo_gpio_irq(int irq, void *data)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) handle_nested_irq(irq);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) The hallmark of threaded GPIO irqchips is that they set the .can_sleep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) flag on struct gpio_chip to true, indicating that this chip may sleep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) when accessing the GPIOs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) These kinds of irqchips are inherently realtime tolerant as they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) already set up to handle sleeping contexts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) Infrastructure helpers for GPIO irqchips
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) ----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) To help out in handling the set-up and management of GPIO irqchips and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) associated irqdomain and resource allocation callbacks. These are activated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) by selecting the Kconfig symbol GPIOLIB_IRQCHIP. If the symbol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) IRQ_DOMAIN_HIERARCHY is also selected, hierarchical helpers will also be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) provided. A big portion of overhead code will be managed by gpiolib,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) under the assumption that your interrupts are 1-to-1-mapped to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) GPIO line index:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) .. csv-table::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) :header: GPIO line offset, Hardware IRQ
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) 0,0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) 1,1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) 2,2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) ...,...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) ngpio-1, ngpio-1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) If some GPIO lines do not have corresponding IRQs, the bitmask valid_mask
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) and the flag need_valid_mask in gpio_irq_chip can be used to mask off some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) lines as invalid for associating with IRQs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) The preferred way to set up the helpers is to fill in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) struct gpio_irq_chip inside struct gpio_chip before adding the gpio_chip.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) If you do this, the additional irq_chip will be set up by gpiolib at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) same time as setting up the rest of the GPIO functionality. The following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) is a typical example of a cascaded interrupt handler using gpio_irq_chip:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) /* Typical state container with dynamic irqchip */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) struct my_gpio {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) struct gpio_chip gc;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) struct irq_chip irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) int irq; /* from platform etc */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) struct my_gpio *g;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) struct gpio_irq_chip *girq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) /* Set up the irqchip dynamically */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) g->irq.name = "my_gpio_irq";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) g->irq.irq_ack = my_gpio_ack_irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) g->irq.irq_mask = my_gpio_mask_irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) g->irq.irq_unmask = my_gpio_unmask_irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) g->irq.irq_set_type = my_gpio_set_irq_type;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) /* Get a pointer to the gpio_irq_chip */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) girq = &g->gc.irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) girq->chip = &g->irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) girq->parent_handler = ftgpio_gpio_irq_handler;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) girq->num_parents = 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) girq->parents = devm_kcalloc(dev, 1, sizeof(*girq->parents),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) if (!girq->parents)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) return -ENOMEM;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) girq->default_type = IRQ_TYPE_NONE;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) girq->handler = handle_bad_irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) girq->parents[0] = irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) return devm_gpiochip_add_data(dev, &g->gc, g);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) The helper support using hierarchical interrupt controllers as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) In this case the typical set-up will look like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) /* Typical state container with dynamic irqchip */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) struct my_gpio {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) struct gpio_chip gc;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) struct irq_chip irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) struct fwnode_handle *fwnode;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) int irq; /* from platform etc */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) struct my_gpio *g;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) struct gpio_irq_chip *girq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) /* Set up the irqchip dynamically */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) g->irq.name = "my_gpio_irq";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) g->irq.irq_ack = my_gpio_ack_irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) g->irq.irq_mask = my_gpio_mask_irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) g->irq.irq_unmask = my_gpio_unmask_irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) g->irq.irq_set_type = my_gpio_set_irq_type;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) /* Get a pointer to the gpio_irq_chip */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) girq = &g->gc.irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) girq->chip = &g->irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) girq->default_type = IRQ_TYPE_NONE;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) girq->handler = handle_bad_irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) girq->fwnode = g->fwnode;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) girq->parent_domain = parent;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) girq->child_to_parent_hwirq = my_gpio_child_to_parent_hwirq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) return devm_gpiochip_add_data(dev, &g->gc, g);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) As you can see pretty similar, but you do not supply a parent handler for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) the IRQ, instead a parent irqdomain, an fwnode for the hardware and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) a funcion .child_to_parent_hwirq() that has the purpose of looking up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) the parent hardware irq from a child (i.e. this gpio chip) hardware irq.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) As always it is good to look at examples in the kernel tree for advice
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) on how to find the required pieces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) The old way of adding irqchips to gpiochips after registration is also still
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) available but we try to move away from this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) - DEPRECATED: gpiochip_irqchip_add(): adds a chained cascaded irqchip to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) gpiochip. It will pass the struct gpio_chip* for the chip to all IRQ
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) callbacks, so the callbacks need to embed the gpio_chip in its state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) container and obtain a pointer to the container using container_of().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) (See Documentation/driver-api/driver-model/design-patterns.rst)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) - gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) as discussed above regarding different types of cascaded irqchips. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) cascaded irq has to be handled by a threaded interrupt handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) Apart from that it works exactly like the chained irqchip.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) - gpiochip_set_nested_irqchip(): sets up a nested cascaded irq handler for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) gpio_chip from a parent IRQ. As the parent IRQ has usually been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) explicitly requested by the driver, this does very little more than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) mark all the child IRQs as having the other IRQ as parent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) If there is a need to exclude certain GPIO lines from the IRQ domain handled by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) these helpers, we can set .irq.need_valid_mask of the gpiochip before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) devm_gpiochip_add_data() or gpiochip_add_data() is called. This allocates an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) .irq.valid_mask with as many bits set as there are GPIO lines in the chip, each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) bit representing line 0..n-1. Drivers can exclude GPIO lines by clearing bits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) from this mask. The mask must be filled in before gpiochip_irqchip_add() or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) gpiochip_irqchip_add_nested() is called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) To use the helpers please keep the following in mind:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) - Make sure to assign all relevant members of the struct gpio_chip so that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) the irqchip can initialize. E.g. .dev and .can_sleep shall be set up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) properly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) - Nominally set all handlers to handle_bad_irq() in the setup call and pass
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) handle_bad_irq() as flow handler parameter in gpiochip_irqchip_add() if it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) expected for GPIO driver that irqchip .set_type() callback will be called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) before using/enabling each GPIO IRQ. Then set the handler to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) handle_level_irq() and/or handle_edge_irq() in the irqchip .set_type()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) callback depending on what your controller supports and what is requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) by the consumer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) Locking IRQ usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) Since GPIO and irq_chip are orthogonal, we can get conflicts between different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) use cases. For example a GPIO line used for IRQs should be an input line,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) it does not make sense to fire interrupts on an output GPIO.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) If there is competition inside the subsystem which side is using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) resource (a certain GPIO line and register for example) it needs to deny
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) certain operations and keep track of usage inside of the gpiolib subsystem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) to mark the GPIO as being used as an IRQ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) is released::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) When implementing an irqchip inside a GPIO driver, these two functions should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) typically be called in the .startup() and .shutdown() callbacks from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) irqchip.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) When using the gpiolib irqchip helpers, these callbacks are automatically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) assigned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) Disabling and enabling IRQs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) ---------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) In some (fringe) use cases, a driver may be using a GPIO line as input for IRQs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) but occasionally switch that line over to drive output and then back to being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) an input with interrupts again. This happens on things like CEC (Consumer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) Electronics Control).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) When a GPIO is used as an IRQ signal, then gpiolib also needs to know if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) the IRQ is enabled or disabled. In order to inform gpiolib about this,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) the irqchip driver should call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) void gpiochip_disable_irq(struct gpio_chip *chip, unsigned int offset)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) This allows drivers to drive the GPIO as an output while the IRQ is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) disabled. When the IRQ is enabled again, a driver should call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) void gpiochip_enable_irq(struct gpio_chip *chip, unsigned int offset)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) When implementing an irqchip inside a GPIO driver, these two functions should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) typically be called in the .irq_disable() and .irq_enable() callbacks from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) irqchip.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) When using the gpiolib irqchip helpers, these callbacks are automatically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) assigned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) Real-Time compliance for GPIO IRQ chips
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) ---------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) Any provider of irqchips needs to be carefully tailored to support Real-Time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) preemption. It is desirable that all irqchips in the GPIO subsystem keep this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) in mind and do the proper testing to assure they are real time-enabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) So, pay attention on above realtime considerations in the documentation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) The following is a checklist to follow when preparing a driver for real-time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) compliance:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) - ensure spinlock_t is not used as part irq_chip implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) - ensure that sleepable APIs are not used as part irq_chip implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) If sleepable APIs have to be used, these can be done from the .irq_bus_lock()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) and .irq_bus_unlock() callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) - Chained GPIO irqchips: ensure spinlock_t or any sleepable APIs are not used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) from the chained IRQ handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) - Generic chained GPIO irqchips: take care about generic_handle_irq() calls and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) apply corresponding work-around
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) - Chained GPIO irqchips: get rid of the chained IRQ handler and use generic irq
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) handler if possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) - regmap_mmio: it is possible to disable internal locking in regmap by setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) .disable_locking and handling the locking in the GPIO driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) - Test your driver with the appropriate in-kernel real-time test cases for both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) level and edge IRQs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) * [1] http://www.spinics.net/lists/linux-omap/msg120425.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) * [2] https://lkml.org/lkml/2015/9/25/494
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) * [3] https://lkml.org/lkml/2015/9/25/495
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) Requesting self-owned GPIO pins
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) Sometimes it is useful to allow a GPIO chip driver to request its own GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) descriptors through the gpiolib API. A GPIO driver can use the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) functions to request and free descriptors::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) u16 hwnum,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) const char *label,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) enum gpiod_flags flags)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) void gpiochip_free_own_desc(struct gpio_desc *desc)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) Descriptors requested with gpiochip_request_own_desc() must be released with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) gpiochip_free_own_desc().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) These functions must be used with care since they do not affect module use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) count. Do not use the functions to request gpio descriptors not owned by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) calling driver.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags