pio.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2021 Otto-von-Guericke-Universität Magdeburg
 * SPDX-License-Identifier: LGPL-2.1-only
 */
 
#pragma once

 
#include "periph_conf.h"
#include "periph/gpio.h"
#include "periph/pio.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#if defined(CPU_MODEL_RP2040) || defined(DOXYGEN)
#define PIO_SM_NUMOF    4

#define PIO_INSTR_NUMOF 32

#define PIO_IRQ_NUMOF   8
#endif

typedef uint16_t pio_instr_t;

#define PIO_GPIO_INIT_HIGH(pin)     (((gpio_t)(1)) << (pin))

#define PIO_GPIO_INIT_LOW(pin)      ((gpio_t)0)

#define PIO_GPIO_INIT_OUT(pin)      (((gpio_t)(1)) << (pin))

#define PIO_GPIO_INIT_IN(pin)       ((gpio_t)0)

typedef struct {
    gpio_pad_ctrl_t pad;    
    gpio_io_ctrl_t io;      
    gpio_t gpio_state;      
    gpio_t gpio_direction;  
    gpio_t gpio_base;       
    unsigned gpio_count;    
} pio_gpio_init_t;

#define PIO_INST_JMP                    (0u << 13)
#define PIO_INST_JMP_MASK               (7u << 13)
#define PIO_INST_JMP_CONDITION_SHIFT    5
#define PIO_INST_JMP_CONDITION_MASK     (7u << PIO_INST_JMP_CONDITION_SHIFT)
#define PIO_INST_JMP_ADDRESS_MASK       (31u)
typedef enum {
    PIO_INST_JMP_COND_NONE              = 0,    
    PIO_INST_JMP_COND_X_ZERO            = 1,    
    PIO_INST_JMP_COND_X_DEC             = 2,    
    PIO_INST_JMP_COND_Y_ZERO            = 3,    
    PIO_INST_JMP_COND_Y_DEC             = 4,    
    PIO_INST_JMP_COND_NOT_X_EQ_Y        = 5,    
    PIO_INST_JMP_COND_PIN               = 6,    
    PIO_INST_JMP_COND_NOT_OSR_EMPTY     = 7     
} pio_inst_jmp_cond_t;

#define PIO_INST_WAIT                   (1u << 13)
#define PIO_INST_WAIT_MASK              (7u << 13)
#define PIO_INST_WAIT_POL_SHIFT         7
#define PIO_INST_WAIT_POL_MASK          (1u << PIO_INST_WAIT_POL_SHIFT)
#define PIO_INST_WAIT_SOURCE_SHIFT      5
#define PIO_INST_WAIT_SOURCE_MASK       (3u << PIO_INST_WAIT_SOURCE_SHIFT)
#define PIO_INST_WAIT_INDEX_MASK        (31u)
typedef enum {
    PIO_INST_WAIT_POL_LOW               = 0,    
    PIO_INST_WAIT_POL_HIGH              = 1,    
} pio_inst_wait_pol_t;

typedef enum {
    PIO_INST_WAIT_SRC_GPIO              = 0,    
    PIO_INST_WAIT_SRC_PIN               = 1,    
    PIO_INST_WAIT_SRC_IRQ               = 2     
} pio_inst_wait_src_t;

#define PIO_INST_IN                     (2u << 13)
#define PIO_INST_IN_MASK                (7u << 13)
#define PIO_INST_IN_SOURCE_SHIFT        5
#define PIO_INST_IN_SOURCE_MASK         (7u << PIO_INST_IN_SOURCE_SHIFT)
#define PIO_INST_IN_BIT_COUNT_MASK      (31u)
typedef enum {
    PIO_INST_IN_SRC_PINS                = 0,    
    PIO_INST_IN_SRC_X                   = 1,    
    PIO_INST_IN_SRC_Y                   = 2,    
    PIO_INST_IN_SRC_NULL                = 3,    
    PIO_INST_IN_SRC_ISR                 = 6,    
    PIO_INST_IN_SRC_OSR                 = 7     
} pio_inst_in_src_t;

