1 /*
2  * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 
7 #ifndef _HARDWARE_GPIO_H
8 #define _HARDWARE_GPIO_H
9 
10 #include "pico.h"
11 #include "hardware/structs/sio.h"
12 #include "hardware/structs/padsbank0.h"
13 #include "hardware/structs/iobank0.h"
14 #include "hardware/irq.h"
15 
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19 
20 // PICO_CONFIG: PARAM_ASSERTIONS_ENABLED_GPIO, Enable/disable assertions in the GPIO module, type=bool, default=0, group=hardware_gpio
21 #ifndef PARAM_ASSERTIONS_ENABLED_GPIO
22 #define PARAM_ASSERTIONS_ENABLED_GPIO 0
23 #endif
24 
25 /** \file gpio.h
26  *  \defgroup hardware_gpio hardware_gpio
27  *
28  * General Purpose Input/Output (GPIO) API
29  *
30  * RP2040 has 36 multi-functional General Purpose Input / Output (GPIO) pins, divided into two banks. In a typical use case,
31  * the pins in the QSPI bank (QSPI_SS, QSPI_SCLK and QSPI_SD0 to QSPI_SD3) are used to execute code from an external
32  * flash device, leaving the User bank (GPIO0 to GPIO29) for the programmer to use. All GPIOs support digital input and
33  * output, but GPIO26 to GPIO29 can also be used as inputs to the chip’s Analogue to Digital Converter (ADC). Each GPIO
34  * can be controlled directly by software running on the processors, or by a number of other functional blocks.
35  *
36  * The function allocated to each GPIO is selected by calling the \ref gpio_set_function function. \note Not all functions
37  * are available on all pins.
38  *
39  * Each GPIO can have one function selected at a time. Likewise, each peripheral input (e.g. UART0 RX) should only be selected on
40  * one _GPIO_ at a time. If the same peripheral input is connected to multiple GPIOs, the peripheral sees the logical OR of these
41  * GPIO inputs. Please refer to the datasheet for more information on GPIO function select.
42  *
43  * ### Function Select Table
44  *
45  *  GPIO   | F1       | F2        | F3       | F4     | F5  | F6   | F7   | F8            | F9
46  *  -------|----------|-----------|----------|--------|-----|------|------|---------------|----
47  *  0      | SPI0 RX  | UART0 TX  | I2C0 SDA | PWM0 A | SIO | PIO0 | PIO1 |               | USB OVCUR DET
48  *  1      | SPI0 CSn | UART0 RX  | I2C0 SCL | PWM0 B | SIO | PIO0 | PIO1 |               | USB VBUS DET
49  *  2      | SPI0 SCK | UART0 CTS | I2C1 SDA | PWM1 A | SIO | PIO0 | PIO1 |               | USB VBUS EN
50  *  3      | SPI0 TX  | UART0 RTS | I2C1 SCL | PWM1 B | SIO | PIO0 | PIO1 |               | USB OVCUR DET
51  *  4      | SPI0 RX  | UART1 TX  | I2C0 SDA | PWM2 A | SIO | PIO0 | PIO1 |               | USB VBUS DET
52  *  5      | SPI0 CSn | UART1 RX  | I2C0 SCL | PWM2 B | SIO | PIO0 | PIO1 |               | USB VBUS EN
53  *  6      | SPI0 SCK | UART1 CTS | I2C1 SDA | PWM3 A | SIO | PIO0 | PIO1 |               | USB OVCUR DET
54  *  7      | SPI0 TX  | UART1 RTS | I2C1 SCL | PWM3 B | SIO | PIO0 | PIO1 |               | USB VBUS DET
55  *  8      | SPI1 RX  | UART1 TX  | I2C0 SDA | PWM4 A | SIO | PIO0 | PIO1 |               | USB VBUS EN
56  *  9      | SPI1 CSn | UART1 RX  | I2C0 SCL | PWM4 B | SIO | PIO0 | PIO1 |               | USB OVCUR DET
57  *  10     | SPI1 SCK | UART1 CTS | I2C1 SDA | PWM5 A | SIO | PIO0 | PIO1 |               | USB VBUS DET
58  *  11     | SPI1 TX  | UART1 RTS | I2C1 SCL | PWM5 B | SIO | PIO0 | PIO1 |               | USB VBUS EN
59  *  12     | SPI1 RX  | UART0 TX  | I2C0 SDA | PWM6 A | SIO | PIO0 | PIO1 |               | USB OVCUR DET
60  *  13     | SPI1 CSn | UART0 RX  | I2C0 SCL | PWM6 B | SIO | PIO0 | PIO1 |               | USB VBUS DET
61  *  14     | SPI1 SCK | UART0 CTS | I2C1 SDA | PWM7 A | SIO | PIO0 | PIO1 |               | USB VBUS EN
62  *  15     | SPI1 TX  | UART0 RTS | I2C1 SCL | PWM7 B | SIO | PIO0 | PIO1 |               | USB OVCUR DET
63  *  16     | SPI0 RX  | UART0 TX  | I2C0 SDA | PWM0 A | SIO | PIO0 | PIO1 |               | USB VBUS DET
64  *  17     | SPI0 CSn | UART0 RX  | I2C0 SCL | PWM0 B | SIO | PIO0 | PIO1 |               | USB VBUS EN
65  *  18     | SPI0 SCK | UART0 CTS | I2C1 SDA | PWM1 A | SIO | PIO0 | PIO1 |               | USB OVCUR DET
66  *  19     | SPI0 TX  | UART0 RTS | I2C1 SCL | PWM1 B | SIO | PIO0 | PIO1 |               | USB VBUS DET
67  *  20     | SPI0 RX  | UART1 TX  | I2C0 SDA | PWM2 A | SIO | PIO0 | PIO1 | CLOCK GPIN0   | USB VBUS EN
68  *  21     | SPI0 CSn | UART1 RX  | I2C0 SCL | PWM2 B | SIO | PIO0 | PIO1 | CLOCK GPOUT0  | USB OVCUR DET
69  *  22     | SPI0 SCK | UART1 CTS | I2C1 SDA | PWM3 A | SIO | PIO0 | PIO1 | CLOCK GPIN1   | USB VBUS DET
70  *  23     | SPI0 TX  | UART1 RTS | I2C1 SCL | PWM3 B | SIO | PIO0 | PIO1 | CLOCK GPOUT1  | USB VBUS EN
71  *  24     | SPI1 RX  | UART1 TX  | I2C0 SDA | PWM4 A | SIO | PIO0 | PIO1 | CLOCK GPOUT2  | USB OVCUR DET
72  *  25     | SPI1 CSn | UART1 RX  | I2C0 SCL | PWM4 B | SIO | PIO0 | PIO1 | CLOCK GPOUT3  | USB VBUS DET
73  *  26     | SPI1 SCK | UART1 CTS | I2C1 SDA | PWM5 A | SIO | PIO0 | PIO1 |               | USB VBUS EN
74  *  27     | SPI1 TX  | UART1 RTS | I2C1 SCL | PWM5 B | SIO | PIO0 | PIO1 |               | USB OVCUR DET
75  *  28     | SPI1 RX  | UART0 TX  | I2C0 SDA | PWM6 A | SIO | PIO0 | PIO1 |               | USB VBUS DET
76  *  29     | SPI1 CSn | UART0 RX  | I2C0 SCL | PWM6 B | SIO | PIO0 | PIO1 |               | USB VBUS EN
77 
78  */
79 
80 /*! \brief  GPIO function definitions for use with function select
81  *  \ingroup hardware_gpio
82  * \brief GPIO function selectors
83  *
84  * Each GPIO can have one function selected at a time. Likewise, each peripheral input (e.g. UART0 RX) should only be
85  * selected on one GPIO at a time. If the same peripheral input is connected to multiple GPIOs, the peripheral sees the logical
86  * OR of these GPIO inputs.
87  *
88  * Please refer to the datasheet for more information on GPIO function selection.
89  */
90 enum gpio_function {
91     GPIO_FUNC_XIP = 0,
92     GPIO_FUNC_SPI = 1,
93     GPIO_FUNC_UART = 2,
94     GPIO_FUNC_I2C = 3,
95     GPIO_FUNC_PWM = 4,
96     GPIO_FUNC_SIO = 5,
97     GPIO_FUNC_PIO0 = 6,
98     GPIO_FUNC_PIO1 = 7,
99     GPIO_FUNC_GPCK = 8,
100     GPIO_FUNC_USB = 9,
101     GPIO_FUNC_NULL = 0x1f,
102 };
103 
104 #define GPIO_OUT 1
105 #define GPIO_IN 0
106 
107 /*! \brief  GPIO Interrupt level definitions (GPIO events)
108  *  \ingroup hardware_gpio
109  *  \brief GPIO Interrupt levels
110  *
111  * An interrupt can be generated for every GPIO pin in 4 scenarios:
112  *
113  * * Level High: the GPIO pin is a logical 1
114  * * Level Low: the GPIO pin is a logical 0
115  * * Edge High: the GPIO has transitioned from a logical 0 to a logical 1
116  * * Edge Low: the GPIO has transitioned from a logical 1 to a logical 0
117  *
118  * The level interrupts are not latched. This means that if the pin is a logical 1 and the level high interrupt is active, it will
119  * become inactive as soon as the pin changes to a logical 0. The edge interrupts are stored in the INTR register and can be
120  * cleared by writing to the INTR register.
121  */
122 enum gpio_irq_level {
123     GPIO_IRQ_LEVEL_LOW = 0x1u,
124     GPIO_IRQ_LEVEL_HIGH = 0x2u,
125     GPIO_IRQ_EDGE_FALL = 0x4u,
126     GPIO_IRQ_EDGE_RISE = 0x8u,
127 };
128 
129 /*! Callback function type for GPIO events
130  *  \ingroup hardware_gpio
131  *
132  * \param gpio Which GPIO caused this interrupt
133  * \param event_mask Which events caused this interrupt. See \ref gpio_irq_level for details.
134  * \sa gpio_set_irq_enabled_with_callback()
135  * \sa gpio_set_irq_callback()
136  */
137 typedef void (*gpio_irq_callback_t)(uint gpio, uint32_t event_mask);
138 
139 enum gpio_override {
140     GPIO_OVERRIDE_NORMAL = 0,      ///< peripheral signal selected via \ref gpio_set_function
141     GPIO_OVERRIDE_INVERT = 1,      ///< invert peripheral signal selected via \ref gpio_set_function
142     GPIO_OVERRIDE_LOW = 2,         ///< drive low/disable output
143     GPIO_OVERRIDE_HIGH = 3,        ///< drive high/enable output
144 };
145 
146 /*! \brief Slew rate limiting levels for GPIO outputs
147  *  \ingroup hardware_gpio
148  *
149  * Slew rate limiting increases the minimum rise/fall time when a GPIO output
150  * is lightly loaded, which can help to reduce electromagnetic emissions.
151  * \sa gpio_set_slew_rate
152  */
153 enum gpio_slew_rate {
154     GPIO_SLEW_RATE_SLOW = 0,  ///< Slew rate limiting enabled
155     GPIO_SLEW_RATE_FAST = 1   ///< Slew rate limiting disabled
156 };
157 
158 /*! \brief Drive strength levels for GPIO outputs
159  *  \ingroup hardware_gpio
160  *
161  * Drive strength levels for GPIO outputs.
162  * \sa gpio_set_drive_strength
163  */
164 enum gpio_drive_strength {
165     GPIO_DRIVE_STRENGTH_2MA = 0, ///< 2 mA nominal drive strength
166     GPIO_DRIVE_STRENGTH_4MA = 1, ///< 4 mA nominal drive strength
167     GPIO_DRIVE_STRENGTH_8MA = 2, ///< 8 mA nominal drive strength
168     GPIO_DRIVE_STRENGTH_12MA = 3 ///< 12 mA nominal drive strength
169 };
170 
check_gpio_param(__unused uint gpio)171 static inline void check_gpio_param(__unused uint gpio) {
172     invalid_params_if(GPIO, gpio >= NUM_BANK0_GPIOS);
173 }
174 
175 // ----------------------------------------------------------------------------
176 // Pad Controls + IO Muxing
177 // ----------------------------------------------------------------------------
178 // Declarations for gpio.c
179 
180 /*! \brief Select GPIO function
181  *  \ingroup hardware_gpio
182  *
183  * \param gpio GPIO number
184  * \param fn Which GPIO function select to use from list \ref gpio_function
185  */
186 void gpio_set_function(uint gpio, enum gpio_function fn);
187 
188 /*! \brief Determine current GPIO function
189  *  \ingroup hardware_gpio
190  *
191  * \param gpio GPIO number
192  * \return Which GPIO function is currently selected from list \ref gpio_function
193  */
194 enum gpio_function gpio_get_function(uint gpio);
195 
196 /*! \brief Select up and down pulls on specific GPIO
197  *  \ingroup hardware_gpio
198  *
199  * \param gpio GPIO number
200  * \param up If true set a pull up on the GPIO
201  * \param down If true set a pull down on the GPIO
202  *
203  * \note On the RP2040, setting both pulls enables a "bus keep" function,
204  * i.e. a weak pull to whatever is current high/low state of GPIO.
205  */
206 void gpio_set_pulls(uint gpio, bool up, bool down);
207 
208 /*! \brief Set specified GPIO to be pulled up.
209  *  \ingroup hardware_gpio
210  *
211  * \param gpio GPIO number
212  */
gpio_pull_up(uint gpio)213 static inline void gpio_pull_up(uint gpio) {
214     gpio_set_pulls(gpio, true, false);
215 }
216 
217 /*! \brief Determine if the specified GPIO is pulled up.
218  *  \ingroup hardware_gpio
219  *
220  * \param gpio GPIO number
221  * \return true if the GPIO is pulled up
222  */
gpio_is_pulled_up(uint gpio)223 static inline bool gpio_is_pulled_up(uint gpio) {
224     return (padsbank0_hw->io[gpio] & PADS_BANK0_GPIO0_PUE_BITS) != 0;
225 }
226 
227 /*! \brief Set specified GPIO to be pulled down.
228  *  \ingroup hardware_gpio
229  *
230  * \param gpio GPIO number
231  */
gpio_pull_down(uint gpio)232 static inline void gpio_pull_down(uint gpio) {
233     gpio_set_pulls(gpio, false, true);
234 }
235 
236 /*! \brief Determine if the specified GPIO is pulled down.
237  *  \ingroup hardware_gpio
238  *
239  * \param gpio GPIO number
240  * \return true if the GPIO is pulled down
241  */
gpio_is_pulled_down(uint gpio)242 static inline bool gpio_is_pulled_down(uint gpio) {
243     return (padsbank0_hw->io[gpio] & PADS_BANK0_GPIO0_PDE_BITS) != 0;
244 }
245 
246 /*! \brief Disable pulls on specified GPIO
247  *  \ingroup hardware_gpio
248  *
249  * \param gpio GPIO number
250  */
gpio_disable_pulls(uint gpio)251 static inline void gpio_disable_pulls(uint gpio) {
252     gpio_set_pulls(gpio, false, false);
253 }
254 
255 /*! \brief Set GPIO IRQ override
256  *  \ingroup hardware_gpio
257  *
258  * Optionally invert a GPIO IRQ signal, or drive it high or low
259  *
260  * \param gpio GPIO number
261  * \param value See \ref gpio_override
262  */
263 void gpio_set_irqover(uint gpio, uint value);
264 
265 /*! \brief Set GPIO output override
266  *  \ingroup hardware_gpio
267  *
268  * \param gpio GPIO number
269  * \param value See \ref gpio_override
270  */
271 void gpio_set_outover(uint gpio, uint value);
272 
273 /*! \brief Select GPIO input override
274  *  \ingroup hardware_gpio
275  *
276  * \param gpio GPIO number
277  * \param value See \ref gpio_override
278  */
279 void gpio_set_inover(uint gpio, uint value);
280 
281 /*! \brief Select GPIO output enable override
282  *  \ingroup hardware_gpio
283  *
284  * \param gpio GPIO number
285  * \param value See \ref gpio_override
286  */
287 void gpio_set_oeover(uint gpio, uint value);
288 
289 /*! \brief Enable GPIO input
290  *  \ingroup hardware_gpio
291  *
292  * \param gpio GPIO number
293  * \param enabled true to enable input on specified GPIO
294  */
295 void gpio_set_input_enabled(uint gpio, bool enabled);
296 
297 /*! \brief Enable/disable GPIO input hysteresis (Schmitt trigger)
298  *  \ingroup hardware_gpio
299  *
300  * Enable or disable the Schmitt trigger hysteresis on a given GPIO. This is
301  * enabled on all GPIOs by default. Disabling input hysteresis can lead to
302  * inconsistent readings when the input signal has very long rise or fall
303  * times, but slightly reduces the GPIO's input delay.
304  *
305  * \sa gpio_is_input_hysteresis_enabled
306  * \param gpio GPIO number
307  * \param enabled true to enable input hysteresis on specified GPIO
308  */
309 void gpio_set_input_hysteresis_enabled(uint gpio, bool enabled);
310 
311 /*! \brief Determine whether input hysteresis is enabled on a specified GPIO
312  *  \ingroup hardware_gpio
313  *
314  * \sa gpio_set_input_hysteresis_enabled
315  * \param gpio GPIO number
316  */
317 bool gpio_is_input_hysteresis_enabled(uint gpio);
318 
319 
320 /*! \brief Set slew rate for a specified GPIO
321  *  \ingroup hardware_gpio
322  *
323  * \sa gpio_get_slew_rate
324  * \param gpio GPIO number
325  * \param slew GPIO output slew rate
326  */
327 void gpio_set_slew_rate(uint gpio, enum gpio_slew_rate slew);
328 
329 /*! \brief Determine current slew rate for a specified GPIO
330  *  \ingroup hardware_gpio
331  *
332  * \sa gpio_set_slew_rate
333  * \param gpio GPIO number
334  * \return Current slew rate of that GPIO
335  */
336 enum gpio_slew_rate gpio_get_slew_rate(uint gpio);
337 
338 /*! \brief Set drive strength for a specified GPIO
339  *  \ingroup hardware_gpio
340  *
341  * \sa gpio_get_drive_strength
342  * \param gpio GPIO number
343  * \param drive GPIO output drive strength
344  */
345 void gpio_set_drive_strength(uint gpio, enum gpio_drive_strength drive);
346 
347 /*! \brief Determine current slew rate for a specified GPIO
348  *  \ingroup hardware_gpio
349  *
350  * \sa gpio_set_drive_strength
351  * \param gpio GPIO number
352  * \return Current drive strength of that GPIO
353  */
354 enum gpio_drive_strength gpio_get_drive_strength(uint gpio);
355 
356 /*! \brief Enable or disable specific interrupt events for specified GPIO
357  *  \ingroup hardware_gpio
358  *
359  * This function sets which GPIO events cause a GPIO interrupt on the calling core. See
360  * \ref gpio_set_irq_callback, \ref gpio_set_irq_enabled_with_callback and
361  * \ref gpio_add_raw_irq_handler to set up a GPIO interrupt handler to handle the events.
362  *
363  * \note The IO IRQs are independent per-processor. This configures the interrupt events for
364  * the processor that calls the function.
365  *
366  * \param gpio GPIO number
367  * \param event_mask Which events will cause an interrupt
368  * \param enabled Enable or disable flag
369  *
370  * Events is a bitmask of the following \ref gpio_irq_level values:
371  *
372  * bit | constant            | interrupt
373  * ----|----------------------------------------------------------
374  *   0 | GPIO_IRQ_LEVEL_LOW  | Continuously while level is low
375  *   1 | GPIO_IRQ_LEVEL_HIGH | Continuously while level is high
376  *   2 | GPIO_IRQ_EDGE_FALL  | On each transition from high to low
377  *   3 | GPIO_IRQ_EDGE_RISE  | On each transition from low to high
378  *
379  * which are specified in \ref gpio_irq_level
380  */
381 void gpio_set_irq_enabled(uint gpio, uint32_t event_mask, bool enabled);
382 
383 // PICO_CONFIG: GPIO_IRQ_CALLBACK_ORDER_PRIORITY, the irq priority order of the default IRQ callback, min=0, max=255, default=PICO_SHARED_IRQ_HANDLER_LOWEST_ORDER_PRIORITY, group=hardware_gpio
384 #ifndef GPIO_IRQ_CALLBACK_ORDER_PRIORITY
385 #define GPIO_IRQ_CALLBACK_ORDER_PRIORITY PICO_SHARED_IRQ_HANDLER_LOWEST_ORDER_PRIORITY
386 #endif
387 
388 // PICO_CONFIG: GPIO_RAW_IRQ_HANDLER_DEFAULT_ORDER_PRIORITY, the irq priority order of raw IRQ handlers if the priortiy is not specified, min=0, max=255, default=PICO_SHARED_IRQ_HANDLER_DEFAULT_ORDER_PRIORITY, group=hardware_gpio
389 #ifndef GPIO_RAW_IRQ_HANDLER_DEFAULT_ORDER_PRIORITY
390 #define GPIO_RAW_IRQ_HANDLER_DEFAULT_ORDER_PRIORITY PICO_SHARED_IRQ_HANDLER_DEFAULT_ORDER_PRIORITY
391 #endif
392 
393 /*! \brief Set the generic callback used for GPIO IRQ events for the current core
394  *  \ingroup hardware_gpio
395  *
396  * This function sets the callback used for all GPIO IRQs on the current core that are not explicitly
397  * hooked via \ref gpio_add_raw_irq_handler or other gpio_add_raw_irq_handler_ functions.
398  *
399  * This function is called with the GPIO number and event mask for each of the (not explicitly hooked)
400  * GPIOs that have events enabled and that are pending (see \ref gpio_get_irq_event_mask).
401  *
402  * \note The IO IRQs are independent per-processor. This function affects
403  * the processor that calls the function.
404  *
405  * \param callback default user function to call on GPIO irq. Note only one of these can be set per processor.
406  */
407 void gpio_set_irq_callback(gpio_irq_callback_t callback);
408 
409 /*! \brief Convenience function which performs multiple GPIO IRQ related initializations
410  *  \ingroup hardware_gpio
411  *
412  * This method is a slightly eclectic mix of initialization, that:
413  *
414  * \li Updates whether the specified events for the specified GPIO causes an interrupt on the calling core based
415  * on the enable flag.
416  *
417  * \li Sets the callback handler for the calling core to callback (or clears the handler if the callback is NULL).
418  *
419  * \li Enables GPIO IRQs on the current core if enabled is true.
420  *
421  * This method is commonly used to perform a one time setup, and following that any additional IRQs/events are enabled
422  * via \ref gpio_set_irq_enabled. All GPIOs/events added in this way on the same core share the same callback; for multiple
423  * independent handlers for different GPIOs you should use \ref gpio_add_raw_irq_handler and related functions.
424  *
425  * This method is equivalent to:
426  *
427  * \code{.c}
428  * gpio_set_irq_enabled(gpio, event_mask, enabled);
429  * gpio_set_irq_callback(callback);
430  * if (enabled) irq_set_enabled(IO_IRQ_BANK0, true);
431  * \endcode
432  *
433  * \note The IO IRQs are independent per-processor. This method affects only the processor that calls the function.
434  *
435  * \param gpio GPIO number
436  * \param event_mask Which events will cause an interrupt. See \ref gpio_irq_level for details.
437  * \param enabled Enable or disable flag
438  * \param callback user function to call on GPIO irq. if NULL, the callback is removed
439  */
440 void gpio_set_irq_enabled_with_callback(uint gpio, uint32_t event_mask, bool enabled, gpio_irq_callback_t callback);
441 
442 /*! \brief Enable dormant wake up interrupt for specified GPIO and events
443  *  \ingroup hardware_gpio
444  *
445  * This configures IRQs to restart the XOSC or ROSC when they are
446  * disabled in dormant mode
447  *
448  * \param gpio GPIO number
449  * \param event_mask Which events will cause an interrupt. See \ref gpio_irq_level for details.
450  * \param enabled Enable/disable flag
451  */
452 void gpio_set_dormant_irq_enabled(uint gpio, uint32_t event_mask, bool enabled);
453 
454 /*! \brief Return the current interrupt status (pending events) for the given GPIO
455  *  \ingroup hardware_gpio
456  *
457  * \param gpio GPIO number
458  * \return Bitmask of events that are currently pending for the GPIO. See \ref gpio_irq_level for details.
459  * \sa gpio_acknowledge_irq
460  */
gpio_get_irq_event_mask(uint gpio)461 static inline uint32_t gpio_get_irq_event_mask(uint gpio) {
462     check_gpio_param(gpio);
463     io_irq_ctrl_hw_t *irq_ctrl_base = get_core_num() ?
464                                       &iobank0_hw->proc1_irq_ctrl : &iobank0_hw->proc0_irq_ctrl;
465     io_ro_32 *status_reg = &irq_ctrl_base->ints[gpio >> 3u];
466     return (*status_reg >> (4 * (gpio & 7u))) & 0xfu;
467 }
468 
469 /*! \brief Acknowledge a GPIO interrupt for the specified events on the calling core
470  *  \ingroup hardware_gpio
471  *
472  * \note This may be called with a mask of any of valid bits specified in \ref gpio_irq_level, however
473  * it has no effect on \a level sensitive interrupts which remain pending while the GPIO is at the specified
474  * level. When handling \a level sensitive interrupts, you should generally disable the interrupt (see
475  * \ref gpio_set_irq_enabled) and then set it up again later once the GPIO level has changed (or to catch
476  * the opposite level).
477  *
478  * \param gpio GPIO number
479  *
480  * \note For callbacks set with \ref gpio_set_irq_enabled_with_callback, or \ref gpio_set_irq_callback, this function is called automatically.
481  * \param event_mask Bitmask of events to clear. See \ref gpio_irq_level for details.
482  */
483 void gpio_acknowledge_irq(uint gpio, uint32_t event_mask);
484 
485 /*! \brief Adds a raw GPIO IRQ handler for the specified GPIOs on the current core
486  *  \ingroup hardware_gpio
487  *
488  * In addition to the default mechanism of a single GPIO IRQ event callback per core (see \ref gpio_set_irq_callback),
489  * it is possible to add explicit GPIO IRQ handlers which are called independent of the default callback. The order
490  * relative to the default callback can be controlled via the order_priority parameter (the default callback has the priority
491  * \ref GPIO_IRQ_CALLBACK_ORDER_PRIORITY which defaults to the lowest priority with the intention of it running last).
492  *
493  * This method adds such an explicit GPIO IRQ handler, and disables the "default" callback for the specified GPIOs.
494  *
495  * \note Multiple raw handlers should not be added for the same GPIOs, and this method will assert if you attempt to.
496  *
497  * A raw handler should check for whichever GPIOs and events it handles, and acknowledge them itself; it might look something like:
498  *
499  * \code{.c}
500  * void my_irq_handler(void) {
501  *     if (gpio_get_irq_event_mask(my_gpio_num) & my_gpio_event_mask) {
502  *        gpio_acknowledge_irq(my_gpio_num, my_gpio_event_mask);
503  *       // handle the IRQ
504  *     }
505  *     if (gpio_get_irq_event_mask(my_gpio_num2) & my_gpio_event_mask2) {
506  *        gpio_acknowledge_irq(my_gpio_num2, my_gpio_event_mask2);
507  *       // handle the IRQ
508  *     }
509  * }
510  * \endcode
511  *
512  * @param gpio_mask a bit mask of the GPIO numbers that will no longer be passed to the default callback for this core
513  * @param handler the handler to add to the list of GPIO IRQ handlers for this core
514  * @param order_priority the priority order to determine the relative position of the handler in the list of GPIO IRQ handlers for this core.
515  */
516 void gpio_add_raw_irq_handler_with_order_priority_masked(uint gpio_mask, irq_handler_t handler, uint8_t order_priority);
517 
518 /*! \brief Adds a raw GPIO IRQ handler for a specific GPIO on the current core
519  *  \ingroup hardware_gpio
520  *
521  * In addition to the default mechanism of a single GPIO IRQ event callback per core (see \ref gpio_set_irq_callback),
522  * it is possible to add explicit GPIO IRQ handlers which are called independent of the default callback. The order
523  * relative to the default callback can be controlled via the order_priority parameter(the default callback has the priority
524  * \ref GPIO_IRQ_CALLBACK_ORDER_PRIORITY which defaults to the lowest priority with the intention of it running last).
525  *
526  * This method adds such a callback, and disables the "default" callback for the specified GPIO.
527  *
528  * \note Multiple raw handlers should not be added for the same GPIO, and this method will assert if you attempt to.
529  *
530  * A raw handler should check for whichever GPIOs and events it handles, and acknowledge them itself; it might look something like:
531  *
532  * \code{.c}
533  * void my_irq_handler(void) {
534  *     if (gpio_get_irq_event_mask(my_gpio_num) & my_gpio_event_mask) {
535  *        gpio_acknowledge_irq(my_gpio_num, my_gpio_event_mask);
536  *       // handle the IRQ
537  *     }
538  * }
539  * \endcode
540  *
541  * @param gpio the GPIO number that will no longer be passed to the default callback for this core
542  * @param handler the handler to add to the list of GPIO IRQ handlers for this core
543  * @param order_priority the priority order to determine the relative position of the handler in the list of GPIO IRQ handlers for this core.
544  */
gpio_add_raw_irq_handler_with_order_priority(uint gpio,irq_handler_t handler,uint8_t order_priority)545 static inline void gpio_add_raw_irq_handler_with_order_priority(uint gpio, irq_handler_t handler, uint8_t order_priority) {
546     check_gpio_param(gpio);
547     gpio_add_raw_irq_handler_with_order_priority_masked(1u << gpio, handler, order_priority);
548 }
549 
550 /*! \brief Adds a raw GPIO IRQ handler for the specified GPIOs on the current core
551  *  \ingroup hardware_gpio
552  *
553  * In addition to the default mechanism of a single GPIO IRQ event callback per core (see \ref gpio_set_irq_callback),
554  * it is possible to add explicit GPIO IRQ handlers which are called independent of the default event callback.
555  *
556  * This method adds such a callback, and disables the "default" callback for the specified GPIOs.
557  *
558  * \note Multiple raw handlers should not be added for the same GPIOs, and this method will assert if you attempt to.
559  *
560  * A raw handler should check for whichever GPIOs and events it handles, and acknowledge them itself; it might look something like:
561  *
562  * \code{.c}
563  * void my_irq_handler(void) {
564  *     if (gpio_get_irq_event_mask(my_gpio_num) & my_gpio_event_mask) {
565  *        gpio_acknowledge_irq(my_gpio_num, my_gpio_event_mask);
566  *       // handle the IRQ
567  *     }
568  *     if (gpio_get_irq_event_mask(my_gpio_num2) & my_gpio_event_mask2) {
569  *        gpio_acknowledge_irq(my_gpio_num2, my_gpio_event_mask2);
570  *       // handle the IRQ
571  *     }
572  * }
573  * \endcode
574  *
575  * @param gpio_mask a bit mask of the GPIO numbers that will no longer be passed to the default callback for this core
576  * @param handler the handler to add to the list of GPIO IRQ handlers for this core
577  */
578 void gpio_add_raw_irq_handler_masked(uint gpio_mask, irq_handler_t handler);
579 
580 /*! \brief Adds a raw GPIO IRQ handler for a specific GPIO on the current core
581  *  \ingroup hardware_gpio
582  *
583  * In addition to the default mechanism of a single GPIO IRQ event callback per core (see \ref gpio_set_irq_callback),
584  * it is possible to add explicit GPIO IRQ handlers which are called independent of the default event callback.
585  *
586  * This method adds such a callback, and disables the "default" callback for the specified GPIO.
587  *
588  * \note Multiple raw handlers should not be added for the same GPIO, and this method will assert if you attempt to.
589  *
590  * A raw handler should check for whichever GPIOs and events it handles, and acknowledge them itself; it might look something like:
591  *
592  * \code{.c}
593  * void my_irq_handler(void) {
594  *     if (gpio_get_irq_event_mask(my_gpio_num) & my_gpio_event_mask) {
595  *        gpio_acknowledge_irq(my_gpio_num, my_gpio_event_mask);
596  *       // handle the IRQ
597  *     }
598  * }
599  * \endcode
600  *
601  * @param gpio the GPIO number that will no longer be passed to the default callback for this core
602  * @param handler the handler to add to the list of GPIO IRQ handlers for this core
603  */
gpio_add_raw_irq_handler(uint gpio,irq_handler_t handler)604 static inline void gpio_add_raw_irq_handler(uint gpio, irq_handler_t handler) {
605     check_gpio_param(gpio);
606     gpio_add_raw_irq_handler_masked(1u << gpio, handler);
607 }
608 
609 /*! \brief Removes a raw GPIO IRQ handler for the specified GPIOs on the current core
610  *  \ingroup hardware_gpio
611  *
612  * In addition to the default mechanism of a single GPIO IRQ event callback per core (see \ref gpio_set_irq_callback),
613  * it is possible to add explicit GPIO IRQ handlers which are called independent of the default event callback.
614  *
615  * This method removes such a callback, and enables the "default" callback for the specified GPIOs.
616  *
617  * @param gpio_mask a bit mask of the GPIO numbers that will now be passed to the default callback for this core
618  * @param handler the handler to remove from the list of GPIO IRQ handlers for this core
619  */
620 void gpio_remove_raw_irq_handler_masked(uint gpio_mask, irq_handler_t handler);
621 
622 /*! \brief Removes a raw GPIO IRQ handler for the specified GPIO on the current core
623  *  \ingroup hardware_gpio
624  *
625  * In addition to the default mechanism of a single GPIO IRQ event callback per core (see \ref gpio_set_irq_callback),
626  * it is possible to add explicit GPIO IRQ handlers which are called independent of the default event callback.
627  *
628  * This method removes such a callback, and enables the "default" callback for the specified GPIO.
629  *
630  * @param gpio the GPIO number that will now be passed to the default callback for this core
631  * @param handler the handler to remove from the list of GPIO IRQ handlers for this core
632  */
gpio_remove_raw_irq_handler(uint gpio,irq_handler_t handler)633 static inline void gpio_remove_raw_irq_handler(uint gpio, irq_handler_t handler) {
634     check_gpio_param(gpio);
635     gpio_remove_raw_irq_handler_masked(1u << gpio, handler);
636 }
637 
638 /*! \brief Initialise a GPIO for (enabled I/O and set func to GPIO_FUNC_SIO)
639  *  \ingroup hardware_gpio
640  *
641  * Clear the output enable (i.e. set to input).
642  * Clear any output value.
643  *
644  * \param gpio GPIO number
645  */
646 void gpio_init(uint gpio);
647 
648 /*! \brief Resets a GPIO back to the NULL function, i.e. disables it.
649  *  \ingroup hardware_gpio
650  *
651  * \param gpio GPIO number
652  */
653 void gpio_deinit(uint gpio);
654 
655 /*! \brief Initialise multiple GPIOs (enabled I/O and set func to GPIO_FUNC_SIO)
656  *  \ingroup hardware_gpio
657  *
658  * Clear the output enable (i.e. set to input).
659  * Clear any output value.
660  *
661  * \param gpio_mask Mask with 1 bit per GPIO number to initialize
662  */
663 void gpio_init_mask(uint gpio_mask);
664 // ----------------------------------------------------------------------------
665 // Input
666 // ----------------------------------------------------------------------------
667 
668 /*! \brief Get state of a single specified GPIO
669  *  \ingroup hardware_gpio
670  *
671  * \param gpio GPIO number
672  * \return Current state of the GPIO. 0 for low, non-zero for high
673  */
gpio_get(uint gpio)674 static inline bool gpio_get(uint gpio) {
675     return !!((1ul << gpio) & sio_hw->gpio_in);
676 }
677 
678 /*! \brief Get raw value of all GPIOs
679  *  \ingroup hardware_gpio
680  *
681  * \return Bitmask of raw GPIO values, as bits 0-29
682  */
gpio_get_all(void)683 static inline uint32_t gpio_get_all(void) {
684     return sio_hw->gpio_in;
685 }
686 
687 // ----------------------------------------------------------------------------
688 // Output
689 // ----------------------------------------------------------------------------
690 
691 /*! \brief Drive high every GPIO appearing in mask
692  *  \ingroup hardware_gpio
693  *
694  * \param mask Bitmask of GPIO values to set, as bits 0-29
695  */
gpio_set_mask(uint32_t mask)696 static inline void gpio_set_mask(uint32_t mask) {
697     sio_hw->gpio_set = mask;
698 }
699 
700 /*! \brief Drive low every GPIO appearing in mask
701  *  \ingroup hardware_gpio
702  *
703  * \param mask Bitmask of GPIO values to clear, as bits 0-29
704  */
gpio_clr_mask(uint32_t mask)705 static inline void gpio_clr_mask(uint32_t mask) {
706     sio_hw->gpio_clr = mask;
707 }
708 
709 /*! \brief Toggle every GPIO appearing in mask
710  *  \ingroup hardware_gpio
711  *
712  * \param mask Bitmask of GPIO values to toggle, as bits 0-29
713  */
gpio_xor_mask(uint32_t mask)714 static inline void gpio_xor_mask(uint32_t mask) {
715     sio_hw->gpio_togl = mask;
716 }
717 
718 /*! \brief Drive GPIO high/low depending on parameters
719  *  \ingroup hardware_gpio
720  *
721  * \param mask Bitmask of GPIO values to change, as bits 0-29
722  * \param value Value to set
723  *
724  * For each 1 bit in \p mask, drive that pin to the value given by
725  * corresponding bit in \p value, leaving other pins unchanged.
726  * Since this uses the TOGL alias, it is concurrency-safe with e.g. an IRQ
727  * bashing different pins from the same core.
728  */
gpio_put_masked(uint32_t mask,uint32_t value)729 static inline void gpio_put_masked(uint32_t mask, uint32_t value) {
730     sio_hw->gpio_togl = (sio_hw->gpio_out ^ value) & mask;
731 }
732 
733 /*! \brief Drive all pins simultaneously
734  *  \ingroup hardware_gpio
735  *
736  * \param value Bitmask of GPIO values to change, as bits 0-29
737  */
gpio_put_all(uint32_t value)738 static inline void gpio_put_all(uint32_t value) {
739     sio_hw->gpio_out = value;
740 }
741 
742 /*! \brief Drive a single GPIO high/low
743  *  \ingroup hardware_gpio
744  *
745  * \param gpio GPIO number
746  * \param value If false clear the GPIO, otherwise set it.
747  */
gpio_put(uint gpio,bool value)748 static inline void gpio_put(uint gpio, bool value) {
749     uint32_t mask = 1ul << gpio;
750     if (value)
751         gpio_set_mask(mask);
752     else
753         gpio_clr_mask(mask);
754 }
755 
756 /*! \brief Determine whether a GPIO is currently driven high or low
757  *  \ingroup hardware_gpio
758  *
759  * This function returns the high/low output level most recently assigned to a
760  * GPIO via gpio_put() or similar. This is the value that is presented outward
761  * to the IO muxing, *not* the input level back from the pad (which can be
762  * read using gpio_get()).
763  *
764  * To avoid races, this function must not be used for read-modify-write
765  * sequences when driving GPIOs -- instead functions like gpio_put() should be
766  * used to atomically update GPIOs. This accessor is intended for debug use
767  * only.
768  *
769  * \param gpio GPIO number
770  * \return true if the GPIO output level is high, false if low.
771  */
gpio_get_out_level(uint gpio)772 static inline bool gpio_get_out_level(uint gpio) {
773     return !!(sio_hw->gpio_out & (1u << gpio));
774 }
775 
776 // ----------------------------------------------------------------------------
777 // Direction
778 // ----------------------------------------------------------------------------
779 
780 /*! \brief Set a number of GPIOs to output
781  *  \ingroup hardware_gpio
782  *
783  * Switch all GPIOs in "mask" to output
784  *
785  * \param mask Bitmask of GPIO to set to output, as bits 0-29
786  */
gpio_set_dir_out_masked(uint32_t mask)787 static inline void gpio_set_dir_out_masked(uint32_t mask) {
788     sio_hw->gpio_oe_set = mask;
789 }
790 
791 /*! \brief Set a number of GPIOs to input
792  *  \ingroup hardware_gpio
793  *
794  * \param mask Bitmask of GPIO to set to input, as bits 0-29
795  */
gpio_set_dir_in_masked(uint32_t mask)796 static inline void gpio_set_dir_in_masked(uint32_t mask) {
797     sio_hw->gpio_oe_clr = mask;
798 }
799 
800 /*! \brief Set multiple GPIO directions
801  *  \ingroup hardware_gpio
802  *
803  * \param mask Bitmask of GPIO to set to input, as bits 0-29
804  * \param value Values to set
805  *
806  * For each 1 bit in "mask", switch that pin to the direction given by
807  * corresponding bit in "value", leaving other pins unchanged.
808  * E.g. gpio_set_dir_masked(0x3, 0x2); -> set pin 0 to input, pin 1 to output,
809  * simultaneously.
810  */
gpio_set_dir_masked(uint32_t mask,uint32_t value)811 static inline void gpio_set_dir_masked(uint32_t mask, uint32_t value) {
812     sio_hw->gpio_oe_togl = (sio_hw->gpio_oe ^ value) & mask;
813 }
814 
815 /*! \brief Set direction of all pins simultaneously.
816  *  \ingroup hardware_gpio
817  *
818  * \param values individual settings for each gpio; for GPIO N, bit N is 1 for out, 0 for in
819  */
gpio_set_dir_all_bits(uint32_t values)820 static inline void gpio_set_dir_all_bits(uint32_t values) {
821     sio_hw->gpio_oe = values;
822 }
823 
824 /*! \brief Set a single GPIO direction
825  *  \ingroup hardware_gpio
826  *
827  * \param gpio GPIO number
828  * \param out true for out, false for in
829  */
gpio_set_dir(uint gpio,bool out)830 static inline void gpio_set_dir(uint gpio, bool out) {
831     uint32_t mask = 1ul << gpio;
832     if (out)
833         gpio_set_dir_out_masked(mask);
834     else
835         gpio_set_dir_in_masked(mask);
836 }
837 
838 /*! \brief Check if a specific GPIO direction is OUT
839  *  \ingroup hardware_gpio
840  *
841  * \param gpio GPIO number
842  * \return true if the direction for the pin is OUT
843  */
gpio_is_dir_out(uint gpio)844 static inline bool gpio_is_dir_out(uint gpio) {
845     return !!(sio_hw->gpio_oe & (1u << (gpio)));
846 }
847 
848 /*! \brief Get a specific GPIO direction
849  *  \ingroup hardware_gpio
850  *
851  * \param gpio GPIO number
852  * \return 1 for out, 0 for in
853  */
gpio_get_dir(uint gpio)854 static inline uint gpio_get_dir(uint gpio) {
855     return gpio_is_dir_out(gpio); // note GPIO_OUT is 1/true and GPIO_IN is 0/false anyway
856 }
857 
858 extern void gpio_debug_pins_init(void);
859 
860 #ifdef __cplusplus
861 }
862 #endif
863 
864 
865 // PICO_CONFIG: PICO_DEBUG_PIN_BASE, First pin to use for debug output (if enabled), min=0, max=28, default=19, group=hardware_gpio
866 #ifndef PICO_DEBUG_PIN_BASE
867 #define PICO_DEBUG_PIN_BASE 19u
868 #endif
869 
870 // PICO_CONFIG: PICO_DEBUG_PIN_COUNT, Number of pins to use for debug output (if enabled), min=1, max=28, default=3, group=hardware_gpio
871 #ifndef PICO_DEBUG_PIN_COUNT
872 #define PICO_DEBUG_PIN_COUNT 3u
873 #endif
874 
875 #ifndef __cplusplus
876 // note these two macros may only be used once per and only apply per compilation unit (hence the CU_)
877 #define CU_REGISTER_DEBUG_PINS(...) enum __unused DEBUG_PIN_TYPE { _none = 0, __VA_ARGS__ }; static enum DEBUG_PIN_TYPE __selected_debug_pins;
878 #define CU_SELECT_DEBUG_PINS(x) static enum DEBUG_PIN_TYPE __selected_debug_pins = (x);
879 #define DEBUG_PINS_ENABLED(p) (__selected_debug_pins == (p))
880 #else
881 #define CU_REGISTER_DEBUG_PINS(p...) \
882     enum DEBUG_PIN_TYPE { _none = 0, p }; \
883     template <enum DEBUG_PIN_TYPE> class __debug_pin_settings { \
884         public: \
885             static inline bool enabled() { return false; } \
886     };
887 #define CU_SELECT_DEBUG_PINS(x) template<> inline bool __debug_pin_settings<x>::enabled() { return true; };
888 #define DEBUG_PINS_ENABLED(p) (__debug_pin_settings<p>::enabled())
889 #endif
890 #define DEBUG_PINS_SET(p, v) if (DEBUG_PINS_ENABLED(p)) gpio_set_mask((unsigned)(v)<<PICO_DEBUG_PIN_BASE)
891 #define DEBUG_PINS_CLR(p, v) if (DEBUG_PINS_ENABLED(p)) gpio_clr_mask((unsigned)(v)<<PICO_DEBUG_PIN_BASE)
892 #define DEBUG_PINS_XOR(p, v) if (DEBUG_PINS_ENABLED(p)) gpio_xor_mask((unsigned)(v)<<PICO_DEBUG_PIN_BASE)
893 
894 #endif // _GPIO_H_
895