v2.0.0
spi.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6
7#ifndef _HARDWARE_SPI_H
8#define _HARDWARE_SPI_H
9
10#include "pico.h"
11#include "hardware/structs/spi.h"
12#include "hardware/regs/dreq.h"
13
14// PICO_CONFIG: PARAM_ASSERTIONS_ENABLED_HARDWARE_SPI, Enable/disable assertions in the hardware_spi module, type=bool, default=0, group=hardware_spi
15#ifndef PARAM_ASSERTIONS_ENABLED_HARDWARE_SPI
16#ifdef PARAM_ASSERTIONS_ENABLED_SPI // backwards compatibility with SDK < 2.0.0
17#define PARAM_ASSERTIONS_ENABLED_HARDWARE_SPI PARAM_ASSERTIONS_ENABLED_SPI
18#else
19#define PARAM_ASSERTIONS_ENABLED_HARDWARE_SPI 0
20#endif
21#endif
22
23#ifdef __cplusplus
24extern "C" {
25#endif
26
42// 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
43// PICO_CONFIG: PICO_DEFAULT_SPI_SCK_PIN, Define the default SPI SCK pin, min=0, max=29, default=Usually provided via board header, group=hardware_spi
44// PICO_CONFIG: PICO_DEFAULT_SPI_TX_PIN, Define the default SPI TX pin, min=0, max=29, default=Usually provided via board header, group=hardware_spi
45// PICO_CONFIG: PICO_DEFAULT_SPI_RX_PIN, Define the default SPI RX pin, min=0, max=29, default=Usually provided via board header, group=hardware_spi
46// PICO_CONFIG: PICO_DEFAULT_SPI_CSN_PIN, Define the default SPI CSN pin, min=0, max=29, default=Usually provided via board header, group=hardware_spi
47
51 typedef struct spi_inst spi_inst_t;
52
59#define spi0 ((spi_inst_t *)spi0_hw)
60
67#define spi1 ((spi_inst_t *)spi1_hw)
68
75#if !defined(PICO_DEFAULT_SPI_INSTANCE) && defined(PICO_DEFAULT_SPI)
76#define PICO_DEFAULT_SPI_INSTANCE() (__CONCAT(spi,PICO_DEFAULT_SPI))
77#endif
78
92#ifdef PICO_DEFAULT_SPI_INSTANCE
93#define spi_default PICO_DEFAULT_SPI_INSTANCE()
94#endif
95
104#ifndef SPI_NUM
105static_assert(NUM_SPIS == 2, "");
106#define SPI_NUM(spi) ((spi) == spi1)
107#endif
108
117#ifndef SPI_INSTANCE
118static_assert(NUM_SPIS == 2, "");
119#define SPI_INSTANCE(num) ((num) ? spi1 : spi0)
120#endif
121
131#ifndef SPI_DREQ_NUM
132static_assert(DREQ_SPI0_RX == DREQ_SPI0_TX + 1, "");
133static_assert(DREQ_SPI1_RX == DREQ_SPI1_TX + 1, "");
134static_assert(DREQ_SPI1_TX == DREQ_SPI0_TX + 2, "");
135#define SPI_DREQ_NUM(spi, is_tx) (DREQ_SPI0_TX + SPI_NUM(spi) * 2 + !(is_tx))
136#endif
137
141 typedef enum {
142 SPI_CPHA_0 = 0,
143 SPI_CPHA_1 = 1
144} spi_cpha_t;
145
149 typedef enum {
150 SPI_CPOL_0 = 0,
151 SPI_CPOL_1 = 1
152} spi_cpol_t;
153
157 typedef enum {
158 SPI_LSB_FIRST = 0,
159 SPI_MSB_FIRST = 1
160} spi_order_t;
161
162// ----------------------------------------------------------------------------
163// Setup
164
178uint spi_init(spi_inst_t *spi, uint baudrate);
179
188void spi_deinit(spi_inst_t *spi);
189
200uint spi_set_baudrate(spi_inst_t *spi, uint baudrate);
201
210uint spi_get_baudrate(const spi_inst_t *spi);
211
218 static inline uint spi_get_index(const spi_inst_t *spi) {
219 invalid_params_if(HARDWARE_SPI, spi != spi0 && spi != spi1);
220 return SPI_NUM(spi);
221}
222
223static inline spi_hw_t *spi_get_hw(spi_inst_t *spi) {
224 spi_get_index(spi); // check it is a hw spi
225 return (spi_hw_t *)spi;
226}
227
228static inline const spi_hw_t *spi_get_const_hw(const spi_inst_t *spi) {
229 spi_get_index(spi); // check it is a hw spi
230 return (const spi_hw_t *)spi;
231}
232
244 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) {
245 invalid_params_if(HARDWARE_SPI, data_bits < 4 || data_bits > 16);
246 // LSB-first not supported on PL022:
247 invalid_params_if(HARDWARE_SPI, order != SPI_MSB_FIRST);
248 invalid_params_if(HARDWARE_SPI, cpol != SPI_CPOL_0 && cpol != SPI_CPOL_1);
249 invalid_params_if(HARDWARE_SPI, cpha != SPI_CPHA_0 && cpha != SPI_CPHA_1);
250
251 // Disable the SPI
252 uint32_t enable_mask = spi_get_hw(spi)->cr1 & SPI_SSPCR1_SSE_BITS;
253 hw_clear_bits(&spi_get_hw(spi)->cr1, SPI_SSPCR1_SSE_BITS);
254
255 hw_write_masked(&spi_get_hw(spi)->cr0,
256 ((uint)(data_bits - 1)) << SPI_SSPCR0_DSS_LSB |
257 ((uint)cpol) << SPI_SSPCR0_SPO_LSB |
258 ((uint)cpha) << SPI_SSPCR0_SPH_LSB,
259 SPI_SSPCR0_DSS_BITS |
260 SPI_SSPCR0_SPO_BITS |
261 SPI_SSPCR0_SPH_BITS);
262
263 // Re-enable the SPI
264 hw_set_bits(&spi_get_hw(spi)->cr1, enable_mask);
265}
266
276 static inline void spi_set_slave(spi_inst_t *spi, bool slave) {
277 // Disable the SPI
278 uint32_t enable_mask = spi_get_hw(spi)->cr1 & SPI_SSPCR1_SSE_BITS;
279 hw_clear_bits(&spi_get_hw(spi)->cr1, SPI_SSPCR1_SSE_BITS);
280
281 if (slave)
282 hw_set_bits(&spi_get_hw(spi)->cr1, SPI_SSPCR1_MS_BITS);
283 else
284 hw_clear_bits(&spi_get_hw(spi)->cr1, SPI_SSPCR1_MS_BITS);
285
286 // Re-enable the SPI
287 hw_set_bits(&spi_get_hw(spi)->cr1, enable_mask);
288}
289
290// ----------------------------------------------------------------------------
291// Generic input/output
292
299 static inline bool spi_is_writable(const spi_inst_t *spi) {
300 return (spi_get_const_hw(spi)->sr & SPI_SSPSR_TNF_BITS);
301}
302
309 static inline bool spi_is_readable(const spi_inst_t *spi) {
310 return (spi_get_const_hw(spi)->sr & SPI_SSPSR_RNE_BITS);
311}
312
319 static inline bool spi_is_busy(const spi_inst_t *spi) {
320 return (spi_get_const_hw(spi)->sr & SPI_SSPSR_BSY_BITS);
321}
322
335 int spi_write_read_blocking(spi_inst_t *spi, const uint8_t *src, uint8_t *dst, size_t len);
336
348 int spi_write_blocking(spi_inst_t *spi, const uint8_t *src, size_t len);
349
365 int spi_read_blocking(spi_inst_t *spi, uint8_t repeated_tx_data, uint8_t *dst, size_t len);
366
367// ----------------------------------------------------------------------------
368// SPI-specific operations and aliases
369
370// FIXME need some instance-private data for select() and deselect() if we are going that route
371
386 int spi_write16_read16_blocking(spi_inst_t *spi, const uint16_t *src, uint16_t *dst, size_t len);
387
401 int spi_write16_blocking(spi_inst_t *spi, const uint16_t *src, size_t len);
402
420 int spi_read16_blocking(spi_inst_t *spi, uint16_t repeated_tx_data, uint16_t *dst, size_t len);
421
428 static inline uint spi_get_dreq(spi_inst_t *spi, bool is_tx) {
429 return SPI_DREQ_NUM(spi, is_tx);
430}
431
432#ifdef __cplusplus
433}
434#endif
435
436#endif
hw_set_bits
static __force_inline void hw_set_bits(io_rw_32 *addr, uint32_t mask)
Atomically set the specified bits to 1 in a HW register.
Definition: address_mapped.h:135
hw_write_masked
static __force_inline void hw_write_masked(io_rw_32 *addr, uint32_t values, uint32_t write_mask)
Set new values for a sub-set of the bits in a HW register.
Definition: address_mapped.h:171
hw_clear_bits
static __force_inline void hw_clear_bits(io_rw_32 *addr, uint32_t mask)
Atomically clear the specified bits to 0 in a HW register.
Definition: address_mapped.h:145
DREQ_SPI1_TX
@ DREQ_SPI1_TX
Select SPI1's TX FIFO as DREQ.
Definition: dreq.h:108
DREQ_SPI1_RX
@ DREQ_SPI1_RX
Select SPI1's RX FIFO as DREQ.
Definition: dreq.h:109
DREQ_SPI0_RX
@ DREQ_SPI0_RX
Select SPI0's RX FIFO as DREQ.
Definition: dreq.h:107
DREQ_SPI0_TX
@ DREQ_SPI0_TX
Select SPI0's TX FIFO as DREQ.
Definition: dreq.h:106
spi_is_writable
static bool spi_is_writable(const spi_inst_t *spi)
Check whether a write can be done on SPI device.
Definition: spi.h:299
spi_set_slave
static void spi_set_slave(spi_inst_t *spi, bool slave)
Set SPI master/slave.
Definition: spi.h:276
spi_set_format
static void spi_set_format(spi_inst_t *spi, uint data_bits, spi_cpol_t cpol, spi_cpha_t cpha, __unused spi_order_t order)
Configure SPI.
Definition: spi.h:244
spi_init
uint spi_init(spi_inst_t *spi, uint baudrate)
Initialise SPI instances.
Definition: spi.c:21
spi_is_readable
static bool spi_is_readable(const spi_inst_t *spi)
Check whether a read can be done on SPI device.
Definition: spi.h:309
spi_set_baudrate
uint spi_set_baudrate(spi_inst_t *spi, uint baudrate)
Set SPI baudrate.
Definition: spi.c:42
SPI_NUM
#define SPI_NUM(spi)
Returns the SPI number for a SPI instance.
Definition: spi.h:106
spi1
#define spi1
Definition: spi.h:67
spi_read_blocking
int spi_read_blocking(spi_inst_t *spi, uint8_t repeated_tx_data, uint8_t *dst, size_t len)
Read from an SPI device.
spi_cpol_t
spi_cpol_t
Enumeration of SPI CPOL (clock polarity) values.
Definition: spi.h:149
spi_write_blocking
int spi_write_blocking(spi_inst_t *spi, const uint8_t *src, size_t len)
Write to an SPI device, blocking.
spi_is_busy
static bool spi_is_busy(const spi_inst_t *spi)
Check whether SPI is busy.
Definition: spi.h:319
spi_get_dreq
static uint spi_get_dreq(spi_inst_t *spi, bool is_tx)
Return the DREQ to use for pacing transfers to/from a particular SPI instance.
Definition: spi.h:428
spi_read16_blocking
int spi_read16_blocking(spi_inst_t *spi, uint16_t repeated_tx_data, uint16_t *dst, size_t len)
Read from an SPI device.
spi_get_index
static uint spi_get_index(const spi_inst_t *spi)
Convert SPI instance to hardware instance number.
Definition: spi.h:218
spi_cpha_t
spi_cpha_t
Enumeration of SPI CPHA (clock phase) values.
Definition: spi.h:141
spi0
#define spi0
Definition: spi.h:59
spi_get_baudrate
uint spi_get_baudrate(const spi_inst_t *spi)
Get SPI baudrate.
Definition: spi.c:76
SPI_DREQ_NUM
#define SPI_DREQ_NUM(spi, is_tx)
Returns the dreq_num_t used for pacing DMA transfers to or from this SPI instance....
Definition: spi.h:135
spi_order_t
spi_order_t
Enumeration of SPI bit-order values.
Definition: spi.h:157
spi_write_read_blocking
int spi_write_read_blocking(spi_inst_t *spi, const uint8_t *src, uint8_t *dst, size_t len)
Write/Read to/from an SPI device.
spi_write16_blocking
int spi_write16_blocking(spi_inst_t *spi, const uint16_t *src, size_t len)
Write to an SPI device.
spi_write16_read16_blocking
int spi_write16_read16_blocking(spi_inst_t *spi, const uint16_t *src, uint16_t *dst, size_t len)
Write/Read half words to/from an SPI device.
spi_deinit
void spi_deinit(spi_inst_t *spi)
Deinitialise SPI instances.
Definition: spi.c:36
pico.h
spi_inst_t
struct spi_inst spi_inst_t
Opaque type representing an SPI instance.
Definition: spi.h:51
spi_hw_t
Definition: spi.h:26