#define PIO_INST_OUT                    (3u << 13)
#define PIO_INST_OUT_MASK               (7u << 13)
#define PIO_INST_OUT_DESTINATION_SHIFT  5
#define PIO_INST_OUT_DESTINATION_MASK   (7u << PIO_INST_OUT_DESTINATION_SHIFT)
#define PIO_INST_OUT_BIT_COUNT_MASK     (31u)
typedef enum {
    PIO_INST_OUT_DST_PINS               = 0,    
    PIO_INST_OUT_DST_X                  = 1,    
    PIO_INST_OUT_DST_Y                  = 2,    
    PIO_INST_OUT_DST_NULL               = 3,    
    PIO_INST_OUT_DST_PINDIRS            = 4,    
    PIO_INST_OUT_DST_PC                 = 5,    
    PIO_INST_OUT_DST_ISR                = 6,    
    PIO_INST_OUT_DST_EXEC               = 7     
} pio_inst_out_dst_t;

#define PIO_INST_PUSH                   (4u << 13)
#define PIO_INST_PUSH_MASK              ((7u << 13) | (1u << 7) | 31u)
#define PIO_INST_PUSH_IF_FULL_SHIFT     6
#define PIO_INST_PUSH_IF_FULL_MASK      (1u << PIO_INST_PUSH_IF_FULL_SHIFT)
#define PIO_INST_PUSH_BLOCK_SHIFT       5
#define PIO_INST_PUSH_BLOCK_MASK        (1u << PIO_INST_PUSH_BLOCK_SHIFT)
#define PIO_INST_PULL                   ((4u << 13) | (1u << 7))
#define PIO_INST_PULL_MASK              ((7u << 13) | (1u << 7) | 31u)
#define PIO_INST_PULL_IF_EMPTY_SHIFT    6
#define PIO_INST_PULL_IF_EMPTY_MASK     (1u << PIO_INST_PULL_IF_EMPTY_SHIFT)
#define PIO_INST_PULL_BLOCK_SHIFT       5
#define PIO_INST_PULL_BLOCK_MASK        (1u << PIO_INST_PULL_BLOCK_SHIFT)
#define PIO_INST_MOV                    (5u << 13)
#define PIO_INST_MOV_MASK               (7u << 13)
#define PIO_INST_MOV_DESTINATION_SHIFT  5
#define PIO_INST_MOV_DESTINATION_MASK   (7u << PIO_INST_MOV_DESTINATION_SHIFT)
#define PIO_INST_MOV_OP_SHIFT           3
#define PIO_INST_MOV_OP_MASK            (3u << PIO_INST_MOV_OP_SHIFT)
#define PIO_INST_MOV_SOURCE_SHIFT       0
#define PIO_INST_MOV_SOURCE_MASK        (7u)
typedef enum {
    PIO_INST_MOV_DST_PINS               = 0,    
    PIO_INST_MOV_DST_X                  = 1,    
    PIO_INST_MOV_DST_Y                  = 2,    
    PIO_INST_MOV_DST_EXEC               = 4,    
    PIO_INST_MOV_DST_PC                 = 5,    
    PIO_INST_MOV_DST_ISR                = 6,    
    PIO_INST_MOV_DST_OSR                = 7     
} pio_inst_mov_dst_t;

typedef enum {
    PIO_INST_MOV_OP_NONE                = 0,    
    PIO_INST_MOV_OP_INVERT              = 1,    
    PIO_INST_MOV_OP_REVERSE             = 2     
} pio_inst_mov_op_t;

typedef enum {
    PIO_INST_MOV_SRC_PINS               = 0,    
    PIO_INST_MOV_SRC_X                  = 1,    
    PIO_INST_MOV_SRC_Y                  = 2,    
    PIO_INST_MOV_SRC_NULL               = 3,    
    PIO_INST_MOV_SRC_STATUS             = 5,    
    PIO_INST_MOV_SRC_ISR                = 6,    
    PIO_INST_MOV_SRC_OSR                = 7     
} pio_inst_mov_src_t;

