gpio.h
Go to the documentation of this file.
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 
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 
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 
137 typedef void (*gpio_irq_callback_t)(uint gpio, uint32_t event_mask);
138 
144 };
145 
156 };
157 
169 };
170 
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 
186 void gpio_set_function(uint gpio, enum gpio_function fn);
187 
194 enum gpio_function gpio_get_function(uint gpio);
195 
206 void gpio_set_pulls(uint gpio, bool up, bool down);
207 
213 static inline void gpio_pull_up(uint gpio) {
214  gpio_set_pulls(gpio, true, false);
215 }
216 
223 static inline bool gpio_is_pulled_up(uint gpio) {
224  return (padsbank0_hw->io[gpio] & PADS_BANK0_GPIO0_PUE_BITS) != 0;
225 }
226 
232 static inline void gpio_pull_down(uint gpio) {
233  gpio_set_pulls(gpio, false, true);
234 }
235 
242 static inline bool gpio_is_pulled_down(uint gpio) {
243  return (padsbank0_hw->io[gpio] & PADS_BANK0_GPIO0_PDE_BITS) != 0;
244 }
245 
251 static inline void gpio_disable_pulls(uint gpio) {
252  gpio_set_pulls(gpio, false, false);
253 }
254 
263 void gpio_set_irqover(uint gpio, uint value);
264 
271 void gpio_set_outover(uint gpio, uint value);
272 
279 void gpio_set_inover(uint gpio, uint value);
280 
287 void gpio_set_oeover(uint gpio, uint value);
288 
295 void gpio_set_input_enabled(uint gpio, bool enabled);
296 
309 void gpio_set_input_hysteresis_enabled(uint gpio, bool enabled);
310 
317 bool gpio_is_input_hysteresis_enabled(uint gpio);
318 
319 
327 void gpio_set_slew_rate(uint gpio, enum gpio_slew_rate slew);
328 
336 enum gpio_slew_rate gpio_get_slew_rate(uint gpio);
337 
345 void gpio_set_drive_strength(uint gpio, enum gpio_drive_strength drive);
346 
355 
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 
408 
440 void gpio_set_irq_enabled_with_callback(uint gpio, uint32_t event_mask, bool enabled, gpio_irq_callback_t callback);
441 
452 void gpio_set_dormant_irq_enabled(uint gpio, uint32_t event_mask, bool enabled);
453 
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 
484 void gpio_acknowledge_irq(uint gpio, uint32_t event_mask);
485 
517 void gpio_add_raw_irq_handler_with_order_priority_masked(uint gpio_mask, irq_handler_t handler, uint8_t order_priority);
518 
546 static inline void gpio_add_raw_irq_handler_with_order_priority(uint gpio, irq_handler_t handler, uint8_t order_priority) {
547  check_gpio_param(gpio);
548  gpio_add_raw_irq_handler_with_order_priority_masked(1u << gpio, handler, order_priority);
549 }
550 
579 void gpio_add_raw_irq_handler_masked(uint gpio_mask, irq_handler_t handler);
580 
605 static inline void gpio_add_raw_irq_handler(uint gpio, irq_handler_t handler) {
606  check_gpio_param(gpio);
607  gpio_add_raw_irq_handler_masked(1u << gpio, handler);
608 }
609 
621 void gpio_remove_raw_irq_handler_masked(uint gpio_mask, irq_handler_t handler);
622 
634 static inline void gpio_remove_raw_irq_handler(uint gpio, irq_handler_t handler) {
635  check_gpio_param(gpio);
636  gpio_remove_raw_irq_handler_masked(1u << gpio, handler);
637 }
638 
647 void gpio_init(uint gpio);
648 
654 void gpio_deinit(uint gpio);
655 
664 void gpio_init_mask(uint gpio_mask);
665 // ----------------------------------------------------------------------------
666 // Input
667 // ----------------------------------------------------------------------------
668 
675 static inline bool gpio_get(uint gpio) {
676  return !!((1ul << gpio) & sio_hw->gpio_in);
677 }
678 
684 static inline uint32_t gpio_get_all(void) {
685  return sio_hw->gpio_in;
686 }
687 
688 // ----------------------------------------------------------------------------
689 // Output
690 // ----------------------------------------------------------------------------
691 
697 static inline void gpio_set_mask(uint32_t mask) {
698  sio_hw->gpio_set = mask;
699 }
700 
706 static inline void gpio_clr_mask(uint32_t mask) {
707  sio_hw->gpio_clr = mask;
708 }
709 
715 static inline void gpio_xor_mask(uint32_t mask) {
716  sio_hw->gpio_togl = mask;
717 }
718 
730 static inline void gpio_put_masked(uint32_t mask, uint32_t value) {
731  sio_hw->gpio_togl = (sio_hw->gpio_out ^ value) & mask;
732 }
733 
739 static inline void gpio_put_all(uint32_t value) {
740  sio_hw->gpio_out = value;
741 }
742 
749 static inline void gpio_put(uint gpio, bool value) {
750  uint32_t mask = 1ul << gpio;
751  if (value)
752  gpio_set_mask(mask);
753  else
754  gpio_clr_mask(mask);
755 }
756 
773 static inline bool gpio_get_out_level(uint gpio) {
774  return !!(sio_hw->gpio_out & (1u << gpio));
775 }
776 
777 // ----------------------------------------------------------------------------
778 // Direction
779 // ----------------------------------------------------------------------------
780 
788 static inline void gpio_set_dir_out_masked(uint32_t mask) {
789  sio_hw->gpio_oe_set = mask;
790 }
791 
797 static inline void gpio_set_dir_in_masked(uint32_t mask) {
798  sio_hw->gpio_oe_clr = mask;
799 }
800 
812 static inline void gpio_set_dir_masked(uint32_t mask, uint32_t value) {
813  sio_hw->gpio_oe_togl = (sio_hw->gpio_oe ^ value) & mask;
814 }
815 
821 static inline void gpio_set_dir_all_bits(uint32_t values) {
822  sio_hw->gpio_oe = values;
823 }
824 
831 static inline void gpio_set_dir(uint gpio, bool out) {
832  uint32_t mask = 1ul << gpio;
833  if (out)
835  else
837 }
838 
845 static inline bool gpio_is_dir_out(uint gpio) {
846  return !!(sio_hw->gpio_oe & (1u << (gpio)));
847 }
848 
855 static inline uint gpio_get_dir(uint gpio) {
856  return gpio_is_dir_out(gpio); // note GPIO_OUT is 1/true and GPIO_IN is 0/false anyway
857 }
858 
859 extern void gpio_debug_pins_init(void);
860 
861 #ifdef __cplusplus
862 }
863 #endif
864 
865 
866 // PICO_CONFIG: PICO_DEBUG_PIN_BASE, First pin to use for debug output (if enabled), min=0, max=28, default=19, group=hardware_gpio
867 #ifndef PICO_DEBUG_PIN_BASE
868 #define PICO_DEBUG_PIN_BASE 19u
869 #endif
870 
871 // 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
872 #ifndef PICO_DEBUG_PIN_COUNT
873 #define PICO_DEBUG_PIN_COUNT 3u
874 #endif
875 
876 #ifndef __cplusplus
877 // note these two macros may only be used once per and only apply per compilation unit (hence the CU_)
878 #define CU_REGISTER_DEBUG_PINS(...) enum __unused DEBUG_PIN_TYPE { _none = 0, __VA_ARGS__ }; static enum DEBUG_PIN_TYPE __selected_debug_pins;
879 #define CU_SELECT_DEBUG_PINS(x) static enum DEBUG_PIN_TYPE __selected_debug_pins = (x);
880 #define DEBUG_PINS_ENABLED(p) (__selected_debug_pins == (p))
881 #else
882 #define CU_REGISTER_DEBUG_PINS(p...) \
883  enum DEBUG_PIN_TYPE { _none = 0, p }; \
884  template <enum DEBUG_PIN_TYPE> class __debug_pin_settings { \
885  public: \
886  static inline bool enabled() { return false; } \
887  };
888 #define CU_SELECT_DEBUG_PINS(x) template<> inline bool __debug_pin_settings<x>::enabled() { return true; };
889 #define DEBUG_PINS_ENABLED(p) (__debug_pin_settings<p>::enabled())
890 #endif
891 #define DEBUG_PINS_SET(p, v) if (DEBUG_PINS_ENABLED(p)) gpio_set_mask((unsigned)(v)<<PICO_DEBUG_PIN_BASE)
892 #define DEBUG_PINS_CLR(p, v) if (DEBUG_PINS_ENABLED(p)) gpio_clr_mask((unsigned)(v)<<PICO_DEBUG_PIN_BASE)
893 #define DEBUG_PINS_XOR(p, v) if (DEBUG_PINS_ENABLED(p)) gpio_xor_mask((unsigned)(v)<<PICO_DEBUG_PIN_BASE)
894 
895 #endif // _GPIO_H_
gpio_override
Definition: gpio.h:139
@ GPIO_OVERRIDE_INVERT
invert peripheral signal selected via gpio_set_function
Definition: gpio.h:141
@ GPIO_OVERRIDE_HIGH
drive high/enable output
Definition: gpio.h:143
@ GPIO_OVERRIDE_LOW
drive low/disable output
Definition: gpio.h:142
@ GPIO_OVERRIDE_NORMAL
peripheral signal selected via gpio_set_function
Definition: gpio.h:140
static void gpio_add_raw_irq_handler_with_order_priority(uint gpio, irq_handler_t handler, uint8_t order_priority)
Adds a raw GPIO IRQ handler for a specific GPIO on the current core.
Definition: gpio.h:546
void gpio_set_irq_enabled(uint gpio, uint32_t event_mask, bool enabled)
Enable or disable specific interrupt events for specified GPIO.
Definition: gpio.c:176
void gpio_acknowledge_irq(uint gpio, uint32_t event_mask)
Acknowledge a GPIO interrupt for the specified events on the calling core.
Definition: gpio.c:225
static bool gpio_get_out_level(uint gpio)
Determine whether a GPIO is currently driven high or low.
Definition: gpio.h:773
void gpio_set_dormant_irq_enabled(uint gpio, uint32_t event_mask, bool enabled)
Enable dormant wake up interrupt for specified GPIO and events.
Definition: gpio.c:219
void gpio_set_drive_strength(uint gpio, enum gpio_drive_strength drive)
Set drive strength for a specified GPIO.
Definition: gpio.c:128
enum gpio_drive_strength gpio_get_drive_strength(uint gpio)
Determine current slew rate for a specified GPIO.
Definition: gpio.c:136
gpio_drive_strength
Drive strength levels for GPIO outputs.
Definition: gpio.h:164
void gpio_set_input_hysteresis_enabled(uint gpio, bool enabled)
Enable/disable GPIO input hysteresis (Schmitt trigger)
Definition: gpio.c:96
void gpio_add_raw_irq_handler_with_order_priority_masked(uint gpio_mask, irq_handler_t handler, uint8_t order_priority)
Adds a raw GPIO IRQ handler for the specified GPIOs on the current core.
Definition: gpio.c:203
void gpio_set_oeover(uint gpio, uint value)
Select GPIO output enable override.
Definition: gpio.c:88
static uint gpio_get_dir(uint gpio)
Get a specific GPIO direction.
Definition: gpio.h:855
gpio_function
GPIO function definitions for use with function select.
Definition: gpio.h:90
static void gpio_add_raw_irq_handler(uint gpio, irq_handler_t handler)
Adds a raw GPIO IRQ handler for a specific GPIO on the current core.
Definition: gpio.h:605
void gpio_init_mask(uint gpio_mask)
Initialise multiple GPIOs (enabled I/O and set func to GPIO_FUNC_SIO)
Definition: gpio.c:256
static void gpio_pull_up(uint gpio)
Set specified GPIO to be pulled up.
Definition: gpio.h:213
void gpio_add_raw_irq_handler_masked(uint gpio_mask, irq_handler_t handler)
Adds a raw GPIO IRQ handler for the specified GPIOs on the current core.
Definition: gpio.c:209
void gpio_set_irq_callback(gpio_irq_callback_t callback)
Set the generic callback used for GPIO IRQ events for the current core.
Definition: gpio.c:190
enum gpio_slew_rate gpio_get_slew_rate(uint gpio)
Determine current slew rate for a specified GPIO.
Definition: gpio.c:118
static void gpio_remove_raw_irq_handler(uint gpio, irq_handler_t handler)
Removes a raw GPIO IRQ handler for the specified GPIO on the current core.
Definition: gpio.h:634
void gpio_deinit(uint gpio)
Resets a GPIO back to the NULL function, i.e. disables it.
Definition: gpio.c:252
static void gpio_set_dir_all_bits(uint32_t values)
Set direction of all pins simultaneously.
Definition: gpio.h:821
static bool gpio_is_pulled_down(uint gpio)
Determine if the specified GPIO is pulled down.
Definition: gpio.h:242
void gpio_set_inover(uint gpio, uint value)
Select GPIO input override.
Definition: gpio.c:72
void gpio_set_irq_enabled_with_callback(uint gpio, uint32_t event_mask, bool enabled, gpio_irq_callback_t callback)
Convenience function which performs multiple GPIO IRQ related initializations.
Definition: gpio.c:184
gpio_irq_level
GPIO Interrupt level definitions (GPIO events)
Definition: gpio.h:122
static void gpio_xor_mask(uint32_t mask)
Toggle every GPIO appearing in mask.
Definition: gpio.h:715
static void gpio_set_dir(uint gpio, bool out)
Set a single GPIO direction.
Definition: gpio.h:831
static void gpio_clr_mask(uint32_t mask)
Drive low every GPIO appearing in mask.
Definition: gpio.h:706
static void gpio_put(uint gpio, bool value)
Drive a single GPIO high/low.
Definition: gpio.h:749
gpio_slew_rate
Slew rate limiting levels for GPIO outputs.
Definition: gpio.h:153
void gpio_set_input_enabled(uint gpio, bool enabled)
Enable GPIO input.
Definition: gpio.c:239
static void gpio_set_dir_in_masked(uint32_t mask)
Set a number of GPIOs to input.
Definition: gpio.h:797
static void gpio_put_all(uint32_t value)
Drive all pins simultaneously.
Definition: gpio.h:739
static void gpio_set_dir_out_masked(uint32_t mask)
Set a number of GPIOs to output.
Definition: gpio.h:788
void gpio_set_outover(uint gpio, uint value)
Set GPIO output override.
Definition: gpio.c:80
void gpio_init(uint gpio)
Initialise a GPIO for (enabled I/O and set func to GPIO_FUNC_SIO)
Definition: gpio.c:246
void(* gpio_irq_callback_t)(uint gpio, uint32_t event_mask)
Definition: gpio.h:137
void gpio_set_irqover(uint gpio, uint value)
Set GPIO IRQ override.
Definition: gpio.c:63
static bool gpio_is_dir_out(uint gpio)
Check if a specific GPIO direction is OUT.
Definition: gpio.h:845
static void gpio_set_dir_masked(uint32_t mask, uint32_t value)
Set multiple GPIO directions.
Definition: gpio.h:812
void gpio_set_function(uint gpio, enum gpio_function fn)
Select GPIO function.
Definition: gpio.c:32
void gpio_set_pulls(uint gpio, bool up, bool down)
Select up and down pulls on specific GPIO.
Definition: gpio.c:53
enum gpio_function gpio_get_function(uint gpio)
Determine current GPIO function.
Definition: gpio.c:46
bool gpio_is_input_hysteresis_enabled(uint gpio)
Determine whether input hysteresis is enabled on a specified GPIO.
Definition: gpio.c:105
static bool gpio_is_pulled_up(uint gpio)
Determine if the specified GPIO is pulled up.
Definition: gpio.h:223
static void gpio_put_masked(uint32_t mask, uint32_t value)
Drive GPIO high/low depending on parameters.
Definition: gpio.h:730
static void gpio_disable_pulls(uint gpio)
Disable pulls on specified GPIO.
Definition: gpio.h:251
static uint32_t gpio_get_all(void)
Get raw value of all GPIOs.
Definition: gpio.h:684
static void gpio_pull_down(uint gpio)
Set specified GPIO to be pulled down.
Definition: gpio.h:232
void gpio_set_slew_rate(uint gpio, enum gpio_slew_rate slew)
Set slew rate for a specified GPIO.
Definition: gpio.c:110
static uint32_t gpio_get_irq_event_mask(uint gpio)
Return the current interrupt status (pending events) for the given GPIO.
Definition: gpio.h:461
static bool gpio_get(uint gpio)
Get state of a single specified GPIO.
Definition: gpio.h:675
static void gpio_set_mask(uint32_t mask)
Drive high every GPIO appearing in mask.
Definition: gpio.h:697
void gpio_remove_raw_irq_handler_masked(uint gpio_mask, irq_handler_t handler)
Removes a raw GPIO IRQ handler for the specified GPIOs on the current core.
Definition: gpio.c:213
@ GPIO_DRIVE_STRENGTH_2MA
2 mA nominal drive strength
Definition: gpio.h:165
@ GPIO_DRIVE_STRENGTH_8MA
8 mA nominal drive strength
Definition: gpio.h:167
@ GPIO_DRIVE_STRENGTH_12MA
12 mA nominal drive strength
Definition: gpio.h:168
@ GPIO_DRIVE_STRENGTH_4MA
4 mA nominal drive strength
Definition: gpio.h:166
@ GPIO_SLEW_RATE_FAST
Slew rate limiting disabled.
Definition: gpio.h:155
@ GPIO_SLEW_RATE_SLOW
Slew rate limiting enabled.
Definition: gpio.h:154
void(* irq_handler_t)(void)
Interrupt handler function type.
Definition: irq.h:123
static __always_inline uint get_core_num(void)
Get the current core number.
Definition: platform.h:436
Definition: iobank0.h:46