spi.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */
 
#ifndef _HARDWARE_SPI_H
#define _HARDWARE_SPI_H
 
#include "pico.h"
#include "hardware/structs/spi.h"
#include "hardware/regs/dreq.h"
 
// PICO_CONFIG: PARAM_ASSERTIONS_ENABLED_HARDWARE_SPI, Enable/disable assertions in the hardware_spi module, type=bool, default=0, group=hardware_spi
#ifndef PARAM_ASSERTIONS_ENABLED_HARDWARE_SPI
#ifdef PARAM_ASSERTIONS_ENABLED_SPI // backwards compatibility with SDK < 2.0.0
#define PARAM_ASSERTIONS_ENABLED_HARDWARE_SPI PARAM_ASSERTIONS_ENABLED_SPI
#else
#define PARAM_ASSERTIONS_ENABLED_HARDWARE_SPI 0
#endif
#endif
 
#ifdef __cplusplus
extern "C" {
#endif

 
// PICO_CONFIG: PICO_DEFAULT_SPI, Define the default SPI for a board, min=0, max=1, default=Usually provided via board header, group=hardware_spi
// PICO_CONFIG: PICO_DEFAULT_SPI_SCK_PIN, Define the default SPI SCK pin, min=0, max=47 on RP2350B, 29 otherwise, default=Usually provided via board header, group=hardware_spi
// PICO_CONFIG: PICO_DEFAULT_SPI_TX_PIN, Define the default SPI TX pin, min=0, max=47 on RP2350B, 29 otherwise, default=Usually provided via board header, group=hardware_spi
// PICO_CONFIG: PICO_DEFAULT_SPI_RX_PIN, Define the default SPI RX pin, min=0, max=47 on RP2350B, 29 otherwise, default=Usually provided via board header, group=hardware_spi
// PICO_CONFIG: PICO_DEFAULT_SPI_CSN_PIN, Define the default SPI CSN pin, min=0, max=47 on RP2350B, 29 otherwise, default=Usually provided via board header, group=hardware_spi

typedef struct spi_inst spi_inst_t;

#define spi0 ((spi_inst_t *)spi0_hw)

#define spi1 ((spi_inst_t *)spi1_hw)

#if !defined(PICO_DEFAULT_SPI_INSTANCE) && defined(PICO_DEFAULT_SPI)
#define PICO_DEFAULT_SPI_INSTANCE() (__CONCAT(spi,PICO_DEFAULT_SPI))
#endif


#ifdef PICO_DEFAULT_SPI_INSTANCE
#define spi_default PICO_DEFAULT_SPI_INSTANCE()
#endif

#ifndef SPI_NUM
static_assert(NUM_SPIS == 2, "");
#define SPI_NUM(spi) ((spi) == spi1)
#endif

#ifndef SPI_INSTANCE
static_assert(NUM_SPIS == 2, "");
#define SPI_INSTANCE(num) ((num) ? spi1 : spi0)
#endif

#ifndef SPI_IS_INSTANCE
static_assert(NUM_SPIS == 2, "");
#define SPI_IS_INSTANCE(spi) ((spi) == spi0 || (spi) == spi1)
#endif
 

#ifndef SPI_DREQ_NUM
static_assert(DREQ_SPI0_RX == DREQ_SPI0_TX + 1, "");
static_assert(DREQ_SPI1_RX == DREQ_SPI1_TX + 1, "");
static_assert(DREQ_SPI1_TX == DREQ_SPI0_TX + 2, "");
#define SPI_DREQ_NUM(spi, is_tx) (DREQ_SPI0_TX + SPI_NUM(spi) * 2 + !(is_tx))
#endif

#ifndef SPI_RESET_NUM
#include "hardware/resets.h"
#define SPI_RESET_NUM(spi) (spi_get_index(spi) ? RESET_SPI1 : RESET_SPI0)
#endif

typedef enum {
    SPI_CPHA_0 = 0,
    SPI_CPHA_1 = 1
} spi_cpha_t;

typedef enum {
    SPI_CPOL_0 = 0,
    SPI_CPOL_1 = 1
} spi_cpol_t;

typedef enum {
    SPI_LSB_FIRST = 0,
    SPI_MSB_FIRST = 1
} spi_order_t;
 
// ----------------------------------------------------------------------------
// Setup

uint spi_init(spi_inst_t *spi, uint baudrate);

void spi_deinit(spi_inst_t *spi);

uint spi_set_baudrate(spi_inst_t *spi, uint baudrate);

uint spi_get_baudrate(const spi_inst_t *spi);

static inline uint spi_get_index(const spi_inst_t *spi) {
    valid_params_if(HARDWARE_SPI, SPI_IS_INSTANCE(spi));
    return SPI_NUM(spi);
}

static inline spi_inst_t *spi_get_instance(uint num) {
    invalid_params_if(HARDWARE_SPI, num >= NUM_SPIS);
    return SPI_INSTANCE(num);
}
 
static inline spi_hw_t *spi_get_hw(spi_inst_t *spi) {
    valid_params_if(HARDWARE_SPI, SPI_IS_INSTANCE(spi));
    return (spi_hw_t *)spi;
}
 
static inline const spi_hw_t *spi_get_const_hw(const spi_inst_t *spi) {
    valid_params_if(HARDWARE_SPI, SPI_IS_INSTANCE(spi));
    return (const spi_hw_t *)spi;
}

static inline void spi_set_format(spi_inst_t *spi, uint data_bits, spi_cpol_t cpol, spi_cpha_t cpha, __unused spi_order_t order) {
    valid_params_if(HARDWARE_SPI, SPI_IS_INSTANCE(spi));
    invalid_params_if(HARDWARE_SPI, data_bits < 4 || data_bits > 16);
    // LSB-first not supported on PL022:
    invalid_params_if(HARDWARE_SPI, order != SPI_MSB_FIRST);
    invalid_params_if(HARDWARE_SPI, cpol != SPI_CPOL_0 && cpol != SPI_CPOL_1);
    invalid_params_if(HARDWARE_SPI, cpha != SPI_CPHA_0 && cpha != SPI_CPHA_1);
 
    // Disable the SPI
    uint32_t enable_mask = spi_get_hw(spi)->cr1 & SPI_SSPCR1_SSE_BITS;
    hw_clear_bits(&spi_get_hw(spi)->cr1, SPI_SSPCR1_SSE_BITS);
 
    hw_write_masked(&spi_get_hw(spi)->cr0,
                    ((uint)(data_bits - 1)) << SPI_SSPCR0_DSS_LSB |
                    ((uint)cpol) << SPI_SSPCR0_SPO_LSB |
                    ((uint)cpha) << SPI_SSPCR0_SPH_LSB,
        SPI_SSPCR0_DSS_BITS |
        SPI_SSPCR0_SPO_BITS |
        SPI_SSPCR0_SPH_BITS);
 
    // Re-enable the SPI
    hw_set_bits(&spi_get_hw(spi)->cr1, enable_mask);
}

static inline void spi_set_slave(spi_inst_t *spi, bool slave) {
    valid_params_if(HARDWARE_SPI, SPI_IS_INSTANCE(spi));
    // Disable the SPI
    uint32_t enable_mask = spi_get_hw(spi)->cr1 & SPI_SSPCR1_SSE_BITS;
    hw_clear_bits(&spi_get_hw(spi)->cr1, SPI_SSPCR1_SSE_BITS);
 
    if (slave)
        hw_set_bits(&spi_get_hw(spi)->cr1, SPI_SSPCR1_MS_BITS);
    else
        hw_clear_bits(&spi_get_hw(spi)->cr1, SPI_SSPCR1_MS_BITS);
 
    // Re-enable the SPI
    hw_set_bits(&spi_get_hw(spi)->cr1, enable_mask);
}
 
// ----------------------------------------------------------------------------
// Generic input/output

static inline bool spi_is_writable(const spi_inst_t *spi) {
    valid_params_if(HARDWARE_SPI, SPI_IS_INSTANCE(spi));
    return (spi_get_const_hw(spi)->sr & SPI_SSPSR_TNF_BITS);
}

static inline bool spi_is_readable(const spi_inst_t *spi) {
    valid_params_if(HARDWARE_SPI, SPI_IS_INSTANCE(spi));
    return (spi_get_const_hw(spi)->sr & SPI_SSPSR_RNE_BITS);
}

static inline bool spi_is_busy(const spi_inst_t *spi) {
    valid_params_if(HARDWARE_SPI, SPI_IS_INSTANCE(spi));
    return (spi_get_const_hw(spi)->sr & SPI_SSPSR_BSY_BITS);
}

int spi_write_read_blocking(spi_inst_t *spi, const uint8_t *src, uint8_t *dst, size_t len);

int spi_write_blocking(spi_inst_t *spi, const uint8_t *src, size_t len);

int spi_read_blocking(spi_inst_t *spi, uint8_t repeated_tx_data, uint8_t *dst, size_t len);
 
// ----------------------------------------------------------------------------
// SPI-specific operations and aliases
 
// FIXME need some instance-private data for select() and deselect() if we are going that route

int spi_write16_read16_blocking(spi_inst_t *spi, const uint16_t *src, uint16_t *dst, size_t len);

int spi_write16_blocking(spi_inst_t *spi, const uint16_t *src, size_t len);

int spi_read16_blocking(spi_inst_t *spi, uint16_t repeated_tx_data, uint16_t *dst, size_t len);

static inline uint spi_get_dreq(spi_inst_t *spi, bool is_tx) {
    return SPI_DREQ_NUM(spi, is_tx);
}
 
#ifdef __cplusplus
}
#endif
 
#endif