#define PIO_INST_IRQ                    (6u << 13)
#define PIO_INST_IRQ_MASK               ((7u << 13) | (1u << 7))
#define PIO_INST_IRQ_CLR_SHIFT          6
#define PIO_INST_IRQ_CLR_MASK           (1u << PIO_INST_IRQ_CLR_SHIFT)
#define PIO_INST_IRQ_WAIT_SHIFT         5
#define PIO_INST_IRQ_WAIT_MASK          (1u << PIO_INST_IRQ_WAIT_SHIFT)
#define PIO_INST_IRQ_INDEX_MASK         (31u)
#define PIO_INST_SET                    (7u << 13)
#define PIO_INST_SET_MASK               (7u << 13)
#define PIO_INST_SET_DESTINATION_SHIFT  5
#define PIO_INST_SET_DESTINATION_MASK   (7u << PIO_INST_SET_DESTINATION_SHIFT)
#define PIO_INST_SET_DATA_MASK          (31u)
typedef enum {
    PIO_INST_SET_DST_PINS               = 0,    
    PIO_INST_SET_DST_X                  = 1,    
    PIO_INST_SET_DST_Y                  = 2,    
    PIO_INST_SET_DST_PINDIRS            = 4     
} pio_inst_set_dst_t;

static inline pio_instr_t pio_inst_jmp(pio_inst_jmp_cond_t condition,
                                       unsigned address)
{
    return PIO_INST_JMP |
           (((unsigned)condition) << PIO_INST_JMP_CONDITION_SHIFT) |
           address;
}

static inline pio_instr_t pio_inst_wait(pio_inst_wait_pol_t polarity,
                                        pio_inst_wait_src_t source,
                                        bool relative,
                                        unsigned index)
{
    return PIO_INST_WAIT |
           ((unsigned)polarity << PIO_INST_WAIT_POL_SHIFT) |
           ((unsigned)source << PIO_INST_WAIT_SOURCE_SHIFT) |
           ((!!relative) << 4) | index;
}

static inline pio_instr_t pio_inst_in(pio_inst_in_src_t source,
                                      unsigned bit_count)
{
    return PIO_INST_IN |
           ((unsigned)source << PIO_INST_IN_SOURCE_SHIFT) |
           (bit_count % 32);
}

static inline pio_instr_t pio_inst_out(pio_inst_out_dst_t destination,
                                       unsigned bit_count)
{
    return PIO_INST_OUT |
           ((unsigned)destination << PIO_INST_OUT_DESTINATION_SHIFT) |
           (bit_count % 32);
}

static inline pio_instr_t pio_inst_push(bool if_full,
                                        bool block)
{
    return PIO_INST_PUSH |
           ((!!if_full) << PIO_INST_PUSH_IF_FULL_SHIFT) |
           ((!!block) << PIO_INST_PUSH_BLOCK_SHIFT);
}

static inline pio_instr_t pio_inst_pull(bool if_empty,
                                        bool block)
{
    return PIO_INST_PULL |
           ((!!if_empty) << PIO_INST_PULL_IF_EMPTY_SHIFT) |
           ((!!block) << PIO_INST_PULL_BLOCK_SHIFT);
}

static inline pio_instr_t pio_inst_mov(pio_inst_mov_dst_t destination,
                                       pio_inst_mov_op_t operation,
                                       pio_inst_mov_src_t source)
{
    return PIO_INST_MOV |
           ((unsigned)destination << PIO_INST_MOV_DESTINATION_SHIFT) |
           ((unsigned)operation << PIO_INST_MOV_OP_SHIFT) |
           ((unsigned)source << PIO_INST_MOV_SOURCE_SHIFT);
}

static inline pio_instr_t pio_inst_irq(bool clear,
                                       bool wait,
                                       bool relative,
                                       unsigned index)
{
    return PIO_INST_IRQ |
           (!!clear << PIO_INST_IRQ_CLR_SHIFT) |
           (!!wait << PIO_INST_IRQ_WAIT_SHIFT) |
           ((!!relative << 4) | index);
}

static inline pio_instr_t pio_inst_set(pio_inst_set_dst_t destination,
                                       unsigned data)
{
    return PIO_INST_SET |
           ((unsigned)destination << PIO_INST_SET_DESTINATION_SHIFT) |
           data;
}

