1 /** 2 * @file spi.h 3 * @brief Serial Peripheral Interface (SPIMSS) function prototypes and data types. 4 */ 5 6 /* **************************************************************************** 7 * Copyright (C) 2017 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 * $Date: 2018-11-07 14:48:15 -0600 (Wed, 07 Nov 2018) $ 38 * $Revision: 39010 $ 39 * 40 *************************************************************************** */ 41 42 /* Define to prevent redundant inclusion */ 43 #ifndef _SPI_H_ 44 #define _SPI_H_ 45 46 /* **** Includes **** */ 47 #include "spi17y_regs.h" 48 #include "spimss_regs.h" 49 #include "spimss.h" 50 #include "spi17y.h" 51 #include "mxc_sys.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 /** 66 * @brief Enums assigning numbers to SPI 67 */ 68 typedef enum { 69 SPI0A, // SPI17Y (0A) 70 SPI1A, // SPIMSS (1A) 71 SPI1B, // SPIMSS (1B) 72 }spi_type; 73 74 75 /** 76 * @brief Renaming the SPI address names 77 */ 78 #define MXC_SPI0 MXC_SPI17Y // SPI0A 79 #define MXC_SPI1 MXC_SPIMSS // SPI1A & SPI1B 80 81 82 /** 83 * @brief Renaming Interrupt SPI Interrupt sources 84 */ 85 #define SPI0_IRQn SPI17Y_IRQn // SPI0A 86 #define SPI1_IRQn SPIMSS_IRQn // SPI1A & SPI1B 87 88 89 /** 90 * @brief Renaming SPI Width 91 */ 92 #define SPI0_WIDTH_1 SPI17Y_WIDTH_1 /**< 1 Data Line. */ 93 #define SPI0_WIDTH_2 SPI17Y_WIDTH_2 /**< 2 Data Lines (x2). */ 94 #define SPI0_WIDTH_4 SPI17Y_WIDTH_4 /**< 4 Data Lines (x4). */ 95 96 /** 97 * @brief Renaming SPI Polarity 98 */ 99 #define SPI_POL_LOW SPI17Y_POL_LOW /**< Slave Select polarity Low. */ 100 #define SPI_POL_HIGH SPI17Y_POL_HIGH /**< Slave Select polarity High. */ 101 102 /** 103 * @brief Structure type representing a SPI Master Transaction request. 104 */ 105 typedef struct spi_req spi_req_t; 106 107 /** 108 * @brief Callback function type used in asynchronous SPI Master communication requests. 109 * @details The function declaration for the SPI Master callback is: 110 * @code 111 * void callback(spi_req_t * req, int error_code); 112 * @endcode 113 * | | | 114 * | -----: | :----------------------------------------- | 115 * | \p req | Pointer to a #spi_req object representing the active SPI Master active transaction. | 116 * | \p error_code | An error code if the active transaction had a failure or #E_NO_ERROR if successful. | 117 * @note Callback will execute in interrupt context 118 * @addtogroup spi_async 119 */ 120 typedef void (*spi_callback_fn)(void * req, int error_code); 121 122 /** 123 * @brief Structure definition for an SPI Master Transaction request. 124 * @note When using this structure for an asynchronous operation, the 125 * structure must remain allocated until the callback is completed. 126 * @addtogroup spi_async 127 */ 128 struct spi_req { 129 uint8_t ssel; /**< Slave select line to use. (Master only) */ 130 uint8_t deass; /**< Non-zero to de-assert slave select after transaction. (Master only)*/ 131 spi17y_sspol_t ssel_pol; /**< Slave select line polarity. */ 132 const void *tx_data; /**< Pointer to a buffer to transmit data from. NULL if undesired. */ 133 void *rx_data; /**< Pointer to a buffer to store data received. NULL if undesired.*/ 134 spi17y_width_t width; /**< Number of data lines to use, see #spi17y_width_t. */ 135 unsigned len; /**< Number of transfer units to send from the \p tx_data buffer. */ 136 unsigned bits; /**< Number of bits in transfer unit (e.g. 8 for byte, 16 for short) */ 137 unsigned rx_num; /**< Number of bytes actually read into the \p rx_data buffer. */ 138 unsigned tx_num; /**< Number of bytes actually sent from the \p tx_data buffer */ 139 spi_callback_fn callback; /**< Callback function if desired, NULL otherwise */ 140 }; 141 142 143 /* **** Function Prototypes **** */ 144 145 /** 146 * @brief Initialize the spi. 147 * @param spi_name spi module to initialize. 148 * @param mode SPI mode for clock phase and polarity. 149 * @param freq Desired clock frequency. 150 * 151 * @return #E_NO_ERROR if successful, @ref 152 * MXC_Error_Codes "error" if unsuccessful. 153 */ 154 int SPI_Init(spi_type spi_name, unsigned mode, unsigned freq); 155 156 /** 157 * @brief Asynchronously read/write SPI Master data 158 * 159 * @param spi_name SPI instance being used 160 * @param req Pointer to spi request 161 * 162 * @return #E_NO_ERROR if successful, @ref 163 * MXC_Error_Codes "error" if unsuccessful. 164 */ 165 int SPI_MasterTransAsync(spi_type spi_name, spi_req_t *req); 166 167 /** 168 * @brief Execute a master transaction. 169 * @param spi_name SPI instance being used 170 * @param req Pointer to spi request 171 * 172 * @return #E_NO_ERROR if successful, @ref 173 * MXC_Error_Codes "error" if unsuccessful. 174 */ 175 int SPI_MasterTrans(spi_type spi_name, spi_req_t *req); 176 177 /** 178 * @brief Asynchronously read/write SPI Slave data 179 * @param spi_name SPI instance being used 180 * @param req Pointer to spi request 181 * 182 * @return #E_NO_ERROR if successful, @ref 183 * MXC_Error_Codes "error" if unsuccessful. 184 */ 185 int SPI_SlaveTransAsync(spi_type spi_name, spi_req_t *req); 186 187 /** 188 * @brief Execute a slave transaction. 189 * @param spi_name SPI instance being used 190 * @param req Pointer to spi request 191 * 192 * @return #E_NO_ERROR if successful, @ref 193 * MXC_Error_Codes "error" if unsuccessful. 194 */ 195 int SPI_SlaveTrans(spi_type spi_name, spi_req_t *req); 196 197 /** 198 * @brief Shutdown SPI module. 199 * @param spi_name SPI instance being used 200 * 201 * @return #E_NO_ERROR if successful, appropriate error otherwise 202 */ 203 int SPI_Shutdown(spi_type spi_name); 204 205 206 /** 207 * @brief Aborts an Asynchronous request 208 * @param spi_name SPI instance being used 209 * @param req Pointer to spi request 210 * 211 * @return #E_NO_ERROR if successful, @ref 212 * MXC_Error_Codes "error" if unsuccessful. 213 */ 214 int SPI_AbortAsync(spi_type spi_name, spi_req_t *req); 215 216 /** 217 * @brief Execute SPI transaction based on interrupt handler 218 * @param spi_name SPI instance being used 219 * 220 * @return #E_NO_ERROR if successful, 221 * @return #E_BAD_PARAM otherwise 222 */ 223 int SPI_Handler(spi_type spi_name); 224 225 /** 226 * @brief Enable SPI 227 * @param spi_name Pointer to spi module. 228 * 229 * @return #E_NO_ERROR if successful, appropriate error otherwise 230 */ 231 int SPI_Enable(spi_type spi_name); 232 233 /** 234 * @brief Disable SPI 235 * @param spi_name Pointer to spi module. 236 * 237 * @return #E_NO_ERROR if successful, appropriate error otherwise 238 */ 239 int SPI_Disable(spi_type spi_name); 240 241 /** 242 * @brief Clear the TX and RX FIFO 243 * @param spi_name Pointer to spi module. 244 * 245 * @return #E_NO_ERROR if successful, appropriate error otherwise 246 */ 247 int SPI_Clear_fifo(spi_type spi_name); 248 249 //------------------------------------------------------------------------------------------- 250 /**@} end of group spi */ 251 252 #ifdef __cplusplus 253 } 254 #endif 255 256 #endif /* _SPI_H_ */ 257 258 259 260