Lines Matching +full:gpio +full:- +full:open +full:- +full:drain
2 GPIO Descriptor Driver Interface
5 This document serves as a guide for GPIO chip drivers writers. Note that it
6 describes the new descriptor-based interface. For a description of the
7 deprecated integer-based GPIO interface please refer to gpio-legacy.txt.
9 Each GPIO controller driver needs to include the following header, which defines
10 the structures used to define a GPIO driver:
12 #include <linux/gpio/driver.h>
18 Inside a GPIO driver, individual GPIOs are identified by their hardware number,
21 GPIO descriptor is never made visible outside of the driver.
23 On top of this internal number, each GPIO also need to have a global number in
24 the integer GPIO namespace so that it can be used with the legacy GPIO
26 assigned), and for each GPIO the global number will be (base + hardware number).
30 So for example one platform could use numbers 32-159 for GPIOs, with a
32 numbers 0..63 with one set of GPIO controllers, 64-79 with another type of GPIO
33 controller, and on one particular board 80-95 with an FPGA. The numbers need not
34 be contiguous; either of those platforms could also use numbers 2000-2063 to
35 identify GPIOs in a bank of I2C GPIO expanders.
41 In the gpiolib framework each GPIO controller is packaged as a "struct
42 gpio_chip" (see linux/gpio/driver.h for its complete definition) with members
45 - methods to establish GPIO line direction
46 - methods used to access GPIO line values
47 - method to set electrical configuration for a given GPIO line
48 - method to return the IRQ number associated to a given GPIO line
49 - flag saying whether calls to its methods may sleep
50 - optional line names array to identify lines
51 - optional debugfs dump method (showing extra state like pullup config)
52 - optional base number (will be automatically assigned if omitted)
53 - optional label for diagnostics and GPIO chip mapping using platform data
58 Removing a GPIO controller should be rare; use ``[devm_]gpiochip_remove()``
61 Often a gpio_chip is part of an instance-specific structure with states not
62 exposed by the GPIO interfaces, such as addressing, power management, and more.
63 Chips such as audio codecs will have complex non-GPIO states.
67 NULL or the label associated with that GPIO when it was requested.
69 RT_FULL: the GPIO driver should not use spinlock_t or any sleepable APIs
71 control callbacks) if it is expected to call GPIO APIs from atomic context
72 on -RT (inside hard IRQ handlers and similar contexts). Normally this should
76 GPIO electrical configuration
77 -----------------------------
81 single-ended modes (open drain/open source). These settings are described
88 ending up in the pin control back-end "behind" the GPIO controller, usually
90 listed GPIO configurations.
92 If a pin controller back-end is used, the GPIO controller or hardware
93 description needs to provide "GPIO ranges" mapping the GPIO line offsets to pin
94 numbers on the pin controller so they can properly cross-reference each other.
98 ---------------------------
114 GPIOs with open drain/source support
115 ------------------------------------
117 Open drain (CMOS) or open collector (TTL) means the line is not actively driven
118 high: instead you provide the drain/collector as output, so when the transistor
119 is not open, it will present a high-impedance (tristate) to the external rail::
124 ||--- out +--- out
125 in ----|| |/
126 ||--+ in ----|
132 - Level-shifting: to reach a logical level higher than that of the silicon
135 - inverse wire-OR on an I/O line, for example a GPIO line, making it possible
139 wire-OR bus.
141 Both usecases require that the line be equipped with a pull-up resistor. This
145 The level on the line will go as high as the VDD on the pull-up resistor, which
147 level-shift to the higher VDD.
150 "totem-pole" with one N-MOS and one P-MOS transistor where one of them drives
151 the line high and one of them drives the line low. This is called a push-pull
152 output. The "totem-pole" looks like so::
156 OD ||--+
157 +--/ ---o|| P-MOS-FET
158 | ||--+
159 IN --+ +----- out
160 | ||--+
161 +--/ ----|| N-MOS-FET
162 OS ||--+
166 The desired output signal (e.g. coming directly from some GPIO output register)
168 a push-pull circuit.
171 P-MOS or N-MOS transistor right after the split of the input. As you can see,
172 either transistor will go totally numb if this switch is open. The totem-pole
174 high or low respectively. That is usually how software-controlled open
175 drain/source works.
177 Some GPIO hardware come in open drain / open source configuration. Some are
178 hard-wired lines that will only support open drain or open source no matter
179 what: there is only one transistor there. Some are software-configurable:
180 by flipping a bit in a register the output can be configured as open drain
181 or open source, in practice by flicking open the switches labeled "OD" and "OS"
184 By disabling the P-MOS transistor, the output can be driven between GND and
185 high impedance (open drain), and by disabling the N-MOS transistor, the output
186 can be driven between VDD and high impedance (open source). In the first case,
187 a pull-up resistor is needed on the outgoing rail to complete the circuit, and
188 in the second case, a pull-down resistor is needed on the rail.
190 Hardware that supports open drain or open source or both, can implement a
192 pinconf packed value telling whether to configure the line as open drain,
193 open source or push-pull. This will happen in response to the
197 If this state can not be configured in hardware, i.e. if the GPIO hardware does
198 not support open drain/open source in hardware, the GPIO library will instead
199 use a trick: when a line is set as output, if the line is flagged as open
200 drain, and the IN output value is low, it will be driven low as usual. But
203 achieveing an "open drain emulation" of sorts: electrically the behaviour will
207 For open source configuration the same principle is used, just that instead
211 GPIO drivers providing IRQs
212 ---------------------------
213 It is custom that GPIO drivers (GPIO chips) are also providing interrupts,
215 cases the GPIO logic is melded with a SoC's primary interrupt controller.
217 The IRQ portions of the GPIO block are implemented using an irqchip, using
218 the header <linux/irq.h>. So basically such a driver is utilizing two sub-
219 systems simultaneously: gpio and irq.
221 RT_FULL: a realtime compliant GPIO driver should not use spinlock_t or any
229 GPIO irqchips usually fall in one of two categories:
231 * CHAINED GPIO irqchips: these are usually the type that is embedded on
234 system interrupt controller. This means that the GPIO irqchip handler will
236 disabled. The GPIO irqchip will then end up calling something like this
244 Chained GPIO irqchips typically can NOT set the .can_sleep flag on
248 RT_FULL: Note, chained IRQ handlers will not be forced threaded on -RT.
251 If required (and if it can't be converted to the nested threaded GPIO irqchip)
253 it will be a threaded IRQ handler on -RT and a hard IRQ handler on non-RT
262 raw_spin_lock_irqsave(&bank->wa_lock, wa_lock_flags);
263 generic_handle_irq(irq_find_mapping(bank->chip.irq.domain, bit));
264 raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags);
266 * GENERIC CHAINED GPIO irqchips: these are the same as "CHAINED GPIO irqchips",
267 but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is
269 The GPIO irqchip will then end up calling something like this sequence in
273 for each detected GPIO IRQ
276 RT_FULL: Such kind of handlers will be forced threaded on -RT, as result IRQ
278 the same W/A as for "CHAINED GPIO irqchips" can be applied.
280 * NESTED THREADED GPIO irqchips: these are off-chip GPIO expanders and any
281 other GPIO irqchip residing on the other side of a sleeping bus. Of course
293 The hallmark of threaded GPIO irqchips is that they set the .can_sleep
297 To help out in handling the set-up and management of GPIO irqchips and the
306 (See Documentation/driver-model/design-patterns.txt)
330 - Make sure to assign all relevant members of the struct gpio_chip so that
334 - Nominally set all handlers to handle_bad_irq() in the setup call and pass
336 expected for GPIO driver that irqchip .set_type() callback have to be called
337 before using/enabling GPIO IRQ. Then set the handler to handle_level_irq()
342 if that is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and
347 certain GPIO line and should not be relied upon to have been called before
351 callbacks from the GPIO and irqchip APIs. Do not rely on gpiod_to_irq() having
356 GPIO line and register for example) it needs to deny certain operations and
362 -----------------
364 to mark the GPIO as being used as an IRQ::
368 This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
373 When implementing an irqchip inside a GPIO driver, these two functions should
380 Real-Time compliance for GPIO IRQ chips
381 ---------------------------------------
384 preemption. It is desirable that all irqchips in the GPIO subsystem keep this
385 in mind and do the proper testing to assure they are real time-enabled.
388 time-compliance:
390 - ensure spinlock_t is not used as part irq_chip implementation;
391 - ensure that sleepable APIs are not used as part irq_chip implementation.
394 - Chained GPIO irqchips: ensure spinlock_t or any sleepable APIs are not used
396 - Generic chained GPIO irqchips: take care about generic_handle_irq() calls and
398 - Chained GPIO irqchips: get rid of chained IRQ handler and use generic irq
400 - regmap_mmio: Sry, but you are in trouble :( if MMIO regmap is used as for
401 GPIO IRQ chip implementation;
402 - Test your driver with the appropriate in-kernel real time test cases for both
406 Requesting self-owned GPIO pins
407 -------------------------------
409 Sometimes it is useful to allow a GPIO chip driver to request its own GPIO
412 try_module_get()). A GPIO driver can use the following functions instead
424 count. Do not use the functions to request gpio descriptors not owned by the
427 * [1] http://www.spinics.net/lists/linux-omap/msg120425.html