1 /** 2 * @file spi17y.h 3 * @brief Serial Peripheral Interface (SPI17Y) function prototypes and data types. 4 */ 5 6 /* **************************************************************************** 7 * Copyright (C) 2016 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-12-18 15:37:22 -0600 (Tue, 18 Dec 2018) $ 38 * $Revision: 40072 $ 39 * 40 *************************************************************************** */ 41 42 /* Define to prevent redundant inclusion */ 43 #ifndef _SPI17Y_H_ 44 #define _SPI17Y_H_ 45 46 /* **** Includes **** */ 47 #include "mxc_config.h" 48 #include "spi17y_regs.h" 49 #include "mxc_sys.h" 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 /** 56 * @defgroup spi17y SPI17Y 57 * @ingroup spi 58 * @{ 59 */ 60 61 /* **** Definitions **** */ 62 63 /** 64 * Enumeration type for setting the number data lines to use for communication. 65 */ 66 typedef enum { 67 SPI17Y_WIDTH_1 = 0, /**< 1 Data Line. */ 68 SPI17Y_WIDTH_2 = 1, /**< 2 Data Lines (x2). */ 69 SPI17Y_WIDTH_4 = 2 /**< 4 Data Lines (x4). */ 70 } spi17y_width_t; 71 72 /** 73 * Enumeration type for setting the polarity of ss lines. 74 */ 75 typedef enum { 76 SPI17Y_POL_LOW = 0, /**< Polarity Low. */ 77 SPI17Y_POL_HIGH = 1 /**< Polarity High. */ 78 } spi17y_sspol_t; 79 80 /** 81 * Structure type representing a SPI17Y Master Transaction request. 82 */ 83 typedef struct spi17y_req spi17y_req_t; 84 85 86 /** 87 * @brief Callback function type used in asynchronous SPI Master communication requests. 88 * @details The function declaration for the SPI Master callback is: 89 * @code 90 * void callback(spi17y_req_t * req, int error_code); 91 * @endcode 92 * | | | 93 * | -----: | :----------------------------------------- | 94 * | \p req | Pointer to a #spi_req object representing the active SPI Master active transaction. | 95 * | \p error_code | An error code if the active transaction had a failure or #E_NO_ERROR if successful. | 96 * @note Callback will execute in interrupt context 97 * @addtogroup spi_async 98 */ 99 typedef void (*spi17y_callback_fn)(spi17y_req_t * req, int error_code); 100 101 /** 102 * @brief Structure definition for an SPI Master Transaction request. 103 * @note When using this structure for an asynchronous operation, the 104 * structure must remain allocated until the callback is completed. 105 * @addtogroup spi_async 106 */ 107 struct spi17y_req { 108 uint8_t ssel; /**< Slave select line to use. (Master only, ignored in slave mode) */ 109 uint8_t deass; /**< Non-zero to de-assert slave select after transaction. (Master only, ignored in slave mode)*/ 110 spi17y_sspol_t ssel_pol; /**< Slave select line polarity. */ 111 const void *tx_data; /**< Pointer to a buffer to transmit data from. NULL if undesired. */ 112 void *rx_data; /**< Pointer to a buffer to store data received. NULL if undesired.*/ 113 spi17y_width_t width; /**< Number of data lines to use, see #spi17y_width_t. */ 114 unsigned len; /**< Number of transfer units to send from the \p tx_data buffer. */ 115 unsigned bits; /**< Number of bits in transfer unit (e.g. 8 for byte, 16 for short) */ 116 unsigned rx_num; /**< Number of bytes actually read into the \p rx_data buffer. */ 117 unsigned tx_num; /**< Number of bytes actually sent from the \p tx_data buffer */ 118 spi17y_callback_fn callback; /**< Callback function if desired, NULL otherwise */ 119 }; 120 121 122 /* **** Function Prototypes **** */ 123 124 /** 125 * @brief Initialize the spi. 126 * @param spi Pointer to spi module to initialize. 127 * @param mode SPI mode for clock phase and polarity. 128 * @param freq Desired clock frequency. 129 * @param sys_cfg System configuration object 130 * 131 * @return #E_NO_ERROR if successful, @ref 132 * MXC_Error_Codes "error" if unsuccessful. 133 */ 134 int SPI17Y_Init(mxc_spi17y_regs_t *spi, unsigned int mode, unsigned int freq, const sys_cfg_spi17y_t* sys_cfg); 135 136 /** 137 * @brief Shutdown SPI module. 138 * @param spi Pointer to SPI regs. 139 * 140 * @return #E_NO_ERROR if successful, @ref 141 * MXC_Error_Codes "error" if unsuccessful. 142 */ 143 int SPI17Y_Shutdown(mxc_spi17y_regs_t *spi); 144 145 /** 146 * @brief Processing function for asynchronous SPI operations. 147 * This function must be called either from the SPI interrupt 148 * handler or periodically. 149 * 150 * @param spi Pointer to spi module. 151 */ 152 void SPI17Y_Handler(mxc_spi17y_regs_t *spi); 153 154 /** 155 * @brief Execute a master transaction. 156 * This function will block until the transaction is complete. 157 * @param spi Pointer to spi module. 158 * @param req Pointer to spi request 159 * 160 * @return #E_NO_ERROR if successful, @ref 161 * MXC_Error_Codes "error" if unsuccessful. 162 */ 163 int SPI17Y_MasterTrans(mxc_spi17y_regs_t *spi, spi17y_req_t *req); 164 165 /** 166 * @brief Execute a slave transaction. 167 * This function will block until the transaction is complete. 168 * @param spi Pointer to spi module. 169 * @param req Pointer to spi request 170 * 171 * @return #E_NO_ERROR if successful, @ref 172 * MXC_Error_Codes "error" if unsuccessful. 173 */ 174 int SPI17Y_SlaveTrans(mxc_spi17y_regs_t *spi, spi17y_req_t *req); 175 176 /** 177 * @brief Asynchronously read/write SPI Master data 178 * 179 * @param spi Pointer to spi module 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 SPI17Y_MasterTransAsync(mxc_spi17y_regs_t *spi, spi17y_req_t *req); 186 187 /** 188 * @brief Asynchronously read/write SPI Slave data 189 * 190 * @param spi Pointer to spi module 191 * @param req Pointer to spi request 192 * 193 * @return #E_NO_ERROR if successful, @ref 194 * MXC_Error_Codes "error" if unsuccessful. 195 */ 196 int SPI17Y_SlaveTransAsync(mxc_spi17y_regs_t *spi, spi17y_req_t *req); 197 198 /** 199 * @brief Aborts an Asynchronous request 200 * 201 * @param req Pointer to spi request 202 * @return #E_NO_ERROR if successful, @ref 203 * MXC_Error_Codes "error" if unsuccessful. 204 */ 205 int SPI17Y_AbortAsync(spi17y_req_t *req); 206 207 /** 208 * @brief Enable SPI 209 * @param spi Pointer to spi module. 210 * 211 * @return #E_NO_ERROR if successful, @ref 212 * MXC_Error_Codes "error" if unsuccessful. 213 */ 214 void SPI17Y_Enable(mxc_spi17y_regs_t* spi); 215 216 /** 217 * @brief Disable SPI. Any pending asynchronous transactions will not 218 * complete and their callbacks will not be executed. 219 * @param spi Pointer to spi module. 220 * 221 * @return #E_NO_ERROR if successful, @ref 222 * MXC_Error_Codes "error" if unsuccessful. 223 */ 224 void SPI17Y_Disable(mxc_spi17y_regs_t* spi); 225 226 /** 227 * @brief Clear the TX and RX FIFO 228 * @param spi Pointer to spi module. 229 * 230 * @return #E_NO_ERROR if successful, @ref 231 * MXC_Error_Codes "error" if unsuccessful. 232 */ 233 void SPI17Y_Clear_fifo(mxc_spi17y_regs_t* spi); 234 235 236 /**@} end of group spi17y */ 237 238 #ifdef __cplusplus 239 } 240 #endif 241 242 #endif /* _SPI17Y_H_ */ 243