Based on kernel version 4.13.3. Page generated on 2017-09-23 13:55 EST.
1 GPIO Descriptor Driver Interface 2 ================================ 3 4 This document serves as a guide for GPIO chip drivers writers. Note that it 5 describes the new descriptor-based interface. For a description of the 6 deprecated integer-based GPIO interface please refer to gpio-legacy.txt. 7 8 Each GPIO controller driver needs to include the following header, which defines 9 the structures used to define a GPIO driver: 10 11 #include <linux/gpio/driver.h> 12 13 14 Internal Representation of GPIOs 15 ================================ 16 17 Inside a GPIO driver, individual GPIOs are identified by their hardware number, 18 which is a unique number between 0 and n, n being the number of GPIOs managed by 19 the chip. This number is purely internal: the hardware number of a particular 20 GPIO descriptor is never made visible outside of the driver. 21 22 On top of this internal number, each GPIO also need to have a global number in 23 the integer GPIO namespace so that it can be used with the legacy GPIO 24 interface. Each chip must thus have a "base" number (which can be automatically 25 assigned), and for each GPIO the global number will be (base + hardware number). 26 Although the integer representation is considered deprecated, it still has many 27 users and thus needs to be maintained. 28 29 So for example one platform could use numbers 32-159 for GPIOs, with a 30 controller defining 128 GPIOs at a "base" of 32 ; while another platform uses 31 numbers 0..63 with one set of GPIO controllers, 64-79 with another type of GPIO 32 controller, and on one particular board 80-95 with an FPGA. The numbers need not 33 be contiguous; either of those platforms could also use numbers 2000-2063 to 34 identify GPIOs in a bank of I2C GPIO expanders. 35 36 37 Controller Drivers: gpio_chip 38 ============================= 39 40 In the gpiolib framework each GPIO controller is packaged as a "struct 41 gpio_chip" (see linux/gpio/driver.h for its complete definition) with members 42 common to each controller of that type: 43 44 - methods to establish GPIO line direction 45 - methods used to access GPIO line values 46 - method to set electrical configuration to a a given GPIO line 47 - method to return the IRQ number associated to a given GPIO line 48 - flag saying whether calls to its methods may sleep 49 - optional line names array to identify lines 50 - optional debugfs dump method (showing extra state like pullup config) 51 - optional base number (will be automatically assigned if omitted) 52 - optional label for diagnostics and GPIO chip mapping using platform data 53 54 The code implementing a gpio_chip should support multiple instances of the 55 controller, possibly using the driver model. That code will configure each 56 gpio_chip and issue gpiochip_add[_data]() or devm_gpiochip_add_data(). 57 Removing a GPIO controller should be rare; use [devm_]gpiochip_remove() when 58 it is unavoidable. 59 60 Often a gpio_chip is part of an instance-specific structure with states not 61 exposed by the GPIO interfaces, such as addressing, power management, and more. 62 Chips such as audio codecs will have complex non-GPIO states. 63 64 Any debugfs dump method should normally ignore signals which haven't been 65 requested as GPIOs. They can use gpiochip_is_requested(), which returns either 66 NULL or the label associated with that GPIO when it was requested. 67 68 RT_FULL: the GPIO driver should not use spinlock_t or any sleepable APIs 69 (like PM runtime) in its gpio_chip implementation (.get/.set and direction 70 control callbacks) if it is expected to call GPIO APIs from atomic context 71 on -RT (inside hard IRQ handlers and similar contexts). Normally this should 72 not be required. 73 74 75 GPIO electrical configuration 76 ----------------------------- 77 78 GPIOs can be configured for several electrical modes of operation by using the 79 .set_config() callback. Currently this API supports setting debouncing and 80 single-ended modes (open drain/open source). These settings are described 81 below. 82 83 The .set_config() callback uses the same enumerators and configuration 84 semantics as the generic pin control drivers. This is not a coincidence: it is 85 possible to assign the .set_config() to the function gpiochip_generic_config() 86 which will result in pinctrl_gpio_set_config() being called and eventually 87 ending up in the pin control back-end "behind" the GPIO controller, usually 88 closer to the actual pins. This way the pin controller can manage the below 89 listed GPIO configurations. 90 91 92 GPIOs with debounce support 93 --------------------------- 94 95 Debouncing is a configuration set to a pin indicating that it is connected to 96 a mechanical switch or button, or similar that may bounce. Bouncing means the 97 line is pulled high/low quickly at very short intervals for mechanical 98 reasons. This can result in the value being unstable or irqs fireing repeatedly 99 unless the line is debounced. 100 101 Debouncing in practice involves setting up a timer when something happens on 102 the line, wait a little while and then sample the line again, so see if it 103 still has the same value (low or high). This could also be repeated by a clever 104 state machine, waiting for a line to become stable. In either case, it sets 105 a certain number of milliseconds for debouncing, or just "on/off" if that time 106 is not configurable. 107 108 109 GPIOs with open drain/source support 110 ------------------------------------ 111 112 Open drain (CMOS) or open collector (TTL) means the line is not actively driven 113 high: instead you provide the drain/collector as output, so when the transistor 114 is not open, it will present a high-impedance (tristate) to the external rail. 115 116 117 CMOS CONFIGURATION TTL CONFIGURATION 118 119 ||--- out +--- out 120 in ----|| |/ 121 ||--+ in ----| 122 | |\ 123 GND GND 124 125 This configuration is normally used as a way to achieve one of two things: 126 127 - Level-shifting: to reach a logical level higher than that of the silicon 128 where the output resides. 129 130 - inverse wire-OR on an I/O line, for example a GPIO line, making it possible 131 for any driving stage on the line to drive it low even if any other output 132 to the same line is simultaneously driving it high. A special case of this 133 is driving the SCL and SCA lines of an I2C bus, which is by definition a 134 wire-OR bus. 135 136 Both usecases require that the line be equipped with a pull-up resistor. This 137 resistor will make the line tend to high level unless one of the transistors on 138 the rail actively pulls it down. 139 140 The level on the line will go as high as the VDD on the pull-up resistor, which 141 may be higher than the level supported by the transistor, achieveing a 142 level-shift to the higher VDD. 143 144 Integrated electronics often have an output driver stage in the form of a CMOS 145 "totem-pole" with one N-MOS and one P-MOS transistor where one of them drives 146 the line high and one of them drives the line low. This is called a push-pull 147 output. The "totem-pole" looks like so: 148 149 VDD 150 | 151 OD ||--+ 152 +--/ ---o|| P-MOS-FET 153 | ||--+ 154 IN --+ +----- out 155 | ||--+ 156 +--/ ----|| N-MOS-FET 157 OS ||--+ 158 | 159 GND 160 161 The desired output signal (e.g. coming directly from some GPIO output register) 162 arrives at IN. The switches named "OD" and "OS" are normally closed, creating 163 a push-pull circuit. 164 165 Consider the little "switches" named "OD" and "OS" that enable/disable the 166 P-MOS or N-MOS transistor right after the split of the input. As you can see, 167 either transistor will go totally numb if this switch is open. The totem-pole 168 is then halved and give high impedance instead of actively driving the line 169 high or low respectively. That is usually how software-controlled open 170 drain/source works. 171 172 Some GPIO hardware come in open drain / open source configuration. Some are 173 hard-wired lines that will only support open drain or open source no matter 174 what: there is only one transistor there. Some are software-configurable: 175 by flipping a bit in a register the output can be configured as open drain 176 or open source, in practice by flicking open the switches labeled "OD" and "OS" 177 in the drawing above. 178 179 By disabling the P-MOS transistor, the output can be driven between GND and 180 high impedance (open drain), and by disabling the N-MOS transistor, the output 181 can be driven between VDD and high impedance (open source). In the first case, 182 a pull-up resistor is needed on the outgoing rail to complete the circuit, and 183 in the second case, a pull-down resistor is needed on the rail. 184 185 Hardware that supports open drain or open source or both, can implement a 186 special callback in the gpio_chip: .set_config() that takes a generic 187 pinconf packed value telling whether to configure the line as open drain, 188 open source or push-pull. This will happen in response to the 189 GPIO_OPEN_DRAIN or GPIO_OPEN_SOURCE flag set in the machine file, or coming 190 from other hardware descriptions. 191 192 If this state can not be configured in hardware, i.e. if the GPIO hardware does 193 not support open drain/open source in hardware, the GPIO library will instead 194 use a trick: when a line is set as output, if the line is flagged as open 195 drain, and the IN output value is low, it will be driven low as usual. But 196 if the IN output value is set to high, it will instead *NOT* be driven high, 197 instead it will be switched to input, as input mode is high impedance, thus 198 achieveing an "open drain emulation" of sorts: electrically the behaviour will 199 be identical, with the exception of possible hardware glitches when switching 200 the mode of the line. 201 202 For open source configuration the same principle is used, just that instead 203 of actively driving the line low, it is set to input. 204 205 206 GPIO drivers providing IRQs 207 --------------------------- 208 It is custom that GPIO drivers (GPIO chips) are also providing interrupts, 209 most often cascaded off a parent interrupt controller, and in some special 210 cases the GPIO logic is melded with a SoC's primary interrupt controller. 211 212 The IRQ portions of the GPIO block are implemented using an irqchip, using 213 the header <linux/irq.h>. So basically such a driver is utilizing two sub- 214 systems simultaneously: gpio and irq. 215 216 RT_FULL: a realtime compliant GPIO driver should not use spinlock_t or any 217 sleepable APIs (like PM runtime) as part of its irq_chip implementation. 218 - spinlock_t should be replaced with raw_spinlock_t . 219 - If sleepable APIs have to be used, these can be done from the .irq_bus_lock() 220 and .irq_bus_unlock() callbacks, as these are the only slowpath callbacks 221 on an irqchip. Create the callbacks if needed . 222 223 GPIO irqchips usually fall in one of two categories: 224 225 * CHAINED GPIO irqchips: these are usually the type that is embedded on 226 an SoC. This means that there is a fast IRQ flow handler for the GPIOs that 227 gets called in a chain from the parent IRQ handler, most typically the 228 system interrupt controller. This means that the GPIO irqchip handler will 229 be called immediately from the parent irqchip, while holding the IRQs 230 disabled. The GPIO irqchip will then end up calling something like this 231 sequence in its interrupt handler: 232 233 static irqreturn_t foo_gpio_irq(int irq, void *data) 234 chained_irq_enter(...); 235 generic_handle_irq(...); 236 chained_irq_exit(...); 237 238 Chained GPIO irqchips typically can NOT set the .can_sleep flag on 239 struct gpio_chip, as everything happens directly in the callbacks: no 240 slow bus traffic like I2C can be used. 241 242 RT_FULL: Note, chained IRQ handlers will not be forced threaded on -RT. 243 As result, spinlock_t or any sleepable APIs (like PM runtime) can't be used 244 in chained IRQ handler. 245 If required (and if it can't be converted to the nested threaded GPIO irqchip) 246 a chained IRQ handler can be converted to generic irq handler and this way 247 it will be a threaded IRQ handler on -RT and a hard IRQ handler on non-RT 248 (for example, see ). 249 Know W/A: The generic_handle_irq() is expected to be called with IRQ disabled, 250 so the IRQ core will complain if it is called from an IRQ handler which is 251 forced to a thread. The "fake?" raw lock can be used to W/A this problem: 252 253 raw_spinlock_t wa_lock; 254 static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank) 255 unsigned long wa_lock_flags; 256 raw_spin_lock_irqsave(&bank->wa_lock, wa_lock_flags); 257 generic_handle_irq(irq_find_mapping(bank->chip.irqdomain, bit)); 258 raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags); 259 260 * GENERIC CHAINED GPIO irqchips: these are the same as "CHAINED GPIO irqchips", 261 but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is 262 performed by generic IRQ handler which is configured using request_irq(). 263 The GPIO irqchip will then end up calling something like this sequence in 264 its interrupt handler: 265 266 static irqreturn_t gpio_rcar_irq_handler(int irq, void *dev_id) 267 for each detected GPIO IRQ 268 generic_handle_irq(...); 269 270 RT_FULL: Such kind of handlers will be forced threaded on -RT, as result IRQ 271 core will complain that generic_handle_irq() is called with IRQ enabled and 272 the same W/A as for "CHAINED GPIO irqchips" can be applied. 273 274 * NESTED THREADED GPIO irqchips: these are off-chip GPIO expanders and any 275 other GPIO irqchip residing on the other side of a sleeping bus. Of course 276 such drivers that need slow bus traffic to read out IRQ status and similar, 277 traffic which may in turn incur other IRQs to happen, cannot be handled 278 in a quick IRQ handler with IRQs disabled. Instead they need to spawn a 279 thread and then mask the parent IRQ line until the interrupt is handled 280 by the driver. The hallmark of this driver is to call something like 281 this in its interrupt handler: 282 283 static irqreturn_t foo_gpio_irq(int irq, void *data) 284 ... 285 handle_nested_irq(irq); 286 287 The hallmark of threaded GPIO irqchips is that they set the .can_sleep 288 flag on struct gpio_chip to true, indicating that this chip may sleep 289 when accessing the GPIOs. 290 291 To help out in handling the set-up and management of GPIO irqchips and the 292 associated irqdomain and resource allocation callbacks, the gpiolib has 293 some helpers that can be enabled by selecting the GPIOLIB_IRQCHIP Kconfig 294 symbol: 295 296 * gpiochip_irqchip_add(): adds a chained irqchip to a gpiochip. It will pass 297 the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks 298 need to embed the gpio_chip in its state container and obtain a pointer 299 to the container using container_of(). 300 (See Documentation/driver-model/design-patterns.txt) 301 302 * gpiochip_irqchip_add_nested(): adds a nested irqchip to a gpiochip. 303 Apart from that it works exactly like the chained irqchip. 304 305 * gpiochip_set_chained_irqchip(): sets up a chained irq handler for a 306 gpio_chip from a parent IRQ and passes the struct gpio_chip* as handler 307 data. (Notice handler data, since the irqchip data is likely used by the 308 parent irqchip!). 309 310 * gpiochip_set_nested_irqchip(): sets up a nested irq handler for a 311 gpio_chip from a parent IRQ. As the parent IRQ has usually been 312 explicitly requested by the driver, this does very little more than 313 mark all the child IRQs as having the other IRQ as parent. 314 315 If there is a need to exclude certain GPIOs from the IRQ domain, you can 316 set .irq_need_valid_mask of the gpiochip before gpiochip_add_data() is 317 called. This allocates an .irq_valid_mask with as many bits set as there 318 are GPIOs in the chip. Drivers can exclude GPIOs by clearing bits from this 319 mask. The mask must be filled in before gpiochip_irqchip_add() or 320 gpiochip_irqchip_add_nested() is called. 321 322 To use the helpers please keep the following in mind: 323 324 - Make sure to assign all relevant members of the struct gpio_chip so that 325 the irqchip can initialize. E.g. .dev and .can_sleep shall be set up 326 properly. 327 328 - Nominally set all handlers to handle_bad_irq() in the setup call and pass 329 handle_bad_irq() as flow handler parameter in gpiochip_irqchip_add() if it is 330 expected for GPIO driver that irqchip .set_type() callback have to be called 331 before using/enabling GPIO IRQ. Then set the handler to handle_level_irq() 332 and/or handle_edge_irq() in the irqchip .set_type() callback depending on 333 what your controller supports. 334 335 It is legal for any IRQ consumer to request an IRQ from any irqchip no matter 336 if that is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and 337 irq_chip are orthogonal, and offering their services independent of each 338 other. 339 340 gpiod_to_irq() is just a convenience function to figure out the IRQ for a 341 certain GPIO line and should not be relied upon to have been called before 342 the IRQ is used. 343 344 So always prepare the hardware and make it ready for action in respective 345 callbacks from the GPIO and irqchip APIs. Do not rely on gpiod_to_irq() having 346 been called first. 347 348 This orthogonality leads to ambiguities that we need to solve: if there is 349 competition inside the subsystem which side is using the resource (a certain 350 GPIO line and register for example) it needs to deny certain operations and 351 keep track of usage inside of the gpiolib subsystem. This is why the API 352 below exists. 353 354 355 Locking IRQ usage 356 ----------------- 357 Input GPIOs can be used as IRQ signals. When this happens, a driver is requested 358 to mark the GPIO as being used as an IRQ: 359 360 int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset) 361 362 This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock 363 is released: 364 365 void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset) 366 367 When implementing an irqchip inside a GPIO driver, these two functions should 368 typically be called in the .startup() and .shutdown() callbacks from the 369 irqchip. 370 371 When using the gpiolib irqchip helpers, these callback are automatically 372 assigned. 373 374 Real-Time compliance for GPIO IRQ chips 375 --------------------------------------- 376 377 Any provider of irqchips needs to be carefully tailored to support Real Time 378 preemption. It is desirable that all irqchips in the GPIO subsystem keep this 379 in mind and does the proper testing to assure they are real time-enabled. 380 So, pay attention on above " RT_FULL:" notes, please. 381 The following is a checklist to follow when preparing a driver for real 382 time-compliance: 383 384 - ensure spinlock_t is not used as part irq_chip implementation; 385 - ensure that sleepable APIs are not used as part irq_chip implementation. 386 If sleepable APIs have to be used, these can be done from the .irq_bus_lock() 387 and .irq_bus_unlock() callbacks; 388 - Chained GPIO irqchips: ensure spinlock_t or any sleepable APIs are not used 389 from chained IRQ handler; 390 - Generic chained GPIO irqchips: take care about generic_handle_irq() calls and 391 apply corresponding W/A; 392 - Chained GPIO irqchips: get rid of chained IRQ handler and use generic irq 393 handler if possible :) 394 - regmap_mmio: Sry, but you are in trouble :( if MMIO regmap is used as for 395 GPIO IRQ chip implementation; 396 - Test your driver with the appropriate in-kernel real time test cases for both 397 level and edge IRQs. 398 399 400 Requesting self-owned GPIO pins 401 ------------------------------- 402 403 Sometimes it is useful to allow a GPIO chip driver to request its own GPIO 404 descriptors through the gpiolib API. Using gpio_request() for this purpose 405 does not help since it pins the module to the kernel forever (it calls 406 try_module_get()). A GPIO driver can use the following functions instead 407 to request and free descriptors without being pinned to the kernel forever. 408 409 struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc, 410 const char *label) 411 412 void gpiochip_free_own_desc(struct gpio_desc *desc) 413 414 Descriptors requested with gpiochip_request_own_desc() must be released with 415 gpiochip_free_own_desc(). 416 417 These functions must be used with care since they do not affect module use 418 count. Do not use the functions to request gpio descriptors not owned by the 419 calling driver. 420 421  http://www.spinics.net/lists/linux-omap/msg120425.html 422  https://lkml.org/lkml/2015/9/25/494 423  https://lkml.org/lkml/2015/9/25/495