Documentation/gpio/driver.txt

   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 [1].
 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 [2].
 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 [3]).
 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.irq.domain, 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 [1] http://www.spinics.net/lists/linux-omap/msg120425.html
 422 [2] https://lkml.org/lkml/2015/9/25/494
 423 [3] https://lkml.org/lkml/2015/9/25/495