util.h

Go to the documentation of this file.

// MIT License
// 
// Copyright (c) 2023 Daniel Robertson
// 
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
// 
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
// 
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
 
#ifndef UTIL_H_BC9FF78B_B978_444A_8AA1_FF169B09B09E
#define UTIL_H_BC9FF78B_B978_444A_8AA1_FF169B09B09E
 
#include <stdint.h>
#include "hardware/pio.h"
#include "hardware/platform_defs.h"
#include "hardware/sync.h"
#include "pico/mutex.h"
#include "pico/types.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
// RP2040 sdk doesn't seem to define this
#define UTIL_NUM_DMA_IRQS UINT8_C(2)
 
#define UTIL_DMA_IRQ_INDEX_MIN UINT8_C(0)
#define UTIL_DMA_IRQ_INDEX_MAX UINT8_C(UTIL_NUM_DMA_IRQS - 1)
 
#define UTIL_PIO_IRQ_INDEX_MIN UINT8_C(0)
#define UTIL_PIO_IRQ_INDEX_MAX UINT8_C(NUM_PIOS - 1)
 
#define UTIL_PIO_INTERRUPT_NUM_MIN UINT8_C(0)
#define UTIL_PIO_INTERRUPT_NUM_MAX UINT8_C(7)
 
#define UTIL_ROUTABLE_PIO_INTERRUPT_NUM_MIN UINT8_C(0)
#define UTIL_ROUTABLE_PIO_INTERRUPT_NUM_MAX UINT8_C(3)
 
#define UTIL_MUTEX_BLOCK(mut, ...) \
    do { \
        mutex_enter_blocking(&mut); \
        __VA_ARGS__ \
        mutex_exit(&mut); \
    } while(0)
 
#define UTIL_INTERRUPTS_OFF_BLOCK(...) \
    do { \
        const uint32_t interrupt_status_cb918069_eadf_49bc_9d8c_a8a4defad20c = save_and_disable_interrupts(); \
        __VA_ARGS__ \
        restore_interrupts(interrupt_status_cb918069_eadf_49bc_9d8c_a8a4defad20c); \
    } while(0)
 
#define UTIL_DECL_IN_RANGE_FUNC(TYPE) \
    bool util_ ## TYPE ##_in_range( \
        const TYPE val, \
        const TYPE min, \
        const TYPE max);
 
UTIL_DECL_IN_RANGE_FUNC(int32_t)
UTIL_DECL_IN_RANGE_FUNC(uint32_t)
UTIL_DECL_IN_RANGE_FUNC(int)
UTIL_DECL_IN_RANGE_FUNC(uint)
 
 
extern const uint8_t util_pio_to_irq_map[NUM_PIOS * 2];
 
extern const uint8_t util_dma_to_irq_map[UTIL_NUM_DMA_IRQS];
 
bool util_dma_irq_index_is_valid(const uint idx);
 
uint util_dma_get_irq_from_index(const uint idx);
 
int util_dma_get_index_from_irq(const uint irq_num);
 
void util_dma_set_exclusive_channel_irq_handler(
    const uint irq_index,
    const uint channel,
    const irq_handler_t handler,
    const bool enabled);
 
uint32_t util_dma_get_transfer_count(const uint channel);
 
bool util_dma_channel_wait_for_finish_timeout(
    const uint channel,
    const absolute_time_t* const end);
 
uint util_dma_get_irqn(const uint irq_index);
 
void util_dma_channel_set_quiet(
    const uint channel,
    const bool quiet);
 
void util_gpio_set_contiguous_input_pins(
    const uint base,
    const uint len);
 
void util_gpio_set_output(const uint gpio);
 
void util_irq_set_exclusive_pio_interrupt_num_handler(
    PIO const pio,
    const uint irq_index,
    const uint pio_interrupt_num,
    const irq_handler_t handler,
    const bool enabled);
 
bool util_pio_irq_index_is_valid(const uint idx);
 
uint util_pio_get_irq_from_index(
    PIO const pio,
    const uint idx);
 
int util_pio_get_index_from_irq(const uint irq_num);
 
PIO const util_pio_get_pio_from_irq(const uint irq_num);
 
uint util_pion_get_irqn(
    PIO const pio,
    const uint irq_index);
 
uint util_pio_get_pis_from_pio_interrupt_num(
    const uint pio_interrupt_num);
 
void util_pio_gpio_contiguous_init(
    PIO const pio,
    const uint base,
    const uint len);
 
void util_pio_sm_clear_rx_fifo(
    PIO const pio,
    const uint sm);
 
void util_pio_sm_clear_osr(
    PIO const pio,
    const uint sm);
 
void util_pio_sm_clear_isr(
    PIO const pio,
    const uint sm);
 
bool util_pio_sm_is_enabled(
    PIO const pio,
    const uint sm);
 
bool util_pio_interrupt_num_is_valid(
    const uint pio_interrupt_num);
 
bool util_routable_pio_interrupt_num_is_valid(
    const uint pio_interrupt_num);
 
void util_pio_interrupt_wait(
    PIO const pio,
    const uint pio_interrupt_num);
 
void util_pio_interrupt_wait_cleared(
    PIO const pio,
    const uint pio_interrupt_num);
 
bool util_pio_interrupt_wait_cleared_timeout(
    PIO const pio,
    const uint pio_interrupt_num,
    const absolute_time_t* const end);
 
void util_pio_interrupt_wait_clear(
    PIO const pio,
    const uint pio_interrupt_num);
 
bool util_pio_interrupt_wait_timeout(
    PIO const pio,
    const uint pio_interrupt_num,
    const absolute_time_t* const end);
 
bool util_pio_interrupt_wait_clear_timeout(
    PIO const pio,
    const uint pio_interrupt_num,
    const absolute_time_t* const end);
 
bool util_pio_sm_try_get(
    PIO const pio,
    const uint sm,
    uint32_t* const word,
    const uint threshold);
 
#undef UTIL_DECL_IN_RANGE_FUNC
 
#ifdef __cplusplus
}
#endif
 
#endif