git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/T-HEAD_CB2201_CDK/csi/csi_driver/include/drv_spi.h

   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 /**
 237   \brief       config the SPI mode.
 238   \param[in]   handle   spi handle
 239   \param[in]   mode     spi mode. \ref spi_mode_e
 240   \return      error code
 241 */
 242 int32_t csi_spi_config_mode(spi_handle_t handle, spi_mode_e  mode);
 243
 244 /**
 245   \brief       Set the SPI clock divider.
 246   \param[in]   handle   spi handle
 247   \param[in]   baud     spi baud rate
 248   \param[in]   apbfreq  sysclk for spi module.
 249   \return      error code
 250 */
 251 int32_t csi_spi_config_baudrate(spi_handle_t handle, int32_t baud, int32_t apbfreq);
 252
 253 /**
 254   \brief       config the SPI mode.
 255   \param[in]   handle   spi handle
 256   \param[in]   order    spi bit order.\ref spi_bit_order_e
 257   \return      error code
 258 */
 259 int32_t csi_spi_config_bit_order(spi_handle_t handle, spi_bit_order_e order);
 260
 261 /**
 262   \brief       Set the SPI datawidth.
 263   \param[in]   handle     spi handle
 264   \param[in]   datawidth  date frame size in bits
 265   \return      error code
 266 */
 267 int32_t csi_spi_config_datawidth(spi_handle_t handle, int32_t datawidth);
 268
 269 /**
 270   \brief       config the SPI format.
 271   \param[in]   handle   spi handle
 272   \param[in]   format   spi format. \ref spi_format_e
 273   \return      error code
 274 */
 275 int32_t csi_spi_config_format(spi_handle_t handle, spi_format_e format);
 276
 277 /**
 278   \brief       config the SPI slave select mode.
 279   \param[in]   handle   spi handle
 280   \param[in]   ss_mode  spi slave select mode. \ref spi_ss_mode_e
 281   \return      error code
 282 */
 283 int32_t csi_spi_config_ss_mode(spi_handle_t handle, spi_ss_mode_e ss_mode);
 284
 285 /**
 286   \brief       Get spi transferred data count.
 287   \param[in]   handle  spi handle to operate.
 288   \return      number of data bytes transferred
 289 */
 290 uint32_t csi_spi_get_data_count(spi_handle_t handle);
 291
 292 /**
 293   \brief       control spi power.
 294   \param[in]   handle  spi handle to operate.
 295   \param[in]   state   power state.\ref csi_power_stat_e.
 296   \return      error code
 297 */
 298 int32_t csi_spi_power_control(spi_handle_t handle, csi_power_stat_e state);
 299
 300 /**
 301   \brief       Check if a value is available to read.
 302   \param[in]   handle  spi handle to operate.
 303   \return      non-zero if a value is available
 304 */
 305 int32_t csi_spi_slave_readable(spi_handle_t handle);
 306
 307 /**
 308   \brief       Control the Slave Select signal (SS).
 309   \param[in]   handle  spi handle to operate.
 310   \param[in]   stat    SS state. \ref spi_ss_stat_e.
 311   \return      error code
 312 */
 313 int32_t csi_spi_ss_control(spi_handle_t handle, spi_ss_stat_e stat);
 314
 315
 316 #ifdef __cplusplus
 317 }
 318 #endif
 319
 320 #endif /* _CSI_SPI_H_ */