gpio_ll.h

Go to the documentation of this file.

/*
 * Copyright (C) 2020 Gunar Schorcht
 *               2021 Otto-von-Guericke-Universität Magdeburg
 *
 * This file is subject to the terms and conditions of the GNU Lesser
 * General Public License v2.1. See the file LICENSE in the top level
 * directory for more details.
 */
 
#pragma once

 
#include <assert.h>
#include <stdbool.h>
#include <stdint.h>
 
#include "architecture.h"
#include "periph/gpio.h"
#include "periph_cpu.h"
 
#ifdef __cplusplus
extern "C" {
#endif

typedef uintptr_t gpio_port_t;
 
#if !defined(GPIO_PORT_UNDEF) || defined(DOXYGEN)
#define GPIO_PORT_UNDEF         UINTPTR_MAX
#endif
 
#if defined(DOXYGEN)
#  define GPIO_PORT_NUMBERING_ALPHABETIC    implementation_specific
#endif
 
#ifdef DOXYGEN
#define GPIO_PORT_0     implementation_specific

gpio_port_t gpio_port(uword_t num);

uword_t gpio_port_num(gpio_port_t port);
#endif /* DOXYGEN */
 
#if !defined(HAVE_GPIO_STATE_T) || defined(DOXYGEN)
typedef enum {
    GPIO_OUTPUT_PUSH_PULL,
    GPIO_OUTPUT_OPEN_DRAIN,
    GPIO_OUTPUT_OPEN_SOURCE,
    GPIO_INPUT,
    GPIO_USED_BY_PERIPHERAL,
    GPIO_DISCONNECT,
} gpio_state_t;
#endif
 
#if !defined(HAVE_GPIO_PULL_T) || defined(DOXYGEN)
typedef enum {
    GPIO_FLOATING,  
    GPIO_PULL_UP,   
    GPIO_PULL_DOWN, 
    GPIO_PULL_KEEP, 
} gpio_pull_t;
#endif
 
#if !defined(HAVE_GPIO_PULL_STRENGTH_T) || defined(DOXYGEN)
typedef enum {
    GPIO_PULL_WEAKEST,      
    GPIO_PULL_WEAK,         
    GPIO_PULL_STRONG,       
    GPIO_PULL_STRONGEST,    
} gpio_pull_strength_t;
#endif

#define GPIO_PULL_NUMOF (1U + (GPIO_PULL_WEAKEST != GPIO_PULL_WEAK) \
                            + (GPIO_PULL_WEAK != GPIO_PULL_STRONG) \
                            + (GPIO_PULL_STRONG != GPIO_PULL_STRONGEST))
 
#if !defined(HAVE_GPIO_DRIVE_STRENGTH_T) || defined(DOXYGEN)
typedef enum {
    GPIO_DRIVE_WEAKEST,     
    GPIO_DRIVE_WEAK,        
    GPIO_DRIVE_STRONG,      
    GPIO_DRIVE_STRONGEST,   
} gpio_drive_strength_t;
#endif

#define GPIO_DRIVE_NUMOF (1U + (GPIO_DRIVE_WEAKEST != GPIO_DRIVE_WEAK) \
                             + (GPIO_DRIVE_WEAK != GPIO_DRIVE_STRONG) \
                             + (GPIO_DRIVE_STRONG != GPIO_DRIVE_STRONGEST))
 
#if !defined(HAVE_GPIO_SLEW_T) || defined(DOXYGEN)
typedef enum {
    GPIO_SLEW_SLOWEST,  
    GPIO_SLEW_SLOW,     
    GPIO_SLEW_FAST,     
    GPIO_SLEW_FASTEST,  
} gpio_slew_t;
#endif

#define GPIO_SLEW_NUMOF (1U + (GPIO_SLEW_SLOWEST != GPIO_SLEW_SLOW) \
                            + (GPIO_SLEW_SLOW != GPIO_SLEW_FAST) \
                            + (GPIO_SLEW_FAST != GPIO_SLEW_FASTEST))

