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