1 /* ----------------------------------------------------------------------------- 2 * SPDX-License-Identifier: Zlib 3 * Copyright (c) 2013-2014 ARM Ltd. 4 * 5 * This software is provided 'as-is', without any express or implied warranty. 6 * In no event will the authors be held liable for any damages arising from 7 * the use of this software. Permission is granted to anyone to use this 8 * software for any purpose, including commercial applications, and to alter 9 * it and redistribute it freely, subject to the following restrictions: 10 * 11 * 1. The origin of this software must not be misrepresented; you must not 12 * claim that you wrote the original software. If you use this software in 13 * a product, an acknowledgment in the product documentation would be 14 * appreciated but is not required. 15 * 16 * 2. Altered source versions must be plainly marked as such, and must not be 17 * misrepresented as being the original software. 18 * 19 * 3. This notice may not be removed or altered from any source distribution. 20 * 21 * 22 * $Date: 17. Apr 2014 23 * $Revision: V2.01 24 * 25 * Project: SPI (Serial Peripheral Interface) Driver definitions 26 * -------------------------------------------------------------------------- */ 27 28 /* History: 29 * Version 2.01 30 * Renamed status flag "tx_rx_busy" to "busy" 31 * Version 2.00 32 * New simplified driver: 33 * complexity moved to upper layer (especially data handling) 34 * more unified API for different communication interfaces 35 * Added: 36 * Slave Mode 37 * Half-duplex Modes 38 * Configurable number of data bits 39 * Support for TI Mode and Microwire 40 * Changed prefix ARM_DRV -> ARM_DRIVER 41 * Version 1.10 42 * Namespace prefix ARM_ added 43 * Version 1.01 44 * Added "send_done_event" to Capabilities 45 * Version 1.00 46 * Initial release 47 */ 48 49 #ifndef __DRIVER_SPI_H 50 #define __DRIVER_SPI_H 51 52 #include "Driver_Common.h" 53 54 #define ARM_SPI_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,00) /* API version */ 55 56 57 /****** SPI Control Codes *****/ 58 59 #define ARM_SPI_CONTROL_Pos 0 60 #define ARM_SPI_CONTROL_Msk (0xFFUL << ARM_SPI_CONTROL_Pos) 61 62 /*----- SPI Control Codes: Mode -----*/ 63 #define ARM_SPI_MODE_INACTIVE (0x00UL << ARM_SPI_CONTROL_Pos) ///< SPI Inactive 64 #define ARM_SPI_MODE_MASTER (0x01UL << ARM_SPI_CONTROL_Pos) ///< SPI Master (Output on MOSI, Input on MISO); arg = Bus Speed in bps 65 #define ARM_SPI_MODE_SLAVE (0x02UL << ARM_SPI_CONTROL_Pos) ///< SPI Slave (Output on MISO, Input on MOSI) 66 #define ARM_SPI_MODE_MASTER_SIMPLEX (0x03UL << ARM_SPI_CONTROL_Pos) ///< SPI Master (Output/Input on MOSI); arg = Bus Speed in bps 67 #define ARM_SPI_MODE_SLAVE_SIMPLEX (0x04UL << ARM_SPI_CONTROL_Pos) ///< SPI Slave (Output/Input on MISO) 68 69 /*----- SPI Control Codes: Mode Parameters: Frame Format -----*/ 70 #define ARM_SPI_FRAME_FORMAT_Pos 8 71 #define ARM_SPI_FRAME_FORMAT_Msk (7UL << ARM_SPI_FRAME_FORMAT_Pos) 72 #define ARM_SPI_CPOL0_CPHA0 (0UL << ARM_SPI_FRAME_FORMAT_Pos) ///< Clock Polarity 0, Clock Phase 0 (default) 73 #define ARM_SPI_CPOL0_CPHA1 (1UL << ARM_SPI_FRAME_FORMAT_Pos) ///< Clock Polarity 0, Clock Phase 1 74 #define ARM_SPI_CPOL1_CPHA0 (2UL << ARM_SPI_FRAME_FORMAT_Pos) ///< Clock Polarity 1, Clock Phase 0 75 #define ARM_SPI_CPOL1_CPHA1 (3UL << ARM_SPI_FRAME_FORMAT_Pos) ///< Clock Polarity 1, Clock Phase 1 76 #define ARM_SPI_TI_SSI (4UL << ARM_SPI_FRAME_FORMAT_Pos) ///< Texas Instruments Frame Format 77 #define ARM_SPI_MICROWIRE (5UL << ARM_SPI_FRAME_FORMAT_Pos) ///< National Microwire Frame Format 78 79 /*----- SPI Control Codes: Mode Parameters: Data Bits -----*/ 80 #define ARM_SPI_DATA_BITS_Pos 12 81 #define ARM_SPI_DATA_BITS_Msk (0x3FUL << ARM_SPI_DATA_BITS_Pos) 82 #define ARM_SPI_DATA_BITS(n) (((n) & 0x3F) << ARM_SPI_DATA_BITS_Pos) ///< Number of Data bits 83 84 /*----- SPI Control Codes: Mode Parameters: Bit Order -----*/ 85 #define ARM_SPI_BIT_ORDER_Pos 18 86 #define ARM_SPI_BIT_ORDER_Msk (1UL << ARM_SPI_BIT_ORDER_Pos) 87 #define ARM_SPI_MSB_LSB (0UL << ARM_SPI_BIT_ORDER_Pos) ///< SPI Bit order from MSB to LSB (default) 88 #define ARM_SPI_LSB_MSB (1UL << ARM_SPI_BIT_ORDER_Pos) ///< SPI Bit order from LSB to MSB 89 90 /*----- SPI Control Codes: Mode Parameters: Slave Select Mode -----*/ 91 #define ARM_SPI_SS_MASTER_MODE_Pos 19 92 #define ARM_SPI_SS_MASTER_MODE_Msk (3UL << ARM_SPI_SS_MASTER_MODE_Pos) 93 #define ARM_SPI_SS_MASTER_UNUSED (0UL << ARM_SPI_SS_MASTER_MODE_Pos) ///< SPI Slave Select when Master: Not used (default) 94 #define ARM_SPI_SS_MASTER_SW (1UL << ARM_SPI_SS_MASTER_MODE_Pos) ///< SPI Slave Select when Master: Software controlled 95 #define ARM_SPI_SS_MASTER_HW_OUTPUT (2UL << ARM_SPI_SS_MASTER_MODE_Pos) ///< SPI Slave Select when Master: Hardware controlled Output 96 #define ARM_SPI_SS_MASTER_HW_INPUT (3UL << ARM_SPI_SS_MASTER_MODE_Pos) ///< SPI Slave Select when Master: Hardware monitored Input 97 #define ARM_SPI_SS_SLAVE_MODE_Pos 21 98 #define ARM_SPI_SS_SLAVE_MODE_Msk (1UL << ARM_SPI_SS_SLAVE_MODE_Pos) 99 #define ARM_SPI_SS_SLAVE_HW (0UL << ARM_SPI_SS_SLAVE_MODE_Pos) ///< SPI Slave Select when Slave: Hardware monitored (default) 100 #define ARM_SPI_SS_SLAVE_SW (1UL << ARM_SPI_SS_SLAVE_MODE_Pos) ///< SPI Slave Select when Slave: Software controlled 101 102 103 /*----- SPI Control Codes: Miscellaneous Controls -----*/ 104 #define ARM_SPI_SET_BUS_SPEED (0x10UL << ARM_SPI_CONTROL_Pos) ///< Set Bus Speed in bps; arg = value 105 #define ARM_SPI_GET_BUS_SPEED (0x11UL << ARM_SPI_CONTROL_Pos) ///< Get Bus Speed in bps 106 #define ARM_SPI_SET_DEFAULT_TX_VALUE (0x12UL << ARM_SPI_CONTROL_Pos) ///< Set default Transmit value; arg = value 107 #define ARM_SPI_CONTROL_SS (0x13UL << ARM_SPI_CONTROL_Pos) ///< Control Slave Select; arg: 0=inactive, 1=active 108 #define ARM_SPI_ABORT_TRANSFER (0x14UL << ARM_SPI_CONTROL_Pos) ///< Abort current data transfer 109 110 111 /****** SPI Slave Select Signal definitions *****/ 112 #define ARM_SPI_SS_INACTIVE 0 ///< SPI Slave Select Signal Inactive 113 #define ARM_SPI_SS_ACTIVE 1 ///< SPI Slave Select Signal Active 114 115 116 /****** SPI specific error codes *****/ 117 #define ARM_SPI_ERROR_MODE (ARM_DRIVER_ERROR_SPECIFIC - 1) ///< Specified Mode not supported 118 #define ARM_SPI_ERROR_FRAME_FORMAT (ARM_DRIVER_ERROR_SPECIFIC - 2) ///< Specified Frame Format not supported 119 #define ARM_SPI_ERROR_DATA_BITS (ARM_DRIVER_ERROR_SPECIFIC - 3) ///< Specified number of Data bits not supported 120 #define ARM_SPI_ERROR_BIT_ORDER (ARM_DRIVER_ERROR_SPECIFIC - 4) ///< Specified Bit order not supported 121 #define ARM_SPI_ERROR_SS_MODE (ARM_DRIVER_ERROR_SPECIFIC - 5) ///< Specified Slave Select Mode not supported 122 123 124 /** 125 \brief SPI Status 126 */ 127 typedef struct _ARM_SPI_STATUS { 128 unsigned int busy : 1; ///< Transmitter/Receiver busy flag 129 unsigned int data_lost : 1; ///< Data lost: Receive overflow / Transmit underflow (cleared on start of transfer operation) 130 unsigned int mode_fault : 1; ///< Mode fault detected; optional (cleared on start of transfer operation) 131 } ARM_SPI_STATUS; 132 133 134 /****** SPI Event *****/ 135 #define ARM_SPI_EVENT_TRANSFER_COMPLETE (1UL << 0) ///< Data Transfer completed 136 #define ARM_SPI_EVENT_DATA_LOST (1UL << 1) ///< Data lost: Receive overflow / Transmit underflow 137 #define ARM_SPI_EVENT_MODE_FAULT (1UL << 2) ///< Master Mode Fault (SS deactivated when Master) 138 #define ARM_SPI_EVENT_SEND_COMPLETE (1UL << 3) ///< Master Mode Fault (SS deactivated when Master) 139 140 141 // Function documentation 142 /** 143 \fn ARM_DRIVER_VERSION ARM_SPI_GetVersion (void) 144 \brief Get driver version. 145 \return \ref ARM_DRIVER_VERSION 146 147 \fn ARM_SPI_CAPABILITIES ARM_SPI_GetCapabilities (void) 148 \brief Get driver capabilities. 149 \return \ref ARM_SPI_CAPABILITIES 150 151 \fn int32_t ARM_SPI_Initialize (ARM_SPI_SignalEvent_t cb_event) 152 \brief Initialize SPI Interface. 153 \param[in] cb_event Pointer to \ref ARM_SPI_SignalEvent 154 \return \ref execution_status 155 156 \fn int32_t ARM_SPI_Uninitialize (void) 157 \brief De-initialize SPI Interface. 158 \return \ref execution_status 159 160 \fn int32_t ARM_SPI_PowerControl (ARM_POWER_STATE state) 161 \brief Control SPI Interface Power. 162 \param[in] state Power state 163 \return \ref execution_status 164 165 \fn int32_t ARM_SPI_Send (const void *data, uint32_t num) 166 \brief Start sending data to SPI transmitter. 167 \param[in] data Pointer to buffer with data to send to SPI transmitter 168 \param[in] num Number of data items to send 169 \return \ref execution_status 170 171 \fn int32_t ARM_SPI_Receive (void *data, uint32_t num) 172 \brief Start receiving data from SPI receiver. 173 \param[out] data Pointer to buffer for data to receive from SPI receiver 174 \param[in] num Number of data items to receive 175 \return \ref execution_status 176 177 \fn int32_t ARM_SPI_Transfer (const void *data_out, 178 void *data_in, 179 uint32_t num) 180 \brief Start sending/receiving data to/from SPI transmitter/receiver. 181 \param[in] data_out Pointer to buffer with data to send to SPI transmitter 182 \param[out] data_in Pointer to buffer for data to receive from SPI receiver 183 \param[in] num Number of data items to transfer 184 \return \ref execution_status 185 186 \fn uint32_t ARM_SPI_GetDataCount (void) 187 \brief Get transferred data count. 188 \return number of data items transferred 189 190 \fn int32_t ARM_SPI_Control (uint32_t control, uint32_t arg) 191 \brief Control SPI Interface. 192 \param[in] control Operation 193 \param[in] arg Argument of operation (optional) 194 \return common \ref execution_status and driver specific \ref spi_execution_status 195 196 \fn ARM_SPI_STATUS ARM_SPI_GetStatus (void) 197 \brief Get SPI status. 198 \return SPI status \ref ARM_SPI_STATUS 199 200 \fn void ARM_SPI_SignalEvent (uint32_t event) 201 \brief Signal SPI Events. 202 \param[in] event \ref SPI_events notification mask 203 \return none 204 */ 205 206 typedef void (*ARM_SPI_SignalEvent_t) (uint32_t event); ///< Pointer to \ref ARM_SPI_SignalEvent : Signal SPI Event. 207 208 209 /** 210 \brief SPI Driver Capabilities. 211 */ 212 typedef struct _ARM_SPI_CAPABILITIES { 213 unsigned int simplex : 1; ///< supports Simplex Mode (Master and Slave) 214 unsigned int ti_ssi : 1; ///< supports TI Synchronous Serial Interface 215 unsigned int microwire : 1; ///< supports Microwire Interface 216 unsigned int event_mode_fault : 1; ///< Signal Mode Fault event: \ref ARM_SPI_EVENT_MODE_FAULT 217 } ARM_SPI_CAPABILITIES; 218 219 220 /** 221 \brief Access structure of the SPI Driver. 222 */ 223 typedef struct _ARM_DRIVER_SPI { 224 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_SPI_GetVersion : Get driver version. 225 ARM_SPI_CAPABILITIES (*GetCapabilities) (void); ///< Pointer to \ref ARM_SPI_GetCapabilities : Get driver capabilities. 226 int32_t (*Initialize) (ARM_SPI_SignalEvent_t cb_event); ///< Pointer to \ref ARM_SPI_Initialize : Initialize SPI Interface. 227 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_SPI_Uninitialize : De-initialize SPI Interface. 228 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_SPI_PowerControl : Control SPI Interface Power. 229 int32_t (*Send) (const void *data, uint32_t num); ///< Pointer to \ref ARM_SPI_Send : Start sending data to SPI Interface. 230 int32_t (*Receive) ( void *data, uint32_t num); ///< Pointer to \ref ARM_SPI_Receive : Start receiving data from SPI Interface. 231 int32_t (*Transfer) (const void *data_out, 232 void *data_in, 233 uint32_t num); ///< Pointer to \ref ARM_SPI_Transfer : Start sending/receiving data to/from SPI. 234 uint32_t (*GetDataCount) (void); ///< Pointer to \ref ARM_SPI_GetDataCount : Get transferred data count. 235 int32_t (*Control) (uint32_t control, uint32_t arg); ///< Pointer to \ref ARM_SPI_Control : Control SPI Interface. 236 ARM_SPI_STATUS (*GetStatus) (void); ///< Pointer to \ref ARM_SPI_GetStatus : Get SPI status. 237 } const ARM_DRIVER_SPI; 238 239 #endif /* __DRIVER_SPI_H */ 240
