gpio.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */
 
#ifndef _HARDWARE_GPIO_H
#define _HARDWARE_GPIO_H
 
#include "pico.h"
#include "hardware/structs/sio.h"
#include "hardware/structs/pads_bank0.h"
#include "hardware/structs/io_bank0.h"
#include "hardware/irq.h"
 
// PICO_CONFIG: PICO_USE_GPIO_COPROCESSOR, Enable/disable use of the GPIO coprocessor for GPIO access, type=bool, default=1, group=hardware_gpio
#if !defined(PICO_USE_GPIO_COPROCESSOR) && HAS_GPIO_COPROCESSOR
#define PICO_USE_GPIO_COPROCESSOR 1
#endif
 
#if PICO_USE_GPIO_COPROCESSOR
#include "hardware/gpio_coproc.h"
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
// PICO_CONFIG: PARAM_ASSERTIONS_ENABLED_HARDWARE_GPIO, Enable/disable assertions in the hardware_gpio module, type=bool, default=0, group=hardware_gpio
#ifndef PARAM_ASSERTIONS_ENABLED_HARDWARE_GPIO
#ifdef PARAM_ASSERTIONS_ENABLED_GPIO // backwards compatibility with SDK < 2.0.0
#define PARAM_ASSERTIONS_ENABLED_HARDWARE_GPIO PARAM_ASSERTIONS_ENABLED_GPIO
#else
#define PARAM_ASSERTIONS_ENABLED_HARDWARE_GPIO 0
#endif
#endif
 
enum gpio_dir {
    GPIO_OUT = 1u, 
    GPIO_IN = 0u,  
};
 
enum gpio_irq_level {
    GPIO_IRQ_LEVEL_LOW = 0x1u,  
    GPIO_IRQ_LEVEL_HIGH = 0x2u, 
    GPIO_IRQ_EDGE_FALL = 0x4u,  
    GPIO_IRQ_EDGE_RISE = 0x8u,  
};
 
typedef void (*gpio_irq_callback_t)(uint gpio, uint32_t event_mask);
 
enum gpio_override {
    GPIO_OVERRIDE_NORMAL = 0,      
    GPIO_OVERRIDE_INVERT = 1,      
    GPIO_OVERRIDE_LOW = 2,         
    GPIO_OVERRIDE_HIGH = 3,        
};
 
enum gpio_slew_rate {
    GPIO_SLEW_RATE_SLOW = 0,  
    GPIO_SLEW_RATE_FAST = 1   
};
 
enum gpio_drive_strength {
    GPIO_DRIVE_STRENGTH_2MA = 0, 
    GPIO_DRIVE_STRENGTH_4MA = 1, 
    GPIO_DRIVE_STRENGTH_8MA = 2, 
    GPIO_DRIVE_STRENGTH_12MA = 3 
};
 
static inline void check_gpio_param(__unused uint gpio) {
    invalid_params_if(HARDWARE_GPIO, gpio >= NUM_BANK0_GPIOS);
}
 
// ----------------------------------------------------------------------------
// Pad Controls + IO Muxing
// ----------------------------------------------------------------------------
// Declarations for gpio.c
 
void gpio_set_function(uint gpio, gpio_function_t fn);
 
void gpio_set_function_masked(uint32_t gpio_mask, gpio_function_t fn);
 
void gpio_set_function_masked64(uint64_t gpio_mask, gpio_function_t fn);
 
gpio_function_t gpio_get_function(uint gpio);
 
void gpio_set_pulls(uint gpio, bool up, bool down);
 
static inline void gpio_pull_up(uint gpio) {
    gpio_set_pulls(gpio, true, false);
}
 
static inline bool gpio_is_pulled_up(uint gpio) {
    return (pads_bank0_hw->io[gpio] & PADS_BANK0_GPIO0_PUE_BITS) != 0;
}
 
static inline void gpio_pull_down(uint gpio) {
    gpio_set_pulls(gpio, false, true);
}
 
