1 /* 2 * Copyright (C) 2017-2020 Alibaba Group Holding Limited 3 */ 4 5 /****************************************************************************** 6 * @file drv/usi_spi.h 7 * @brief Header File for SPI Driver 8 * @version V1.0 9 * @date 02. June 2020 10 * @model usi_spi 11 ******************************************************************************/ 12 13 #ifndef _DRV_SPI_USI_H_ 14 #define _DRV_SPI_USI_H_ 15 16 #include <stdint.h> 17 #include <drv/common.h> 18 #include <drv/spi.h> 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 /** 24 \brief Initialize SPI Interface. 25 Initializes the resources needed for the SPI instance 26 \param[in] spi SPI handle 27 \param[in] idx SPI instance index 28 \return Error code 29 */ 30 csi_error_t csi_usi_spi_init(csi_spi_t *spi, uint32_t idx); 31 32 /** 33 \brief De-initialize SPI Interface 34 Stops operation and releases the software resources used by the spi instance 35 \param[in] spi SPI handle 36 \return None 37 */ 38 void csi_usi_spi_uninit(csi_spi_t *spi); 39 40 /** 41 \brief Attach the callback handler to SPI 42 \param[in] spi Operate handle. 43 \param[in] callback Callback function 44 \param[in] arg User can define it by himself as callback's param 45 \return Error code 46 */ 47 csi_error_t csi_usi_spi_attach_callback(csi_spi_t *spi, void *callback, void *arg); 48 49 /** 50 \brief Detach the callback handler 51 \param[in] spi Operate handle. 52 \return None 53 */ 54 void csi_usi_spi_detach_callback(csi_spi_t *spi); 55 56 57 /** 58 \brief Config spi mode (master or slave). 59 \param[in] spi SPI handle 60 \param[in] mode The mode of spi (master or slave) 61 \return Error code 62 */ 63 csi_error_t csi_usi_spi_mode(csi_spi_t *spi, csi_spi_mode_t mode); 64 65 /** 66 \brief Config spi cp format. 67 \param[in] spi SPI handle 68 \param[in] format SPI cp format 69 \return Error code 70 */ 71 csi_error_t csi_usi_spi_cp_format(csi_spi_t *spi, csi_spi_cp_format_t format); 72 73 /** 74 \brief Config spi frame len. 75 \param[in] spi SPI handle 76 \param[in] length spi frame len 77 \return error code 78 */ 79 csi_error_t csi_usi_spi_frame_len(csi_spi_t *spi, csi_spi_frame_len_t length); 80 81 /** 82 \brief Config spi work frequence. 83 \param[in] spi SPI handle 84 \param[in] baud SPI work baud 85 \return The actual config frequency 86 */ 87 uint32_t csi_usi_spi_baud(csi_spi_t *spi, uint32_t baud); 88 89 /** 90 \brief Config spi mode. 91 \param[in] Handle spi handle to operate. 92 \param[in] baud SPI baud rate. If negative, then this attribute not changed 93 \param[in] mode \ref spi_mode_e . If negative, then this attribute not changed 94 \param[in] format \ref spi_format_e . If negative, then this attribute not changed 95 \param[in] order \ref spi_bit_order_e . If negative, then this attribute not changed 96 \param[in] ss_mode \ref spi_ss_mode_t . If negative, then this attribute not changed 97 \param[in] bit_width SPI data bitwidth: (1 ~ SPI_DATAWIDTH_MAX) . If negative, then this attribute not changed 98 \return Error code 99 */ 100 csi_error_t drv_usi_spi_config(csi_spi_t *spi, csi_spi_mode_t mode, csi_spi_frame_len_t width, csi_spi_cp_format_t format); 101 102 /** 103 \brief Sending data to SPI transmitter,(received data is ignored). 104 Blocking mode ,return unti all data has been sent or err happened 105 \param[in] spi Handle to operate. 106 \param[in] data Pointer to buffer with data to send to SPI transmitter. 107 \param[in] size Number of data to send(byte) 108 \param[in] timeout Unit in mini-second 109 \return If send success, this function shall return the num of data witch is sent successful 110 otherwise, the function shall return error code 111 */ 112 int32_t csi_usi_spi_send(csi_spi_t *spi, const void *data, uint32_t size, uint32_t timeout); 113 114 /** 115 \brief Sending data to SPI transmitter,(received data is ignored). 116 non-blocking mode,transfer done event will be signaled by driver 117 \param[in] spi Handle to operate. 118 \param[in] data Pointer to buffer with data to send to SPI transmitter. 119 \param[in] size Number of data items to send(byte) 120 \return Error code 121 */ 122 csi_error_t csi_usi_spi_send_async(csi_spi_t *spi, const void *data, uint32_t size); 123 124 /** 125 \brief Receiving data from SPI receiver. 126 Blocking mode, return untill curtain data items are readed 127 \param[in] spi Handle to operate. 128 \param[out] data Pointer to buffer for data to receive from SPI receiver 129 \param[in] size Number of data items to receive(byte) 130 \param[in] timeout Unit in mini-second 131 \return If receive success, this function shall return the num of data witch is received successful 132 Otherwise, the function shall return error code 133 */ 134 int32_t csi_usi_spi_receive(csi_spi_t *spi, void *data, uint32_t size, uint32_t timeout); 135 136 /** 137 \brief Receiving data from SPI receiver. 138 Not-blocking mode, event will be signaled when receive done or err happend 139 \param[in] spi Handle to operate. 140 \param[out] data Pointer to buffer for data to receive from SPI receiver 141 \param[in] size Number of data items to receive(byte) 142 \return Error code 143 */ 144 csi_error_t csi_usi_spi_receive_async(csi_spi_t *spi, void *data, uint32_t size); 145 146 /** 147 \brief Dulplex,sending and receiving data at the same time 148 \ref csi_spi_event_t is signaled when operation completes or error happens. 149 \ref csi_spi_get_state can get operation status. 150 Blocking mode, this function returns after operation completes or error happens. 151 \param[in] Handle spi handle to operate. 152 \param[in] data_out Pointer to buffer with data to send to SPI transmitter 153 \param[out] data_in Pointer to buffer for data to receive from SPI receiver 154 \param[in] size Data size(byte) 155 \return If transfer success, this function shall return the num of data witch is transfer successful 156 otherwise, the function shall return error code 157 */ 158 int32_t csi_usi_spi_send_receive(csi_spi_t *spi, const void *data_out, void *data_in, uint32_t size, uint32_t timeout); 159 160 /** 161 \brief Transmit first then receive ,receive will begin after transmit is done 162 if non-blocking mode, this function only starts the transfer, 163 \ref csi_spi_event_t is signaled when operation completes or error happens. 164 \ref csi_spi_get_state can get operation status. 165 \param[in] handle spi Handle to operate. 166 \param[in] data_out Pointer to buffer with data to send to SPI transmitter 167 \param[out] data_in Pointer to buffer for data to receive from SPI receiver 168 \param[in] size Data size(byte) 169 \return Error code 170 */ 171 csi_error_t csi_usi_spi_send_receive_async(csi_spi_t *spi, const void *data_out, void *data_in, uint32_t size); 172 173 /* 174 \brief Set slave select num. Only valid for master 175 \param[in] Handle spi handle to operate. 176 \param[in] slave_num SPI slave num. 177 \return None 178 */ 179 void csi_usi_spi_select_slave(csi_spi_t *spi, uint32_t slave_num); 180 181 /** 182 \brief Link DMA channel to spi device 183 \param[in] spi SPI handle to operate. 184 \param[in] tx_dma The DMA channel handle for send, when it is NULL means to unlink the channel 185 \param[in] rx_dma The DMA channel handle for receive, when it is NULL means to unlink the channel 186 \return Error code 187 */ 188 csi_error_t csi_usi_spi_link_dma(csi_spi_t *spi, csi_dma_ch_t *tx_dma, csi_dma_ch_t *rx_dma); 189 190 /** 191 \brief Get the state of spi device 192 \param[in] spi SPI handle to operate. 193 \param[out] state The state of spi device 194 \return Error code 195 */ 196 csi_error_t csi_usi_spi_get_state(csi_spi_t *spi, csi_state_t *state); 197 198 /** 199 \brief Enable spi power manage 200 \param[in] spi SPI handle to operate. 201 \return Error code 202 */ 203 csi_error_t csi_usi_spi_enable_pm(csi_spi_t *spi); 204 205 /** 206 \brief Disable spi power manage 207 \param[in] spi SPI handle to operate. 208 \return Error code 209 */ 210 void csi_spi_disable_pm(csi_spi_t *spi); 211 #ifdef __cplusplus 212 } 213 #endif 214 215 #endif /* _DRV_SPI_USI_H_ */ 216