1 /** 2 * @file spimss.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-12-18 15:37:22 -0600 (Tue, 18 Dec 2018) $ 38 * $Revision: 40072 $ 39 * 40 *************************************************************************** */ 41 42 /* Define to prevent redundant inclusion */ 43 #ifndef _SPIMSS_H_ 44 #define _SPIMSS_H_ 45 46 /* **** Includes **** */ 47 #include "mxc_config.h" 48 #include "mxc_sys.h" 49 #include "spimss_regs.h" 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 /** 56 * @defgroup spimss SPIMSS 57 * @ingroup spi 58 * @{ 59 */ 60 61 /* **** Definitions **** */ 62 63 64 /** 65 * @brief Enumeration type for setting the number data lines to use for communication. 66 */ 67 typedef enum { // ONLY FOR COMPATIBILITY FOR CONSOLIDATION WITH SPY17, NOT USED OR NEEDED 68 DUMMY_1, /**< NOT USED */ 69 DUMMY_2, /**< NOT USED */ 70 DUMMY_3, /**< NOT USED */ 71 } spimss_width_t; 72 73 /** 74 * @brief Structure type representing a SPI Master Transaction request. 75 */ 76 typedef struct spimss_req spimss_req_t; 77 78 /** 79 * @brief Callback function type used in asynchronous SPI Master communication requests. 80 * @details The function declaration for the SPI Master callback is: 81 * @code 82 * void callback(spi_req_t * req, int error_code); 83 * @endcode 84 * | | | 85 * | -----: | :----------------------------------------- | 86 * | \p req | Pointer to a #spi_req object representing the active SPI Master active transaction. | 87 * | \p error_code | An error code if the active transaction had a failure or #E_NO_ERROR if successful. | 88 * @note Callback will execute in interrupt context 89 * @addtogroup spi_async 90 */ 91 typedef void (*spimss_callback_fn)(spimss_req_t * req, int error_code); 92 93 /** 94 * @brief Structure definition for an SPI Master Transaction request. 95 * @note When using this structure for an asynchronous operation, the 96 * structure must remain allocated until the callback is completed. 97 * @addtogroup spi_async 98 */ 99 struct spimss_req { 100 uint8_t ssel; /**< Not Used*/ 101 uint8_t deass; /**< Not Used*/ 102 const void *tx_data; /**< Pointer to a buffer to transmit data from. NULL if undesired. */ 103 void *rx_data; /**< Pointer to a buffer to store data received. NULL if undesired.*/ 104 spimss_width_t width; /**< Not Used */ 105 unsigned len; /**< Number of transfer units to send from the \p tx_data buffer. */ 106 unsigned bits; /**< Number of bits in transfer unit (e.g. 8 for byte, 16 for short) */ 107 unsigned rx_num; /**< Number of bytes actually read into the \p rx_data buffer. */ 108 unsigned tx_num; /**< Number of bytes actually sent from the \p tx_data buffer */ 109 spimss_callback_fn callback; /**< Callback function if desired, NULL otherwise */ 110 }; 111 112 /* **** Function Prototypes **** */ 113 114 /** 115 * @brief Initialize the spi. 116 * @param spi Pointer to spi module to initialize. 117 * @param mode SPI mode for clock phase and polarity. 118 * @param freq Desired clock frequency. 119 * @param sys_cfg System configuration object 120 * 121 * @return \c #E_NO_ERROR if successful, appropriate error otherwise 122 */ 123 int SPIMSS_Init(mxc_spimss_regs_t *spi, unsigned mode, unsigned freq, const sys_cfg_spimss_t* sys_cfg); 124 125 /** 126 * @brief Shutdown SPI module. 127 * @param spi Pointer to SPI regs. 128 * 129 * @return \c #E_NO_ERROR if successful, appropriate error otherwise 130 */ 131 int SPIMSS_Shutdown(mxc_spimss_regs_t *spi); 132 133 /** 134 * @brief Execute a master transaction. 135 * @param spi Pointer to spi module. 136 * @param req Pointer to spi request 137 * 138 * @return \c #E_NO_ERROR if successful, @ref 139 * MXC_Error_Codes "error" if unsuccessful. 140 */ 141 int SPIMSS_MasterTrans(mxc_spimss_regs_t *spi, spimss_req_t *req); 142 143 /** 144 * @brief Execute SPI transaction based on interrupt handler 145 * @param spi The spi 146 * 147 */ 148 void SPIMSS_Handler(mxc_spimss_regs_t *spi); 149 150 /** 151 * @brief Execute a slave transaction. 152 * @param spi Pointer to spi module. 153 * @param req Pointer to spi request 154 * 155 * @return \c #E_NO_ERROR if successful, @ref 156 * MXC_Error_Codes "error" if unsuccessful. 157 */ 158 int SPIMSS_SlaveTrans(mxc_spimss_regs_t *spi, spimss_req_t *req); 159 160 /** 161 * @brief Asynchronously read/write SPI Master data 162 * 163 * @param spi Pointer to spi module 164 * @param req Pointer to spi request 165 * 166 * @return \c #E_NO_ERROR if successful, @ref 167 * MXC_Error_Codes "error" if unsuccessful. 168 */ 169 int SPIMSS_MasterTransAsync(mxc_spimss_regs_t *spi, spimss_req_t *req); 170 171 /** 172 * @brief Asynchronously read/write SPI Slave data 173 * 174 * @param spi Pointer to spi module 175 * @param req Pointer to spi request 176 * 177 * @return \c #E_NO_ERROR if successful, @ref 178 * MXC_Error_Codes "error" if unsuccessful. 179 */ 180 int SPIMSS_SlaveTransAsync(mxc_spimss_regs_t *spi, spimss_req_t *req); 181 182 /** 183 * @brief Aborts an Asynchronous request 184 * 185 * @param req Pointer to spi request 186 * @return \c #E_NO_ERROR if successful, @ref 187 * MXC_Error_Codes "error" if unsuccessful. 188 */ 189 int SPIMSS_AbortAsync(spimss_req_t *req); 190 191 /**@} end of group spimss */ 192 193 #ifdef __cplusplus 194 } 195 #endif 196 197 #endif /* _SPIMSS_H_ */ 198