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