static inline pio_instr_t pio_inst_delay_sideset(unsigned sideset,
                                                 unsigned sideset_count,
                                                 bool sideset_opt,
                                                 unsigned delay)
{
    return ((!!sideset_opt) << 12) |
           (sideset << (13 - (!!sideset_opt + sideset_count))) |
           (delay << 8);
}


typedef struct pio_sm_ctrl_regs {
    volatile uint32_t clkdiv;       
    volatile uint32_t execctrl;     
    volatile uint32_t shiftctrl;    
    const volatile uint32_t addr;   
    volatile uint32_t instr;        
    volatile uint32_t pinctrl;      
} pio_sm_ctrl_regs_t;

#define PIO_SM_CTRL_BASE(dev)   ((pio_sm_ctrl_regs_t *)(&((dev)->SM0_CLKDIV)))

#define PIO_SM_CLKDIV_MAX               65536

#define PIO_SM_MASK(sm)                 (1u << (sm))

#define PIO_IRQ_MASK(irq)               (1u << (irq))

static inline unsigned pio_irq_rel_index(unsigned irq_abs, unsigned sm) {
    assert(irq_abs < PIO_IRQ_NUMOF);
    assert(sm < PIO_SM_NUMOF);
    return (irq_abs & 0b100u) | ((irq_abs + sm) & 0b011u);
}

static inline unsigned pio_irq_rel_sm(unsigned irq_abs, unsigned irq_rel) {
    assert(irq_abs < PIO_IRQ_NUMOF);
    assert(irq_rel < PIO_IRQ_NUMOF);
    return (irq_abs & 0b100u) | ((irq_rel - irq_abs) & 0b011u);
}

#define PIO_IRQ_REL_MASK(irq, sm)       PIO_IRQ_MASK(pio_irq_rel_index(irq, sm))

typedef enum {
    /* lower 4 hardware IRQs which are issued with 'irq <0-3> [rel]' and are routed to NVIC */
    /* This does not encode the state machine index of which state machine fired! */
    PIO_IRQ_SM_3                        = PIO0_INTR_SM3_Msk,            
    PIO_IRQ_SM_2                        = PIO0_INTR_SM2_Msk,            
    PIO_IRQ_SM_1                        = PIO0_INTR_SM1_Msk,            
    PIO_IRQ_SM_0                        = PIO0_INTR_SM0_Msk,            
    /* FIFO interrupts per state machine */
    PIO_IRQ_TXNFULL_SM3                 = PIO0_INTR_SM3_TXNFULL_Msk,    
    PIO_IRQ_TXNFULL_SM2                 = PIO0_INTR_SM2_TXNFULL_Msk,    
    PIO_IRQ_TXNFULL_SM1                 = PIO0_INTR_SM1_TXNFULL_Msk,    
    PIO_IRQ_TXNFULL_SM0                 = PIO0_INTR_SM0_TXNFULL_Msk,    
    PIO_IRQ_RXNEMPTY_SM3                = PIO0_INTR_SM3_RXNEMPTY_Msk,   
    PIO_IRQ_RXNEMPTY_SM2                = PIO0_INTR_SM2_RXNEMPTY_Msk,   
    PIO_IRQ_RXNEMPTY_SM1                = PIO0_INTR_SM1_RXNEMPTY_Msk,   
    PIO_IRQ_RXNEMPTY_SM0                = PIO0_INTR_SM0_RXNEMPTY_Msk,   
    /* all routed state machine interrupts */
    PIO_IRQ_ALL_SM                      = (PIO_IRQ_SM_3         |
                                           PIO_IRQ_SM_2         |
                                           PIO_IRQ_SM_1         |
                                           PIO_IRQ_SM_0),               
    /* all interrupts */
    PIO_IRQ_ALL                         = (PIO_IRQ_ALL_SM       |
                                           PIO_IRQ_TXNFULL_SM3  |
                                           PIO_IRQ_TXNFULL_SM2  |
                                           PIO_IRQ_TXNFULL_SM1  |
                                           PIO_IRQ_TXNFULL_SM0  |
                                           PIO_IRQ_RXNEMPTY_SM3 |
                                           PIO_IRQ_RXNEMPTY_SM2 |
                                           PIO_IRQ_RXNEMPTY_SM1 |
                                           PIO_IRQ_RXNEMPTY_SM0),   
} pio_irq_source_t;

