1 /**
2 * \file
3 *
4 * \brief SAM Serial Peripheral Interface Driver
5 *
6 * Copyright (C) 2012-2016 Atmel Corporation. All rights reserved.
7 *
8 * \asf_license_start
9 *
10 * \page License
11 *
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions are met:
14 *
15 * 1. Redistributions of source code must retain the above copyright notice,
16 * this list of conditions and the following disclaimer.
17 *
18 * 2. Redistributions in binary form must reproduce the above copyright notice,
19 * this list of conditions and the following disclaimer in the documentation
20 * and/or other materials provided with the distribution.
21 *
22 * 3. The name of Atmel may not be used to endorse or promote products derived
23 * from this software without specific prior written permission.
24 *
25 * 4. This software may only be redistributed and used in connection with an
26 * Atmel microcontroller product.
27 *
28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
38 * POSSIBILITY OF SUCH DAMAGE.
39 *
40 * \asf_license_stop
41 *
42 */
43 /*
44 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
45 */
46
47 #ifndef SPI_H_INCLUDED
48 #define SPI_H_INCLUDED
49
50 /**
51 * \defgroup asfdoc_sam0_sercom_spi_group SAM Serial Peripheral Interface (SERCOM SPI) Driver
52 *
53 * This driver for Atmel® | SMART ARM®-based microcontrollers provides
54 * an interface for the configuration and management of the SERCOM module in
55 * its SPI mode to transfer SPI data frames. The following driver API modes
56 * are covered by this manual:
57 *
58 * - Polled APIs
59 * \if SPI_CALLBACK_MODE
60 * - Callback APIs
61 * \endif
62 *
63 * The following peripheral is used by this module:
64 * - SERCOM (Serial Communication Interface)
65 *
66 * The following devices can use this module:
67 * - Atmel | SMART SAM D20/D21
68 * - Atmel | SMART SAM R21
69 * - Atmel | SMART SAM D09/D10/D11
70 * - Atmel | SMART SAM L21/L22
71 * - Atmel | SMART SAM DA1
72 * - Atmel | SMART SAM C20/C21
73 * - Atmel | SMART SAM HA1
74 * - Atmel | SMART SAM R30
75 *
76 * The outline of this documentation is as follows:
77 * - \ref asfdoc_sam0_sercom_spi_prerequisites
78 * - \ref asfdoc_sam0_sercom_spi_module_overview
79 * - \ref asfdoc_sam0_sercom_spi_special_considerations
80 * - \ref asfdoc_sam0_sercom_spi_extra_info
81 * - \ref asfdoc_sam0_sercom_spi_examples
82 * - \ref asfdoc_sam0_sercom_spi_api_overview
83 *
84 * \section asfdoc_sam0_sercom_spi_prerequisites Prerequisites
85 * There are no prerequisites.
86 *
87 *
88 * \section asfdoc_sam0_sercom_spi_module_overview Module Overview
89 * The Serial Peripheral Interface (SPI) is a high-speed synchronous data
90 * transfer interface using three or four pins. It allows fast communication
91 * between a master device and one or more peripheral devices.
92 *
93 * A device connected to the bus must act as a master or a slave. The master
94 * initiates and controls all data transactions.
95 * The SPI master initiates a communication cycle by pulling low the Slave
96 * Select (SS) pin of the desired slave. The Slave Select pin is active low.
97 * Master and slave prepare data to be sent in their respective shift
98 * registers, and the master generates the required clock pulses on the SCK
99 * line to interchange data. Data is always shifted from master to slave on
100 * the Master Out - Slave In (MOSI) line, and from slave to master on the
101 * Master In - Slave Out (MISO) line. After each data transfer, the master can
102 * synchronize to the slave by pulling the SS line high.
103 *
104 * \subsection asfdoc_sam0_sercom_spi_module_features Driver Feature Macro Definition
105 * <table>
106 * <tr>
107 * <th>Driver feature macro</th>
108 * <th>Supported devices</th>
109 * </tr>
110 * <tr>
111 * <td>FEATURE_SPI_SLAVE_SELECT_LOW_DETECT</td>
112 * <td>SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/R30</td>
113 * </tr>
114 * <tr>
115 * <td>FEATURE_SPI_HARDWARE_SLAVE_SELECT</td>
116 * <td>SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/R30</td>
117 * </tr>
118 * <tr>
119 * <td>FEATURE_SPI_ERROR_INTERRUPT</td>
120 * <td>SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/R30</td>
121 * </tr>
122 * <tr>
123 * <td>FEATURE_SPI_SYNC_SCHEME_VERSION_2</td>
124 * <td>SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/R30</td>
125 * </tr>
126 * </table>
127 * \note The specific features are only available in the driver when the
128 * selected device supports those features.
129 *
130 * \subsection asfdoc_sam0_sercom_spi_bus SPI Bus Connection
131 * In \ref asfdoc_sam0_spi_connection_example "the figure below", the
132 * connection between one master and one slave is shown.
133 *
134 * \anchor asfdoc_sam0_spi_connection_example
135 * \dot
136 * digraph spi_slaves_par {
137 * subgraph cluster_spi_master {
138 * shift_reg [label="Shift register", shape=box];
139 * mosi_m [label="MOSI", shape=none];
140 * miso_m [label="MISO", shape=none];
141 * sck_m [label="SCK", shape=none];
142 * ss_m [label="GPIO pin", shape=none];
143 * {rank=same; mosi_m miso_m sck_m ss_m}
144 * label="SPI Master";
145 * }
146 * subgraph cluster_spi_slave {
147 * mosi_s [label="MOSI", shape=none];
148 * miso_s [label="MISO", shape=none];
149 * sck_s [label="SCK", shape=none];
150 * ss_s [label="SS", shape=none];
151 * shift_reg_s [label="Shift register", shape=box];
152 * {rank=same; mosi_s miso_s sck_s ss_s}
153 * label="SPI Slave";
154 * rankdir=LR;
155 * }
156 * shift_reg:e -> mosi_m:w [label=""];
157 * mosi_m:e -> mosi_s:w [label=""];
158 * mosi_s:e -> shift_reg_s:w [label=""];
159 * miso_s:w -> miso_m:e [label=""];
160 * sck_m -> sck_s;
161 * ss_m -> ss_s;
162 * shift_reg_s:se -> miso_s:e [label=""];
163 * miso_m:w -> shift_reg:sw [label=""];
164 * rankdir=LR;
165 * }
166 * \enddot
167 *
168 * The different lines are as follows:
169 * - \b MISO Master Input Slave Output. The line where the data is shifted
170 * out from the slave and into the master.
171 * - \b MOSI Master Output Slave Input. The line where the data is shifted
172 * out from the master and into the slave.
173 * - \b SCK Serial Clock. Generated by the master device.
174 * - \b SS Slave Select. To initiate a transaction, the master must pull this
175 * line low.
176 *
177 * If the bus consists of several SPI slaves, they can be connected in parallel
178 * and the SPI master can use general I/O pins to control separate SS lines to
179 * each slave on the bus.
180 *
181 * It is also possible to connect all slaves in series. In this configuration,
182 * a common SS is provided to \c N slaves, enabling them simultaneously. The
183 * MISO from the \c N-1 slaves is connected to the MOSI on the next slave. The
184 * \c N<SUP>th</SUP> slave connects its MISO back to the master. For a
185 * complete transaction, the master must shift \c N+1 characters.
186 *
187 * \subsection asfdoc_sam0_sercom_spi_chsize SPI Character Size
188 * The SPI character size is configurable to eight or nine bits.
189 *
190 * \subsection asfdoc_sam0_sercom_spi_master_mode Master Mode
191 * When configured as a master, the SS pin will be configured as an output.
192 *
193 * \subsubsection asfdoc_sam0_sercom_spi_master_mode_data_transfer Data Transfer
194 * Writing a character will start the SPI clock generator, and
195 * the character is transferred to the shift register when the shift
196 * register is empty.
197 * Once this is done, a new character can be written.
198 * As each character is shifted out from the master, a character is shifted in
199 * from the slave. If the receiver is enabled, the data is moved to the receive
200 * buffer at the completion of the frame and can be read.
201 *
202 * \subsection asfdoc_sam0_sercom_spi_slave_mode Slave Mode
203 * When configured as a slave, the SPI interface will remain inactive with MISO
204 * tri-stated as long as the SS pin is driven high.
205 *
206 * \subsubsection asfdoc_sam0_sercom_spi_slave_mode_data_transfer_slave Data Transfer
207 * The data register can be updated at any time.
208 * As the SPI slave shift register is clocked by SCK, a minimum of three SCK
209 * cycles are needed from the time new data is written, until the character is
210 * ready to be shifted out. If the shift register has not been loaded with
211 * data, the current contents will be transmitted.
212 *
213 * If constant transmission of data is needed in SPI slave mode, the system
214 * clock should be faster than SCK.
215 * If the receiver is enabled, the received character can be read from the
216 * receive buffer. When SS line is driven high, the slave will not receive any
217 * additional data.
218 *
219 * \subsubsection asfdoc_sam0_sercom_spi_slave_mode_addr_recognition Address Recognition
220 * When the SPI slave is configured with address recognition, the first
221 * character in a transaction is checked for an address match. If there is a
222 * match, the MISO output is enabled and the transaction is processed.
223 * If the address does not match, the complete transaction is ignored.
224 *
225 * If the device is asleep, it can be woken up by an address match in order
226 * to process the transaction.
227 *
228 * \note In master mode, an address packet is written by the
229 * \ref spi_select_slave function if the address_enabled configuration is
230 * set in the \ref spi_slave_inst_config struct.
231 *
232 * \subsection asfdoc_sam0_sercom_spi_data_modes Data Modes
233 * There are four combinations of SCK phase and polarity with respect to
234 * serial data. \ref asfdoc_sam0_spi_mode_table "The table below" shows the
235 * clock polarity (CPOL) and clock phase (CPHA) in the different modes.
236 * <i>Leading edge</i> is the first clock edge in a clock cycle and
237 * <i>trailing edge</i> is the last clock edge in a clock cycle.
238 *
239 * \anchor asfdoc_sam0_spi_mode_table
240 * <table>
241 * <caption>SPI Data Modes</caption>
242 * <tr>
243 * <th>Mode</th>
244 * <th>CPOL</th>
245 * <th>CPHA</th>
246 * <th>Leading Edge</th>
247 * <th>Trailing Edge</th>
248 * </tr>
249 * <tr>
250 * <td> 0 </td>
251 * <td> 0 </td>
252 * <td> 0 </td>
253 * <td> Rising, Sample </td>
254 * <td> Falling, Setup </td>
255 * </tr>
256 * <tr>
257 * <td> 1 </td>
258 * <td> 0 </td>
259 * <td> 1 </td>
260 * <td> Rising, Setup </td>
261 * <td> Falling, Sample </td>
262 * </tr>
263 * <tr>
264 * <td> 2 </td>
265 * <td> 1 </td>
266 * <td> 0 </td>
267 * <td> Falling, Sample </td>
268 * <td> Rising, Setup </td>
269 * </tr>
270 * <tr>
271 * <td> 3 </td>
272 * <td> 1 </td>
273 * <td> 1 </td>
274 * <td> Falling, Setup </td>
275 * <td> Rising, Sample </td>
276 * </tr>
277 * </table>
278 *
279 *
280 * \subsection asfdoc_sam0_sercom_spi_pads SERCOM Pads
281 * The SERCOM pads are automatically configured as seen in
282 * \ref asfdoc_sam0_spi_sercom_pad_table "the table below". If the receiver
283 * is disabled, the data input (MISO for master, MOSI for slave) can be used
284 * for other purposes.
285 *
286 * In master mode, the SS pin(s) must be configured using the \ref spi_slave_inst
287 * struct.
288 *
289 * \anchor asfdoc_sam0_spi_sercom_pad_table
290 * <table>
291 * <caption>SERCOM SPI Pad Usages</caption>
292 * <tr>
293 * <th> Pin </th>
294 * <th> Master SPI </th>
295 * <th> Slave SPI </th>
296 * </tr>
297 * <tr>
298 * <td> MOSI </td>
299 * <td> Output </td>
300 * <td> Input </td>
301 * </tr>
302 * <tr>
303 * <td> MISO </td>
304 * <td> Input </td>
305 * <td> Output </td>
306 * </tr>
307 * <tr>
308 * <td> SCK </td>
309 * <td> Output </td>
310 * <td> Input </td>
311 * </tr>
312 * <tr>
313 * <td> SS </td>
314 * <td> User defined output enable </td>
315 * <td> Input </td>
316 * </tr>
317 * </table>
318 *
319 * \subsection asfdoc_sam0_sercom_spi_sleep_modes Operation in Sleep Modes
320 * The SPI module can operate in all sleep modes by setting the run_in_standby
321 * option in the \ref spi_config struct. The operation in slave and master mode
322 * is shown in the table below.
323 * <table>
324 * <tr>
325 * <th> run_in_standby </th>
326 * <th> Slave </th>
327 * <th> Master </th>
328 * </tr>
329 * <tr>
330 * <td> false </td>
331 * <td> Disabled, all reception is dropped </td>
332 * <td> GCLK is disabled when master is idle, wake on transmit complete </td>
333 * </tr>
334 * <tr>
335 * <td> true </td>
336 * <td> Wake on reception </td>
337 * <td> GCLK is enabled while in sleep modes, wake on all interrupts </td>
338 * </tr>
339 * </table>
340 *
341 * \subsection asfdoc_sam0_sercom_spi_clock_generation Clock Generation
342 * In SPI master mode, the clock (SCK) is generated internally using the
343 * SERCOM baudrate generator. In SPI slave mode, the clock is provided by
344 * an external master on the SCK pin. This clock is used to directly clock
345 * the SPI shift register.
346 *
347 * \section asfdoc_sam0_sercom_spi_special_considerations Special Considerations
348 * \subsection pin_mux pinmux Settings
349 * The pin MUX settings must be configured properly, as not all settings
350 * can be used in different modes of operation.
351 *
352 * \section asfdoc_sam0_sercom_spi_extra_info Extra Information
353 * For extra information, see \ref asfdoc_sam0_sercom_spi_extra. This includes:
354 * - \ref asfdoc_sam0_sercom_spi_extra_acronyms
355 * - \ref asfdoc_sam0_sercom_spi_extra_dependencies
356 * - \ref asfdoc_sam0_sercom_spi_extra_workarounds
357 * - \ref asfdoc_sam0_sercom_spi_extra_history
358 *
359 * \section asfdoc_sam0_sercom_spi_examples Examples
360 *
361 * For a list of examples related to this driver, see
362 * \ref asfdoc_sam0_sercom_spi_exqsg.
363 *
364 * \section asfdoc_sam0_sercom_spi_api_overview API Overview
365 * @{
366 */
367
368 #include <compiler.h>
369 #include <port.h>
370 #include <sercom.h>
371 #include <pinmux.h>
372 #include <string.h>
373 #include <conf_spi.h>
374
375 # if SPI_CALLBACK_MODE == true
376 # include <sercom_interrupt.h>
377 # endif
378
379 #ifdef __cplusplus
380 extern "C" {
381 #endif
382
383 #if (CONF_SPI_MASTER_ENABLE == false) && (CONF_SPI_SLAVE_ENABLE == false)
384 #error "Not possible compile SPI driver, invalid driver configuration. Make sure that either/both CONF_SPI_MASTER_ENABLE/CONF_SPI_SLAVE_ENABLE is set to true."
385 #endif
386
387 /**
388 * \name Driver Feature Definition
389 * Define SERCOM SPI features set according to different device family.
390 * @{
391 */
392 # if (SAMD21) || (SAMR21) || (SAMD11) || (SAMD10) || (SAML21) || (SAMDA1) || (SAMHA1) ||\
393 (SAML22) || (SAMC20) || (SAMC21) || (SAMD09) || (SAMR30) || defined(__DOXYGEN__)
394 /** SPI slave select low detection. */
395 # define FEATURE_SPI_SLAVE_SELECT_LOW_DETECT
396 /** Slave select can be controlled by hardware. */
397 # define FEATURE_SPI_HARDWARE_SLAVE_SELECT
398 /** SPI with error detect feature. */
399 # define FEATURE_SPI_ERROR_INTERRUPT
400 /** SPI sync scheme version 2. */
401 # define FEATURE_SPI_SYNC_SCHEME_VERSION_2
402 # endif
403 /*@}*/
404
405 # ifndef PINMUX_DEFAULT
406 /** Default pinmux. */
407 # define PINMUX_DEFAULT 0
408 # endif
409
410 # ifndef PINMUX_UNUSED
411 /** Unused pinmux. */
412 # define PINMUX_UNUSED 0xFFFFFFFF
413 # endif
414
415 # ifndef SPI_TIMEOUT
416 /** SPI timeout value. */
417 # define SPI_TIMEOUT 10000
418 # endif
419
420 # if SPI_CALLBACK_MODE == true
421 /**
422 * \brief SPI Callback enum
423 *
424 * Callbacks for SPI callback driver.
425 *
426 * \note For slave mode, these callbacks will be called when a transaction
427 * is ended by the master pulling Slave Select high.
428 *
429 */
430 enum spi_callback {
431 /** Callback for buffer transmitted */
432 SPI_CALLBACK_BUFFER_TRANSMITTED,
433 /** Callback for buffer received */
434 SPI_CALLBACK_BUFFER_RECEIVED,
435 /** Callback for buffers transceived */
436 SPI_CALLBACK_BUFFER_TRANSCEIVED,
437 /** Callback for error */
438 SPI_CALLBACK_ERROR,
439 /**
440 * Callback for transmission ended by master before the entire buffer was
441 * read or written from slave
442 */
443 SPI_CALLBACK_SLAVE_TRANSMISSION_COMPLETE,
444 # ifdef FEATURE_SPI_SLAVE_SELECT_LOW_DETECT
445 /** Callback for slave select low */
446 SPI_CALLBACK_SLAVE_SELECT_LOW,
447 # endif
448 # ifdef FEATURE_SPI_ERROR_INTERRUPT
449 /** Callback for combined error happen */
450 SPI_CALLBACK_COMBINED_ERROR,
451 # endif
452 # if !defined(__DOXYGEN__)
453 /** Number of available callbacks */
454 SPI_CALLBACK_N,
455 # endif
456 };
457 # endif
458
459 #if SPI_CALLBACK_MODE == true
460 # if !defined(__DOXYGEN__)
461 /**
462 * \internal SPI transfer directions
463 */
464 enum _spi_direction {
465 /** Transfer direction is read */
466 SPI_DIRECTION_READ,
467 /** Transfer direction is write */
468 SPI_DIRECTION_WRITE,
469 /** Transfer direction is read and write */
470 SPI_DIRECTION_BOTH,
471 /** No transfer */
472 SPI_DIRECTION_IDLE,
473 };
474 # endif
475 #endif
476
477 /**
478 * \brief SPI Interrupt Flags
479 *
480 * Interrupt flags for the SPI module.
481 *
482 */
483 enum spi_interrupt_flag {
484 /**
485 * This flag is set when the contents of the data register has been moved
486 * to the shift register and the data register is ready for new data
487 */
488 SPI_INTERRUPT_FLAG_DATA_REGISTER_EMPTY = SERCOM_SPI_INTFLAG_DRE,
489 /**
490 * This flag is set when the contents of the shift register has been
491 * shifted out
492 */
493 SPI_INTERRUPT_FLAG_TX_COMPLETE = SERCOM_SPI_INTFLAG_TXC,
494 /** This flag is set when data has been shifted into the data register */
495 SPI_INTERRUPT_FLAG_RX_COMPLETE = SERCOM_SPI_INTFLAG_RXC,
496 # ifdef FEATURE_SPI_SLAVE_SELECT_LOW_DETECT
497 /** This flag is set when slave select low */
498 SPI_INTERRUPT_FLAG_SLAVE_SELECT_LOW = SERCOM_SPI_INTFLAG_SSL,
499 # endif
500 # ifdef FEATURE_SPI_ERROR_INTERRUPT
501 /** This flag is set when combined error happen */
502 SPI_INTERRUPT_FLAG_COMBINED_ERROR = SERCOM_SPI_INTFLAG_ERROR,
503 # endif
504 };
505
506 /**
507 * \brief SPI transfer modes enum
508 *
509 * SPI transfer mode.
510 */
511 enum spi_transfer_mode {
512 /** Mode 0. Leading edge: rising, sample. Trailing edge: falling, setup */
513 SPI_TRANSFER_MODE_0 = 0,
514 /** Mode 1. Leading edge: rising, setup. Trailing edge: falling, sample */
515 SPI_TRANSFER_MODE_1 = SERCOM_SPI_CTRLA_CPHA,
516 /** Mode 2. Leading edge: falling, sample. Trailing edge: rising, setup */
517 SPI_TRANSFER_MODE_2 = SERCOM_SPI_CTRLA_CPOL,
518 /** Mode 3. Leading edge: falling, setup. Trailing edge: rising, sample */
519 SPI_TRANSFER_MODE_3 = SERCOM_SPI_CTRLA_CPHA | SERCOM_SPI_CTRLA_CPOL,
520 };
521
522 /**
523 * \brief SPI frame format enum
524 *
525 * Frame format for slave mode.
526 */
527 enum spi_frame_format {
528 /** SPI frame */
529 SPI_FRAME_FORMAT_SPI_FRAME = SERCOM_SPI_CTRLA_FORM(0),
530 /** SPI frame with address */
531 SPI_FRAME_FORMAT_SPI_FRAME_ADDR = SERCOM_SPI_CTRLA_FORM(2),
532 };
533
534 /**
535 * \brief SPI signal MUX settings
536 *
537 * Set the functionality of the SERCOM pins. As not all combinations can be used
538 * in different modes of operation, proper combinations must be chosen according
539 * to the rest of the configuration.
540 *
541 * \note In master operation: DI is MISO, DO is MOSI.
542 * In slave operation: DI is MOSI, DO is MISO.
543 *
544 * See \ref asfdoc_sam0_sercom_spi_mux_settings for a description of the
545 * various MUX setting options.
546 */
547 enum spi_signal_mux_setting {
548 /** SPI MUX combination A. DOPO: 0x0, DIPO: 0x0 */
549 SPI_SIGNAL_MUX_SETTING_A =
550 (0x0 << SERCOM_SPI_CTRLA_DOPO_Pos) |
551 (0x0 << SERCOM_SPI_CTRLA_DIPO_Pos),
552 /** SPI MUX combination B. DOPO: 0x0, DIPO: 0x1 */
553 SPI_SIGNAL_MUX_SETTING_B =
554 (0x0 << SERCOM_SPI_CTRLA_DOPO_Pos) |
555 (0x1 << SERCOM_SPI_CTRLA_DIPO_Pos),
556 /** SPI MUX combination C. DOPO: 0x0, DIPO: 0x2 */
557 SPI_SIGNAL_MUX_SETTING_C =
558 (0x0 << SERCOM_SPI_CTRLA_DOPO_Pos) |
559 (0x2 << SERCOM_SPI_CTRLA_DIPO_Pos),
560 /** SPI MUX combination D. DOPO: 0x0, DIPO: 0x3 */
561 SPI_SIGNAL_MUX_SETTING_D =
562 (0x0 << SERCOM_SPI_CTRLA_DOPO_Pos) |
563 (0x3 << SERCOM_SPI_CTRLA_DIPO_Pos),
564 /** SPI MUX combination E. DOPO: 0x1, DIPO: 0x0 */
565 SPI_SIGNAL_MUX_SETTING_E =
566 (0x1 << SERCOM_SPI_CTRLA_DOPO_Pos) |
567 (0x0 << SERCOM_SPI_CTRLA_DIPO_Pos),
568 /** SPI MUX combination F. DOPO: 0x1, DIPO: 0x1 */
569 SPI_SIGNAL_MUX_SETTING_F =
570 (0x1 << SERCOM_SPI_CTRLA_DOPO_Pos) |
571 (0x1 << SERCOM_SPI_CTRLA_DIPO_Pos),
572 /** SPI MUX combination G. DOPO: 0x1, DIPO: 0x2 */
573 SPI_SIGNAL_MUX_SETTING_G =
574 (0x1 << SERCOM_SPI_CTRLA_DOPO_Pos) |
575 (0x2 << SERCOM_SPI_CTRLA_DIPO_Pos),
576 /** SPI MUX combination H. DOPO: 0x1, DIPO: 0x3 */
577 SPI_SIGNAL_MUX_SETTING_H =
578 (0x1 << SERCOM_SPI_CTRLA_DOPO_Pos) |
579 (0x3 << SERCOM_SPI_CTRLA_DIPO_Pos),
580 /** SPI MUX combination I. DOPO: 0x2, DIPO: 0x0 */
581 SPI_SIGNAL_MUX_SETTING_I =
582 (0x2 << SERCOM_SPI_CTRLA_DOPO_Pos) |
583 (0x0 << SERCOM_SPI_CTRLA_DIPO_Pos),
584 /** SPI MUX combination J. DOPO: 0x2, DIPO: 0x1 */
585 SPI_SIGNAL_MUX_SETTING_J =
586 (0x2 << SERCOM_SPI_CTRLA_DOPO_Pos) |
587 (0x1 << SERCOM_SPI_CTRLA_DIPO_Pos),
588 /** SPI MUX combination K. DOPO: 0x2, DIPO: 0x2 */
589 SPI_SIGNAL_MUX_SETTING_K =
590 (0x2 << SERCOM_SPI_CTRLA_DOPO_Pos) |
591 (0x2 << SERCOM_SPI_CTRLA_DIPO_Pos),
592 /** SPI MUX combination L. DOPO: 0x2, DIPO: 0x3 */
593 SPI_SIGNAL_MUX_SETTING_L =
594 (0x2 << SERCOM_SPI_CTRLA_DOPO_Pos) |
595 (0x3 << SERCOM_SPI_CTRLA_DIPO_Pos),
596 /** SPI MUX combination M. DOPO: 0x3, DIPO: 0x0 */
597 SPI_SIGNAL_MUX_SETTING_M =
598 (0x3 << SERCOM_SPI_CTRLA_DOPO_Pos) |
599 (0x0 << SERCOM_SPI_CTRLA_DIPO_Pos),
600 /** SPI MUX combination N. DOPO: 0x3, DIPO: 0x1 */
601 SPI_SIGNAL_MUX_SETTING_N =
602 (0x3 << SERCOM_SPI_CTRLA_DOPO_Pos) |
603 (0x1 << SERCOM_SPI_CTRLA_DIPO_Pos),
604 /** SPI MUX combination O. DOPO: 0x3, DIPO: 0x2 */
605 SPI_SIGNAL_MUX_SETTING_O =
606 (0x3 << SERCOM_SPI_CTRLA_DOPO_Pos) |
607 (0x2 << SERCOM_SPI_CTRLA_DIPO_Pos),
608 /** SPI MUX combination P. DOPO: 0x3, DIPO: 0x3 */
609 SPI_SIGNAL_MUX_SETTING_P =
610 (0x3 << SERCOM_SPI_CTRLA_DOPO_Pos) |
611 (0x3 << SERCOM_SPI_CTRLA_DIPO_Pos),
612 };
613
614 /**
615 * \brief SPI address modes enum
616 *
617 * For slave mode when using the SPI frame with address format.
618 *
619 */
620 enum spi_addr_mode {
621 /**
622 * \c address_mask in the \ref spi_config struct is used as a mask to the register
623 */
624 SPI_ADDR_MODE_MASK = SERCOM_SPI_CTRLB_AMODE(0),
625 /**
626 * The slave responds to the two unique addresses in \c address and
627 * \c address_mask in the \ref spi_config struct
628 */
629 SPI_ADDR_MODE_UNIQUE = SERCOM_SPI_CTRLB_AMODE(1),
630 /**
631 * The slave responds to the range of addresses between and including \c address
632 * and \c address_mask in the \ref spi_config struct
633 */
634 SPI_ADDR_MODE_RANGE = SERCOM_SPI_CTRLB_AMODE(2),
635 };
636
637 /**
638 * \brief SPI modes enum
639 *
640 * SPI mode selection.
641 */
642 enum spi_mode {
643 /** Master mode */
644 SPI_MODE_MASTER = 1,
645 /** Slave mode */
646 SPI_MODE_SLAVE = 0,
647 };
648
649 /**
650 * \brief SPI data order enum
651 *
652 * SPI data order.
653 *
654 */
655 enum spi_data_order {
656 /** The LSB of the data is transmitted first */
657 SPI_DATA_ORDER_LSB = SERCOM_SPI_CTRLA_DORD,
658 /** The MSB of the data is transmitted first */
659 SPI_DATA_ORDER_MSB = 0,
660 };
661
662 /**
663 * \brief SPI character size enum
664 *
665 * SPI character size.
666 *
667 */
668 enum spi_character_size {
669 /** 8-bit character */
670 SPI_CHARACTER_SIZE_8BIT = SERCOM_SPI_CTRLB_CHSIZE(0),
671 /** 9-bit character */
672 SPI_CHARACTER_SIZE_9BIT = SERCOM_SPI_CTRLB_CHSIZE(1),
673 };
674
675 # if SPI_CALLBACK_MODE == true
676 /** Prototype for the device instance */
677 struct spi_module;
678
679 /** Type of the callback functions */
680 typedef void (*spi_callback_t)(struct spi_module *const module);
681
682 # if !defined(__DOXYGEN__)
683 /** Prototype for the interrupt handler */
684 extern void _spi_interrupt_handler(uint8_t instance);
685 # endif
686 # endif
687
688 /**
689 * \brief SERCOM SPI driver software device instance structure.
690 *
691 * SERCOM SPI driver software instance structure, used to retain software state
692 * information of an associated hardware module instance.
693 *
694 * \note The fields of this structure should not be altered by the user
695 * application; they are reserved for module-internal use only.
696 */
697 struct spi_module {
698 # if !defined(__DOXYGEN__)
699 /** SERCOM hardware module */
700 Sercom *hw;
701 /** Module lock */
702 volatile bool locked;
703 /** SPI mode */
704 enum spi_mode mode;
705 /** SPI character size */
706 enum spi_character_size character_size;
707 /** Receiver enabled */
708 bool receiver_enabled;
709 # ifdef FEATURE_SPI_HARDWARE_SLAVE_SELECT
710 /** Enable Hardware Slave Select */
711 bool master_slave_select_enable;
712 # endif
713 # if SPI_CALLBACK_MODE == true
714 /** Direction of transaction */
715 volatile enum _spi_direction dir;
716 /** Array to store callback function pointers in */
717 spi_callback_t callback[SPI_CALLBACK_N];
718 /** Buffer pointer to where the next received character will be put */
719 volatile uint8_t *rx_buffer_ptr;
720 /** Buffer pointer to where the next character will be transmitted from
721 **/
722 volatile uint8_t *tx_buffer_ptr;
723 /** Remaining characters to receive */
724 volatile uint16_t remaining_rx_buffer_length;
725 /** Remaining dummy characters to send when reading */
726 volatile uint16_t remaining_dummy_buffer_length;
727 /** Remaining characters to transmit */
728 volatile uint16_t remaining_tx_buffer_length;
729 /** Bit mask for callbacks registered */
730 uint8_t registered_callback;
731 /** Bit mask for callbacks enabled */
732 uint8_t enabled_callback;
733 /** Holds the status of the ongoing or last operation */
734 volatile enum status_code status;
735 # endif
736 # endif
737 };
738
739 /**
740 * \brief SPI peripheral slave instance structure
741 *
742 * SPI peripheral slave software instance structure, used to configure the
743 * correct SPI transfer mode settings for an attached slave. See
744 * \ref spi_select_slave.
745 */
746 struct spi_slave_inst {
747 /** Pin to use as slave select */
748 uint8_t ss_pin;
749 /** Address recognition enabled in slave device */
750 bool address_enabled;
751 /** Address of slave device */
752 uint8_t address;
753 };
754
755 /**
756 * \brief SPI peripheral slave configuration structure
757 *
758 * SPI Peripheral slave configuration structure.
759 */
760 struct spi_slave_inst_config {
761 /** Pin to use as slave select */
762 uint8_t ss_pin;
763 /** Enable address */
764 bool address_enabled;
765 /** Address of slave */
766 uint8_t address;
767 };
768
769 /**
770 * \brief SPI Master configuration structure
771 *
772 * SPI Master configuration structure.
773 */
774 struct spi_master_config {
775 /** Baud rate */
776 uint32_t baudrate;
777 };
778
779 /**
780 * \brief SPI slave configuration structure
781 *
782 * SPI slave configuration structure.
783 */
784 struct spi_slave_config {
785 /** Frame format */
786 enum spi_frame_format frame_format;
787 /** Address mode */
788 enum spi_addr_mode address_mode;
789 /** Address */
790 uint8_t address;
791 /** Address mask */
792 uint8_t address_mask;
793 /** Preload data to the shift register while SS is high */
794 bool preload_enable;
795 };
796
797 /**
798 * \brief SPI configuration structure
799 *
800 * Configuration structure for an SPI instance. This structure should be
801 * initialized by the \ref spi_get_config_defaults function before being
802 * modified by the user application.
803 */
804 struct spi_config {
805 /** SPI mode */
806 enum spi_mode mode;
807 /** Data order */
808 enum spi_data_order data_order;
809 /** Transfer mode */
810 enum spi_transfer_mode transfer_mode;
811 /** MUX setting */
812 enum spi_signal_mux_setting mux_setting;
813 /** SPI character size */
814 enum spi_character_size character_size;
815 /** Enabled in sleep modes */
816 bool run_in_standby;
817 /** Enable receiver */
818 bool receiver_enable;
819 # ifdef FEATURE_SPI_SLAVE_SELECT_LOW_DETECT
820 /** Enable Slave Select Low Detect */
821 bool select_slave_low_detect_enable;
822 # endif
823 # ifdef FEATURE_SPI_HARDWARE_SLAVE_SELECT
824 /** Enable Master Slave Select */
825 bool master_slave_select_enable;
826 # endif
827 /** Union for slave or master specific configuration */
828 union {
829 /** Slave specific configuration */
830 struct spi_slave_config slave;
831 /** Master specific configuration */
832 struct spi_master_config master;
833 } mode_specific;
834 /** GCLK generator to use as clock source */
835 enum gclk_generator generator_source;
836 /** PAD0 pinmux */
837 uint32_t pinmux_pad0;
838 /** PAD1 pinmux */
839 uint32_t pinmux_pad1;
840 /** PAD2 pinmux */
841 uint32_t pinmux_pad2;
842 /** PAD3 pinmux */
843 uint32_t pinmux_pad3;
844 };
845
846 /**
847 * \brief Determines if the SPI module is currently synchronizing to the bus.
848 *
849 * This function will check if the underlying hardware peripheral module is
850 * currently synchronizing across multiple clock domains to the hardware bus.
851 * This function can be used to delay further operations on the module until it
852 * is ready.
853 *
854 * \param[in] module SPI hardware module
855 *
856 * \return Synchronization status of the underlying hardware module.
857 * \retval true Module synchronization is ongoing
858 * \retval false Module synchronization is not ongoing
859 *
860 */
spi_is_syncing(struct spi_module * const module)861 static inline bool spi_is_syncing(
862 struct spi_module *const module)
863 {
864 /* Sanity check arguments */
865 Assert(module);
866 Assert(module->hw);
867
868 SercomSpi *const spi_module = &(module->hw->SPI);
869
870 # ifdef FEATURE_SPI_SYNC_SCHEME_VERSION_2
871 /* Return synchronization status */
872 return (spi_module->SYNCBUSY.reg);
873 # else
874 /* Return synchronization status */
875 return (spi_module->STATUS.reg & SERCOM_SPI_STATUS_SYNCBUSY);
876 # endif
877 }
878
879 /**
880 * \name Driver Initialization and Configuration
881 * @{
882 */
883
884 /**
885 * \brief Initializes an SPI configuration structure to default values
886 *
887 * This function will initialize a given SPI configuration structure to a set
888 * of known default values. This function should be called on any new
889 * instance of the configuration structures before being modified by the
890 * user application.
891 *
892 * The default configuration is as follows:
893 * \li Master mode enabled
894 * \li MSB of the data is transmitted first
895 * \li Transfer mode 0
896 * \li MUX Setting D
897 * \li Character size eight bits
898 * \li Not enabled in sleep mode
899 * \li Receiver enabled
900 * \li Baudrate 100000
901 * \li Default pinmux settings for all pads
902 * \li GCLK generator 0
903 *
904 * \param[out] config Configuration structure to initialize to default values
905 */
spi_get_config_defaults(struct spi_config * const config)906 static inline void spi_get_config_defaults(
907 struct spi_config *const config)
908 {
909 /* Sanity check arguments */
910 Assert(config);
911
912 /* Default configuration values */
913 config->mode = SPI_MODE_MASTER;
914 config->data_order = SPI_DATA_ORDER_MSB;
915 config->transfer_mode = SPI_TRANSFER_MODE_0;
916 config->mux_setting = SPI_SIGNAL_MUX_SETTING_D;
917 config->character_size = SPI_CHARACTER_SIZE_8BIT;
918 config->run_in_standby = false;
919 config->receiver_enable = true;
920 # ifdef FEATURE_SPI_SLAVE_SELECT_LOW_DETECT
921 config->select_slave_low_detect_enable= true;
922 # endif
923 # ifdef FEATURE_SPI_HARDWARE_SLAVE_SELECT
924 config->master_slave_select_enable= false;
925 # endif
926 config->generator_source = GCLK_GENERATOR_0;
927
928 /* Clear mode specific config */
929 memset(&(config->mode_specific), 0, sizeof(config->mode_specific));
930
931 /* Master config defaults */
932 config->mode_specific.master.baudrate = 100000;
933
934 /* pinmux config defaults */
935 config->pinmux_pad0 = PINMUX_DEFAULT;
936 config->pinmux_pad1 = PINMUX_DEFAULT;
937 config->pinmux_pad2 = PINMUX_DEFAULT;
938 config->pinmux_pad3 = PINMUX_DEFAULT;
939
940 };
941
942 /**
943 * \brief Initializes an SPI peripheral slave device configuration structure to default values
944 *
945 * This function will initialize a given SPI slave device configuration
946 * structure to a set of known default values. This function should be called
947 * on any new instance of the configuration structures before being modified by
948 * the user application.
949 *
950 * The default configuration is as follows:
951 * \li Slave Select on GPIO pin 10
952 * \li Addressing not enabled
953 *
954 * \param[out] config Configuration structure to initialize to default values
955 */
spi_slave_inst_get_config_defaults(struct spi_slave_inst_config * const config)956 static inline void spi_slave_inst_get_config_defaults(
957 struct spi_slave_inst_config *const config)
958 {
959 Assert(config);
960
961 config->ss_pin = 10;
962 config->address_enabled = false;
963 config->address = 0;
964 }
965
966 /**
967 * \brief Attaches an SPI peripheral slave
968 *
969 * This function will initialize the software SPI peripheral slave, based on
970 * the values of the config struct. The slave can then be selected and
971 * optionally addressed by the \ref spi_select_slave function.
972 *
973 * \param[out] slave Pointer to the software slave instance struct
974 * \param[in] config Pointer to the config struct
975 *
976 */
spi_attach_slave(struct spi_slave_inst * const slave,const struct spi_slave_inst_config * const config)977 static inline void spi_attach_slave(
978 struct spi_slave_inst *const slave,
979 const struct spi_slave_inst_config *const config)
980 {
981 Assert(slave);
982 Assert(config);
983
984 slave->ss_pin = config->ss_pin;
985 slave->address_enabled = config->address_enabled;
986 slave->address = config->address;
987
988 /* Get default config for pin */
989 struct port_config pin_conf;
990 port_get_config_defaults(&pin_conf);
991
992 /* Edit config to set the pin as output */
993 pin_conf.direction = PORT_PIN_DIR_OUTPUT;
994
995 /* Set config on Slave Select pin */
996 port_pin_set_config(slave->ss_pin, &pin_conf);
997 port_pin_set_output_level(slave->ss_pin, true);
998 }
999
1000 enum status_code spi_init(
1001 struct spi_module *const module,
1002 Sercom *const hw,
1003 const struct spi_config *const config);
1004
1005 /** @} */
1006
1007 /**
1008 * \name Enable/Disable
1009 * @{
1010 */
1011
1012 /**
1013 * \brief Enables the SERCOM SPI module
1014 *
1015 * This function will enable the SERCOM SPI module.
1016 *
1017 * \param[in,out] module Pointer to the software instance struct
1018 */
spi_enable(struct spi_module * const module)1019 static inline void spi_enable(
1020 struct spi_module *const module)
1021 {
1022 /* Sanity check arguments */
1023 Assert(module);
1024 Assert(module->hw);
1025
1026 SercomSpi *const spi_module = &(module->hw->SPI);
1027
1028 # if SPI_CALLBACK_MODE == true
1029 system_interrupt_enable(_sercom_get_interrupt_vector(module->hw));
1030 # endif
1031
1032 while (spi_is_syncing(module)) {
1033 /* Wait until the synchronization is complete */
1034 }
1035
1036 /* Enable SPI */
1037 spi_module->CTRLA.reg |= SERCOM_SPI_CTRLA_ENABLE;
1038 }
1039
1040 /**
1041 * \brief Disables the SERCOM SPI module
1042 *
1043 * This function will disable the SERCOM SPI module.
1044 *
1045 * \param[in,out] module Pointer to the software instance struct
1046 */
spi_disable(struct spi_module * const module)1047 static inline void spi_disable(
1048 struct spi_module *const module)
1049 {
1050 /* Sanity check arguments */
1051 Assert(module);
1052 Assert(module->hw);
1053
1054 SercomSpi *const spi_module = &(module->hw->SPI);
1055
1056 # if SPI_CALLBACK_MODE == true
1057 system_interrupt_disable(_sercom_get_interrupt_vector(module->hw));
1058 # endif
1059
1060 while (spi_is_syncing(module)) {
1061 /* Wait until the synchronization is complete */
1062 }
1063
1064 /* Disbale interrupt */
1065 spi_module->INTENCLR.reg = SERCOM_SPI_INTENCLR_MASK;
1066 /* Clear interrupt flag */
1067 spi_module->INTFLAG.reg = SERCOM_SPI_INTFLAG_MASK;
1068
1069 /* Disable SPI */
1070 spi_module->CTRLA.reg &= ~SERCOM_SPI_CTRLA_ENABLE;
1071 }
1072
1073 void spi_reset(
1074 struct spi_module *const module);
1075
1076 /** @} */
1077
1078 enum status_code spi_set_baudrate(
1079 struct spi_module *const module,
1080 uint32_t baudrate);
1081
1082 /**
1083 * \name Lock/Unlock
1084 * @{
1085 */
1086
1087 /**
1088 * \brief Attempt to get lock on driver instance
1089 *
1090 * This function checks the instance's lock, which indicates whether or not it
1091 * is currently in use, and sets the lock if it was not already set.
1092 *
1093 * The purpose of this is to enable exclusive access to driver instances, so
1094 * that, e.g., transactions by different services will not interfere with each
1095 * other.
1096 *
1097 * \param[in,out] module Pointer to the driver instance to lock
1098 *
1099 * \retval STATUS_OK If the module was locked
1100 * \retval STATUS_BUSY If the module was already locked
1101 */
spi_lock(struct spi_module * const module)1102 static inline enum status_code spi_lock(struct spi_module *const module)
1103 {
1104 enum status_code status;
1105
1106 system_interrupt_enter_critical_section();
1107
1108 if (module->locked) {
1109 status = STATUS_BUSY;
1110 } else {
1111 module->locked = true;
1112 status = STATUS_OK;
1113 }
1114
1115 system_interrupt_leave_critical_section();
1116
1117 return status;
1118 }
1119
1120 /**
1121 * \brief Unlock driver instance
1122 *
1123 * This function clears the instance lock, indicating that it is available for
1124 * use.
1125 *
1126 * \param[in,out] module Pointer to the driver instance to lock
1127 *
1128 * \retval STATUS_OK If the module was locked
1129 * \retval STATUS_BUSY If the module was already locked
1130 */
spi_unlock(struct spi_module * const module)1131 static inline void spi_unlock(struct spi_module *const module)
1132 {
1133 module->locked = false;
1134 }
1135
1136 /** @} */
1137
1138 /**
1139 * \name Ready to Write/Read
1140 * @{
1141 */
1142
1143 /**
1144 * \brief Checks if the SPI in master mode has shifted out last data, or if the master has ended the transfer in slave mode.
1145 *
1146 * This function will check if the SPI master module has shifted out last data,
1147 * or if the slave select pin has been drawn high by the master for the SPI
1148 * slave module.
1149 *
1150 * \param[in] module Pointer to the software instance struct
1151 *
1152 * \return Indication of whether any writes are ongoing.
1153 * \retval true If the SPI master module has shifted out data, or slave select
1154 * has been drawn high for SPI slave
1155 * \retval false If the SPI master module has not shifted out data
1156 */
spi_is_write_complete(struct spi_module * const module)1157 static inline bool spi_is_write_complete(
1158 struct spi_module *const module)
1159 {
1160 /* Sanity check arguments */
1161 Assert(module);
1162 Assert(module->hw);
1163
1164 SercomSpi *const spi_module = &(module->hw->SPI);
1165
1166 /* Check interrupt flag */
1167 return (spi_module->INTFLAG.reg & SERCOM_SPI_INTFLAG_TXC);
1168 }
1169
1170 /**
1171 * \brief Checks if the SPI module is ready to write data
1172 *
1173 * This function will check if the SPI module is ready to write data.
1174 *
1175 * \param[in] module Pointer to the software instance struct
1176 *
1177 * \return Indication of whether the module is ready to read data or not.
1178 * \retval true If the SPI module is ready to write data
1179 * \retval false If the SPI module is not ready to write data
1180 */
spi_is_ready_to_write(struct spi_module * const module)1181 static inline bool spi_is_ready_to_write(
1182 struct spi_module *const module)
1183 {
1184 /* Sanity check arguments */
1185 Assert(module);
1186 Assert(module->hw);
1187
1188 SercomSpi *const spi_module = &(module->hw->SPI);
1189
1190 /* Check interrupt flag */
1191 return (spi_module->INTFLAG.reg & SERCOM_SPI_INTFLAG_DRE);
1192 }
1193
1194 /**
1195 * \brief Checks if the SPI module is ready to read data
1196 *
1197 * This function will check if the SPI module is ready to read data.
1198 *
1199 * \param[in] module Pointer to the software instance struct
1200 *
1201 * \return Indication of whether the module is ready to read data or not.
1202 * \retval true If the SPI module is ready to read data
1203 * \retval false If the SPI module is not ready to read data
1204 */
spi_is_ready_to_read(struct spi_module * const module)1205 static inline bool spi_is_ready_to_read(
1206 struct spi_module *const module)
1207 {
1208 /* Sanity check arguments */
1209 Assert(module);
1210 Assert(module->hw);
1211
1212 SercomSpi *const spi_module = &(module->hw->SPI);
1213
1214 /* Check interrupt flag */
1215 return (spi_module->INTFLAG.reg & SERCOM_SPI_INTFLAG_RXC);
1216 }
1217 /** @} */
1218
1219 /**
1220 * \name Read/Write
1221 * @{
1222 */
1223
1224 /**
1225 * \brief Transfers a single SPI character
1226 *
1227 * This function will send a single SPI character via SPI and ignore any data
1228 * shifted in by the connected device. To both send and receive data, use the
1229 * \ref spi_transceive_wait function or use the \ref spi_read function after
1230 * writing a character. The \ref spi_is_ready_to_write function
1231 * should be called before calling this function.
1232 *
1233 * Note that this function does not handle the SS (Slave Select)
1234 * pin(s) in master mode; this must be handled from the user application.
1235 *
1236 * \note In slave mode, the data will not be transferred before a master
1237 * initiates a transaction.
1238 *
1239 * \param[in] module Pointer to the software instance struct
1240 * \param[in] tx_data Data to transmit
1241 *
1242 * \return Status of the procedure.
1243 * \retval STATUS_OK If the data was written
1244 * \retval STATUS_BUSY If the last write was not completed
1245 */
spi_write(struct spi_module * module,uint16_t tx_data)1246 static inline enum status_code spi_write(
1247 struct spi_module *module,
1248 uint16_t tx_data)
1249 {
1250 /* Sanity check arguments */
1251 Assert(module);
1252 Assert(module->hw);
1253
1254 SercomSpi *const spi_module = &(module->hw->SPI);
1255
1256 /* Check if the data register has been copied to the shift register */
1257 if (!spi_is_ready_to_write(module)) {
1258 /* Data register has not been copied to the shift register, return */
1259 return STATUS_BUSY;
1260 }
1261
1262 /* Write the character to the DATA register */
1263 spi_module->DATA.reg = tx_data & SERCOM_SPI_DATA_MASK;
1264
1265 return STATUS_OK;
1266 }
1267
1268 enum status_code spi_write_buffer_wait(
1269 struct spi_module *const module,
1270 const uint8_t *tx_data,
1271 uint16_t length);
1272
1273 /**
1274 * \brief Reads last received SPI character
1275 *
1276 * This function will return the last SPI character shifted into the receive
1277 * register by the \ref spi_write function.
1278 *
1279 * \note The \ref spi_is_ready_to_read function should be called before calling
1280 * this function.
1281 *
1282 * \note Receiver must be enabled in the configuration.
1283 *
1284 * \param[in] module Pointer to the software instance struct
1285 * \param[out] rx_data Pointer to store the received data
1286 *
1287 * \returns Status of the read operation.
1288 * \retval STATUS_OK If data was read
1289 * \retval STATUS_ERR_IO If no data is available
1290 * \retval STATUS_ERR_OVERFLOW If the data is overflown
1291 */
spi_read(struct spi_module * const module,uint16_t * rx_data)1292 static inline enum status_code spi_read(
1293 struct spi_module *const module,
1294 uint16_t *rx_data)
1295 {
1296 /* Sanity check arguments */
1297 Assert(module);
1298 Assert(module->hw);
1299
1300 SercomSpi *const spi_module = &(module->hw->SPI);
1301
1302 /* Check if data is ready to be read */
1303 if (!spi_is_ready_to_read(module)) {
1304 /* No data has been received, return */
1305 return STATUS_ERR_IO;
1306 }
1307
1308 /* Return value */
1309 enum status_code retval = STATUS_OK;
1310
1311 /* Check if data is overflown */
1312 if (spi_module->STATUS.reg & SERCOM_SPI_STATUS_BUFOVF) {
1313 retval = STATUS_ERR_OVERFLOW;
1314 /* Clear overflow flag */
1315 spi_module->STATUS.reg = SERCOM_SPI_STATUS_BUFOVF;
1316 }
1317
1318 /* Read the character from the DATA register */
1319 if (module->character_size == SPI_CHARACTER_SIZE_9BIT) {
1320 *rx_data = (spi_module->DATA.reg & SERCOM_SPI_DATA_MASK);
1321 } else {
1322 *rx_data = (uint8_t)spi_module->DATA.reg;
1323 }
1324
1325 return retval;
1326 }
1327
1328 enum status_code spi_read_buffer_wait(
1329 struct spi_module *const module,
1330 uint8_t *rx_data,
1331 uint16_t length,
1332 uint16_t dummy);
1333
1334 enum status_code spi_transceive_wait(
1335 struct spi_module *const module,
1336 uint16_t tx_data,
1337 uint16_t *rx_data);
1338
1339 enum status_code spi_transceive_buffer_wait(
1340 struct spi_module *const module,
1341 uint8_t *tx_data,
1342 uint8_t *rx_data,
1343 uint16_t length);
1344
1345 enum status_code spi_select_slave(
1346 struct spi_module *const module,
1347 struct spi_slave_inst *const slave,
1348 bool select);
1349
1350 /** @} */
1351
1352 #ifdef __cplusplus
1353 }
1354 #endif
1355
1356 /** @} */
1357
1358
1359 /**
1360 * \page asfdoc_sam0_sercom_spi_extra Extra Information for SERCOM SPI Driver
1361 *
1362 * \section asfdoc_sam0_sercom_spi_extra_acronyms Acronyms
1363 * Below is a table listing the acronyms used in this module, along with their
1364 * intended meanings.
1365 *
1366 * <table>
1367 * <tr>
1368 * <th>Acronym</th>
1369 * <th>Description</th>
1370 * </tr>
1371 * <tr>
1372 * <td>SERCOM</td>
1373 * <td>Serial Communication Interface</td>
1374 * </tr>
1375 * <tr>
1376 * <td>SPI</td>
1377 * <td>Serial Peripheral Interface</td>
1378 * </tr>
1379 * <tr>
1380 * <td>SCK</td>
1381 * <td>Serial Clock</td>
1382 * </tr>
1383 * <tr>
1384 * <td>MOSI</td>
1385 * <td>Master Output Slave Input</td>
1386 * </tr>
1387 * <tr>
1388 * <td>MISO</td>
1389 * <td>Master Input Slave Output</td>
1390 * </tr>
1391 * <tr>
1392 * <td>SS</td>
1393 * <td>Slave Select</td>
1394 * </tr>
1395 * <tr>
1396 * <td>DIO</td>
1397 * <td>Data Input Output</td>
1398 * </tr>
1399 * <tr>
1400 * <td>DO</td>
1401 * <td>Data Output</td>
1402 * </tr>
1403 * <tr>
1404 * <td>DI</td>
1405 * <td>Data Input</td>
1406 * </tr>
1407 * <tr>
1408 * <td>DMA</td>
1409 * <td>Direct Memory Access</td>
1410 * </tr>
1411 * </table>
1412 *
1413 * \section asfdoc_sam0_sercom_spi_extra_dependencies Dependencies
1414 * The SPI driver has the following dependencies:
1415 * \li \ref asfdoc_sam0_system_pinmux_group "System Pin Multiplexer Driver"
1416 *
1417 *
1418 * \section asfdoc_sam0_sercom_spi_extra_workarounds Workarounds Implemented by Driver
1419 * No workarounds in driver.
1420 *
1421 * \section asfdoc_sam0_sercom_spi_extra_history Module History
1422 * An overview of the module history is presented in the table below, with
1423 * details on the enhancements and fixes made to the module since its first
1424 * release. The current version of this corresponds to the newest version in the table.
1425 *
1426 * <table>
1427 * <tr>
1428 * <th>Changelog</th>
1429 * </tr>
1430 * <tr>
1431 * <td>Added new features as below:
1432 * \li Slave select low detect
1433 * \li Hardware slave select
1434 * \li DMA support </td>
1435 * </tr>
1436 * <tr>
1437 * <td>Edited slave part of write and transceive buffer functions to ensure
1438 * that second character is sent at the right time</td>
1439 * </tr>
1440 * <tr>
1441 * <td>Renamed the anonymous union in \c struct spi_config to
1442 * \c mode_specific</td>
1443 * </tr>
1444 * <tr>
1445 * <td>Initial Release</td>
1446 * </tr>
1447 * </table>
1448 */
1449
1450 /**
1451 * \page asfdoc_sam0_sercom_spi_exqsg Examples for SERCOM SPI Driver
1452 *
1453 * This is a list of the available Quick Start guides (QSGs) and example
1454 * applications for \ref asfdoc_sam0_sercom_spi_group. QSGs are simple examples with
1455 * step-by-step instructions to configure and use this driver in a selection of
1456 * use cases. Note that a QSG can be compiled as a standalone application or be
1457 * added to the user application.
1458 *
1459 * - \subpage asfdoc_sam0_sercom_spi_master_basic_use
1460 * - \subpage asfdoc_sam0_sercom_spi_slave_basic_use
1461 * \if SPI_CALLBACK_MODE
1462 * - \subpage asfdoc_sam0_sercom_spi_master_callback_use
1463 * - \subpage asfdoc_sam0_sercom_spi_slave_callback_use
1464 * \endif
1465 * - \subpage asfdoc_sam0_sercom_spi_dma_use_case
1466 */
1467
1468 /**
1469 * \page asfdoc_sam0_sercom_spi_mux_settings MUX Settings
1470 *
1471 * The following lists the possible internal SERCOM module pad function
1472 * assignments for the four SERCOM pads in both SPI Master and SPI Slave
1473 * modes. They are combinations of DOPO and DIPO in CTRLA.
1474 * Note that this is in addition to the physical GPIO pin MUX of the device,
1475 * and can be used in conjunction to optimize the serial data pin-out.
1476 *
1477 * \section asfdoc_sam0_sercom_spi_mux_settings_master Master Mode Settings
1478 * The following table describes the SERCOM pin functionalities for the various
1479 * MUX settings, whilst in SPI Master mode.
1480 *
1481 * \note If MISO is unlisted, the SPI receiver must not be enabled for the
1482 * given MUX setting.
1483 *
1484 * <table>
1485 * <tr>
1486 * <th>Combination</th>
1487 * <th>DOPO / DIPO</th>
1488 * <th>SERCOM PAD[0]</th>
1489 * <th>SERCOM PAD[1]</th>
1490 * <th>SERCOM PAD[2]</th>
1491 * <th>SERCOM PAD[3]</th>
1492 * </tr>
1493 * <tr>
1494 * <td>A</td>
1495 * <td>0x0 / 0x0</td>
1496 * <td>MOSI</td>
1497 * <td>SCK</td>
1498 * <td>-</td>
1499 * <td>-</td>
1500 * </tr>
1501 * <tr>
1502 * <td>B</td>
1503 * <td>0x0 / 0x1</td>
1504 * <td>MOSI</td>
1505 * <td>SCK</td>
1506 * <td>-</td>
1507 * <td>-</td>
1508 * </tr>
1509 * <tr>
1510 * <td>C</td>
1511 * <td>0x0 / 0x2</td>
1512 * <td>MOSI</td>
1513 * <td>SCK</td>
1514 * <td>MISO</td>
1515 * <td>-</td>
1516 * </tr>
1517 * <tr>
1518 * <td>D</td>
1519 * <td>0x0 / 0x3</td>
1520 * <td>MOSI</td>
1521 * <td>SCK</td>
1522 * <td>-</td>
1523 * <td>MISO</td>
1524 * </tr>
1525 * <tr>
1526 * <td>E</td>
1527 * <td>0x1 / 0x0</td>
1528 * <td>MISO</td>
1529 * <td>-</td>
1530 * <td>MOSI</td>
1531 * <td>SCK</td>
1532 * </tr>
1533 * <tr>
1534 * <td>F</td>
1535 * <td>0x1 / 0x1</td>
1536 * <td>-</td>
1537 * <td>MISO</td>
1538 * <td>MOSI</td>
1539 * <td>SCK</td>
1540 * </tr>
1541 * <tr>
1542 * <td>G</td>
1543 * <td>0x1 / 0x2</td>
1544 * <td>-</td>
1545 * <td>-</td>
1546 * <td>MOSI</td>
1547 * <td>SCK</td>
1548 * </tr>
1549 * <tr>
1550 * <td>H</td>
1551 * <td>0x1 / 0x3</td>
1552 * <td>-</td>
1553 * <td>-</td>
1554 * <td>MOSI</td>
1555 * <td>SCK</td>
1556 * </tr>
1557 * <tr>
1558 * <td>I</td>
1559 * <td>0x2 / 0x0</td>
1560 * <td>MISO</td>
1561 * <td>SCK</td>
1562 * <td>-</td>
1563 * <td>MOSI</td>
1564 * </tr>
1565 * <tr>
1566 * <td>J</td>
1567 * <td>0x2 / 0x1</td>
1568 * <td>-</td>
1569 * <td>SCK</td>
1570 * <td>-</td>
1571 * <td>MOSI</td>
1572 * </tr>
1573 * <tr>
1574 * <td>K</td>
1575 * <td>0x2 / 0x2</td>
1576 * <td>-</td>
1577 * <td>SCK</td>
1578 * <td>MISO</td>
1579 * <td>MOSI</td>
1580 * </tr>
1581 * <tr>
1582 * <td>L</td>
1583 * <td>0x2 / 0x3</td>
1584 * <td>-</td>
1585 * <td>SCK</td>
1586 * <td>-</td>
1587 * <td>MOSI</td>
1588 * </tr>
1589 * <tr>
1590 * <td>M</td>
1591 * <td>0x3 / 0x0</td>
1592 * <td>MOSI</td>
1593 * <td>-</td>
1594 * <td>-</td>
1595 * <td>SCK</td>
1596 * </tr>
1597 * <tr>
1598 * <td>N</td>
1599 * <td>0x3 / 0x1</td>
1600 * <td>MOSI</td>
1601 * <td>MISO</td>
1602 * <td>-</td>
1603 * <td>SCK</td>
1604 * </tr>
1605 * <tr>
1606 * <td>O</td>
1607 * <td>0x3 / 0x2</td>
1608 * <td>MOSI</td>
1609 * <td>-</td>
1610 * <td>MISO</td>
1611 * <td>SCK</td>
1612 * </tr>
1613 * <tr>
1614 * <td>P</td>
1615 * <td>0x3 / 0x3</td>
1616 * <td>MOSI</td>
1617 * <td>-</td>
1618 * <td>-</td>
1619 * <td>SCK</td>
1620 * </tr>
1621 * </table>
1622 *
1623 *
1624 * \section asfdoc_sam0_sercom_spi_mux_settings_slave Slave Mode Settings
1625 * The following table describes the SERCOM pin functionalities for the various
1626 * MUX settings, whilst in SPI Slave mode.
1627 *
1628 * \note If MISO is unlisted, the SPI receiver must not be enabled for the
1629 * given MUX setting.
1630 *
1631 * <table>
1632 * <tr>
1633 * <th>Combination</th>
1634 * <th>DOPO / DIPO</th>
1635 * <th>SERCOM PAD[0]</th>
1636 * <th>SERCOM PAD[1]</th>
1637 * <th>SERCOM PAD[2]</th>
1638 * <th>SERCOM PAD[3]</th>
1639 * </tr>
1640 * <tr>
1641 * <td>A</td>
1642 * <td>0x0 / 0x0</td>
1643 * <td>MISO</td>
1644 * <td>SCK</td>
1645 * <td>/SS</td>
1646 * <td>-</td>
1647 * </tr>
1648 * <tr>
1649 * <td>B</td>
1650 * <td>0x0 / 0x1</td>
1651 * <td>MISO</td>
1652 * <td>SCK</td>
1653 * <td>/SS</td>
1654 * <td>-</td>
1655 * </tr>
1656 * <tr>
1657 * <td>C</td>
1658 * <td>0x0 / 0x2</td>
1659 * <td>MISO</td>
1660 * <td>SCK</td>
1661 * <td>/SS</td>
1662 * <td>-</td>
1663 * </tr>
1664 * <tr>
1665 * <td>D</td>
1666 * <td>0x0 / 0x3</td>
1667 * <td>MISO</td>
1668 * <td>SCK</td>
1669 * <td>/SS</td>
1670 * <td>MOSI</td>
1671 * </tr>
1672 * <tr>
1673 * <td>E</td>
1674 * <td>0x1 / 0x0</td>
1675 * <td>MOSI</td>
1676 * <td>/SS</td>
1677 * <td>MISO</td>
1678 * <td>SCK</td>
1679 * </tr>
1680 * <tr>
1681 * <td>F</td>
1682 * <td>0x1 / 0x1</td>
1683 * <td>-</td>
1684 * <td>/SS</td>
1685 * <td>MISO</td>
1686 * <td>SCK</td>
1687 * </tr>
1688 * <tr>
1689 * <td>G</td>
1690 * <td>0x1 / 0x2</td>
1691 * <td>-</td>
1692 * <td>/SS</td>
1693 * <td>MISO</td>
1694 * <td>SCK</td>
1695 * </tr>
1696 * <tr>
1697 * <td>H</td>
1698 * <td>0x1 / 0x3</td>
1699 * <td>-</td>
1700 * <td>/SS</td>
1701 * <td>MISO</td>
1702 * <td>SCK</td>
1703 * </tr>
1704 * <tr>
1705 * <td>I</td>
1706 * <td>0x2 / 0x0</td>
1707 * <td>MOSI</td>
1708 * <td>SCK</td>
1709 * <td>/SS</td>
1710 * <td>MISO</td>
1711 * </tr>
1712 * <tr>
1713 * <td>J</td>
1714 * <td>0x2 / 0x1</td>
1715 * <td>-</td>
1716 * <td>SCK</td>
1717 * <td>/SS</td>
1718 * <td>MISO</td>
1719 * </tr>
1720 * <tr>
1721 * <td>K</td>
1722 * <td>0x2 / 0x2</td>
1723 * <td>-</td>
1724 * <td>SCK</td>
1725 * <td>/SS</td>
1726 * <td>MISO</td>
1727 * </tr>
1728 * <tr>
1729 * <td>L</td>
1730 * <td>0x2 / 0x3</td>
1731 * <td>-</td>
1732 * <td>SCK</td>
1733 * <td>/SS</td>
1734 * <td>MISO</td>
1735 * </tr>
1736 * <tr>
1737 * <td>M</td>
1738 * <td>0x3 / 0x0</td>
1739 * <td>MISO</td>
1740 * <td>/SS</td>
1741 * <td>-</td>
1742 * <td>SCK</td>
1743 * </tr>
1744 * <tr>
1745 * <td>N</td>
1746 * <td>0x3 / 0x1</td>
1747 * <td>MISO</td>
1748 * <td>/SS</td>
1749 * <td>-</td>
1750 * <td>SCK</td>
1751 * </tr>
1752 * <tr>
1753 * <td>O</td>
1754 * <td>0x3 / 0x2</td>
1755 * <td>MISO</td>
1756 * <td>/SS</td>
1757 * <td>MOSI</td>
1758 * <td>SCK</td>
1759 * </tr>
1760 * <tr>
1761 * <td>P</td>
1762 * <td>0x3 / 0x3</td>
1763 * <td>MISO</td>
1764 * <td>/SS</td>
1765 * <td>-</td>
1766 * <td>SCK</td>
1767 * </tr>
1768 * </table>
1769 *
1770 *
1771 *
1772 * \page asfdoc_sam0_sercom_spi_document_revision_history Document Revision History
1773 *
1774 * <table>
1775 * <tr>
1776 * <th>Doc. Rev.</th>
1777 * <th>Date</th>
1778 * <th>Comments</th>
1779 * </tr>
1780 * <tr>
1781 * <td>42115E</td>
1782 * <td>12/2015</td>
1783 * <td>Add SAM L21/L22, SAM DA1, SAM D09, SAMR30 and SAM C21 support</td>
1784 * </tr>
1785 * <tr>
1786 * <td>42115D</td>
1787 * <td>12/2014</td>
1788 * <td>Add SAM R21/D10/D11 support</td>
1789 * </tr>
1790 * <tr>
1791 * <td>42115C</td>
1792 * <td>01/2014</td>
1793 * <td>Add SAM D21 support</td>
1794 * </tr>
1795 * <tr>
1796 * <td>42115B</td>
1797 * <td>11/2013</td>
1798 * <td>Replaced the pad multiplexing documentation with a condensed table</td>
1799 * </tr>
1800 * <tr>
1801 * <td>42115A</td>
1802 * <td>06/2013</td>
1803 * <td>Initial release</td>
1804 * </tr>
1805 * </table>
1806 */
1807
1808 #endif /* SPI_H_INCLUDED */
1809