union gpio_conf_minimal {
    uint8_t bits;           
    struct {
        gpio_state_t state              : 3;
        gpio_pull_t pull                : 2;
        bool initial_value              : 1;
        uint8_t                         : 2; 
    };
};
 
#if !defined(HAVE_GPIO_CONF_T) && !defined(DOXYGEN)
typedef union gpio_conf_minimal gpio_conf_t;
#endif
 
#ifdef DOXYGEN
typedef /* implementation specific */ gpio_conf_t;
#endif
 
#ifndef __cplusplus
static const gpio_conf_t gpio_ll_in = {
    .state              = GPIO_INPUT,
    .pull               = GPIO_FLOATING,
};

static const gpio_conf_t gpio_ll_in_pd = {
    .state              = GPIO_INPUT,
    .pull               = GPIO_PULL_DOWN,
};

static const gpio_conf_t gpio_ll_in_pu = {
    .state              = GPIO_INPUT,
    .pull               = GPIO_PULL_UP,
};

static const gpio_conf_t gpio_ll_in_pk = {
    .state              = GPIO_INPUT,
    .pull               = GPIO_PULL_KEEP,
};

static const gpio_conf_t gpio_ll_out = {
    .state              = GPIO_OUTPUT_PUSH_PULL,
    .initial_value      = false,
};

static const gpio_conf_t gpio_ll_od = {
    .state              = GPIO_OUTPUT_OPEN_DRAIN,
    .pull               = GPIO_FLOATING,
    .initial_value      = true,
};

static const gpio_conf_t gpio_ll_od_pu = {
    .state              = GPIO_OUTPUT_OPEN_DRAIN,
    .pull               = GPIO_PULL_UP,
    .initial_value      = true,
};

#endif

static inline bool is_gpio_port_num_valid(uint_fast8_t num);

int gpio_ll_init(gpio_port_t port, uint8_t pin, gpio_conf_t conf);

gpio_conf_t gpio_ll_query_conf(gpio_port_t port, uint8_t pin);

void gpio_ll_print_conf_common(const gpio_conf_t conf);

void gpio_ll_print_conf(const gpio_conf_t conf);

static inline uword_t gpio_ll_read(gpio_port_t port);

static inline uword_t gpio_ll_read_output(gpio_port_t port);

static inline void gpio_ll_set(gpio_port_t port, uword_t mask);

static inline void gpio_ll_clear(gpio_port_t port, uword_t mask);

static inline void gpio_ll_toggle(gpio_port_t port, uword_t mask);
 
#if defined(DOXYGEN) || !defined(HAVE_GPIO_LL_PREPARE_WRITE_ALL_PINS)
static inline uword_t gpio_ll_prepare_write_all_outputs(gpio_port_t port,
                                                        uword_t value)
{
    (void)port;
    return value;
}
#endif
 
#if defined(DOXYGEN) || !defined(HAVE_GPIO_LL_PREPARE_WRITE)
static inline uword_t gpio_ll_prepare_write(gpio_port_t port, uword_t mask,
                                            uword_t value)
{
    return value | (gpio_ll_read_output(port) & (~mask));
}
#endif
 
#if defined(DOXYGEN) || !defined(HAVE_GPIO_LL_PREPARE_SWITCH_DIR)
static inline uword_t gpio_ll_prepare_switch_dir(uword_t mask)
{
    return mask;
}
#endif

static inline void gpio_ll_switch_dir_output(gpio_port_t port, uword_t pins);

static inline void gpio_ll_switch_dir_input(gpio_port_t port, uword_t pins);

static inline void gpio_ll_write(gpio_port_t port, uword_t state);

static inline gpio_port_t gpio_get_port(gpio_t pin);

static inline uint8_t gpio_get_pin_num(gpio_t pin);

static inline gpio_port_t gpio_port_pack_addr(void *addr);

static inline void * gpio_port_unpack_addr(gpio_port_t port);
 
