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