static inline bool gpio_is_pulled_down(uint gpio) {
    return (pads_bank0_hw->io[gpio] & PADS_BANK0_GPIO0_PDE_BITS) != 0;
}
 
static inline void gpio_disable_pulls(uint gpio) {
    gpio_set_pulls(gpio, false, false);
}
 
void gpio_set_irqover(uint gpio, uint value);
 
void gpio_set_outover(uint gpio, uint value);
 
void gpio_set_inover(uint gpio, uint value);
 
void gpio_set_oeover(uint gpio, uint value);
 
void gpio_set_input_enabled(uint gpio, bool enabled);
 
void gpio_set_input_hysteresis_enabled(uint gpio, bool enabled);
 
bool gpio_is_input_hysteresis_enabled(uint gpio);
 
void gpio_set_slew_rate(uint gpio, enum gpio_slew_rate slew);
 
enum gpio_slew_rate gpio_get_slew_rate(uint gpio);
 
void gpio_set_drive_strength(uint gpio, enum gpio_drive_strength drive);
 
enum gpio_drive_strength gpio_get_drive_strength(uint gpio);
 
void gpio_set_irq_enabled(uint gpio, uint32_t event_mask, bool enabled);
 
// PICO_CONFIG: GPIO_IRQ_CALLBACK_ORDER_PRIORITY, IRQ priority order of the default IRQ callback, min=0, max=255, default=PICO_SHARED_IRQ_HANDLER_LOWEST_ORDER_PRIORITY, group=hardware_gpio
#ifndef GPIO_IRQ_CALLBACK_ORDER_PRIORITY
#define GPIO_IRQ_CALLBACK_ORDER_PRIORITY PICO_SHARED_IRQ_HANDLER_LOWEST_ORDER_PRIORITY
#endif
 
// PICO_CONFIG: GPIO_RAW_IRQ_HANDLER_DEFAULT_ORDER_PRIORITY, IRQ priority order of raw IRQ handlers if the priority is not specified, min=0, max=255, default=PICO_SHARED_IRQ_HANDLER_DEFAULT_ORDER_PRIORITY, group=hardware_gpio
#ifndef GPIO_RAW_IRQ_HANDLER_DEFAULT_ORDER_PRIORITY
#define GPIO_RAW_IRQ_HANDLER_DEFAULT_ORDER_PRIORITY PICO_SHARED_IRQ_HANDLER_DEFAULT_ORDER_PRIORITY
#endif
 
void gpio_set_irq_callback(gpio_irq_callback_t callback);
 
void gpio_set_irq_enabled_with_callback(uint gpio, uint32_t event_mask, bool enabled, gpio_irq_callback_t callback);
 
void gpio_set_dormant_irq_enabled(uint gpio, uint32_t event_mask, bool enabled);
 
static inline uint32_t gpio_get_irq_event_mask(uint gpio) {
    check_gpio_param(gpio);
    io_bank0_irq_ctrl_hw_t *irq_ctrl_base = get_core_num() ?
                                            &io_bank0_hw->proc1_irq_ctrl : &io_bank0_hw->proc0_irq_ctrl;
    io_ro_32 *status_reg = &irq_ctrl_base->ints[gpio >> 3u];
    return (*status_reg >> (4 * (gpio & 7u))) & 0xfu;
}
 
void gpio_acknowledge_irq(uint gpio, uint32_t event_mask);
 
void gpio_add_raw_irq_handler_with_order_priority_masked(uint32_t gpio_mask, irq_handler_t handler, uint8_t order_priority);
 
void gpio_add_raw_irq_handler_with_order_priority_masked64(uint64_t gpio_mask, irq_handler_t handler, uint8_t order_priority);
 
