spi.h 8.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259
  1. /**
  2. * @file spi.h
  3. * @brief Serial Peripheral Interface (SPIMSS) function prototypes and data types.
  4. */
  5. /* ****************************************************************************
  6. * Copyright (C) 2017 Maxim Integrated Products, Inc., All Rights Reserved.
  7. *
  8. * Permission is hereby granted, free of charge, to any person obtaining a
  9. * copy of this software and associated documentation files (the "Software"),
  10. * to deal in the Software without restriction, including without limitation
  11. * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  12. * and/or sell copies of the Software, and to permit persons to whom the
  13. * Software is furnished to do so, subject to the following conditions:
  14. *
  15. * The above copyright notice and this permission notice shall be included
  16. * in all copies or substantial portions of the Software.
  17. *
  18. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  19. * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  20. * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  21. * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
  22. * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  23. * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  24. * OTHER DEALINGS IN THE SOFTWARE.
  25. *
  26. * Except as contained in this notice, the name of Maxim Integrated
  27. * Products, Inc. shall not be used except as stated in the Maxim Integrated
  28. * Products, Inc. Branding Policy.
  29. *
  30. * The mere transfer of this software does not imply any licenses
  31. * of trade secrets, proprietary technology, copyrights, patents,
  32. * trademarks, maskwork rights, or any other form of intellectual
  33. * property whatsoever. Maxim Integrated Products, Inc. retains all
  34. * ownership rights.
  35. *
  36. * $Date: 2018-11-07 14:48:15 -0600 (Wed, 07 Nov 2018) $
  37. * $Revision: 39010 $
  38. *
  39. *************************************************************************** */
  40. /* Define to prevent redundant inclusion */
  41. #ifndef _SPI_H_
  42. #define _SPI_H_
  43. /* **** Includes **** */
  44. #include "spi17y_regs.h"
  45. #include "spimss_regs.h"
  46. #include "spimss.h"
  47. #include "spi17y.h"
  48. #include "mxc_sys.h"
  49. #ifdef __cplusplus
  50. extern "C" {
  51. #endif
  52. /**
  53. * @defgroup spi SPI
  54. * @ingroup periphlibs
  55. * @{
  56. */
  57. /* **** Definitions **** */
  58. /**
  59. * @brief Enums assigning numbers to SPI
  60. */
  61. typedef enum {
  62. SPI0A, // SPI17Y (0A)
  63. SPI1A, // SPIMSS (1A)
  64. SPI1B, // SPIMSS (1B)
  65. }spi_type;
  66. /**
  67. * @brief Renaming the SPI address names
  68. */
  69. #define MXC_SPI0 MXC_SPI17Y // SPI0A
  70. #define MXC_SPI1 MXC_SPIMSS // SPI1A & SPI1B
  71. /**
  72. * @brief Renaming Interrupt SPI Interrupt sources
  73. */
  74. #define SPI0_IRQn SPI17Y_IRQn // SPI0A
  75. #define SPI1_IRQn SPIMSS_IRQn // SPI1A & SPI1B
  76. /**
  77. * @brief Renaming SPI Width
  78. */
  79. #define SPI0_WIDTH_1 SPI17Y_WIDTH_1 /**< 1 Data Line. */
  80. #define SPI0_WIDTH_2 SPI17Y_WIDTH_2 /**< 2 Data Lines (x2). */
  81. #define SPI0_WIDTH_4 SPI17Y_WIDTH_4 /**< 4 Data Lines (x4). */
  82. /**
  83. * @brief Renaming SPI Polarity
  84. */
  85. #define SPI_POL_LOW SPI17Y_POL_LOW /**< Slave Select polarity Low. */
  86. #define SPI_POL_HIGH SPI17Y_POL_HIGH /**< Slave Select polarity High. */
  87. /**
  88. * @brief Structure type representing a SPI Master Transaction request.
  89. */
  90. typedef struct spi_req spi_req_t;
  91. /**
  92. * @brief Callback function type used in asynchronous SPI Master communication requests.
  93. * @details The function declaration for the SPI Master callback is:
  94. * @code
  95. * void callback(spi_req_t * req, int error_code);
  96. * @endcode
  97. * | | |
  98. * | -----: | :----------------------------------------- |
  99. * | \p req | Pointer to a #spi_req object representing the active SPI Master active transaction. |
  100. * | \p error_code | An error code if the active transaction had a failure or #E_NO_ERROR if successful. |
  101. * @note Callback will execute in interrupt context
  102. * @addtogroup spi_async
  103. */
  104. typedef void (*spi_callback_fn)(void * req, int error_code);
  105. /**
  106. * @brief Structure definition for an SPI Master Transaction request.
  107. * @note When using this structure for an asynchronous operation, the
  108. * structure must remain allocated until the callback is completed.
  109. * @addtogroup spi_async
  110. */
  111. struct spi_req {
  112. uint8_t ssel; /**< Slave select line to use. (Master only) */
  113. uint8_t deass; /**< Non-zero to de-assert slave select after transaction. (Master only)*/
  114. spi17y_sspol_t ssel_pol; /**< Slave select line polarity. */
  115. const void *tx_data; /**< Pointer to a buffer to transmit data from. NULL if undesired. */
  116. void *rx_data; /**< Pointer to a buffer to store data received. NULL if undesired.*/
  117. spi17y_width_t width; /**< Number of data lines to use, see #spi17y_width_t. */
  118. unsigned len; /**< Number of transfer units to send from the \p tx_data buffer. */
  119. unsigned bits; /**< Number of bits in transfer unit (e.g. 8 for byte, 16 for short) */
  120. unsigned rx_num; /**< Number of bytes actually read into the \p rx_data buffer. */
  121. unsigned tx_num; /**< Number of bytes actually sent from the \p tx_data buffer */
  122. spi_callback_fn callback; /**< Callback function if desired, NULL otherwise */
  123. };
  124. /* **** Function Prototypes **** */
  125. /**
  126. * @brief Initialize the spi.
  127. * @param spi_name spi module to initialize.
  128. * @param mode SPI mode for clock phase and polarity.
  129. * @param freq Desired clock frequency.
  130. *
  131. * @return #E_NO_ERROR if successful, @ref
  132. * MXC_Error_Codes "error" if unsuccessful.
  133. */
  134. int SPI_Init(spi_type spi_name, unsigned mode, unsigned freq);
  135. /**
  136. * @brief Asynchronously read/write SPI Master data
  137. *
  138. * @param spi_name SPI instance being used
  139. * @param req Pointer to spi request
  140. *
  141. * @return #E_NO_ERROR if successful, @ref
  142. * MXC_Error_Codes "error" if unsuccessful.
  143. */
  144. int SPI_MasterTransAsync(spi_type spi_name, spi_req_t *req);
  145. /**
  146. * @brief Execute a master transaction.
  147. * @param spi_name SPI instance being used
  148. * @param req Pointer to spi request
  149. *
  150. * @return #E_NO_ERROR if successful, @ref
  151. * MXC_Error_Codes "error" if unsuccessful.
  152. */
  153. int SPI_MasterTrans(spi_type spi_name, spi_req_t *req);
  154. /**
  155. * @brief Asynchronously read/write SPI Slave data
  156. * @param spi_name SPI instance being used
  157. * @param req Pointer to spi request
  158. *
  159. * @return #E_NO_ERROR if successful, @ref
  160. * MXC_Error_Codes "error" if unsuccessful.
  161. */
  162. int SPI_SlaveTransAsync(spi_type spi_name, spi_req_t *req);
  163. /**
  164. * @brief Execute a slave transaction.
  165. * @param spi_name SPI instance being used
  166. * @param req Pointer to spi request
  167. *
  168. * @return #E_NO_ERROR if successful, @ref
  169. * MXC_Error_Codes "error" if unsuccessful.
  170. */
  171. int SPI_SlaveTrans(spi_type spi_name, spi_req_t *req);
  172. /**
  173. * @brief Shutdown SPI module.
  174. * @param spi_name SPI instance being used
  175. *
  176. * @return #E_NO_ERROR if successful, appropriate error otherwise
  177. */
  178. int SPI_Shutdown(spi_type spi_name);
  179. /**
  180. * @brief Aborts an Asynchronous request
  181. * @param spi_name SPI instance being used
  182. * @param req Pointer to spi request
  183. *
  184. * @return #E_NO_ERROR if successful, @ref
  185. * MXC_Error_Codes "error" if unsuccessful.
  186. */
  187. int SPI_AbortAsync(spi_type spi_name, spi_req_t *req);
  188. /**
  189. * @brief Execute SPI transaction based on interrupt handler
  190. * @param spi_name SPI instance being used
  191. *
  192. * @return #E_NO_ERROR if successful,
  193. * @return #E_BAD_PARAM otherwise
  194. */
  195. int SPI_Handler(spi_type spi_name);
  196. /**
  197. * @brief Enable SPI
  198. * @param spi_name Pointer to spi module.
  199. *
  200. * @return #E_NO_ERROR if successful, appropriate error otherwise
  201. */
  202. int SPI_Enable(spi_type spi_name);
  203. /**
  204. * @brief Disable SPI
  205. * @param spi_name Pointer to spi module.
  206. *
  207. * @return #E_NO_ERROR if successful, appropriate error otherwise
  208. */
  209. int SPI_Disable(spi_type spi_name);
  210. /**
  211. * @brief Clear the TX and RX FIFO
  212. * @param spi_name Pointer to spi module.
  213. *
  214. * @return #E_NO_ERROR if successful, appropriate error otherwise
  215. */
  216. int SPI_Clear_fifo(spi_type spi_name);
  217. //-------------------------------------------------------------------------------------------
  218. /**@} end of group spi */
  219. #ifdef __cplusplus
  220. }
  221. #endif
  222. #endif /* _SPI_H_ */