#ifndef DOXYGEN
#if !MODULE_PERIPH_GPIO_LL_SWITCH_DIR
static inline void gpio_ll_switch_dir_output(gpio_port_t port, uword_t outputs)
{
    (void)port;
    (void)outputs;
    /* Hack: If this function is only used guarded by some
     *
     *      if (IS_USED(MODULE_PERIPH_GPIO_LL_SWITCH_DIR)) {
     *          ...
     *      }
     *
     * as intended, all calls to the following fake function will be optimized
     * due to the elimination of dead branches. If used incorrectly, a linking
     * failure will be the result. The error message will not be ideal, but a
     * compile time error is much better than a runtime error.
     */
    extern void gpio_ll_switch_dir_output_used_but_feature_gpio_ll_switch_dir_is_not_provided(void);
    gpio_ll_switch_dir_output_used_but_feature_gpio_ll_switch_dir_is_not_provided();
}
 
static inline void gpio_ll_switch_dir_input(gpio_port_t port, uword_t inputs)
{
    (void)port;
    (void)inputs;
    /* Same hack as above */
    extern void gpio_ll_switch_dir_input_used_but_feature_gpio_ll_switch_dir_is_not_provided(void);
    gpio_ll_switch_dir_input_used_but_feature_gpio_ll_switch_dir_is_not_provided();
}
 
#endif /* !MODULE_PERIPH_GPIO_LL_SWITCH_DIR */
#endif /* !DOXYGEN */
 
#ifdef __cplusplus
}
#endif
 
/* the hardware specific implementation relies on the types such as gpio_port_t
 * to be provided */
#include "gpio_ll_arch.h" /* IWYU pragma: export */
 
#if !defined(DOXYGEN) && !defined(GPIO_PORT_NUMBERING_ALPHABETIC)
#  define GPIO_PORT_NUMBERING_ALPHABETIC    0
#endif

#if defined(GPIO_PORT_0) || defined(DOXYGEN)
#  define GPIO_PORT_A   GPIO_PORT_0
#endif
#if defined(GPIO_PORT_1) || defined(DOXYGEN)
#  define GPIO_PORT_B   GPIO_PORT_1
#endif
#if defined(GPIO_PORT_2) || defined(DOXYGEN)
#  define GPIO_PORT_C   GPIO_PORT_2
#endif
#if defined(GPIO_PORT_3) || defined(DOXYGEN)
#  define GPIO_PORT_D   GPIO_PORT_3
#endif
#if defined(GPIO_PORT_4) || defined(DOXYGEN)
#  define GPIO_PORT_E   GPIO_PORT_4
#endif
#if defined(GPIO_PORT_5) || defined(DOXYGEN)
#  define GPIO_PORT_F   GPIO_PORT_5
#endif
#if defined(GPIO_PORT_6) || defined(DOXYGEN)
#  define GPIO_PORT_G   GPIO_PORT_6
#endif
#if defined(GPIO_PORT_7) || defined(DOXYGEN)
#  define GPIO_PORT_H   GPIO_PORT_7
#endif
#if defined(GPIO_PORT_8) || defined(DOXYGEN)
#  define GPIO_PORT_I   GPIO_PORT_8
#endif
#if defined(GPIO_PORT_9) || defined(DOXYGEN)
#  define GPIO_PORT_J   GPIO_PORT_9
#endif
#if defined(GPIO_PORT_10) || defined(DOXYGEN)
#  define GPIO_PORT_K   GPIO_PORT_10
#endif
#if defined(GPIO_PORT_11) || defined(DOXYGEN)
#  define GPIO_PORT_L   GPIO_PORT_11
#endif
#if defined(GPIO_PORT_12) || defined(DOXYGEN)
#  define GPIO_PORT_M   GPIO_PORT_12
#endif
#if defined(GPIO_PORT_13) || defined(DOXYGEN)
#  define GPIO_PORT_N   GPIO_PORT_13
#endif
#if defined(GPIO_PORT_14) || defined(DOXYGEN)
#  define GPIO_PORT_O   GPIO_PORT_14
#endif
#if defined(GPIO_PORT_15) || defined(DOXYGEN)
#  define GPIO_PORT_P   GPIO_PORT_15
#endif