typedef enum {
    PIO_IRQ_LINE_0                            = 0,                  
    PIO_IRQ_LINE_1,                                                 
    PIO_IRQ_LINE_NUMOF,                                             
} pio_irq_line_t;

typedef enum {
    PIO_SM0                             = PIO_SM_MASK(0),           
    PIO_SM1                             = PIO_SM_MASK(1),           
    PIO_SM2                             = PIO_SM_MASK(2),           
    PIO_SM3                             = PIO_SM_MASK(3),           
    PIO_SM_ALL                          = (PIO_SM0 | PIO_SM1 |
                                           PIO_SM2 | PIO_SM3)       
} pio_sm_mask_t;

typedef struct pio_isr_vec {
    void (*tx_ready)(pio_t pio, pio_sm_t sm);
    void (*rx_ready)(pio_t pio, pio_sm_t sm);
} pio_isr_vec_t;

typedef struct pio_isr_sm_vec {
    void (*sm)(pio_t pio, unsigned irq);
} pio_isr_sm_vec_t;

typedef struct pio_program_conf {
    unsigned pc_start;          
    unsigned wrap_bottom;       
    unsigned wrap_top;          
    unsigned sideset_count;     
    bool sideset_optional;      
    bool sideset_pindirs;       
} pio_program_conf_t;

typedef struct pio_sm_clkdiv {
    uint16_t div;       
    uint8_t frac_100;   
} pio_sm_clkdiv_t;

int pio_sm_exec(pio_t pio, pio_sm_t sm, pio_instr_t inst);

void pio_sm_exec_block(pio_t pio, pio_sm_t sm, pio_instr_t inst);

 int pio_write_program(pio_t pio, pio_program_t *prog, const pio_instr_t *instr);

void pio_sm_reset(pio_t pio, pio_sm_t sm);

void pio_sm_restart(pio_t pio, pio_sm_t sm);

void pio_set_isr_vec(pio_t pio, pio_sm_t sm, const pio_isr_vec_t *vec);

void pio_set_isr_sm_vec(pio_t pio, unsigned irq, const pio_isr_sm_vec_t *vec);

void pio_sm_set_out_pins(pio_t pio, pio_sm_t sm, gpio_t pin_base, unsigned pin_count);

void pio_sm_set_in_pins(pio_t pio, pio_sm_t sm, gpio_t pin_base);

void pio_sm_set_set_pins(pio_t pio, pio_sm_t sm, gpio_t pin_base, unsigned pin_count);

void pio_sm_set_sideset_pins(pio_t pio, pio_sm_t sm, gpio_t pin_base);

void pio_sm_set_sideset_count(pio_t pio, pio_sm_t sm, unsigned pin_count, bool enable);

void pio_sm_set_sideset_target(pio_t pio, pio_sm_t sm, bool pindir);

pio_sm_clkdiv_t pio_sm_clkdiv(uint32_t f_hz);

void pio_sm_set_clkdiv(pio_t pio, pio_sm_t sm, pio_sm_clkdiv_t clk);

void pio_sm_clkdiv_restart(pio_t pio, unsigned sm_mask);

void pio_sm_set_wrap(pio_t pio, pio_sm_t sm, unsigned prog_loc, uint8_t top, uint8_t bottom);

void pio_sm_set_jmp_pin(pio_t pio, pio_sm_t sm, gpio_t pin);

void pio_sm_set_in_shift(pio_t pio, pio_sm_t sm, bool right, bool autopush, unsigned threshold);

void pio_sm_set_out_shift(pio_t pio, pio_sm_t sm, bool right, bool autopull, unsigned threshold);

void pio_sm_set_fifo_join_rx(pio_t pio, pio_sm_t sm);

void pio_sm_set_fifo_join_tx(pio_t pio, pio_sm_t sm);

void pio_sm_reset_fifos(pio_t pio, pio_sm_t sm);