static inline void gpio_add_raw_irq_handler_with_order_priority(uint gpio, irq_handler_t handler, uint8_t order_priority) {
    check_gpio_param(gpio);
#if NUM_BANK0_GPIOS > 32
    gpio_add_raw_irq_handler_with_order_priority_masked64(1ull << gpio, handler, order_priority);
#else
    gpio_add_raw_irq_handler_with_order_priority_masked(1u << gpio, handler, order_priority);
#endif
}
 
void gpio_add_raw_irq_handler_masked(uint32_t gpio_mask, irq_handler_t handler);
 
void gpio_add_raw_irq_handler_masked64(uint64_t gpio_mask, irq_handler_t handler);
 
static inline void gpio_add_raw_irq_handler(uint gpio, irq_handler_t handler) {
    check_gpio_param(gpio);
#if NUM_BANK0_GPIOS > 32
    gpio_add_raw_irq_handler_masked64(1ull << gpio, handler);
#else
    gpio_add_raw_irq_handler_masked(1u << gpio, handler);
#endif
}
 
void gpio_remove_raw_irq_handler_masked(uint32_t gpio_mask, irq_handler_t handler);
 
void gpio_remove_raw_irq_handler_masked64(uint64_t gpio_mask, irq_handler_t handler);
 
static inline void gpio_remove_raw_irq_handler(uint gpio, irq_handler_t handler) {
    check_gpio_param(gpio);
#if NUM_BANK0_GPIOS > 32
    gpio_remove_raw_irq_handler_masked64(1ull << gpio, handler);
#else
    gpio_remove_raw_irq_handler_masked(1u << gpio, handler);
#endif
}
 
void gpio_init(uint gpio);
 
void gpio_deinit(uint gpio);
 
void gpio_init_mask(uint gpio_mask);
// ----------------------------------------------------------------------------
// Input
// ----------------------------------------------------------------------------
 
static inline bool gpio_get(uint gpio) {
#if NUM_BANK0_GPIOS <= 32
    return sio_hw->gpio_in & (1u << gpio);
#else
    if (gpio < 32) {
        return sio_hw->gpio_in & (1u << gpio);
    } else {
        return sio_hw->gpio_hi_in & (1u << (gpio - 32));
    }
#endif
}
 
static inline uint32_t gpio_get_all(void) {
#if PICO_USE_GPIO_COPROCESSOR
    return gpioc_lo_in_get();
#else
    return sio_hw->gpio_in;
#endif
}
 
static inline uint64_t gpio_get_all64(void) {
#if PICO_USE_GPIO_COPROCESSOR
    return gpioc_hilo_in_get();
#elif NUM_BANK0_GPIOS <= 32
    return sio_hw->gpio_in;
#else
    return sio_hw->gpio_in | (((uint64_t)sio_hw->gpio_hi_in) << 32u);
#endif
}
 
// ----------------------------------------------------------------------------
// Output
// ----------------------------------------------------------------------------
 
static inline void gpio_set_mask(uint32_t mask) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_lo_out_set(mask);
#else
    sio_hw->gpio_set = mask;
#endif
}
 
static inline void gpio_set_mask64(uint64_t mask) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_hilo_out_set(mask);
#elif NUM_BANK0_GPIOS <= 32
    sio_hw->gpio_set = (uint32_t)mask;
#else
    sio_hw->gpio_set = (uint32_t)mask;
    sio_hw->gpio_hi_set = (uint32_t)(mask >> 32u);
#endif
}
 
static inline void gpio_set_mask_n(uint n, uint32_t mask) {
    if (!n) {
        gpio_set_mask(mask);
    } else if (n == 1) {
#if PICO_USE_GPIO_COPROCESSOR
        gpioc_hi_out_set(mask);
#elif NUM_BANK0_GPIOS >= 32
        sio_hw->gpio_hi_set = mask;
#endif
    }
}
 
static inline void gpio_clr_mask(uint32_t mask) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_lo_out_clr(mask);
#else
    sio_hw->gpio_clr = mask;
#endif
}
 
