Mistake on this page?
Report an issue in GitHub or email us
spi_api.h
1 
2 /** \addtogroup hal */
3 /** @{*/
4 /* mbed Microcontroller Library
5  * Copyright (c) 2006-2013 ARM Limited
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 #ifndef MBED_SPI_API_H
21 #define MBED_SPI_API_H
22 
23 #include "device.h"
24 #include "pinmap.h"
25 #include "hal/dma_api.h"
26 #include "hal/buffer.h"
27 
28 #if DEVICE_SPI
29 
30 #define SPI_EVENT_ERROR (1 << 1)
31 #define SPI_EVENT_COMPLETE (1 << 2)
32 #define SPI_EVENT_RX_OVERFLOW (1 << 3)
33 #define SPI_EVENT_ALL (SPI_EVENT_ERROR | SPI_EVENT_COMPLETE | SPI_EVENT_RX_OVERFLOW)
34 
35 #define SPI_EVENT_INTERNAL_TRANSFER_COMPLETE (1 << 30) // Internal flag to report that an event occurred
36 
37 #define SPI_FILL_WORD (0xFFFF)
38 #define SPI_FILL_CHAR (0xFF)
39 
40 #if DEVICE_SPI_ASYNCH
41 /** Asynch SPI HAL structure
42  */
43 typedef struct {
44  struct spi_s spi; /**< Target specific SPI structure */
45  struct buffer_s tx_buff; /**< Tx buffer */
46  struct buffer_s rx_buff; /**< Rx buffer */
47 } spi_t;
48 
49 #else
50 /** Non-asynch SPI HAL structure
51  */
52 typedef struct spi_s spi_t;
53 
54 #endif
55 
56 #ifdef __cplusplus
57 extern "C" {
58 #endif
59 
60 /**
61  * \defgroup hal_GeneralSPI SPI Configuration Functions
62  * @{
63  */
64 
65 #ifdef DEVICE_SPI_COUNT
66 /**
67  * Returns a variant of the SPIName enum uniquely identifying a SPI peripheral of the device.
68  * @param[in] mosi The pin to use for MOSI
69  * @param[in] miso The pin to use for MISO
70  * @param[in] sclk The pin to use for SCLK
71  * @return An SPI peripheral identifier
72  */
73 SPIName spi_get_peripheral_name(PinName mosi, PinName miso, PinName mclk);
74 #endif
75 
76 /** Initialize the SPI peripheral
77  *
78  * Configures the pins used by SPI, sets a default format and frequency, and enables the peripheral
79  * @param[out] obj The SPI object to initialize
80  * @param[in] mosi The pin to use for MOSI
81  * @param[in] miso The pin to use for MISO
82  * @param[in] sclk The pin to use for SCLK
83  * @param[in] ssel The pin to use for SSEL
84  */
85 void spi_init(spi_t *obj, PinName mosi, PinName miso, PinName sclk, PinName ssel);
86 
87 /** Release a SPI object
88  *
89  * TODO: spi_free is currently unimplemented
90  * This will require reference counting at the C++ level to be safe
91  *
92  * Return the pins owned by the SPI object to their reset state
93  * Disable the SPI peripheral
94  * Disable the SPI clock
95  * @param[in] obj The SPI object to deinitialize
96  */
97 void spi_free(spi_t *obj);
98 
99 /** Configure the SPI format
100  *
101  * Set the number of bits per frame, configure clock polarity and phase, shift order and master/slave mode.
102  * The default bit order is MSB.
103  * @param[in,out] obj The SPI object to configure
104  * @param[in] bits The number of bits per frame
105  * @param[in] mode The SPI mode (clock polarity, phase, and shift direction)
106  * @param[in] slave Zero for master mode or non-zero for slave mode
107  */
108 void spi_format(spi_t *obj, int bits, int mode, int slave);
109 
110 /** Set the SPI baud rate
111  *
112  * Actual frequency may differ from the desired frequency due to available dividers and bus clock
113  * Configures the SPI peripheral's baud rate
114  * @param[in,out] obj The SPI object to configure
115  * @param[in] hz The baud rate in Hz
116  */
117 void spi_frequency(spi_t *obj, int hz);
118 
119 /**@}*/
120 /**
121  * \defgroup SynchSPI Synchronous SPI Hardware Abstraction Layer
122  * @{
123  */
124 
125 /** Write a byte out in master mode and receive a value
126  *
127  * @param[in] obj The SPI peripheral to use for sending
128  * @param[in] value The value to send
129  * @return Returns the value received during send
130  */
131 int spi_master_write(spi_t *obj, int value);
132 
133 /** Write a block out in master mode and receive a value
134  *
135  * The total number of bytes sent and received will be the maximum of
136  * tx_length and rx_length. The bytes written will be padded with the
137  * value 0xff.
138  *
139  * @param[in] obj The SPI peripheral to use for sending
140  * @param[in] tx_buffer Pointer to the byte-array of data to write to the device
141  * @param[in] tx_length Number of bytes to write, may be zero
142  * @param[in] rx_buffer Pointer to the byte-array of data to read from the device
143  * @param[in] rx_length Number of bytes to read, may be zero
144  * @param[in] write_fill Default data transmitted while performing a read
145  * @returns
146  * The number of bytes written and read from the device. This is
147  * maximum of tx_length and rx_length.
148  */
149 int spi_master_block_write(spi_t *obj, const char *tx_buffer, int tx_length, char *rx_buffer, int rx_length, char write_fill);
150 
151 /** Check if a value is available to read
152  *
153  * @param[in] obj The SPI peripheral to check
154  * @return non-zero if a value is available
155  */
156 int spi_slave_receive(spi_t *obj);
157 
158 /** Get a received value out of the SPI receive buffer in slave mode
159  *
160  * Blocks until a value is available
161  * @param[in] obj The SPI peripheral to read
162  * @return The value received
163  */
164 int spi_slave_read(spi_t *obj);
165 
166 /** Write a value to the SPI peripheral in slave mode
167  *
168  * Blocks until the SPI peripheral can be written to
169  * @param[in] obj The SPI peripheral to write
170  * @param[in] value The value to write
171  */
172 void spi_slave_write(spi_t *obj, int value);
173 
174 /** Checks if the specified SPI peripheral is in use
175  *
176  * @param[in] obj The SPI peripheral to check
177  * @return non-zero if the peripheral is currently transmitting
178  */
179 int spi_busy(spi_t *obj);
180 
181 /** Get the module number
182  *
183  * @param[in] obj The SPI peripheral to check
184  * @return The module number
185  */
186 uint8_t spi_get_module(spi_t *obj);
187 
188 /** Get the pins that support SPI MOSI
189  *
190  * Return a PinMap array of pins that support SPI MOSI in
191  * master mode. The array is terminated with {NC, NC, 0}.
192  *
193  * @return PinMap array
194  */
195 const PinMap *spi_master_mosi_pinmap(void);
196 
197 /** Get the pins that support SPI MISO
198  *
199  * Return a PinMap array of pins that support SPI MISO in
200  * master mode. The array is terminated with {NC, NC, 0}.
201  *
202  * @return PinMap array
203  */
204 const PinMap *spi_master_miso_pinmap(void);
205 
206 /** Get the pins that support SPI CLK
207  *
208  * Return a PinMap array of pins that support SPI CLK in
209  * master mode. The array is terminated with {NC, NC, 0}.
210  *
211  * @return PinMap array
212  */
213 const PinMap *spi_master_clk_pinmap(void);
214 
215 /** Get the pins that support SPI CS
216  *
217  * Return a PinMap array of pins that support SPI CS in
218  * master mode. The array is terminated with {NC, NC, 0}.
219  *
220  * @return PinMap array
221  */
222 const PinMap *spi_master_cs_pinmap(void);
223 
224 /** Get the pins that support SPI MOSI
225  *
226  * Return a PinMap array of pins that support SPI MOSI in
227  * slave mode. The array is terminated with {NC, NC, 0}.
228  *
229  * @return PinMap array
230  */
231 const PinMap *spi_slave_mosi_pinmap(void);
232 
233 /** Get the pins that support SPI MISO
234  *
235  * Return a PinMap array of pins that support SPI MISO in
236  * slave mode. The array is terminated with {NC, NC, 0}.
237  *
238  * @return PinMap array
239  */
240 const PinMap *spi_slave_miso_pinmap(void);
241 
242 /** Get the pins that support SPI CLK
243  *
244  * Return a PinMap array of pins that support SPI CLK in
245  * slave mode. The array is terminated with {NC, NC, 0}.
246  *
247  * @return PinMap array
248  */
249 const PinMap *spi_slave_clk_pinmap(void);
250 
251 /** Get the pins that support SPI CS
252  *
253  * Return a PinMap array of pins that support SPI CS in
254  * slave mode. The array is terminated with {NC, NC, 0}.
255  *
256  * @return PinMap array
257  */
258 const PinMap *spi_slave_cs_pinmap(void);
259 
260 /**@}*/
261 
262 #if DEVICE_SPI_ASYNCH
263 /**
264  * \defgroup AsynchSPI Asynchronous SPI Hardware Abstraction Layer
265  * @{
266  */
267 
268 /** Begin the SPI transfer. Buffer pointers and lengths are specified in tx_buff and rx_buff
269  *
270  * @param[in] obj The SPI object that holds the transfer information
271  * @param[in] tx The transmit buffer
272  * @param[in] tx_length The number of bytes to transmit
273  * @param[in] rx The receive buffer
274  * @param[in] rx_length The number of bytes to receive
275  * @param[in] bit_width The bit width of buffer words
276  * @param[in] event The logical OR of events to be registered
277  * @param[in] handler SPI interrupt handler
278  * @param[in] hint A suggestion for how to use DMA with this transfer
279  */
280 void spi_master_transfer(spi_t *obj, const void *tx, size_t tx_length, void *rx, size_t rx_length, uint8_t bit_width, uint32_t handler, uint32_t event, DMAUsage hint);
281 
282 /** The asynchronous IRQ handler
283  *
284  * Reads the received values out of the RX FIFO, writes values into the TX FIFO and checks for transfer termination
285  * conditions, such as buffer overflows or transfer complete.
286  * @param[in] obj The SPI object that holds the transfer information
287  * @return Event flags if a transfer termination condition was met; otherwise 0.
288  */
289 uint32_t spi_irq_handler_asynch(spi_t *obj);
290 
291 /** Attempts to determine if the SPI peripheral is already in use
292  *
293  * If a temporary DMA channel has been allocated, peripheral is in use.
294  * If a permanent DMA channel has been allocated, check if the DMA channel is in use. If not, proceed as though no DMA
295  * channel were allocated.
296  * If no DMA channel is allocated, check whether tx and rx buffers have been assigned. For each assigned buffer, check
297  * if the corresponding buffer position is less than the buffer length. If buffers do not indicate activity, check if
298  * there are any bytes in the FIFOs.
299  * @param[in] obj The SPI object to check for activity
300  * @return Non-zero if the SPI port is active or zero if it is not.
301  */
302 uint8_t spi_active(spi_t *obj);
303 
304 /** Abort an SPI transfer
305  *
306  * @param obj The SPI peripheral to stop
307  */
308 void spi_abort_asynch(spi_t *obj);
309 
310 
311 #endif
312 
313 /**@}*/
314 
315 #ifdef __cplusplus
316 }
317 #endif // __cplusplus
318 
319 #endif // SPI_DEVICE
320 
321 #endif // MBED_SPI_API_H
322 
323 /** @}*/
uint8_t spi_active(spi_t *obj)
Attempts to determine if the SPI peripheral is already in use.
const PinMap * spi_master_mosi_pinmap(void)
Get the pins that support SPI MOSI.
Generic buffer structure.
Definition: buffer.h:27
uint32_t spi_irq_handler_asynch(spi_t *obj)
The asynchronous IRQ handler.
void spi_slave_write(spi_t *obj, int value)
Write a value to the SPI peripheral in slave mode.
void spi_format(spi_t *obj, int bits, int mode, int slave)
Configure the SPI format.
void spi_frequency(spi_t *obj, int hz)
Set the SPI baud rate.
void spi_master_transfer(spi_t *obj, const void *tx, size_t tx_length, void *rx, size_t rx_length, uint8_t bit_width, uint32_t handler, uint32_t event, DMAUsage hint)
Begin the SPI transfer.
const PinMap * spi_master_miso_pinmap(void)
Get the pins that support SPI MISO.
const PinMap * spi_master_cs_pinmap(void)
Get the pins that support SPI CS.
const PinMap * spi_master_clk_pinmap(void)
Get the pins that support SPI CLK.
void spi_init(spi_t *obj, PinName mosi, PinName miso, PinName sclk, PinName ssel)
Initialize the SPI peripheral.
int spi_slave_read(spi_t *obj)
Get a received value out of the SPI receive buffer in slave mode.
void spi_free(spi_t *obj)
Release a SPI object.
int spi_master_write(spi_t *obj, int value)
Write a byte out in master mode and receive a value.
int spi_master_block_write(spi_t *obj, const char *tx_buffer, int tx_length, char *rx_buffer, int rx_length, char write_fill)
Write a block out in master mode and receive a value.
const PinMap * spi_slave_cs_pinmap(void)
Get the pins that support SPI CS.
const PinMap * spi_slave_mosi_pinmap(void)
Get the pins that support SPI MOSI.
Definition: pinmap.h:30
void spi_abort_asynch(spi_t *obj)
Abort an SPI transfer.
int spi_slave_receive(spi_t *obj)
Check if a value is available to read.
const PinMap * spi_slave_clk_pinmap(void)
Get the pins that support SPI CLK.
uint8_t spi_get_module(spi_t *obj)
Get the module number.
const PinMap * spi_slave_miso_pinmap(void)
Get the pins that support SPI MISO.
int spi_busy(spi_t *obj)
Checks if the specified SPI peripheral is in use.
Asynch SPI HAL structure.
Definition: spi_api.h:43
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.