1 /*
2 * Copyright (c) 2016, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
33 /**
34 * \ingroup DRV_SPI_MODULE
35 * \defgroup DRV_SPI_MCSPI_MODULE SPI Driver MCSPI API
36 * Multi-Channel SPI driver interface
37 * @{
38 */
40 /** ============================================================================
41 * @file MCSPI.h
42 *
43 * @brief Multi-Channel SPI driver interface
44 *
45 * The MCSPI header file should be included in an application as follows:
46 * @code
47 * #include <ti/drv/spi/MCSPI.h>
48 * @endcode
49 *
50 * ============================================================================
51 */
53 #ifndef MCSPI_H
54 #define MCSPI_H
56 #ifdef __cplusplus
57 extern "C" {
58 #endif
60 #include <ti/drv/spi/SPI.h>
62 /*!
63 * @brief Max number of MCSPI peripheral instances
64 */
65 #define MCSPI_MAX_NUM_INSTANCES (SPI_MAX_CONFIG_CNT)
67 /*!
68 * @brief Max number of channels of a MCSPI peripheral instance
69 */
70 #define MCSPI_MAX_NUM_CHANNELS (4U)
72 /*!
73 * @brief A handle that is returned from a MCSPI_open() call.
74 */
75 typedef struct MCSPI_Config_s *MCSPI_Handle;
77 /*!
78 * @brief The definition of a callback function used by the MCSPI driver
79 * when used in ::SPI_MODE_CALLBACK
80 */
81 typedef void (*MCSPI_CallbackFxn) (MCSPI_Handle handle,
82 SPI_Transaction *transaction);
84 /*!
85 * @brief MCSPI Parameters
86 *
87 * MCSPI Parameters are used to with the MCSPI_open() call. Default values for
88 * these parameters are set using MCSPI_Params_init().
89 *
90 * @sa MCSPI_Params_init()
91 */
92 typedef struct MCSPI_Params_s {
93 SPI_TransferMode transferMode; /*!< Blocking or Callback mode */
94 uint32_t transferTimeout; /*!< Transfer timeout in system
95 ticks (Not supported with all
96 implementations */
97 MCSPI_CallbackFxn transferCallbackFxn;/*!< Callback function pointer */
98 SPI_Mode mode; /*!< Master or Slave mode, all the channels on the same
99 instance should have the same mode */
100 uint32_t bitRate; /*!< SPI bit rate in Hz in single channle mode */
101 uint32_t dataSize; /*!< SPI data frame size in bits in single channle mode */
102 SPI_FrameFormat frameFormat; /*!< SPI frame format in single channle mode */
103 void *custom; /*!< Custom argument used by driver
104 implementation */
106 } MCSPI_Params;
108 /*!
109 * @brief A function pointer to a driver specific implementation of
110 * MCSPI_close().
111 */
112 typedef void (*MCSPI_CloseFxn) (MCSPI_Handle handle);
114 /*!
115 * @brief A function pointer to a driver specific implementation of
116 * MCSPI_control().
117 */
118 typedef int32_t (*MCSPI_ControlFxn) (MCSPI_Handle handle,
119 uint32_t cmd,
120 const void *arg);
122 /*!
123 * @brief A function pointer to a driver specific implementation of
124 * MCSPI_init().
125 */
126 typedef void (*MCSPI_InitFxn) (MCSPI_Handle handle);
128 /*!
129 * @brief A function pointer to a driver specific implementation of
130 * MCSPI_open().
131 */
132 typedef MCSPI_Handle (*MCSPI_OpenFxn) (MCSPI_Handle handle,
133 const MCSPI_Params *params);
135 /*!
136 * @brief A function pointer to a driver specific implementation of
137 * MCSPI_transfer().
138 */
139 typedef bool (*MCSPI_TransferFxn) (MCSPI_Handle handle,
140 SPI_Transaction *transaction);
142 /*!
143 * @brief A function pointer to a driver specific implementation of
144 * MCSPI_transferCancel().
145 */
146 typedef void (*MCSPI_TransferCancelFxn) (MCSPI_Handle handle);
148 /*!
149 * @brief The definition of a MCSPI function table that contains the
150 * required set of functions to control a specific MCSPI driver
151 * implementation.
152 */
153 typedef struct MCSPI_FxnTable_s {
154 /*! Function to close the specified peripheral */
155 MCSPI_CloseFxn closeFxn;
157 /*! Function to implementation specific control function */
158 MCSPI_ControlFxn controlFxn;
160 /*! Function to initialize the given data object */
161 MCSPI_InitFxn mcspiInitFxn;
163 /*! Function to open the specified peripheral */
164 MCSPI_OpenFxn openFxn;
166 /*! Function to initiate a MCSPI data transfer */
167 MCSPI_TransferFxn transferFxn;
169 /*! Function to cancel MCSPI data transfer */
170 MCSPI_TransferCancelFxn transferCancelFxn;
172 } MCSPI_FxnTable;
174 /*!
175 * @brief MCSPI Global configuration
176 *
177 * The MCSPI_Config structure contains a set of pointers used to characterize
178 * the MCSPI driver implementation.
179 *
180 * This structure needs to be defined before calling MCSPI_init() and it must
181 * not be changed thereafter.
182 *
183 * @sa MCSPI_init()
184 */
185 typedef struct MCSPI_Config_s {
186 /*! Pointer to a table of driver-specific implementations of MCSPI APIs */
187 MCSPI_FxnTable const *fxnTablePtr;
189 /*! Pointer to a SPI instance specific configuration data object */
190 SPI_Handle handle;
192 /*! channel number */
193 uint32_t chnNum;
195 } MCSPI_Config;
197 typedef MCSPI_Config MCSPI_config_list[MCSPI_MAX_NUM_INSTANCES][MCSPI_MAX_NUM_CHANNELS];
199 /*!
200 * @brief Function to close a channel of a SPI peripheral specified by the MCSPI handle
201 *
202 * @pre MCSPI_open() has to be called first.
203 *
204 * @param handle A MCSPI handle returned from MCSPI_open()
205 *
206 * @sa MCSPI_open()
207 */
208 extern void MCSPI_close(MCSPI_Handle handle);
210 /*!
211 * @brief Function performs implementation specific features on a
212 * channel of a SPI peripheral specified by the MCSPI handle.
213 *
214 * @pre MCSPI_open() has to be called first.
215 *
216 * @param handle A MCSPI handle returned from MCSPI_open()
217 *
218 * @param cmd A command value defined by the driver specific
219 * implementation
220 *
221 * @param arg An optional R/W (read/write) argument that is
222 * accompanied with cmd
223 *
224 * @return Implementation specific return codes. Negative values indicate
225 * unsuccessful operations.
226 *
227 * @sa MCSPI_open()
228 */
229 extern int32_t MCSPI_control(MCSPI_Handle handle, uint32_t cmd, void *arg);
231 /*!
232 * @brief This function initializes the MCSPI module.
233 *
234 * @pre The MCSPI_config structure must exist and be persistent before this
235 * function can be called. This function must also be called before
236 * any other MCSPI driver APIs. This function call does not modify any
237 * peripheral registers.
238 */
239 extern void MCSPI_init(void);
241 /*!
242 * @brief This function opens a given channel of a given MCSPI peripheral.
243 *
244 * @pre MCSPI controller has been initialized using MCSPI_init()
245 *
246 * @param idx Logical peripheral number for the MCSPI indexed into
247 * the MCSPI_config table
248 *
249 * @param channel Channel number of the SPI peripheral
250 *
251 * @param params Pointer to an parameter block, if NULL it will use
252 * default values. All the fields in this structure are
253 * RO (read-only).
254 *
255 * @return A MCSPI_Handle on success or a NULL on an error or if it has been
256 * opened already.
257 *
258 * @sa MCSPI_init()
259 * @sa MCSPI_close()
260 */
261 extern MCSPI_Handle MCSPI_open(uint32_t idx, uint32_t channel, MCSPI_Params *params);
263 /*!
264 * @brief Function to initialize the MCSPI_Params struct to its defaults
265 *
266 * @param params An pointer to MCSPI_Params structure for
267 * initialization
268 *
269 * Defaults values are:
270 * transferMode = SPI_MODE_BLOCKING
271 * transferTimeout = SPI_WAIT_FOREVER
272 * transferCallbackFxn = NULL
273 * mode = SPI_MASTER
274 * bitRate = 1000000 (Hz)
275 * dataSize = 8 (bits)
276 * frameFormat = SPI_POL0_PHA0
277 */
278 extern void MCSPI_Params_init(MCSPI_Params *params);
280 /*!
281 * @brief Function to perform SPI transactions on a channel of
282 * a SPI peripheral specified by the MCSPI handle.
283 *
284 * If the MCSPI is in ::SPI_MASTER mode, it will immediately start the
285 * transaction. If the MCSPI is in ::SPI_SLAVE mode, it prepares itself for a
286 * transaction with a SPI master.
287 *
288 * In ::SPI_MODE_BLOCKING, MCSPI_transfer will block task execution until the
289 * transaction has completed.
290 *
291 * In ::SPI_MODE_CALLBACK, MCSPI_transfer() does not block task execution and
292 * calls a ::MCSPI_CallbackFxn. This makes the MCSPI_tranfer() safe to be used
293 * within a Task, Swi, or Hwi context. The ::SPI_Transaction structure must
294 * stay persistent until the MCSPI_transfer function has completed!
295 *
296 * @param handle A MCSPI_Handle
297 *
298 * @param spiTrans A pointer to a SPI_Transaction. All of the fields within
299 * transaction except SPI_Transaction.count and
300 * SPI_Transaction.status are WO (write-only) unless
301 * otherwise noted in the driver implementations. If a
302 * transaction timeout has occured, SPI_Transaction.count
303 * will contain the number of frames that were transferred.
304 *
305 * @return true if started successfully; else false
306 *
307 * @sa MCSPI_open
308 * @sa MCSPI_transferCancel
309 */
310 extern bool MCSPI_transfer(MCSPI_Handle handle, SPI_Transaction *spiTrans);
312 /*!
313 * @brief Function to cancel SPI transactions on channel of a
314 * SPI peripheral specified by the MCSPI handle.
315 *
316 * In ::SPI_MODE_BLOCKING, MCSPI_transferCancel has no effect.
317 *
318 * In ::SPI_MODE_CALLBACK, MCSPI_transferCancel() will stop an MCSPI transfer if
319 * if one is in progress.
320 * If a transaction was in progress, its callback function will be called
321 * in context from which this API is called from. The ::MCSPI_CallbackFxn
322 * function can determine if the transaction was successful or not by reading
323 * the ::SPI_Status status value in the ::SPI_Transaction structure.
324 *
325 * @param handle A MCSPI_Handle
326 *
327 * @sa MCSPI_open
328 * @sa MCSPI_transfer
329 */
330 extern void MCSPI_transferCancel(MCSPI_Handle handle);
332 #ifdef __cplusplus
333 }
334 #endif
336 #endif /* _MCSPI_H */
338 /* @} */