static inline void gpio_clr_mask64(uint64_t mask) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_hilo_out_clr(mask);
#elif NUM_BANK0_GPIOS <= 32
    sio_hw->gpio_clr = (uint32_t)mask;
#else
    sio_hw->gpio_clr = (uint32_t)mask;
    sio_hw->gpio_hi_clr = (uint32_t)(mask >> 32u);
#endif
}
 
 
static inline void gpio_clr_mask_n(uint n, uint32_t mask) {
    if (!n) {
        gpio_clr_mask(mask);
    } else if (n == 1) {
#if PICO_USE_GPIO_COPROCESSOR
        gpioc_hi_out_clr(mask);
#elif NUM_BANK0_GPIOS >= 32
        sio_hw->gpio_hi_clr = mask;
#endif
    }
}
 
static inline void gpio_xor_mask(uint32_t mask) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_lo_out_xor(mask);
#else
    sio_hw->gpio_togl = mask;
#endif
}
 
static inline void gpio_xor_mask64(uint64_t mask) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_hilo_out_xor(mask);
#elif NUM_BANK0_GPIOS <= 32
    sio_hw->gpio_togl = (uint32_t)mask;
#else
    sio_hw->gpio_togl = (uint32_t)mask;
    sio_hw->gpio_hi_togl = (uint32_t)(mask >> 32u);
#endif
}
 
static inline void gpio_xor_mask_n(uint n, uint32_t mask) {
    if (!n) {
        gpio_xor_mask(mask);
    } else if (n == 1) {
#if PICO_USE_GPIO_COPROCESSOR
        gpioc_hi_out_xor(mask);
#elif NUM_BANK0_GPIOS >= 32
        sio_hw->gpio_hi_togl = mask;
#endif
    }
}
 
static inline void gpio_put_masked(uint32_t mask, uint32_t value) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_lo_out_xor((gpioc_lo_out_get() ^ value) & mask);
#else
    sio_hw->gpio_togl = (sio_hw->gpio_out ^ value) & mask;
#endif
}
 
static inline void gpio_put_masked64(uint64_t mask, uint64_t value) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_hilo_out_xor((gpioc_hilo_out_get() ^ value) & mask);
#elif NUM_BANK0_GPIOS <= 32
    sio_hw->gpio_togl = (sio_hw->gpio_out ^ (uint32_t)value) & (uint32_t)mask;
#else
    sio_hw->gpio_togl = (sio_hw->gpio_out ^ (uint32_t)value) & (uint32_t)mask;
    sio_hw->gpio_hi_togl = (sio_hw->gpio_hi_out ^ (uint32_t)(value>>32u)) & (uint32_t)(mask>>32u);
#endif
}
 
static inline void gpio_put_masked_n(uint n, uint32_t mask, uint32_t value) {
    if (!n) {
        gpio_put_masked(mask, value);
    } else if (n == 1) {
#if PICO_USE_GPIO_COPROCESSOR
        gpioc_hi_out_xor((gpioc_hi_out_get() ^ value) & mask);
#else
        sio_hw->gpio_hi_togl = (sio_hw->gpio_hi_out ^ value) & mask;
#endif
    }
}
 
static inline void gpio_put_all(uint32_t value) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_lo_out_put(value);
#else
    sio_hw->gpio_out = value;
#endif
}
 
static inline void gpio_put_all64(uint64_t value) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_hilo_out_put(value);
#elif NUM_BANK0_GPIOS <= 32
    sio_hw->gpio_out = (uint32_t)value;
#else
    sio_hw->gpio_out = (uint32_t)value;
    sio_hw->gpio_hi_out = (uint32_t)(value >> 32u);
#endif
}
 
static inline void gpio_put(uint gpio, bool value) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_bit_out_put(gpio, value);
#elif NUM_BANK0_GPIOS <= 32
    uint32_t mask = 1ul << gpio;
    if (value)
        gpio_set_mask(mask);
    else
        gpio_clr_mask(mask);
