1 /** 2 * \file 3 * 4 * \brief SAM Serial Peripheral Interface Driver for SAMB 5 * 6 * Copyright (C) 2015-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_samb_drivers_spi_group SAM Serial Peripheral Interface (SPI) Driver 52 * 53 * This driver for Atmel® | SMART ARM-based microcontrollers provides 54 * an interface for the configuration and management of the 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 * - SPI (Serial Peripheral Interface) 65 * 66 * The following devices can use this module: 67 * - Atmel | SMART SAM B11 68 * 69 * The outline of this documentation is as follows: 70 * - \ref asfdoc_samb_drivers_spi_prerequisites 71 * - \ref asfdoc_samb_drivers_spi_module_overview 72 * - \ref asfdoc_samb_drivers_spi_special_considerations 73 * - \ref asfdoc_samb_drivers_spi_extra_info 74 * - \ref asfdoc_samb_drivers_spi_examples 75 * - \ref asfdoc_samb_drivers_spi_api_overview 76 * 77 * \section asfdoc_samb_drivers_spi_prerequisites Prerequisites 78 * There are no prerequisites for this module. 79 * 80 * 81 * \section asfdoc_samb_drivers_spi_module_overview Module Overview 82 * \subsection asfdoc_samb_drivers_spi_bus SPI Bus Connection 83 * In \ref asfdoc_sam0_spi_connection_example "the figure below", the 84 * connection between one master and one slave is shown. 85 * 86 * \anchor asfdoc_sam0_spi_connection_example 87 * \image html spi_block_diagram.svg "SPI Block Diagram" 88 * 89 * The different lines are as follows: 90 * - \b MISO Master Input Slave Output. The line where the data is shifted 91 * out from the slave and into the master. 92 * - \b MOSI Master Output Slave Input. The line where the data is shifted 93 * out from the master and into the slave. 94 * - \b SCK Serial Clock. Generated by the master device. 95 * - \b SS Slave Select. To initiate a transaction, the master must pull this 96 * line low. 97 * 98 * If the bus consists of several SPI slaves, they can be connected in parallel 99 * and the SPI master can use general I/O pins to control separate SS lines to 100 * each slave on the bus. 101 * 102 * It is also possible to connect all slaves in series. In this configuration, 103 * a common SS is provided to \c N slaves, enabling them simultaneously. The 104 * MISO from the \c N-1 slaves is connected to the MOSI on the next slave. The 105 * \c N<SUP>th</SUP> slave connects its MISO back to the master. For a 106 * complete transaction, the master must shift \c N+1 characters. 107 * 108 * \subsection asfdoc_samb_drivers_spi_chsize SPI Character Size 109 * The SPI character size is configurable to eight bits. 110 * 111 * \subsection asfdoc_samb_drivers_spi_master_mode Master Mode 112 * When configured as a master, the SS pin will be configured as an output. 113 * 114 * \subsubsection asfdoc_samb_drivers_spi_master_mode_data_transfer Data Transfer 115 * Writing a character will start the SPI clock generator, and 116 * the character is transferred to the shift register when the shift 117 * register is empty. 118 * Once this is done, a new character can be written. 119 * As each character is shifted out from the master, a character is shifted in 120 * from the slave. If the receiver is enabled, the data is moved to the receive 121 * buffer at the completion of the frame and can be read. 122 * 123 * \subsection asfdoc_samb_drivers_spi_slave_mode Slave Mode 124 * When configured as a slave, the SPI interface will remain inactive with MISO 125 * tri-stated as long as the SS pin is driven high. 126 * 127 * \subsubsection asfdoc_samb_drivers_spi_slave_mode_data_transfer_slave Data Transfer 128 * The data register can be updated at any time. 129 * As the SPI slave shift register is clocked by SCK, a minimum of three SCK 130 * cycles are needed from the time new data is written, until the character is 131 * ready to be shifted out. If the shift register has not been loaded with 132 * data, the current contents will be transmitted. 133 * 134 * If constant transmission of data is needed in SPI slave mode, the system 135 * clock should be faster than SCK. 136 * 137 * \subsection asfdoc_samb_drivers_spi_data_modes Data Modes 138 * There are four combinations of SCK phase and polarity with respect to 139 * serial data. \ref asfdoc_samb_drivers_spi_mode_table "The table below" shows the 140 * clock polarity (CPOL) and clock phase (CPHA) in the different modes. 141 * <i>Leading edge</i> is the first clock edge in a clock cycle and 142 * <i>trailing edge</i> is the last clock edge in a clock cycle. 143 * 144 * \anchor asfdoc_samb_drivers_spi_mode_table 145 * <table> 146 * <caption>SPI Data Modes</caption> 147 * <tr> 148 * <th>Mode</th> 149 * <th>CPOL</th> 150 * <th>CPHA</th> 151 * <th>Leading Edge</th> 152 * <th>Trailing Edge</th> 153 * </tr> 154 * <tr> 155 * <td> 0 </td> 156 * <td> 0 </td> 157 * <td> 0 </td> 158 * <td> Rising, Sample </td> 159 * <td> Falling, Setup </td> 160 * </tr> 161 * <tr> 162 * <td> 1 </td> 163 * <td> 0 </td> 164 * <td> 1 </td> 165 * <td> Rising, Setup </td> 166 * <td> Falling, Sample </td> 167 * </tr> 168 * <tr> 169 * <td> 2 </td> 170 * <td> 1 </td> 171 * <td> 0 </td> 172 * <td> Falling, Sample </td> 173 * <td> Rising, Setup </td> 174 * </tr> 175 * <tr> 176 * <td> 3 </td> 177 * <td> 1 </td> 178 * <td> 1 </td> 179 * <td> Falling, Setup </td> 180 * <td> Rising, Sample </td> 181 * </tr> 182 * </table> 183 * 184 * \section asfdoc_samb_drivers_spi_special_considerations Special Considerations 185 * The pin MUX settings must be configured properly, as not all settings 186 * can be used in different modes of operation. 187 * 188 * \section asfdoc_samb_drivers_spi_extra_info Extra Information 189 * 190 * For extra information, see \ref asfdoc_samb_drivers_spi_extra. This includes: 191 * - \ref asfdoc_samb_drivers_spi_extra_acronyms 192 * - \ref asfdoc_samb_drivers_spi_extra_dependencies 193 * - \ref asfdoc_samb_drivers_spi_extra_errata 194 * - \ref asfdoc_samb_drivers_spi_extra_history 195 * 196 * \section asfdoc_samb_drivers_spi_examples Examples 197 * 198 * For a list of examples related to this driver, see 199 * \ref asfdoc_samb_drivers_spi_exqsg. 200 * 201 * \section asfdoc_samb_drivers_spi_api_overview API Overview 202 * @{ 203 */ 204 205 #include <stdint.h> 206 #include <string.h> 207 #include <compiler.h> 208 #include <conf_spi.h> 209 #include <gpio.h> 210 #include <system_sam_b.h> 211 212 #ifdef __cplusplus 213 extern "C" { 214 #endif 215 216 #if (CONF_SPI_MASTER_ENABLE == false) && (CONF_SPI_SLAVE_ENABLE == false) 217 #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." 218 #endif 219 220 # ifndef SPI_TIMEOUT 221 /** SPI timeout value */ 222 # define SPI_TIMEOUT 10000 223 # endif 224 225 # ifndef PINMUX_UNUSED 226 /** Unused pinmux. */ 227 # define PINMUX_UNUSED 0xFFFFFFFF 228 # endif 229 230 # if SPI_CALLBACK_MODE == true 231 /** Prototype for the device instance. */ 232 struct spi_module; 233 /** Type of the callback functions */ 234 typedef void (*spi_callback_t)(struct spi_module *const module); 235 236 /** 237 * \brief SPI Callback enum 238 * 239 * Callbacks for SPI callback driver. 240 * 241 * \note For slave mode, these callbacks will be called when a transaction 242 * is ended by the master pulling Slave Select high. 243 * 244 */ 245 enum spi_callback { 246 /** Callback for buffer transmitted */ 247 SPI_CALLBACK_BUFFER_TRANSMITTED, 248 /** Callback for buffer received */ 249 SPI_CALLBACK_BUFFER_RECEIVED, 250 /** Callback for buffers transceived */ 251 SPI_CALLBACK_BUFFER_TRANSCEIVED, 252 /** Callback for error */ 253 SPI_CALLBACK_ERROR, 254 # if !defined(__DOXYGEN__) 255 /** Number of available callbacks */ 256 SPI_CALLBACK_N, 257 # endif 258 }; 259 260 # if !defined(__DOXYGEN__) 261 /** Prototype for the interrupt handler */ 262 extern struct spi_module *_spi_instances[SPI_INST_NUM]; 263 extern void spi_rx0_isr_handler(void); 264 extern void spi_tx0_isr_handler(void); 265 extern void spi_rx1_isr_handler(void); 266 extern void spi_tx1_isr_handler(void); 267 /** 268 * \brief SPI transfer directions 269 */ 270 enum _spi_direction { 271 /** Transfer direction is read. */ 272 SPI_DIRECTION_READ, 273 /** Transfer direction is write. */ 274 SPI_DIRECTION_WRITE, 275 /** Transfer direction is read and write. */ 276 SPI_DIRECTION_BOTH, 277 /** No transfer. */ 278 SPI_DIRECTION_IDLE, 279 }; 280 # endif 281 # endif 282 283 /** 284 * \brief SPI transfer modes enum 285 * 286 * SPI transfer mode. 287 */ 288 enum spi_transfer_mode { 289 /** Mode 0. Leading edge: rising, sample. Trailing edge: falling, setup */ 290 SPI_TRANSFER_MODE_0 = 0, 291 /** Mode 1. Leading edge: rising, setup. Trailing edge: falling, sample */ 292 SPI_TRANSFER_MODE_1 = SPI_CONFIGURATION_SCK_PHASE_1, 293 /** Mode 2. Leading edge: falling, sample. Trailing edge: rising, setup */ 294 SPI_TRANSFER_MODE_2 = SPI_CONFIGURATION_SCK_POLARITY_1, 295 /** Mode 3. Leading edge: falling, setup. Trailing edge: rising, sample */ 296 SPI_TRANSFER_MODE_3 = SPI_CONFIGURATION_SCK_PHASE_1 | \ 297 SPI_CONFIGURATION_SCK_POLARITY_1, 298 }; 299 300 /** 301 * \brief SPI modes enum 302 * 303 * SPI mode selection. 304 */ 305 enum spi_mode { 306 /** Master mode */ 307 SPI_MODE_MASTER = 1, 308 /** Slave mode */ 309 SPI_MODE_SLAVE = 0, 310 }; 311 312 /** 313 * \brief SPI data order enum 314 * 315 * SPI data order. 316 * 317 */ 318 enum spi_data_order { 319 /** The MSB of the data is transmitted first */ 320 SPI_DATA_ORDER_MSB = 0, 321 /** The LSB of the data is transmitted first */ 322 SPI_DATA_ORDER_LSB = SPI_CONFIGURATION_LSB_FIRST_ENABLE_1, 323 }; 324 325 /** 326 * \brief SPI module clock input 327 * 328 * SPI module clock. 329 * 330 */ 331 enum spi_clock_input { 332 /** source from clock input 0 26MHz*/ 333 SPI_CLK_INPUT_0 = 0, 334 /** source from clock input 1 13MHz */ 335 SPI_CLK_INPUT_1, 336 /** source from clock input 2 6.5MHz*/ 337 SPI_CLK_INPUT_2, 338 /** source from clock input 3 3MHz*/ 339 SPI_CLK_INPUT_3, 340 }; 341 342 /** 343 * \brief SPI driver software device instance structure. 344 * 345 * SPI driver software instance structure, used to retain software state 346 * information of an associated hardware module instance. 347 * 348 * \note The fields of this structure should not be altered by the user 349 * application; they are reserved for module-internal use only. 350 */ 351 struct spi_module { 352 # if !defined(__DOXYGEN__) 353 /** Hardware module */ 354 Spi *hw; 355 /** Module lock */ 356 volatile uint8_t locked; 357 /** SPI mode */ 358 enum spi_mode mode; 359 /** Transmit dummy data when receiving*/ 360 uint8_t tx_dummy_byte; 361 #if SPI_CALLBACK_MODE == true 362 /** Direction of transaction */ 363 volatile enum _spi_direction dir; 364 /** Array to store callback function pointers in */ 365 spi_callback_t callback[SPI_CALLBACK_N]; 366 /** Buffer pointer to where the next received character will be put */ 367 volatile uint8_t *rx_buffer_ptr; 368 /** Buffer pointer to where the next character will be transmitted from 369 **/ 370 volatile uint8_t *tx_buffer_ptr; 371 /** Remaining characters to receive */ 372 volatile uint16_t remaining_rx_buffer_length; 373 /** Remaining dummy characters to send when reading */ 374 volatile uint16_t remaining_dummy_buffer_length; 375 /** Remaining characters to transmit */ 376 volatile uint16_t remaining_tx_buffer_length; 377 /** Bit mask for callbacks registered */ 378 uint8_t registered_callback; 379 /** Bit mask for callbacks enabled */ 380 uint8_t enabled_callback; 381 /** Holds the status of the ongoing or last operation */ 382 volatile enum status_code status; 383 # endif 384 # endif 385 }; 386 387 /** 388 * \brief SPI peripheral slave instance structure 389 * 390 * SPI peripheral slave software instance structure, used to configure the 391 * correct SPI transfer mode settings for an attached slave. See 392 * \ref spi_select_slave. 393 */ 394 struct spi_slave_inst { 395 /** Pin to use as Slave Select */ 396 uint8_t ss_pin; 397 /** Address recognition enabled in slave device */ 398 uint8_t address_enabled; 399 /** Address of slave device */ 400 uint8_t address; 401 }; 402 403 /** 404 * \brief SPI peripheral slave configuration structure 405 * 406 * SPI Peripheral slave configuration structure 407 */ 408 struct spi_slave_inst_config { 409 /** Pin to use as Slave Select */ 410 uint8_t ss_pin; 411 /** Enable address */ 412 bool address_enabled; 413 /** Address of slave */ 414 uint8_t address; 415 }; 416 417 /** 418 * \brief SPI configuration structure 419 * 420 * Configuration structure for an SPI instance. This structure should be 421 * initialized by the \ref spi_get_config_defaults function before being 422 * modified by the user application. 423 */ 424 struct spi_config { 425 /** SPI mode */ 426 enum spi_mode mode; 427 /** Data order */ 428 enum spi_data_order data_order; 429 /** Transfer mode */ 430 enum spi_transfer_mode transfer_mode; 431 /** clock source to use */ 432 enum spi_clock_input clock_source; 433 /** clock divider value to use*/ 434 uint8_t clock_divider; 435 /** SPI PAD pin number */ 436 uint32_t pin_number_pad[4]; 437 /** SPI PAD pinmux selection */ 438 uint32_t pinmux_sel_pad[4]; 439 }; 440 441 /** 442 * \name Initialization functions 443 * @{ 444 */ 445 446 enum status_code spi_init( 447 struct spi_module *const module, 448 Spi *const hw, 449 const struct spi_config *const config); 450 451 void spi_reset(struct spi_module *const module); 452 453 void spi_slave_inst_get_config_defaults( 454 struct spi_slave_inst_config *const config); 455 456 void spi_get_config_defaults(struct spi_config *const config); 457 458 void spi_attach_slave( 459 struct spi_slave_inst *const slave, 460 struct spi_slave_inst_config *const config); 461 462 /** @} */ 463 464 /** 465 * \name Enable/Disable 466 * @{ 467 */ 468 469 void spi_enable(struct spi_module *const module); 470 void spi_disable(struct spi_module *const module); 471 472 /** @} */ 473 474 /** 475 * \name Lock/Unlock 476 * @{ 477 */ 478 479 enum status_code spi_lock(struct spi_module *const module); 480 void spi_unlock(struct spi_module *const module); 481 482 /** @} */ 483 484 485 /** 486 * \name Read/Write 487 * @{ 488 */ 489 490 enum status_code spi_write( 491 struct spi_module *module, 492 uint8_t tx_data); 493 494 enum status_code spi_write_buffer_wait( 495 struct spi_module *const module, 496 uint8_t *tx_data, 497 uint16_t length); 498 499 enum status_code spi_read( 500 struct spi_module *const module, 501 uint8_t *rx_data); 502 503 enum status_code spi_read_buffer_wait( 504 struct spi_module *const module, 505 uint8_t *rx_data, 506 uint16_t length, 507 uint8_t dummy); 508 509 enum status_code spi_transceive_wait( 510 struct spi_module *const module, 511 uint8_t *tx_data, 512 uint8_t *rx_data); 513 514 enum status_code spi_transceive_buffer_wait( 515 struct spi_module *const module, 516 uint8_t *tx_data, 517 uint8_t *rx_data, 518 uint16_t length); 519 520 enum status_code spi_select_slave( 521 struct spi_module *const module, 522 struct spi_slave_inst *const slave, 523 bool select); 524 525 /** @} */ 526 527 /** @}*/ 528 529 #ifdef __cplusplus 530 } 531 #endif 532 533 /** 534 * \page asfdoc_samb_drivers_spi_extra Extra Information for SPI Driver 535 * 536 * \section asfdoc_samb_drivers_spi_extra_acronyms Acronyms 537 * The table below presents the acronyms used in this module: 538 * 539 * <table> 540 * <tr> 541 * <th>Acronym</th> 542 * <th>Description</th> 543 * </tr> 544 * <tr> 545 * <td>SPI</td> 546 * <td>Serial Peripheral Interface</td> 547 * </tr> 548 * <tr> 549 * <td>SCK</td> 550 * <td>Serial Clock</td> 551 * </tr> 552 * <tr> 553 * <td>MOSI</td> 554 * <td>Master Output Slave Input</td> 555 * </tr> 556 * <tr> 557 * <td>MISO</td> 558 * <td>Master Input Slave Output</td> 559 * </tr> 560 * <tr> 561 * <td>SS</td> 562 * <td>Slave Select</td> 563 * </tr> 564 * </table> 565 * 566 * \section asfdoc_samb_drivers_spi_extra_dependencies Dependencies 567 * There are no dependencies related to this driver. 568 * 569 * 570 * \section asfdoc_samb_drivers_spi_extra_errata Errata 571 * There are no errata related to this driver. 572 * 573 * \section asfdoc_samb_drivers_spi_extra_history Module History 574 * An overview of the module history is presented in the table below, with 575 * details on the enhancements and fixes made to the module since its first 576 * release. The current version of this corresponds to the newest version in 577 * the table. 578 * 579 * <table> 580 * <tr> 581 * <th>Changelog</th> 582 * </tr> 583 * <tr> 584 * <td>Initial Release</td> 585 * </tr> 586 * </table> 587 */ 588 589 /** 590 * \page asfdoc_samb_drivers_spi_exqsg Examples for SPI Driver 591 * 592 * This is a list of the available Quick Start guides (QSGs) and example 593 * applications for \ref asfdoc_samb_drivers_spi_group. QSGs are simple examples with 594 * step-by-step instructions to configure and use this driver in a selection of 595 * use cases. Note that QSGs can be compiled as a standalone application or be 596 * added to the user application. 597 * 598 * - \subpage asfdoc_samb_spi_master_basic_use 599 * - \subpage asfdoc_samb_spi_slave_basic_use 600 * \if SPI_CALLBACK_MODE 601 * - \subpage asfdoc_samb_spi_master_callback_use 602 * - \subpage asfdoc_samb_spi_slave_callback_use 603 * \endif 604 */ 605 606 /** 607 * 608 * \page asfdoc_samb_drivers_spi_document_revision_history Document Revision History 609 * 610 * <table> 611 * <tr> 612 * <th>Doc. Rev.</td> 613 * <th>Date</td> 614 * <th>Comments</td> 615 * </tr> 616 * <tr> 617 * <td>A</td> 618 * <td>09/2015</td> 619 * <td>Initial release</td> 620 * </tr> 621 * </table> 622 */ 623 624 #endif //SPI_H_INCLUDED 625 626