1 /* 2 * Copyright (C) 2017 C-SKY Microsystems Co., Ltd. All rights reserved. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 /****************************************************************************** 17 * @file drv_spi.h 18 * @brief header file for spi driver 19 * @version V1.0 20 * @date 02. June 2017 21 ******************************************************************************/ 22 23 #ifndef _CSI_SPI_H_ 24 #define _CSI_SPI_H_ 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 #include <stdint.h> 31 #include <drv_common.h> 32 #include <config.h> 33 #ifdef CONFIG_SPI_DMA 34 #include <drv_dmac.h> 35 #endif 36 37 /// definition for spi handle. 38 typedef void *spi_handle_t; 39 40 /****** SPI specific error codes *****/ 41 typedef enum { 42 EDRV_SPI_MODE = (EDRV_SPECIFIC + 1), ///< Specified Mode not supported 43 EDRV_SPI_FRAME_FORMAT, ///< Specified Frame Format not supported 44 EDRV_SPI_DATA_BITS, ///< Specified number of Data bits not supported 45 EDRV_SPI_BIT_ORDER, ///< Specified Bit order not supported 46 EDRV_SPI_SS_MODE ///< Specified Slave Select Mode not supported 47 } drv_spi_err_e; 48 49 /*----- SPI Control Codes: Mode -----*/ 50 typedef enum { 51 SPI_MODE_INACTIVE = 0, ///< SPI Inactive 52 SPI_MODE_MASTER, ///< SPI Master (Output on MOSI, Input on MISO); arg = Bus Speed in bps 53 SPI_MODE_SLAVE, ///< SPI Slave (Output on MISO, Input on MOSI) 54 SPI_MODE_MASTER_SIMPLEX, ///< SPI Master (Output/Input on MOSI); arg = Bus Speed in bps 55 SPI_MODE_SLAVE_SIMPLEX ///< SPI Slave (Output/Input on MISO) 56 } spi_mode_e; 57 58 /*----- SPI Control Codes: Mode Parameters: Frame Format -----*/ 59 typedef enum { 60 SPI_FORMAT_CPOL0_CPHA0 = 0, ///< Clock Polarity 0, Clock Phase 0 (default) 61 SPI_FORMAT_CPOL0_CPHA1, ///< Clock Polarity 0, Clock Phase 1 62 SPI_FORMAT_CPOL1_CPHA0, ///< Clock Polarity 1, Clock Phase 0 63 SPI_FORMAT_CPOL1_CPHA1, ///< Clock Polarity 1, Clock Phase 1 64 } spi_format_e; 65 66 /*----- SPI Control Codes: Mode Parameters: Bit Order -----*/ 67 typedef enum { 68 SPI_ORDER_MSB2LSB = 0, ///< SPI Bit order from MSB to LSB (default) 69 SPI_ORDER_LSB2MSB ///< SPI Bit order from LSB to MSB 70 } spi_bit_order_e; 71 72 /*----- SPI Control Codes: Mode Parameters: Data Width in bits -----*/ 73 #define SPI_DATAWIDTH_MAX 32 /* 1 ~ 32 bit*/ 74 75 /*----- SPI Control Codes: Mode Parameters: Slave Select Mode -----*/ 76 typedef enum { 77 /*options for SPI_MODE_MASTER/SPI_MODE_MASTER_SIMPLEX */ 78 SPI_SS_MASTER_UNUSED = 0, ///< SPI Slave Select when Master: Not used (default).SS line is not controlled by master, For example,SS line connected to a fixed low level 79 SPI_SS_MASTER_SW, ///< SPI Slave Select when Master: Software controlled. SS line is configured by software 80 SPI_SS_MASTER_HW_OUTPUT, ///< SPI Slave Select when Master: Hardware controlled Output.SS line is activated or deactivated automatically by hardware 81 SPI_SS_MASTER_HW_INPUT, ///< SPI Slave Select when Master: Hardware monitored Input.Used in multi-master configuration where a master does not drive the Slave Select when driving the bus, but rather monitors it 82 /*options for SPI_MODE_SLAVE/SPI_MODE_SLAVE_SIMPLEX */ 83 SPI_SS_SLAVE_HW, ///< SPI Slave Select when Slave: Hardware monitored (default).Hardware monitors the Slave Select line and accepts transfers only when the line is active 84 SPI_SS_SLAVE_SW ///< SPI Slave Select when Slave: Software controlled.Used only when the Slave Select line is not used. Software controls if the slave is responding or not(enables or disables transfers) 85 } spi_ss_mode_e; 86 87 /****** SPI Slave Select Signal definitions *****/ 88 typedef enum { 89 SPI_SS_INACTIVE = 0, ///< SPI Slave Select Signal/line Inactive 90 SPI_SS_ACTIVE ///< SPI Slave Select Signal/line Active 91 } spi_ss_stat_e; 92 93 /** 94 \brief SPI Status 95 */ 96 typedef struct { 97 uint32_t busy : 1; ///< Transmitter/Receiver busy flag 98 uint32_t data_lost : 1; ///< Data lost: Receive overflow / Transmit underflow (cleared on start of transfer operation) 99 uint32_t mode_fault : 1; ///< Mode fault detected; optional (cleared on start of transfer operation) 100 } spi_status_t; 101 102 /****** SPI Event *****/ 103 typedef enum { 104 SPI_EVENT_TRANSFER_COMPLETE = 0, ///< Data Transfer completed. Occurs after call to ARM_SPI_Send, ARM_SPI_Receive, or ARM_SPI_Transfer to indicate that all the data has been transferred. The driver is ready for the next transfer operation 105 SPI_EVENT_TX_COMPLETE, ///< Data Transfer completed. Occurs after call to ARM_SPI_Send, ARM_SPI_Receive, or ARM_SPI_Transfer to indicate that all the data has been transferred. The driver is ready for the next transfer operation 106 SPI_EVENT_RX_COMPLETE, ///< Data Transfer completed. Occurs after call to ARM_SPI_Send, ARM_SPI_Receive, or ARM_SPI_Transfer to indicate that all the data has been transferred. The driver is ready for the next transfer operation 107 SPI_EVENT_DATA_LOST, ///< Data lost: Receive overflow / Transmit underflow. Occurs in slave mode when data is requested/sent by master but send/receive/transfer operation has not been started and indicates that data is lost. Occurs also in master mode when driver cannot transfer data fast enough. 108 SPI_EVENT_MODE_FAULT ///< Master Mode Fault (SS deactivated when Master).Occurs in master mode when Slave Select is deactivated and indicates Master Mode Fault. The driver is ready for the next transfer operation. 109 } spi_event_e; 110 111 typedef void (*spi_event_cb_t)(spi_event_e event, void *arg); ///< Pointer to \ref spi_event_cb_t : SPI Event call back. 112 113 /** 114 \brief SPI Driver Capabilities. 115 */ 116 typedef struct { 117 uint32_t simplex : 1; ///< supports Simplex Mode (Master and Slave) 118 uint32_t ti_ssi : 1; ///< supports TI Synchronous Serial Interface 119 uint32_t microwire : 1; ///< supports Microwire Interface 120 uint32_t event_mode_fault : 1; ///< Signal Mode Fault event: \ref spi_event_e 121 } spi_capabilities_t; 122 123 /** 124 \brief Initialize SPI Interface. 1. Initializes the resources needed for the SPI interface 2.registers event callback function 125 \param[in] mosi spi pin of mosi 126 \param[in] miso spi pin of miso 127 \param[in] sclk spi pin of sclk 128 \param[in] ssel spi pin of ssel 129 \param[in] cb_event event call back function \ref spi_event_cb_t 130 \param[in] cb_arg argument for call back function 131 \return return spi handle if success 132 */ 133 spi_handle_t csi_spi_initialize(pin_t mosi, pin_t miso, pin_t sclk, pin_t ssel, spi_event_cb_t cb_event, void *cb_arg); 134 135 /** 136 \brief De-initialize SPI Interface. stops operation and releases the software resources used by the interface 137 \param[in] handle spi handle to operate. 138 \return error code 139 */ 140 int32_t csi_spi_uninitialize(spi_handle_t handle); 141 142 /** 143 \brief Get driver capabilities. 144 \param[in] handle spi handle to operate. 145 \return \ref spi_capabilities_t 146 */ 147 spi_capabilities_t csi_spi_get_capabilities(spi_handle_t handle); 148 149 /** 150 \brief config spi mode. 151 \param[in] handle spi handle to operate. 152 \param[in] sysclk sysclk for spi module. 153 \param[in] baud spi baud rate. if negative, then this attribute not changed 154 \param[in] mode \ref spi_mode_e . if negative, then this attribute not changed 155 \param[in] format \ref spi_format_e . if negative, then this attribute not changed 156 \param[in] order \ref spi_bit_order_e . if negative, then this attribute not changed 157 \param[in] ss_mode \ref spi_ss_mode_e . if negative, then this attribute not changed 158 \param[in] bit_width spi data bitwidth: (1 ~ SPI_DATAWIDTH_MAX) . if negative, then this attribute not changed 159 \return error code 160 */ 161 int32_t csi_spi_config(spi_handle_t handle, 162 int32_t sysclk, 163 int32_t baud, 164 spi_mode_e mode, 165 spi_format_e format, 166 spi_bit_order_e order, 167 spi_ss_mode_e ss_mode, 168 int32_t bit_width); 169 170 /** 171 \brief config spi default tx value. 172 \param[in] handle spi handle to operate. 173 \param[in] value default tx value 174 \return error code 175 */ 176 int32_t csi_spi_set_default_tx_value(spi_handle_t handle, uint32_t value); 177 178 /** 179 \brief sending data to SPI transmitter,(received data is ignored). 180 if non-blocking mode, this function only start the sending, 181 \ref spi_event_e is signaled when operation completes or error happens. 182 \ref csi_spi_get_status can indicates operation status. 183 if blocking mode, this function return after operation completes or error happens. 184 \param[in] handle spi handle to operate. 185 \param[in] data Pointer to buffer with data to send to SPI transmitter. data_type is : uint8_t for 1..8 data bits, uint16_t for 9..16 data bits,uint32_t for 17..32 data bits, 186 \param[in] num Number of data items to send. 187 \param[in] block_mode blocking and non_blocking to selcect 188 \return error code 189 */ 190 int32_t csi_spi_send(spi_handle_t handle, const void *data, uint32_t num, uint8_t block_mode); 191 192 /** 193 \brief receiving data from SPI receiver.transmits the default value as specified by csi_spi_set_default_tx_value 194 if non-blocking mode, this function only start the receiving, 195 \ref spi_event_e is signaled when operation completes or error happens. 196 \ref csi_spi_get_status can indicates operation status. 197 if blocking mode, this function return after operation completes or error happens. 198 \param[in] handle spi handle to operate. 199 \param[out] data Pointer to buffer for data to receive from SPI receiver 200 \param[in] num Number of data items to receive 201 \param[in] block_mode blocking and non_blocking to selcect 202 \return error code 203 */ 204 int32_t csi_spi_receive(spi_handle_t handle, void *data, uint32_t num, uint8_t block_mode); 205 206 /** 207 \brief sending/receiving data to/from SPI transmitter/receiver. 208 if non-blocking mode, this function only start the transfer, 209 \ref spi_event_e is signaled when operation completes or error happens. 210 \ref csi_spi_get_status can indicates operation status. 211 if blocking mode, this function return after operation completes or error happens. 212 \param[in] handle spi handle to operate. 213 \param[in] data_out Pointer to buffer with data to send to SPI transmitter 214 \param[out] data_in Pointer to buffer for data to receive from SPI receiver 215 \param[in] num_out Number of data items to send 216 \param[in] num_in Number of data items to receive 217 \param[in] block_mode blocking and non_blocking to selcect 218 \return error code 219 */ 220 int32_t csi_spi_transfer(spi_handle_t handle, const void *data_out, void *data_in, uint32_t num_out, uint32_t num_in, uint8_t block_mode); 221 222 /** 223 \brief abort spi transfer. 224 \param[in] handle spi handle to operate. 225 \return error code 226 */ 227 int32_t csi_spi_abort_transfer(spi_handle_t handle); 228 229 /** 230 \brief Get SPI status. 231 \param[in] handle spi handle to operate. 232 \return SPI status \ref spi_status_t 233 */ 234 spi_status_t csi_spi_get_status(spi_handle_t handle); 235 236 #ifdef __cplusplus 237 } 238 #endif 239 240 #endif /* _CSI_SPI_H_ */ 241