git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/T-HEAD_CB2201_CDK/csi/csi_driver/include/drv_iic.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_iic.h
  18  * @brief    header file for iic driver
  19  * @version  V1.0
  20  * @date     02. June 2017
  21  ******************************************************************************/
  22
  23 #ifndef _CSI_IIC_H_
  24 #define _CSI_IIC_H_
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 #include <stdint.h>
  31 #include <stdbool.h>
  32 #include <drv_common.h>
  33
  34 /// definition for iic handle.
  35 typedef void *iic_handle_t;
  36
  37 /*----- IIC Control Codes: Mode -----*/
  38 typedef enum {
  39     IIC_MODE_MASTER,             ///< IIC Master
  40     IIC_MODE_SLAVE               ///< IIC Slave
  41 } iic_mode_e;
  42
  43 /*----- IIC Control Codes: IIC Bus Speed -----*/
  44 typedef enum {
  45     I2C_BUS_SPEED_STANDARD  = 0, ///< Standard Speed (100kHz)
  46     I2C_BUS_SPEED_FAST      = 1, ///< Fast Speed     (400kHz)
  47     I2C_BUS_SPEED_FAST_PLUS = 2, ///< Fast+ Speed    (  1MHz)
  48     I2C_BUS_SPEED_HIGH      = 3  ///< High Speed     (3.4MHz)
  49 } iic_speed_e;
  50
  51 /*----- IIC Control Codes: IIC Address Mode -----*/
  52 typedef enum {
  53     I2C_ADDRESS_7BIT        = 0,  ///< 7-bit address mode
  54     I2C_ADDRESS_10BIT       = 1   ///< 10-bit address mode
  55 } iic_address_mode_e;
  56
  57 /**
  58 \brief IIC Status
  59 */
  60 typedef struct {
  61     uint32_t busy             : 1;        ///< Transmitter/Receiver busy flag
  62     uint32_t mode             : 1;        ///< Mode: 0=Slave, 1=Master
  63     uint32_t direction        : 1;        ///< Direction: 0=Transmitter, 1=Receiver
  64     uint32_t general_call     : 1;        ///< General Call(address 0) indication (cleared on start of next Slave operation)
  65     uint32_t arbitration_lost : 1;        ///< Master lost arbitration(in case of multi-masters) (cleared on start of next Master operation)
  66     uint32_t bus_error        : 1;        ///< Bus error detected (cleared on start of next Master/Slave operation)
  67 } iic_status_t;
  68
  69 /****** IIC Event *****/
  70 typedef enum {
  71     I2C_EVENT_TRANSFER_DONE        = 0,  ///< Master/Slave Transmit/Receive finished
  72     I2C_EVENT_TRANSFER_INCOMPLETE  = 1,  ///< Master/Slave Transmit/Receive incomplete transfer
  73     I2C_EVENT_SLAVE_TRANSMIT       = 2,  ///< Slave Transmit operation requested
  74     I2C_EVENT_SLAVE_RECEIVE        = 3,  ///< Slave Receive operation requested
  75     I2C_EVENT_ADDRESS_NACK         = 4,  ///< Address not acknowledged from Slave
  76     I2C_EVENT_GENERAL_CALL         = 5,  ///< General Call indication
  77     I2C_EVENT_ARBITRATION_LOST     = 6,  ///< Master lost arbitration
  78     I2C_EVENT_BUS_ERROR            = 7,  ///< Bus error detected (START/STOP at illegal position)
  79     I2C_EVENT_BUS_CLEAR            = 8   ///< Bus clear finished
  80 } iic_event_e;
  81
  82 typedef void (*iic_event_cb_t)(iic_event_e event, void *arg);  ///< Pointer to \ref iic_event_cb_t : IIC Event call back.
  83
  84 /**
  85 \brief IIC Driver Capabilities.
  86 */
  87 typedef struct  {
  88     uint32_t address_10_bit : 1;          ///< supports 10-bit addressing
  89 } iic_capabilities_t;
  90
  91 /**
  92   \brief       Initialize IIC Interface specified by pins. \n
  93                1. Initializes the resources needed for the IIC interface 2.registers event callback function
  94   \param[in]   scl  scl pin of iic.
  95   \param[in]   sda  sda pin of iic.
  96   \param[in]   cb_event  Pointer to \ref iic_event_cb_t
  97   \param[in]   cb_arg    argument for call back function
  98   \return      0 for success, negative for error code
  99 */
 100 iic_handle_t csi_iic_initialize(pin_t scl, pin_t sda, iic_event_cb_t cb_event, void *cb_arg);
 101
 102 /**
 103   \brief       De-initialize IIC Interface. stops operation and releases the software resources used by the interface
 104   \param[in]   handle  iic handle to operate.
 105   \return      0 for success, negative for error code
 106 */
 107 int32_t csi_iic_uninitialize(iic_handle_t handle);
 108
 109 /**
 110   \brief       Get driver capabilities.
 111   \param[in]   handle  iic handle to operate.
 112   \return      \ref iic_capabilities_t
 113 */
 114 iic_capabilities_t csi_iic_get_capabilities(iic_handle_t handle);
 115
 116 /**
 117   \brief       config iic attributes.
 118   \param[in]   handle    iic handle to operate.
 119   \param[in]   mode      iic mode \ref iic_mode_e. if negative, then this attribute not changed.
 120   \param[in]   speed     iic speed \ref iic_speed_e. if negative, then this attribute not changed.
 121   \param[in]   addr_mode iic address mode \ref iic_address_mode_e. if negative, then this attribute not changed.
 122   \param[in]   slave_addr iic address of slave. if negative, then this attribute not changed.
 123   \return      0 for success, negative for error code
 124 */
 125 int32_t csi_iic_config(iic_handle_t handle,
 126                        iic_mode_e mode,
 127                        iic_speed_e speed,
 128                        iic_address_mode_e addr_mode,
 129                        int32_t slave_addr);
 130
 131 /**
 132   \brief       Start transmitting data as I2C Master.
 133                This function is non-blocking,\ref iic_event_e is signaled when transfer completes or error happens.
 134                \ref csi_iic_get_status can indicates transmission status.
 135   \param[in]   handle         iic handle to operate.
 136   \param[in]   data           data to send to I2C Slave
 137   \param[in]   num            Number of data items to send
 138   \param[in]   xfer_pending   Transfer operation is pending - Stop condition will not be generated
 139   \return      0 for success, negative for error code
 140 */
 141 int32_t csi_iic_master_send(iic_handle_t handle, const void *data, uint32_t num, bool xfer_pending);
 142
 143 /**
 144   \brief       Start receiving data as I2C Master.
 145                This function is non-blocking,\ref iic_event_e is signaled when transfer completes or error happens.
 146                \ref csi_iic_get_status can indicates transmission status.
 147   \param[in]   handle  iic handle to operate.
 148   \param[out]  data    Pointer to buffer for data to receive from IIC receiver
 149   \param[in]   num     Number of data items to receive
 150   \param[in]   xfer_pending   Transfer operation is pending - Stop condition will not be generated
 151   \return      0 for success, negative for error code
 152 */
 153 int32_t csi_iic_master_receive(iic_handle_t handle, void *data, uint32_t num, bool xfer_pending);
 154
 155 /**
 156   \brief       Start transmitting data as I2C Slave.
 157                This function is non-blocking,\ref iic_event_e is signaled when transfer completes or error happens.
 158                \ref csi_iic_get_status can indicates transmission status.
 159   \param[in]   handle  iic handle to operate.
 160   \param[in]   data  Pointer to buffer with data to transmit to I2C Master
 161   \param[in]   num   Number of data items to send
 162   \return      0 for success, negative for error code
 163 */
 164 int32_t csi_iic_slave_send(iic_handle_t handle, const void *data, uint32_t num);
 165
 166 /**
 167   \brief       Start receiving data as I2C Slave.
 168                This function is non-blocking,\ref iic_event_e is signaled when transfer completes or error happens.
 169                \ref csi_iic_get_status can indicates transmission status.
 170   \param[in]   handle  iic handle to operate.
 171   \param[out]  data  Pointer to buffer for data to receive from I2C Master
 172   \param[in]   num   Number of data items to receive
 173   \return      0 for success, negative for error code
 174 */
 175 int32_t csi_iic_slave_receive(iic_handle_t handle, const void *data, uint32_t num);
 176
 177 /**
 178   \brief       abort transfer.
 179   \param[in]   handle  iic handle to operate.
 180   \return      0 for success, negative for error code
 181 */
 182 int32_t csi_iic_abort_transfer(iic_handle_t handle);
 183
 184 /**
 185   \brief       Get IIC status.
 186   \param[in]   handle  iic handle to operate.
 187   \return      IIC status \ref iic_status_t
 188 */
 189 iic_status_t csi_iic_get_status(iic_handle_t handle);
 190
 191 /**
 192   \brief       control IIC power.
 193   \param[in]   handle  iic handle to operate.
 194   \param[in]   state   power state.\ref csi_power_stat_e.
 195   \return      error code
 196 */
 197 int32_t csi_iic_power_control(iic_handle_t handle, csi_power_stat_e state);
 198
 199 /**
 200   \brief       config iic mode.
 201   \param[in]   handle  iic handle to operate.
 202   \param[in]   mode      \ref iic_mode_e.if negative, then this attribute not changed
 203   \return      error code
 204 */
 205 int32_t csi_iic_config_mode(iic_handle_t handle, iic_mode_e mode);
 206
 207 /**
 208   \brief       config iic speed.
 209   \param[in]   handle  iic handle to operate.
 210   \param[in]   speed     \ref iic_speed_e.if negative, then this attribute not changed
 211   \return      error code
 212 */
 213 int32_t csi_iic_config_speed(iic_handle_t handle, iic_speed_e speed);
 214
 215 /**
 216   \brief       config iic address mode.
 217   \param[in]   handle  iic handle to operate.
 218   \param[in]   addr_mode \ref iic_address_mode_e.if negative, then this attribute not changed
 219   \return      error code
 220 */
 221 int32_t csi_iic_config_addr_mode(iic_handle_t handle, iic_address_mode_e addr_mode);
 222
 223
 224 /**
 225   \brief       config iic slave address.
 226   \param[in]   handle  iic handle to operate.
 227   \param[in]   slave_addr slave address.if negative, then this attribute not changed
 228   \return      error code
 229 */
 230 int32_t csi_iic_config_slave_addr(iic_handle_t handle, int32_t slave_addr);
 231
 232 /**
 233   \brief       Get IIC transferred data count.
 234   \param[in]   handle  iic handle to operate.
 235   \return      number of data bytes transferred
 236 */
 237 uint32_t csi_iic_get_data_count(iic_handle_t handle);
 238
 239 /**
 240   \brief       Send START command.
 241   \param[in]   handle  iic handle to operate.
 242   \return      error code
 243 */
 244 int32_t csi_iic_send_start(iic_handle_t handle);
 245
 246 /**
 247   \brief       Send STOP command.
 248   \param[in]   handle  iic handle to operate.
 249   \return      error code
 250 */
 251 int32_t csi_iic_send_stop(iic_handle_t handle);
 252
 253 /**
 254   \brief       Reset I2C peripheral.
 255   \param[in]   handle  iic handle to operate.
 256   \return      error code
 257 */
 258 int32_t csi_iic_reset(iic_handle_t handle);
 259
 260 /**
 261   \brief       Read a single byte from the I2C bus.
 262   \param[in]   handle  iic handle to operate.
 263   \param[in]   last  Acknoledge,indicates if the byte is to be acknowledged (1 = acknowledge)
 264   \return      error code if negative, else the data is the lowest byte of return value
 265 */
 266 int32_t csi_iic_read_byte(iic_handle_t handle, int32_t last);
 267
 268 /**
 269   \brief       Write one byte.
 270   \param[in]   handle  iic handle to operate.
 271   \return      0 if NAK was received, 1 if ACK was received, 2 for timeout. negative for error
 272 */
 273 int32_t csi_iic_write_byte(iic_handle_t handle, uint8_t data);
 274
 275 /**
 276   \brief       Check to see if the I2C slave has been addressed.
 277   \param[in]   handle  iic handle to operate.
 278   \return      1 - read addressed, 2 - write to all slaves,
 279                3 - write addressed, 0 - the slave has not been addressed.
 280                negative for error
 281 */
 282 int32_t csi_iic_slave_check_addressed(iic_handle_t handle);
 283
 284 #ifdef __cplusplus
 285 }
 286 #endif
 287
 288 #endif /* _CSI_IIC_H_ */