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