#else
    uint32_t mask = 1ul << (gpio & 0x1fu);
    if (gpio < 32) {
        if (value) {
            sio_hw->gpio_set = mask;
        } else {
            sio_hw->gpio_clr = mask;
        }
    } else {
        if (value) {
            sio_hw->gpio_hi_set = mask;
        } else {
            sio_hw->gpio_hi_clr = mask;
        }
    }
#endif
}
 
static inline bool gpio_get_out_level(uint gpio) {
#if NUM_BANK0_GPIOS <= 32
    return sio_hw->gpio_out & (1u << gpio);
#else
    uint32_t bits = gpio < 32 ? sio_hw->gpio_out : sio_hw->gpio_hi_out;
    return bits & (1u << (gpio & 0x1fu));
#endif
}
 
// ----------------------------------------------------------------------------
// Direction
// ----------------------------------------------------------------------------
 
static inline void gpio_set_dir_out_masked(uint32_t mask) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_lo_oe_set(mask);
#else
    sio_hw->gpio_oe_set = mask;
#endif
}
 
static inline void gpio_set_dir_out_masked64(uint64_t mask) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_hilo_oe_set(mask);
#elif NUM_BANK0_GPIOS <= 32
    sio_hw->gpio_oe_set = mask;
#else
    sio_hw->gpio_oe_set = (uint32_t)mask;
    sio_hw->gpio_hi_oe_set = (uint32_t)(mask >> 32u);
#endif
}
 
static inline void gpio_set_dir_in_masked(uint32_t mask) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_lo_oe_clr(mask);
#else
    sio_hw->gpio_oe_clr = mask;
#endif
}
 
static inline void gpio_set_dir_in_masked64(uint64_t mask) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_hilo_oe_clr(mask);
#elif NUM_BANK0_GPIOS <= 32
    sio_hw->gpio_oe_clr = mask;
#else
    sio_hw->gpio_oe_clr = (uint32_t)mask;
    sio_hw->gpio_hi_oe_clr = (uint32_t)(mask >> 32u);
#endif
}
 
static inline void gpio_set_dir_masked(uint32_t mask, uint32_t value) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_lo_oe_xor((gpioc_lo_oe_get() ^ value) & mask);
#else
    sio_hw->gpio_oe_togl = (sio_hw->gpio_oe ^ value) & mask;
#endif
}
 
static inline void gpio_set_dir_masked64(uint64_t mask, uint64_t value) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_hilo_oe_xor((gpioc_hilo_oe_get() ^ value) & mask);
#elif NUM_BANK0_GPIOS <= 32
    sio_hw->gpio_oe_togl = (sio_hw->gpio_oe ^ (uint32_t)value) & (uint32_t)mask;
#else
    sio_hw->gpio_oe_togl = (sio_hw->gpio_oe ^ (uint32_t)value) & (uint32_t)mask;
    sio_hw->gpio_hi_oe_togl = (sio_hw->gpio_hi_oe ^ (uint32_t)(value >> 32u)) & (uint32_t)(mask >> 32u);
#endif
}
 
 
static inline void gpio_set_dir_all_bits(uint32_t values) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_lo_oe_put(values);
#else
    sio_hw->gpio_oe = values;
#endif
}
 
static inline void gpio_set_dir_all_bits64(uint64_t values) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_hilo_oe_put(values);
#elif NUM_BANK0_GPIOS <= 32
    sio_hw->gpio_oe = (uint32_t)values;
#else
    sio_hw->gpio_oe = (uint32_t)values;
    sio_hw->gpio_hi_oe = (uint32_t)(values >> 32u);
#endif
}
 