void pio_sm_clear_fifos(pio_t pio, pio_sm_t sm);

void pio_irq_enable(pio_t pio, pio_irq_line_t irq, pio_irq_source_t irq_mask);

void pio_irq_disable(pio_t pio, pio_irq_line_t irq, pio_irq_source_t irq_mask);

int pio_sm_transmit_word(pio_t pio, pio_sm_t sm, uint32_t word);

void pio_sm_transmit_word_block(pio_t pio, pio_sm_t sm, uint32_t word);

void pio_sm_transmit_words_block(pio_t pio, pio_sm_t sm, const uint32_t *words, unsigned count);

int pio_sm_receive_word(pio_t pio, pio_sm_t sm, uint32_t *word);

void pio_sm_receive_word_block(pio_t pio, pio_sm_t sm, uint32_t *word);

void pio_sm_receive_words_block(pio_t pio, pio_sm_t sm, uint32_t *words, unsigned count);

uint32_t pio_irq_get(pio_t pio);

void pio_irq_clear(pio_t pio, unsigned irq_flags);

int pio_sm_init_common(pio_t pio, pio_sm_t sm, const pio_program_t *prog,
                       const pio_program_conf_t *conf);

void pio_sm_set_pindirs_with_mask(pio_t pio, pio_sm_t sm, gpio_t values, gpio_t mask);

void pio_sm_set_pins_with_mask(pio_t pio, pio_sm_t sm, gpio_t values, gpio_t mask);

void pio_sm_set_set_pins_init(pio_t pio, pio_sm_t sm, const pio_gpio_init_t *pin_init);

void pio_sm_set_out_pins_init(pio_t pio, pio_sm_t sm, const pio_gpio_init_t *pin_init);

void pio_sm_set_sideset_pins_init(pio_t pio, pio_sm_t sm, const pio_gpio_init_t *pin_init);

void pio_print_status(pio_t pio);

void pio_print_debug(pio_t pio);

static inline void pio_sm_clear_debug_txstall(pio_t pio, unsigned sm_mask)
{
    io_reg_atomic_set(&pio_config[pio].dev->FDEBUG,
                      ((sm_mask & PIO_SM_ALL) << PIO0_FDEBUG_TXSTALL_Pos));
}

static inline void pio_sm_clear_debug_txover(pio_t pio, unsigned sm_mask)
{
    io_reg_atomic_set(&pio_config[pio].dev->FDEBUG,
                      ((sm_mask & PIO_SM_ALL) << PIO0_FDEBUG_TXOVER_Pos));
}

static inline void pio_sm_clear_debug_rxunder(pio_t pio, unsigned sm_mask)
{
    io_reg_atomic_set(&pio_config[pio].dev->FDEBUG,
                      ((sm_mask & PIO_SM_ALL) << PIO0_FDEBUG_RXUNDER_Pos));
}

static inline void pio_sm_clear_debug_rxstall(pio_t pio, unsigned sm_mask)
{
    io_reg_atomic_set(&pio_config[pio].dev->FDEBUG,
                      ((sm_mask & PIO_SM_ALL) << PIO0_FDEBUG_RXSTALL_Pos));
}

static inline bool pio_sm_tx_fifo_empty(pio_t pio, pio_sm_t sm)
{
    return !!(pio_config[pio].dev->FSTAT & ((1u << sm) << PIO0_FSTAT_TXEMPTY_Pos));
}

static inline bool pio_sm_tx_fifo_full(pio_t pio, pio_sm_t sm)
{
    return !!(pio_config[pio].dev->FSTAT & ((1u << sm) << PIO0_FSTAT_TXFULL_Pos));
}

static inline bool pio_sm_rx_fifo_empty(pio_t pio, pio_sm_t sm)
{
    return !!(pio_config[pio].dev->FSTAT & ((1u << sm) << PIO0_FSTAT_RXEMPTY_Pos));
}

static inline bool pio_sm_rx_fifo_full(pio_t pio, pio_sm_t sm)
{
    return !!((pio_config[pio].dev)->FSTAT & ((1u << sm) << PIO0_FSTAT_RXFULL_Pos));
}
 
#ifdef __cplusplus
}
#endif