2 * Copyright (C) 2017 C-SKY Microsystems Co., Ltd. All rights reserved.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
16 /******************************************************************************
18 * @brief header file for iic driver
21 ******************************************************************************/
32 #include <drv_common.h>
34 /// definition for iic handle.
35 typedef void *iic_handle_t;
37 /*----- IIC Control Codes: Mode -----*/
39 IIC_MODE_MASTER, ///< IIC Master
40 IIC_MODE_SLAVE ///< IIC Slave
43 /*----- IIC Control Codes: IIC Bus Speed -----*/
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)
51 /*----- IIC Control Codes: IIC Address Mode -----*/
53 I2C_ADDRESS_7BIT = 0, ///< 7-bit address mode
54 I2C_ADDRESS_10BIT = 1 ///< 10-bit address mode
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)
69 /****** IIC Event *****/
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
82 typedef void (*iic_event_cb_t)(iic_event_e event, void *arg); ///< Pointer to \ref iic_event_cb_t : IIC Event call back.
85 \brief IIC Driver Capabilities.
88 uint32_t address_10_bit : 1; ///< supports 10-bit addressing
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
100 iic_handle_t csi_iic_initialize(pin_t scl, pin_t sda, iic_event_cb_t cb_event, void *cb_arg);
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
107 int32_t csi_iic_uninitialize(iic_handle_t handle);
110 \brief Get driver capabilities.
111 \param[in] handle iic handle to operate.
112 \return \ref iic_capabilities_t
114 iic_capabilities_t csi_iic_get_capabilities(iic_handle_t handle);
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
125 int32_t csi_iic_config(iic_handle_t handle,
128 iic_address_mode_e addr_mode,
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
141 int32_t csi_iic_master_send(iic_handle_t handle, const void *data, uint32_t num, bool xfer_pending);
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
153 int32_t csi_iic_master_receive(iic_handle_t handle, void *data, uint32_t num, bool xfer_pending);
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
164 int32_t csi_iic_slave_send(iic_handle_t handle, const void *data, uint32_t num);
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
175 int32_t csi_iic_slave_receive(iic_handle_t handle, const void *data, uint32_t num);
178 \brief abort transfer.
179 \param[in] handle iic handle to operate.
180 \return 0 for success, negative for error code
182 int32_t csi_iic_abort_transfer(iic_handle_t handle);
185 \brief Get IIC status.
186 \param[in] handle iic handle to operate.
187 \return IIC status \ref iic_status_t
189 iic_status_t csi_iic_get_status(iic_handle_t handle);
192 \brief control IIC power.
193 \param[in] handle iic handle to operate.
194 \param[in] state power state.\ref csi_power_stat_e.
197 int32_t csi_iic_power_control(iic_handle_t handle, csi_power_stat_e state);
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
205 int32_t csi_iic_config_mode(iic_handle_t handle, iic_mode_e mode);
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
213 int32_t csi_iic_config_speed(iic_handle_t handle, iic_speed_e speed);
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
221 int32_t csi_iic_config_addr_mode(iic_handle_t handle, iic_address_mode_e addr_mode);
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
230 int32_t csi_iic_config_slave_addr(iic_handle_t handle, int32_t slave_addr);
233 \brief Get IIC transferred data count.
234 \param[in] handle iic handle to operate.
235 \return number of data bytes transferred
237 uint32_t csi_iic_get_data_count(iic_handle_t handle);
240 \brief Send START command.
241 \param[in] handle iic handle to operate.
244 int32_t csi_iic_send_start(iic_handle_t handle);
247 \brief Send STOP command.
248 \param[in] handle iic handle to operate.
251 int32_t csi_iic_send_stop(iic_handle_t handle);
254 \brief Reset I2C peripheral.
255 \param[in] handle iic handle to operate.
258 int32_t csi_iic_reset(iic_handle_t handle);
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
266 int32_t csi_iic_read_byte(iic_handle_t handle, int32_t last);
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
273 int32_t csi_iic_write_byte(iic_handle_t handle, uint8_t data);
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.
282 int32_t csi_iic_slave_check_addressed(iic_handle_t handle);
288 #endif /* _CSI_IIC_H_ */