static inline void gpio_set_dir(uint gpio, bool out) {
#if PICO_USE_GPIO_COPROCESSOR
    gpioc_bit_oe_put(gpio, out);
#elif PICO_RP2040 || NUM_BANK0_GPIOS <= 32
    uint32_t mask = 1ul << gpio;
    if (out)
        gpio_set_dir_out_masked(mask);
    else
        gpio_set_dir_in_masked(mask);
#else
    uint32_t mask = 1u << (gpio & 0x1fu);
    if (gpio < 32) {
        if (out) {
            sio_hw->gpio_oe_set = mask;
        } else {
            sio_hw->gpio_oe_clr = mask;
        }
    } else {
        if (out) {
            sio_hw->gpio_hi_oe_set = mask;
        } else {
            sio_hw->gpio_hi_oe_clr = mask;
        }
    }
#endif
}
 
static inline bool gpio_is_dir_out(uint gpio) {
#if NUM_BANK0_GPIOS <= 32
    return sio_hw->gpio_oe & (1u << (gpio));
#else
    uint32_t bits = gpio < 32 ? sio_hw->gpio_oe : sio_hw->gpio_hi_oe;
    return bits & (1u << (gpio & 0x1fu));
#endif
}
 
static inline uint gpio_get_dir(uint gpio) {
    return gpio_is_dir_out(gpio); // note GPIO_OUT is 1/true and GPIO_IN is 0/false anyway
}
 
#if PICO_SECURE
static inline void gpio_assign_to_ns(uint gpio, bool ns) {
    check_gpio_param(gpio);
    if (ns) hw_set_bits(&accessctrl_hw->gpio_nsmask[gpio/32], 1u << (gpio & 0x1fu));
    else hw_clear_bits(&accessctrl_hw->gpio_nsmask[gpio/32], 1u << (gpio & 0x1fu));
}
#endif
extern void gpio_debug_pins_init(void);
 
#ifdef __cplusplus
}
#endif
 
 
// PICO_CONFIG: PICO_DEBUG_PIN_BASE, First pin to use for debug output (if enabled), min=0, max=28, default=19, group=hardware_gpio
#ifndef PICO_DEBUG_PIN_BASE
#define PICO_DEBUG_PIN_BASE 19u
#endif
 
// 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
#ifndef PICO_DEBUG_PIN_COUNT
#define PICO_DEBUG_PIN_COUNT 3u
#endif
 
#ifndef __cplusplus
// note these two macros may only be used once per and only apply per compilation unit (hence the CU_)
#define CU_REGISTER_DEBUG_PINS(...) enum __unused DEBUG_PIN_TYPE { _none = 0, __VA_ARGS__ }; static enum DEBUG_PIN_TYPE __selected_debug_pins;
#define CU_SELECT_DEBUG_PINS(x) static enum DEBUG_PIN_TYPE __selected_debug_pins = (x);
#define DEBUG_PINS_ENABLED(p) (__selected_debug_pins == (p))
#else
#define CU_REGISTER_DEBUG_PINS(p...) \
    enum DEBUG_PIN_TYPE { _none = 0, p }; \
    template <enum DEBUG_PIN_TYPE> class __debug_pin_settings { \
        public: \
            static inline bool enabled() { return false; } \
    };
#define CU_SELECT_DEBUG_PINS(x) template<> inline bool __debug_pin_settings<x>::enabled() { return true; };
#define DEBUG_PINS_ENABLED(p) (__debug_pin_settings<p>::enabled())
#endif
#define DEBUG_PINS_SET(p, v) if (DEBUG_PINS_ENABLED(p)) gpio_set_mask((unsigned)(v)<<PICO_DEBUG_PIN_BASE)
#define DEBUG_PINS_CLR(p, v) if (DEBUG_PINS_ENABLED(p)) gpio_clr_mask((unsigned)(v)<<PICO_DEBUG_PIN_BASE)
#define DEBUG_PINS_XOR(p, v) if (DEBUG_PINS_ENABLED(p)) gpio_xor_mask((unsigned)(v)<<PICO_DEBUG_PIN_BASE)
 
#endif // _GPIO_H_