1 /** 2 * @file 3 * @brief Serial Peripheral Interface (SPI) communications driver. 4 */ 5 6 /****************************************************************************** 7 * 8 * Copyright (C) 2022-2023 Maxim Integrated Products, Inc. (now owned by 9 * Analog Devices, Inc.), 10 * Copyright (C) 2023-2024 Analog Devices, Inc. 11 * 12 * Licensed under the Apache License, Version 2.0 (the "License"); 13 * you may not use this file except in compliance with the License. 14 * You may obtain a copy of the License at 15 * 16 * http://www.apache.org/licenses/LICENSE-2.0 17 * 18 * Unless required by applicable law or agreed to in writing, software 19 * distributed under the License is distributed on an "AS IS" BASIS, 20 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 * See the License for the specific language governing permissions and 22 * limitations under the License. 23 * 24 ******************************************************************************/ 25 26 #ifndef LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX78002_SPI_H_ 27 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX78002_SPI_H_ 28 29 /***** includes *******/ 30 #include <stdbool.h> 31 #include "mxc_assert.h" 32 #include "mxc_device.h" 33 #include "mxc_lock.h" 34 #include "mxc_pins.h" 35 #include "mxc_sys.h" 36 #include "gpio.h" 37 #include "spi_regs.h" 38 #include "dma_regs.h" 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** 45 * @defgroup spi SPI 46 * @ingroup periphlibs 47 * @{ 48 */ 49 50 /***** Definitions *****/ 51 52 // clang-format off 53 54 /** 55 * @brief The list of types for the SPI peripheral. 56 */ 57 typedef enum { 58 MXC_SPI_TYPE_SLAVE = 0, 59 MXC_SPI_TYPE_TARGET = 0, 60 MXC_SPI_TYPE_MASTER = 1, 61 MXC_SPI_TYPE_CONTROLLER = 1 62 } mxc_spi_type_t; 63 64 /** 65 * @brief The list of Target Select Control Scheme Options for 66 * target assertion/deassertion. 67 */ 68 typedef enum { 69 MXC_SPI_TSCONTROL_HW_AUTO = 0, // Automatically by hardware 70 MXC_SPI_TSCONTROL_SW_APP = 1 // Through software in the application 71 } mxc_spi_tscontrol_t; 72 73 /** 74 * @brief The list of possible states for an SPI instance. 75 */ 76 typedef enum { 77 MXC_SPI_STATE_READY = 0, // Ready for transaction 78 MXC_SPI_STATE_BUSY = 1 // Busy transferring 79 } mxc_spi_state_t; 80 81 /** 82 * @brief The list of supported SPI Interface Modes. 83 */ 84 typedef enum { 85 MXC_SPI_INTERFACE_STANDARD = 0, 86 MXC_SPI_INTERFACE_4WIRE = 0, 87 MXC_SPI_INTERFACE_QUAD = 1, 88 MXC_SPI_INTERFACE_3WIRE = 2, 89 MXC_SPI_INTERFACE_DUAL = 3 90 } mxc_spi_interface_t; 91 92 /** 93 * @brief The list of SPI clock modes 94 * 95 * SPI supports four combinations of clock and phase polarity. 96 * 97 * Clock polarity is controlled using the bit SPIn_CTRL2.cpol 98 * and determines if the clock is active high or active low 99 * 100 * Clock phase determines when the data must be stable for sampling 101 */ 102 typedef enum { 103 MXC_SPI_CLKMODE_0 = 0, // CPOL: 0 CPHA: 0 104 MXC_SPI_CLKMODE_1 = 1, // CPOL: 0 CPHA: 1 105 MXC_SPI_CLKMODE_2 = 2, // CPOL: 1 CPHA: 0 106 MXC_SPI_CLKMODE_3 = 3 // CPOL: 1 CPHA: 1 107 } mxc_spi_clkmode_t; 108 109 ///>>> @deprecated 110 /** 111 * @brief The list of SPI Widths supported 112 * 113 * @deprecated. 114 */ 115 typedef enum { 116 SPI_WIDTH_3WIRE, ///< 1 Data line, half duplex 117 SPI_WIDTH_STANDARD, ///< MISO/MOSI, full duplex 118 SPI_WIDTH_DUAL, ///< 2 Data lines, half duplex 119 SPI_WIDTH_QUAD, ///< 4 Data lines, half duplex 120 } mxc_spi_width_t; 121 122 /** 123 * @brief The list of SPI modes 124 * 125 * SPI supports four combinations of clock and phase polarity 126 * 127 * Clock polarity is controlled using the bit SPIn_CTRL2.cpol 128 * and determines if the clock is active high or active low 129 * 130 * Clock phase determines when the data must be stable for sampling 131 * 132 */ 133 typedef enum { 134 SPI_MODE_0, ///< clock phase = 0, clock polarity = 0 135 SPI_MODE_1, ///< clock phase = 0, clock polarity = 1 136 SPI_MODE_2, ///< clock phase = 1, clock polarity = 0 137 SPI_MODE_3, ///< clock phase = 1, clock polarity = 1 138 } mxc_spi_mode_t; 139 ///<<< Deprecated 140 141 typedef struct _mxc_spi_req_t mxc_spi_req_t; 142 143 /** 144 * @brief The callback routine used to indicate the transaction has terminated. 145 * 146 * @param req The details of the transaction. 147 * @param result See \ref MXC_Error_Codes for the list of error codes. 148 */ 149 typedef void (*mxc_spi_callback_t)(void *, int result); 150 typedef mxc_spi_callback_t spi_complete_cb_t; // Support SPI v1 name. 151 152 typedef struct _mxc_spi_pins_t mxc_spi_pins_t; 153 struct _mxc_spi_pins_t { 154 bool ss0; ///< Target select pin 0. 155 bool ss1; ///< Target select pin 1. 156 bool ss2; ///< Target select pin 2. 157 158 bool vddioh; ///< VDDIOH Select 159 160 bool clock; ///< Clock pin 161 bool miso; ///< miso pin 162 bool mosi; ///< mosi pin 163 bool sdio2; ///< SDIO2 pin 164 bool sdio3; ///< SDIO3 pin 165 166 mxc_gpio_drvstr_t drvstr; ///< Drive strength setting 167 }; 168 169 typedef struct { 170 // SPI Settings. 171 mxc_spi_regs_t *spi; // Selected SPI Instance 172 mxc_spi_clkmode_t clk_mode; // Clock modes 173 uint8_t frame_size; // Number of bits per character sent 174 175 // DMA Settings. 176 bool use_dma_tx; // Enable DMA TX. 177 bool use_dma_rx; // Enable DMA RX. (use_dma_tx must be true to use DMA RX). 178 mxc_dma_regs_t *dma; // Select DMA instance for SPI DMA. 179 } mxc_spi_cfg_t; 180 181 // Suppport names for backwards compatibility. 182 struct _mxc_spi_req_t { 183 mxc_spi_regs_t *spi; // Pointer to SPI registers 184 int ssIdx; 185 int ssDeassert; 186 uint8_t *txData; 187 uint8_t *rxData; 188 uint32_t txLen; // Number of frames to be stored in txData 189 uint32_t rxLen; // Number of frames to be stored in rxData 190 uint32_t txCnt; // Number of bytes transmitted from txData (Unused for SPI v2) 191 uint32_t rxCnt; // Number of bytes stored in rxData (Unused for SPI v2) 192 mxc_spi_callback_t completeCB; // completeCB 193 uint16_t txDummyValue; // Value of dummy bytes to be sent 194 }; 195 // clang-format on 196 197 /* ************************************************************************* */ 198 /* Control/Configuration functions */ 199 /* ************************************************************************* */ 200 201 /** 202 * @brief Initialize and enable SPI peripheral. 203 * 204 * This function does not set the Clock Mode (defaults to Clock Mode 0) and 205 * only two interface modes are selectable (Quad Mode or 4-Wire Standard Mode). 206 * To change the clock mode, call MXC_SPI_SetClkMode(..).. 207 * To select another interface mode, call MXC_SPI_SetInterface(..).. 208 * 209 * These parameters can be modified after cfgialization using low level functions 210 * 211 * @param spi Pointer to SPI instance's registers. 212 * @param controller_target Whether to put the device in controller or target mode. Use 213 * non-zero for controller mode, and zero for target mode. 214 * MXC_SPI_TYPE_CONTROLLER - 1 215 * MXC_SPI_TYPE_TARGET - 0 216 * @param if_mode Set the interface mode. 217 * MXC_SPI_INTERFACE_STANDARD - 0 (4 wire) 218 * MXC_SPI_INTERFACE_QUAD - 1 219 * MXC_SPI_INTERFACE_3WIRE - 2 220 * MXC_SPI_INTERFACE_DUAL - 3 221 * @param numTargets This parameter is UNUSED for SPI v2. 222 * The number of target used, if in controller mode. This 223 * is used to obtain control of the necessary TS pins. 224 * In target mode this is ignored and TS1 is used. 225 * @param ts_active_pol_mask This field sets the TS active polarity for each 226 * target, each bit position corresponds to each TS line. 227 * ts_active_pol_mask[0] - TS0 228 * ts_active_pol_mask[1] - TS1 229 * ts_active_pol_mask[n] - TSn 230 * @param freq The requested clock frequency. The actual clock frequency 231 * will be returned by the function if successful. Used in 232 * master mode only. 233 * @param pins SPI pin structure. Pins selected as true will be initialized 234 * for the requested SPI block. 235 * 236 * @return If successful, the actual clock frequency is returned. Otherwise, see 237 * \ref MXC_Error_Codes for a list of return codes. 238 */ 239 int MXC_SPI_Init(mxc_spi_regs_t *spi, mxc_spi_type_t controller_target, mxc_spi_interface_t if_mode, 240 int numTargets, uint8_t ts_active_pol_mask, uint32_t freq, mxc_spi_pins_t pins); 241 242 /** 243 * @brief Configure the SPI peripheral. 244 * 245 * List of Setting that will be updated: 246 * Clock Mode. 247 * Frame Size (bits). 248 * Interface Mode (Dual, Quad, Standard, 3-Wire). 249 * If DMA selections are true, configure and acquire DMA channels. 250 * 251 * @param cfg Pointer to SPI configuration struct. 252 * 253 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 254 */ 255 int MXC_SPI_Config(mxc_spi_cfg_t *cfg); 256 257 /** 258 * @brief Overwrite the cfg struct with default values. 259 * 260 * Settings: 261 * SPI APB (SPI1) instance 262 * Default, predefined SPI pins at VDDIO 263 * Controller Mode 264 * Standard 4-wire mode 265 * 100KHz speed 266 * CPOL: 0, CPHA: 0 267 * Automatic Hardware mode for TS Control 268 * TS0 pin 269 * Target active polarity is LOW (0) 270 * If use_dma = true, set DMATX and RX to true and set the DMA0 as the default instance. 271 * 272 * @param cfg Pointer to SPI configuration struct. 273 * @param use_dma_tx True/False option to configure DMA TX. 274 * @param use_dma_rx True/False option to configure DMA RX. 275 * 276 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes.odes. 277 */ 278 int MXC_SPI_ConfigStruct(mxc_spi_cfg_t *cfg, bool use_dma_tx, bool use_dma_rx); 279 280 /** 281 * @brief Disable and shutdown the SPI instance. 282 * 283 * @param spi Pointer to SPI instance's registers. 284 * 285 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 286 */ 287 int MXC_SPI_Shutdown(mxc_spi_regs_t *spi); 288 289 /** 290 * @brief Gets the interrupt flags that are currently set 291 * 292 * These functions should not be used while using non-blocking Transaction Level 293 * functions (Async or DMA) 294 * 295 * @param spi Pointer to SPI registers (selects the SPI block used). 296 * 297 * @return The interrupt flags. 298 */ 299 unsigned int MXC_SPI_GetFlags(mxc_spi_regs_t *spi); 300 301 /** 302 * @brief Clears the interrupt flags that are currently set. 303 * 304 * These functions should not be used while using non-blocking Transaction Level 305 * functions (Async or DMA). 306 * 307 * @param spi Pointer to SPI registers (selects the SPI block used). 308 */ 309 void MXC_SPI_ClearFlags(mxc_spi_regs_t *spi); 310 311 /** 312 * @brief Enables specific interrupts 313 * 314 * These functions should not be used while using non-blocking Transaction Level 315 * functions (Async or DMA). 316 * 317 * @param spi Pointer to SPI registers (selects the SPI block used). 318 * @param intEn The interrupts to be enabled. 319 */ 320 void MXC_SPI_EnableInt(mxc_spi_regs_t *spi, unsigned int intEn); 321 322 /** 323 * @brief Disables specific interrupts 324 * 325 * These functions should not be used while using non-blocking Transaction Level 326 * functions (Async or DMA) 327 * 328 * @param spi Pointer to SPI registers (selects the SPI block used). 329 * @param intDis The interrupts to be disabled 330 */ 331 void MXC_SPI_DisableInt(mxc_spi_regs_t *spi, unsigned int intDis); 332 333 /** 334 * @brief Returns the frequency of the clock used as the bit rate generator for a given SPI instance. 335 * 336 * @param spi Pointer to SPI instance's registers. 337 * 338 * @return Frequency of the clock used as the bit rate generator 339 */ 340 int MXC_SPI_GetPeripheralClock(mxc_spi_regs_t *spi); 341 342 /** 343 * @brief Configures the Pre-defined SPI Target Select pins for a specific instance. 344 * 345 * @param spi Pointer to SPI instance's registers. 346 * @param ts_control Target Select Control Scheme (\ref mxc_spi_tscontrol_t). 347 * 348 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 349 */ 350 int MXC_SPI_SetTSControl(mxc_spi_regs_t *spi, mxc_spi_tscontrol_t ts_control); 351 352 /** 353 * @brief Set the frequency of the SPI interface. 354 * 355 * This function is applicable in Master mode only 356 * 357 * @param spi Pointer to SPI instance's registers. 358 * @param hz The desired frequency in Hertz. 359 * 360 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 361 */ 362 int MXC_SPI_SetFrequency(mxc_spi_regs_t *spi, unsigned int hz); 363 364 /** 365 * @brief Get the frequency of the SPI interface. 366 * 367 * This function is applicable in Master mode only 368 * 369 * @param spi Pointer to SPI instance's registers. 370 * 371 * @return If successful, the SPI instance's set frequency value is returned. 372 * Otherwise, see \ref MXC_Error_Codes for a list of return codes. 373 */ 374 unsigned int MXC_SPI_GetFrequency(mxc_spi_regs_t *spi); 375 376 /** 377 * @brief Sets the number of bits per frame. 378 * 379 * @param spi Pointer to SPI instance's registers. 380 * @param frame_size The number of bits per frame. 381 * 382 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 383 */ 384 int MXC_SPI_SetFrameSize(mxc_spi_regs_t *spi, int frame_size); 385 386 /** 387 * @brief Gets the number of bits per frame. 388 * 389 * @param spi Pointer to SPI instance's registers. 390 * 391 * @return If successful, the SPI instance's set data size is returned. 392 * Otherwise, see \ref MXC_Error_Codes for a list of return codes. 393 */ 394 int MXC_SPI_GetFrameSize(mxc_spi_regs_t *spi); 395 396 /** 397 * @brief Sets the SPI interface mode used for transmissions. 398 * 399 * 3-Wire, Standard (4-Wire), Quad, Dual Modes 400 * 401 * @param spi Pointer to SPI instance's registers. 402 * @param if_mode SPI interface mode (3-Wire, Standard, Dual SPI, Quad SPI). 403 * See \ref mxc_spi_datawidth_t 404 * 405 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 406 */ 407 int MXC_SPI_SetInterface(mxc_spi_regs_t *spi, mxc_spi_interface_t if_mode); 408 409 /** 410 * @brief Gets the SPI interface mode used for transmissions. 411 * 412 * 3-Wire, Standard (4-Wire), Quad, Dual Modes 413 * 414 * @param spi Pointer to SPI instance's registers. 415 * 416 * @return The selected SPI instance's data line width. See \ref mxc_spi_datawidth_t. 417 */ 418 mxc_spi_interface_t MXC_SPI_GetInterface(mxc_spi_regs_t *spi); 419 420 /** 421 * @brief Sets the SPI clock mode (clock polarity and clock phase). 422 * 423 * @param spi Pointer to SPI instance's registers. 424 * @param clk_mode SPI clock mode. See \ref mxc_spi_clkmode_t. 425 * 426 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 427 */ 428 int MXC_SPI_SetClkMode(mxc_spi_regs_t *spi, mxc_spi_clkmode_t clk_mode); 429 430 /** 431 * @brief Gets the SPI clock mode (clock polarity and clock phase). 432 * 433 * @param spi Pointer to SPI instance's registers. 434 * @param clk_mode SPI clock mode. See \ref mxc_spi_clkmode_t 435 * 436 * @return The selected SPI instance's clock mode. See \ref mxc_spi_clkwidth_t. 437 */ 438 mxc_spi_clkmode_t MXC_SPI_GetClkMode(mxc_spi_regs_t *spi); 439 440 /** 441 * @brief Sets the SPI instance's callback function. 442 * 443 * @param spi Pointer to SPI instance's registers. 444 * @param callback Pointer to callback function called when transaction is complete. 445 * @param data Pointer for data to pass through callback funciton. 446 * 447 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 448 */ 449 int MXC_SPI_SetCallback(mxc_spi_regs_t *spi, mxc_spi_callback_t callback, void *data); 450 451 /** 452 * @brief Checks the SPI instance for an ongoing transmission 453 * 454 * This function is applicable in Controller mode only. 455 * 456 * @param spi Pointer to SPI instance's registers. 457 * 458 * @return Active/Inactive, see \ref MXC_Error_Codes for a list of return codes. 459 */ 460 int MXC_SPI_GetActive(mxc_spi_regs_t *spi); 461 462 /** 463 * @brief Checks whether the SPI instance is ready for sleep. 464 * 465 * @param spi Pointer to SPI instance's registers. 466 * 467 * @return Busy/Ready, see \ref MXC_Error_Codes for a list of return codes. 468 */ 469 int MXC_SPI_ReadyForSleep(mxc_spi_regs_t *spi); 470 471 /** 472 * @brief Starts a SPI Transmission 473 * 474 * This function is applicable in Master mode only 475 * 476 * The user must ensure that there are no ongoing transmissions before 477 * calling this function 478 * 479 * @param spi Pointer to SPI instance's registers. 480 * 481 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 482 */ 483 int MXC_SPI_StartTransmission(mxc_spi_regs_t *spi); 484 485 /** 486 * @brief Aborts an ongoing SPI Transmission 487 * 488 * This function is applicable in Master mode only 489 * 490 * @param spi Pointer to SPI instance's registers. 491 * 492 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 493 */ 494 int MXC_SPI_AbortTransmission(mxc_spi_regs_t *spi); 495 496 /** 497 * @brief Abort any asynchronous requests in progress. 498 * 499 * Abort any asynchronous requests in progress. Any callbacks associated with 500 * the active transaction will be executed to indicate when the transaction 501 * has been terminated. 502 * 503 * @param spi Pointer to SPI instance's registers. 504 */ 505 void MXC_SPI_AbortAsync(mxc_spi_regs_t *spi); 506 507 /** 508 * @brief Get the amount of free space available in the transmit FIFO. 509 * 510 * @param spi Pointer to SPI instance's registers. 511 * 512 * @return The number of bytes available. 513 */ 514 unsigned int MXC_SPI_GetTXFIFOAvailable(mxc_spi_regs_t *spi); 515 516 /** 517 * @brief Get the number of bytes currently available in the receive FIFO. 518 * 519 * @param spi Pointer to SPI instance's registers. 520 * 521 * @return The number of bytes available. 522 */ 523 unsigned int MXC_SPI_GetRXFIFOAvailable(mxc_spi_regs_t *spi); 524 525 /** 526 * @brief Removes and discards all bytes currently in the transmit FIFO. 527 * 528 * @param spi Pointer to SPI instance's registers. 529 */ 530 void MXC_SPI_ClearTXFIFO(mxc_spi_regs_t *spi); 531 532 /** 533 * @brief Removes and discards all bytes currently in the receive FIFO. 534 * 535 * @param spi Pointer to SPI instance's registers. 536 */ 537 void MXC_SPI_ClearRXFIFO(mxc_spi_regs_t *spi); 538 539 /** 540 * @brief Set the transmit threshold level. 541 * 542 * TX FIFO threshold. Smaller values will cause interrupts 543 * to occur more often, but reduce the possibility of terminating 544 * a transaction early in master mode, or transmitting invalid data 545 * in slave mode. Larger values will reduce the time required by 546 * the ISR, but increase the possibility errors occurring. Passing 547 * an invalid value will cause the driver to use the value already 548 * set in the appropriate register. 549 * 550 * @param spi Pointer to SPI instance's registers. 551 * @param numBytes The threshold level to set. This value must be 552 * between 0 and 8 inclusive. 553 * 554 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 555 */ 556 int MXC_SPI_SetTXThreshold(mxc_spi_regs_t *spi, unsigned int numBytes); 557 558 /** 559 * @brief Set the receive threshold level. 560 * 561 * RX FIFO Receive threshold. Smaller values will cause 562 * interrupts to occur more often, but reduce the possibility 563 * of losing data because of a FIFO overflow. Larger values 564 * will reduce the time required by the ISR, but increase the 565 * possibility of data loss. Passing an invalid value will 566 * cause the driver to use the value already set in the 567 * appropriate register. 568 * 569 * @param spi Pointer to SPI instance's registers. 570 * @param numBytes The threshold level to set. This value must be 571 * between 0 and 8 inclusive. 572 * 573 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 574 */ 575 int MXC_SPI_SetRXThreshold(mxc_spi_regs_t *spi, unsigned int numBytes); 576 577 /** 578 * @brief Get the current transmit threshold level. 579 * 580 * @param spi Pointer to SPI instance's registers. 581 * 582 * @return The transmit threshold value (in bytes). 583 */ 584 unsigned int MXC_SPI_GetTXThreshold(mxc_spi_regs_t *spi); 585 586 /** 587 * @brief Get the current receive threshold level. 588 * 589 * @param spi Pointer to SPI instance's registers. 590 * 591 * @return The receive threshold value (in bytes). 592 */ 593 unsigned int MXC_SPI_GetRXThreshold(mxc_spi_regs_t *spi); 594 595 //////>>> Previous Implementation 596 /** 597 * @brief Sets the number of bits per character 598 * 599 * @param spi Pointer to SPI registers (selects the SPI block used). 600 * @param dataSize The number of bits per character 601 * 602 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 603 */ 604 int MXC_SPI_SetDataSize(mxc_spi_regs_t *spi, int dataSize); 605 606 /** 607 * @brief Gets the number of bits per character 608 * 609 * @param spi Pointer to SPI registers (selects the SPI block used). 610 * 611 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 612 */ 613 int MXC_SPI_GetDataSize(mxc_spi_regs_t *spi); 614 615 /** 616 * @brief Sets the SPI width used for transmissions 617 * 618 * @param spi Pointer to SPI registers (selects the SPI block used). 619 * @param spiWidth SPI Width (3-Wire, Standard, Dual SPI, Quad SPI) 620 * 621 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 622 */ 623 int MXC_SPI_SetWidth(mxc_spi_regs_t *spi, mxc_spi_width_t spiWidth); 624 625 /** 626 * @brief Gets the SPI width used for transmissions 627 * 628 * @param spi Pointer to SPI registers (selects the SPI block used). 629 * 630 * @return Spi Width 631 */ 632 mxc_spi_width_t MXC_SPI_GetWidth(mxc_spi_regs_t *spi); 633 634 /** 635 * @brief Sets the slave select (SS) line used for transmissions 636 * 637 * This function is applicable in Master mode only 638 * 639 * @param spi Pointer to SPI instance's registers. 640 * @param ssIdx Slave select index 641 * 642 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 643 */ 644 int MXC_SPI_SetSlave(mxc_spi_regs_t *spi, int ssIdx); 645 646 /** 647 * @brief Gets the slave select (SS) line used for transmissions 648 * 649 * This function is applicable in Master mode only 650 * 651 * @param spi Pointer to SPI instance's registers. 652 * 653 * @return slave slect 654 */ 655 int MXC_SPI_GetSlave(mxc_spi_regs_t *spi); 656 657 /** 658 * @brief Sets the spi mode using clock polarity and clock phase 659 * 660 * @param spi Pointer to SPI registers (selects the SPI block used). 661 * @param spiMode \ref mxc_spi_mode_t 662 * 663 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 664 */ 665 int MXC_SPI_SetMode(mxc_spi_regs_t *spi, mxc_spi_mode_t spiMode); 666 667 /** 668 * @brief Gets the spi mode 669 * 670 * @param spi Pointer to SPI registers (selects the SPI block used). 671 * 672 * @return mxc_spi_mode_t \ref mxc_spi_mode_t 673 */ 674 mxc_spi_mode_t MXC_SPI_GetMode(mxc_spi_regs_t *spi); 675 676 /** 677 * @brief Loads bytes into the transmit FIFO. 678 * 679 * @param spi Pointer to SPI instance's registers. 680 * @param bytes The buffer containing the bytes to write 681 * @param len The number of bytes to write. 682 * 683 * @return The number of bytes actually written. 684 */ 685 unsigned int MXC_SPI_WriteTXFIFO(mxc_spi_regs_t *spi, unsigned char *bytes, unsigned int len); 686 687 /** 688 * @brief Unloads bytes from the receive FIFO. 689 * 690 * @param spi Pointer to SPI instance's registers. 691 * @param bytes The buffer to read the data into. 692 * @param len The number of bytes to read. 693 * 694 * @return The number of bytes actually read. 695 */ 696 unsigned int MXC_SPI_ReadRXFIFO(mxc_spi_regs_t *spi, unsigned char *bytes, unsigned int len); 697 698 /** 699 * @brief Sets the TX data to transmit as a 'dummy' byte 700 * 701 * In single wire master mode, this data is transmitted on MOSI when performing 702 * an RX (MISO) only transaction. This defaults to 0. 703 * 704 * @param spi Pointer to SPI registers (selects the SPI block used). 705 * @param defaultTXData Data to shift out in RX-only transactions 706 * 707 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 708 */ 709 int MXC_SPI_SetDefaultTXData(mxc_spi_regs_t *spi, unsigned int defaultTXData); 710 711 /** 712 * @brief Enable/Disable HW CS control feature. 713 * 714 * Depending on the application, the user might need to manually drive the slave select pin. 715 * The SPI driver automatically drives the SS pin and this function enables/disables this 716 * feature. 717 * 718 * @param spi Pointer to SPI registers (selects the SPI block used.) 719 * @param state Non-zero values: enable HW SS mode. Zero: disable HW SS mode. 720 */ 721 void MXC_SPI_HWSSControl(mxc_spi_regs_t *spi, int state); 722 //////<<< Previous Implementation 723 724 /* ** DMA Functions ** */ 725 726 /** 727 * @brief This function initializes the DMA for SPI DMA transactions. 728 * 729 * @note This function must run before any SPI DMA transactions. 730 * 731 * @param spi Pointer to SPI registers (selects the SPI block used). 732 * @param dma Pointer to DMA registers (selects the DMA block used). 733 * @param use_dma_tx True/False setting to initialize SPI DMA TX. Acquire DMA TX channel. 734 * @param use_dma_rx True/False setting to initialize SPI DMA RX. Acquire DMA RX channel. 735 * use_dma_tx must be true even if use_dma_rx is false. 736 * 737 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 738 */ 739 int MXC_SPI_DMA_Init(mxc_spi_regs_t *spi, mxc_dma_regs_t *dma, bool use_dma_tx, bool use_dma_rx); 740 741 /** 742 * @brief Helper function that checks whether the MXC_SPI_Init function 743 * cfgalized DMA for SPI DMA transactons. 744 * 745 * @param spi Pointer to SPI instance's registers. 746 * 747 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 748 */ 749 bool MXC_SPI_DMA_GetInitialized(mxc_spi_regs_t *spi); 750 751 /** 752 * @brief Retreive the DMA TX Channel associated with SPI instance. 753 * 754 * @param spi Pointer to SPI instance's registers. 755 * 756 * @return If successful, the DMA TX Channel number is returned. Otherwise, see 757 * \ref MXC_Error_Codes for a list of return codes. 758 */ 759 int MXC_SPI_DMA_GetTXChannel(mxc_spi_regs_t *spi); 760 761 /** 762 * @brief Retreive the DMA RX Channel associated with SPI instance. 763 * 764 * @param spi Pointer to SPI instance's registers. 765 * 766 * @return If successful, the DMA RX Channel number is returned. Otherwise, see 767 * \ref MXC_Error_Codes for a list of return codes. 768 */ 769 int MXC_SPI_DMA_GetRXChannel(mxc_spi_regs_t *spi); 770 771 /** 772 * @brief Sets the SPI instance's DMA TX/RX request select. 773 * 774 * @param spi Pointer to SPI instance's registers. 775 * @param use_dma_tx True/False setting to set SPI DMA TX request select. 776 * @param use_dma_rx True/False setting to set SPI DMA RX request select. 777 * 778 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 779 */ 780 int MXC_SPI_DMA_SetRequestSelect(mxc_spi_regs_t *spi, bool use_dma_tx, bool use_dma_rx); 781 782 /* ** Transaction Functions ** */ 783 784 /** 785 * @brief Performs a blocking SPI transaction. 786 * 787 * Performs a blocking SPI transaction. 788 * These actions will be performed in Master Mode: 789 * 1. Assert the specified SS 790 * 2. In Full Duplex Modes, send TX data while receiving RX Data 791 * if rxLen > txLen, pad txData with DefaultTXData 792 * if txLen > rxLen, discard rxData where rxCnt > rxLen 793 * 3. In Half Duplex Modes, send TX Data, then receive RX Data 794 * 4. Deassert the specified SS 795 * 796 * These actions will be performed in Slave Mode: 797 * 1. Fill FIFO with txData 798 * 2. Wait for SS Assert 799 * 3. If needed, pad txData with DefaultTXData 800 * 4. Unload RX FIFO as needed 801 * 5. On SS Deassert, return 802 * 803 * @param req Pointer to details of the transaction. 804 * 805 * @return See \ref MXC_Error_Codes for the list of error return codes. 806 */ 807 int MXC_SPI_MasterTransaction(mxc_spi_req_t *req); 808 809 /** 810 * @brief Setup an interrupt-driven SPI transaction 811 * 812 * The TX FIFO will be filled with txData, padded with DefaultTXData if necessary 813 * Relevant interrupts will be enabled, and relevant registers set (SS, Width, etc) 814 * 815 * @param req Pointer to details of the transaction. 816 * 817 * @return See \ref MXC_Error_Codes for the list of error return codes. 818 */ 819 int MXC_SPI_MasterTransactionAsync(mxc_spi_req_t *req); 820 821 /** 822 * @brief Setup a DMA driven SPI transaction 823 * 824 * The TX FIFO will be filled with txData, padded with DefaultTXData if necessary 825 * Relevant interrupts will be enabled, and relevant registers set (SS, Width, etc) 826 * 827 * The lowest-indexed unused DMA channel will be acquired (using the DMA API) and 828 * set up to load/unload the FIFOs with as few interrupt-based events as 829 * possible. The channel will be reset and returned to the system at the end of 830 * the transaction. 831 * 832 * @param req Pointer to details of the transaction. 833 * 834 * @return See \ref MXC_Error_Codes for the list of error return codes. 835 */ 836 int MXC_SPI_MasterTransactionDMA(mxc_spi_req_t *req); 837 838 /** 839 * @brief Set up a blocking, non-interrupt-driven SPI controller transaction. 840 * 841 * @param req Pointer to details of the transaction. 842 * 843 * @return See \ref MXC_Error_Codes for the list of error return codes. 844 */ 845 int MXC_SPI_ControllerTransaction(mxc_spi_req_t *req); 846 847 /** 848 * @brief Set up a non-blocking, interrupt-driven SPI controller transaction. 849 * 850 * The MXC_SPI_Handler function must be called in the selected SPI instance's 851 * interrupt handler to process the transaction. 852 * 853 * @param req Pointer to details of the transaction. 854 * 855 * @return See \ref MXC_Error_Codes for the list of error return codes. 856 */ 857 int MXC_SPI_ControllerTransactionAsync(mxc_spi_req_t *req); 858 859 /** 860 * @brief Set up a non-blocking, DMA-driven SPI controller transaction. 861 * 862 * The MXC_SPI_Config(...) or MXC_SPI_DMA_Init(..). functions must be 863 * called before calling this DMA transaction function. This function 864 * does not initialize the DMA. 865 * 866 * @param req Pointer to details of the transaction. 867 * 868 * @return See \ref MXC_Error_Codes for the list of error return codes. 869 */ 870 int MXC_SPI_ControllerTransactionDMA(mxc_spi_req_t *req); 871 872 /** 873 * @brief Set up a blocking, DMA-driven SPI controller transaction. 874 * 875 * @param req Pointer to details of the transaction. 876 * 877 * @return See \ref MXC_Error_Codes for the list of error return codes. 878 */ 879 int MXC_SPI_ControllerTransactionDMAB(mxc_spi_req_t *req); 880 881 /** 882 * @brief Performs a blocking SPI transaction. 883 * 884 * @param req Pointer to details of the transaction 885 * 886 * @return See \ref MXC_Error_Codes for the list of error return codes. 887 */ 888 int MXC_SPI_SlaveTransaction(mxc_spi_req_t *req); 889 890 /** 891 * @brief Setup an interrupt-driven SPI transaction 892 * 893 * @param req Pointer to details of the transactionz 894 * 895 * @return See \ref MXC_Error_Codes for the list of error return codes. 896 */ 897 int MXC_SPI_SlaveTransactionAsync(mxc_spi_req_t *req); 898 899 /** 900 * @brief Setup a DMA driven SPI transaction 901 * 902 * The TX FIFO will be filled with txData, padded with DefaultTXData if necessary 903 * Relevant interrupts will be enabled, and relevant registers set (SS, Width, etc) 904 * 905 * The lowest-indexed unused DMA channel will be acquired (using the DMA API) and 906 * set up to load/unload the FIFOs with as few interrupt-based events as 907 * possible. The channel will be reset and returned to the system at the end of 908 * the transaction. 909 * 910 * @param req Pointer to details of the transaction 911 * 912 * @return See \ref MXC_Error_Codes for the list of error return codes. 913 */ 914 int MXC_SPI_SlaveTransactionDMA(mxc_spi_req_t *req); 915 916 /** 917 * @brief Setup a blocking SPI Target transaction. 918 * 919 * @param req Pointer to details of the transaction. 920 * 921 * @return See \ref MXC_Error_Codes for the list of error return codes. 922 */ 923 int MXC_SPI_TargetTransaction(mxc_spi_req_t *req); 924 925 /** 926 * @brief Setup an interrupt-driven, non-blocking SPI Target transaction. 927 * 928 * @param req Pointer to details of the transaction. 929 * 930 * @return See \ref MXC_Error_Codes for the list of error return codes. 931 */ 932 int MXC_SPI_TargetTransactionAsync(mxc_spi_req_t *req); 933 934 /** 935 * @brief Setup a DMA-driven SPI Target transaction. 936 * 937 * The MXC_SPI_Config(...) or MXC_SPI_DMA_Init(..). functions must be 938 * called before calling this DMA transaction function. This function 939 * does not initialize the DMA. 940 * 941 * @param req Pointer to details of the transaction. 942 * 943 * @return See \ref MXC_Error_Codes for the list of error return codes. 944 */ 945 int MXC_SPI_TargetTransactionDMA(mxc_spi_req_t *req); 946 947 /* ** Handler Functions ** */ 948 949 /** 950 * @brief The processing function for asynchronous transactions. 951 * 952 * When using the asynchronous functions, the application must call this 953 * function periodically. This can be done from within the SPI interrupt 954 * handler or periodically by the application if SPI interrupts are disabled. 955 * 956 * @param spi Pointer to SPI instance's registers. 957 */ 958 void MXC_SPI_AsyncHandler(mxc_spi_regs_t *spi); 959 960 /** 961 * @brief The processing function for asynchronous transactions. 962 * 963 * When using the asynchronous functions, the application must call this 964 * function periodically. This can be done from within the SPI interrupt 965 * handler or periodically by the application if SPI interrupts are disabled. 966 * 967 * @param spi Pointer to SPI instance's registers. 968 */ 969 void MXC_SPI_Handler(mxc_spi_regs_t *spi); 970 971 /** 972 * @brief The processing function for DMA TX transactions. 973 * 974 * This function calls the callback function if only TX transaction was made. 975 * 976 * @param spi Pointer to SPI instance's registers. 977 */ 978 void MXC_SPI_DMA_TX_Handler(mxc_spi_regs_t *spi); 979 980 /** 981 * @brief The processing function for DMA RX transactions. 982 * 983 * This function calls the callback function at the end of a TX/RX transaction. 984 * 985 * @param spi Pointer to SPI instance's registers. 986 */ 987 void MXC_SPI_DMA_RX_Handler(mxc_spi_regs_t *spi); 988 989 /**@} end of group spi */ 990 991 #ifdef __cplusplus 992 } 993 #endif 994 995 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX78002_SPI_H_ 996
