1 /** 2 * @file spimss.h 3 * @brief Serial Peripheral Interface (SPIMSS) function prototypes and data types. 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 /* Define to prevent redundant inclusion */ 27 #ifndef LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32660_SPIMSS_H_ 28 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32660_SPIMSS_H_ 29 30 /* **** Includes **** */ 31 #include "mxc_device.h" 32 #include "mxc_sys.h" 33 #include "mxc_pins.h" 34 #include "gpio.h" 35 #include "spimss_regs.h" 36 #include "stdbool.h" 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /** 43 * @defgroup spimss SPIMSS 44 * @ingroup spimss 45 * @{ 46 */ 47 48 /* **** Definitions **** */ 49 50 /** 51 * @brief Enumeration type for setting the number data lines to use for communication. 52 */ 53 typedef enum { // ONLY FOR COMPATIBILITY FOR CONSOLIDATION WITH SPY17, NOT USED OR NEEDED 54 DUMMY_1, /**< NOT USED */ 55 DUMMY_2, /**< NOT USED */ 56 DUMMY_3, /**< NOT USED */ 57 } mxc_spimss_width_t; 58 59 /** 60 * @brief Structure type representing a SPI Master Transaction request. 61 */ 62 typedef struct mxc_spimss_req mxc_spimss_req_t; 63 64 /** 65 * @brief Callback function type used in asynchronous SPI Master communication requests. 66 * @details The function declaration for the SPI Master callback is: 67 * @code 68 * void callback(spi_req_t * req, int error_code); 69 * @endcode 70 * | | | 71 * | -----: | :----------------------------------------- | 72 * | \p req | Pointer to a #spi_req object representing the active SPI Master active transaction. | 73 * | \p error_code | An error code if the active transaction had a failure or #E_NO_ERROR if successful. | 74 * @note Callback will execute in interrupt context 75 */ 76 typedef void (*mxc_spimss_callback_fn)(mxc_spimss_req_t *req, int error_code); 77 78 /** 79 * @brief Structure definition for an SPI Master Transaction request. 80 * @note When using this structure for an asynchronous operation, the 81 * structure must remain allocated until the callback is completed. 82 */ 83 struct mxc_spimss_req { 84 uint8_t ssel; /**< Not Used*/ 85 uint8_t deass; /**< Not Used*/ 86 void *tx_data; /**< Pointer to a buffer to transmit data from. NULL if undesired. */ 87 void *rx_data; /**< Pointer to a buffer to store data received. NULL if undesired.*/ 88 mxc_spimss_width_t width; /**< Not Used */ 89 unsigned len; /**< Number of transfer units to send from the \p tx_data buffer. */ 90 unsigned bits; /**< Number of bits in transfer unit (e.g. 8 for byte, 16 for short) */ 91 unsigned rx_num; /**< Number of bytes actually read into the \p rx_data buffer. */ 92 unsigned tx_num; /**< Number of bytes actually sent from the \p tx_data buffer */ 93 mxc_spimss_callback_fn callback; /**< Callback function if desired, NULL otherwise */ 94 }; 95 96 /* **** Function Prototypes **** */ 97 98 /** 99 * @brief Initialize the spi. 100 * @param spi Pointer to spi module to initialize. 101 * @param mode SPI mode for clock phase and polarity. 102 * @param freq Desired clock frequency. 103 * @param sys_cfg System configuration object 104 * 105 * @return \c #E_NO_ERROR if successful, appropriate error otherwise 106 */ 107 int MXC_SPIMSS_Init(mxc_spimss_regs_t *spi, unsigned mode, unsigned freq, const sys_map_t sys_cfg); 108 109 /** 110 * @brief Shutdown SPI module. 111 * @param spi Pointer to SPI regs. 112 * 113 * @return \c #E_NO_ERROR if successful, appropriate error otherwise 114 */ 115 int MXC_SPIMSS_Shutdown(mxc_spimss_regs_t *spi); 116 117 /** 118 * @brief Execute a master transaction. 119 * @param spi Pointer to spi module. 120 * @param req Pointer to spi request 121 * 122 * @return \c #E_NO_ERROR if successful, @ref 123 * MXC_Error_Codes "error" if unsuccessful. 124 */ 125 int MXC_SPIMSS_MasterTrans(mxc_spimss_regs_t *spi, mxc_spimss_req_t *req); 126 127 /** 128 * @brief Execute a master transaction over DMA. 129 * @param spi Pointer to spi module. 130 * @param req Pointer to spi request. 131 * 132 * @return \c #E_NO_ERROR if successful, @ref 133 * MXC_Error_Codes "error" if unsuccessful. 134 */ 135 int MXC_SPIMSS_MasterTransDMA(mxc_spimss_regs_t *spi, mxc_spimss_req_t *req); 136 137 /** 138 * @brief Execute SPI transaction based on interrupt handler 139 * @param spi The spi 140 * 141 */ 142 void MXC_SPIMSS_Handler(mxc_spimss_regs_t *spi); 143 144 /** 145 * @brief Execute a slave transaction. 146 * @param spi Pointer to spi module. 147 * @param req Pointer to spi request 148 * 149 * @return \c #E_NO_ERROR if successful, @ref 150 * MXC_Error_Codes "error" if unsuccessful. 151 */ 152 int MXC_SPIMSS_SlaveTrans(mxc_spimss_regs_t *spi, mxc_spimss_req_t *req); 153 154 /** 155 * @brief Asynchronously read/write SPI Master data 156 * 157 * @param spi Pointer to spi module 158 * @param req Pointer to spi request 159 * 160 * @return \c #E_NO_ERROR if successful, @ref 161 * MXC_Error_Codes "error" if unsuccessful. 162 */ 163 int MXC_SPIMSS_MasterTransAsync(mxc_spimss_regs_t *spi, mxc_spimss_req_t *req); 164 165 /** 166 * @brief Asynchronously read/write SPI Slave data 167 * 168 * @param spi Pointer to spi module 169 * @param req Pointer to spi request 170 * 171 * @return \c #E_NO_ERROR if successful, @ref 172 * MXC_Error_Codes "error" if unsuccessful. 173 */ 174 int MXC_SPIMSS_SlaveTransAsync(mxc_spimss_regs_t *spi, mxc_spimss_req_t *req); 175 176 /** 177 * @brief Aborts an Asynchronous request 178 * 179 * @param req Pointer to spi request 180 * @return \c #E_NO_ERROR if successful, @ref 181 * MXC_Error_Codes "error" if unsuccessful. 182 */ 183 int MXC_SPIMSS_AbortAsync(mxc_spimss_req_t *req); 184 185 /** 186 * @brief Enable Disable auto dma handling. If set to true, dma channel for transaction 187 * is acquired in the MXC_SPIMSS_MasterTransDMA function. Otherwise, user has to set 188 * tx and rx channel for SPIMSS DMA transaction with MXC_SPIMSS_SetTXDMAChannel and 189 * MXC_SPIMSS_SetRXDMAChannel functions. 190 * 191 * @param spi Pointer to spi module 192 * @param enable Enable Disable auto handler 193 * @return \c #E_NO_ERROR if successful, @ref 194 * MXC_Error_Codes "error" if unsuccessful. 195 */ 196 int MXC_SPIMSS_SetAutoDMAHandlers(mxc_spimss_regs_t *spi, bool enable); 197 198 /** 199 * @brief Set the TX channel id for DMA to be used in SPIMSS DMA transaction. 200 * 201 * @param spi Pointer to spi module 202 * @param channel Id of the channel for TXDma Channel. 203 * @return \c #E_NO_ERROR if successful, @ref 204 * MXC_Error_Codes "error" if unsuccessful. 205 */ 206 int MXC_SPIMSS_SetTXDMAChannel(mxc_spimss_regs_t *spi, unsigned int channel); 207 208 /** 209 * @brief Returns the current TX channel id set for SPIMSS DMA transaction. 210 * 211 * @param spi Pointer to spi module 212 * @return \c #TXDMA_ChannelId of the spi module. 213 */ 214 int MXC_SPIMSS_GetTXDMAChannel(mxc_spimss_regs_t *spi); 215 216 /** 217 * @brief Set the RX channel id for DMA to be used in SPIMSS DMA transaction. 218 * 219 * @param spi Pointer to spi module 220 * @param channel Id of the channel for RXDma Channel. 221 * @return \c #E_NO_ERROR if successful, @ref 222 * MXC_Error_Codes "error" if unsuccessful. 223 */ 224 int MXC_SPIMSS_SetRXDMAChannel(mxc_spimss_regs_t *spi, unsigned int channel); 225 226 /** 227 * @brief Returns the current RX channel id set for SPIMSS DMA transaction. 228 * 229 * @param spi Pointer to spi module 230 * @return \c #RXDMA_ChannelId of the spi module. 231 */ 232 int MXC_SPIMSS_GetRXDMAChannel(mxc_spimss_regs_t *spi); 233 234 /**@} end of group spimss */ 235 236 #ifdef __cplusplus 237 } 238 #endif 239 240 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32660_SPIMSS_H_ 241
