Mistake on this page?
Report an issue in GitHub or email us
i2c_api.h
1 
2 /** \addtogroup hal */
3 /** @{*/
4 /* mbed Microcontroller Library
5  * Copyright (c) 2006-2015 ARM Limited
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 #ifndef MBED_I2C_API_H
21 #define MBED_I2C_API_H
22 
23 #include "device.h"
24 #include "pinmap.h"
25 #include "hal/buffer.h"
26 
27 #if DEVICE_I2C_ASYNCH
28 #include "hal/dma_api.h"
29 #endif
30 
31 #if DEVICE_I2C
32 
33 /**
34  * @defgroup hal_I2CEvents I2C Events Macros
35  *
36  * @{
37  */
38 #define I2C_EVENT_ERROR (1 << 1)
39 #define I2C_EVENT_ERROR_NO_SLAVE (1 << 2)
40 #define I2C_EVENT_TRANSFER_COMPLETE (1 << 3)
41 #define I2C_EVENT_TRANSFER_EARLY_NACK (1 << 4)
42 #define I2C_EVENT_ALL (I2C_EVENT_ERROR | I2C_EVENT_TRANSFER_COMPLETE | I2C_EVENT_ERROR_NO_SLAVE | I2C_EVENT_TRANSFER_EARLY_NACK)
43 
44 /**@}*/
45 
46 #if DEVICE_I2C_ASYNCH
47 /** Asynch I2C HAL structure
48  */
49 typedef struct {
50  struct i2c_s i2c; /**< Target specific I2C structure */
51  struct buffer_s tx_buff; /**< Tx buffer */
52  struct buffer_s rx_buff; /**< Rx buffer */
53 } i2c_t;
54 
55 #else
56 /** Non-asynch I2C HAL structure
57  */
58 typedef struct i2c_s i2c_t;
59 
60 #endif
61 
62 enum {
63  I2C_ERROR_NO_SLAVE = -1,
64  I2C_ERROR_BUS_BUSY = -2
65 };
66 
67 #ifdef __cplusplus
68 extern "C" {
69 #endif
70 
71 /**
72  * \defgroup hal_GeneralI2C I2C Configuration Functions
73  * @{
74  */
75 
76 /** Initialize the I2C peripheral. It sets the default parameters for I2C
77  * peripheral, and configures its specifieds pins.
78  *
79  * @param obj The I2C object
80  * @param sda The sda pin
81  * @param scl The scl pin
82  */
83 void i2c_init(i2c_t *obj, PinName sda, PinName scl);
84 
85 /** Configure the I2C frequency
86  *
87  * @param obj The I2C object
88  * @param hz Frequency in Hz
89  */
90 void i2c_frequency(i2c_t *obj, int hz);
91 
92 /** Send START command
93  *
94  * @param obj The I2C object
95  */
96 int i2c_start(i2c_t *obj);
97 
98 /** Send STOP command
99  *
100  * @param obj The I2C object
101  */
102 int i2c_stop(i2c_t *obj);
103 
104 /** Blocking reading data
105  *
106  * @param obj The I2C object
107  * @param address 7-bit address (last bit is 1)
108  * @param data The buffer for receiving
109  * @param length Number of bytes to read
110  * @param stop Stop to be generated after the transfer is done
111  * @return Number of read bytes
112  */
113 int i2c_read(i2c_t *obj, int address, char *data, int length, int stop);
114 
115 /** Blocking sending data
116  *
117  * @param obj The I2C object
118  * @param address 7-bit address (last bit is 0)
119  * @param data The buffer for sending
120  * @param length Number of bytes to write
121  * @param stop Stop to be generated after the transfer is done
122  * @return
123  * zero or non-zero - Number of written bytes
124  * negative - I2C_ERROR_XXX status
125  */
126 int i2c_write(i2c_t *obj, int address, const char *data, int length, int stop);
127 
128 /** Reset I2C peripheral. TODO: The action here. Most of the implementation sends stop()
129  *
130  * @param obj The I2C object
131  */
132 void i2c_reset(i2c_t *obj);
133 
134 /** Read one byte
135  *
136  * @param obj The I2C object
137  * @param last Acknoledge
138  * @return The read byte
139  */
140 int i2c_byte_read(i2c_t *obj, int last);
141 
142 /** Write one byte
143  *
144  * @param obj The I2C object
145  * @param data Byte to be written
146  * @return 0 if NAK was received, 1 if ACK was received, 2 for timeout.
147  */
148 int i2c_byte_write(i2c_t *obj, int data);
149 
150 /** Get the pins that support I2C SDA
151  *
152  * Return a PinMap array of pins that support I2C SDA in
153  * master mode. The array is terminated with {NC, NC, 0}.
154  *
155  * @return PinMap array
156  */
157 const PinMap *i2c_master_sda_pinmap(void);
158 
159 /** Get the pins that support I2C SCL
160  *
161  * Return a PinMap array of pins that support I2C SCL in
162  * master mode. The array is terminated with {NC, NC, 0}.
163  *
164  * @return PinMap array
165  */
166 const PinMap *i2c_master_scl_pinmap(void);
167 
168 /** Get the pins that support I2C SDA
169  *
170  * Return a PinMap array of pins that support I2C SDA in
171  * slave mode. The array is terminated with {NC, NC, 0}.
172  *
173  * @return PinMap array
174  */
175 const PinMap *i2c_slave_sda_pinmap(void);
176 
177 /** Get the pins that support I2C SCL
178  *
179  * Return a PinMap array of pins that support I2C SCL in
180  * slave mode. The array is terminated with {NC, NC, 0}.
181  *
182  * @return PinMap array
183  */
184 const PinMap *i2c_slave_scl_pinmap(void);
185 
186 /**@}*/
187 
188 #if DEVICE_I2CSLAVE
189 
190 /**
191  * \defgroup SynchI2C Synchronous I2C Hardware Abstraction Layer for slave
192  * @{
193  */
194 
195 /** Configure I2C as slave or master.
196  * @param obj The I2C object
197  * @param enable_slave Enable i2c hardware so you can receive events with ::i2c_slave_receive
198  * @return non-zero if a value is available
199  */
200 void i2c_slave_mode(i2c_t *obj, int enable_slave);
201 
202 /** Check to see if the I2C slave has been addressed.
203  * @param obj The I2C object
204  * @return The status - 1 - read addresses, 2 - write to all slaves,
205  * 3 write addressed, 0 - the slave has not been addressed
206  */
207 int i2c_slave_receive(i2c_t *obj);
208 
209 /** Configure I2C as slave or master.
210  * @param obj The I2C object
211  * @param data The buffer for receiving
212  * @param length Number of bytes to read
213  * @return non-zero if a value is available
214  */
215 int i2c_slave_read(i2c_t *obj, char *data, int length);
216 
217 /** Configure I2C as slave or master.
218  * @param obj The I2C object
219  * @param data The buffer for sending
220  * @param length Number of bytes to write
221  * @return non-zero if a value is available
222  */
223 int i2c_slave_write(i2c_t *obj, const char *data, int length);
224 
225 /** Configure I2C address.
226  * @param obj The I2C object
227  * @param idx Currently not used
228  * @param address The address to be set
229  * @param mask Currently not used
230  */
231 void i2c_slave_address(i2c_t *obj, int idx, uint32_t address, uint32_t mask);
232 
233 #endif
234 
235 /**@}*/
236 
237 #if DEVICE_I2C_ASYNCH
238 
239 /**
240  * \defgroup hal_AsynchI2C Asynchronous I2C Hardware Abstraction Layer
241  * @{
242  */
243 
244 /** Start I2C asynchronous transfer
245  *
246  * @param obj The I2C object
247  * @param tx The transmit buffer
248  * @param tx_length The number of bytes to transmit
249  * @param rx The receive buffer
250  * @param rx_length The number of bytes to receive
251  * @param address The address to be set - 7bit or 9bit
252  * @param stop If true, stop will be generated after the transfer is done
253  * @param handler The I2C IRQ handler to be set
254  * @param event Event mask for the transfer. See \ref hal_I2CEvents
255  * @param hint DMA hint usage
256  */
257 void i2c_transfer_asynch(i2c_t *obj, const void *tx, size_t tx_length, void *rx, size_t rx_length, uint32_t address, uint32_t stop, uint32_t handler, uint32_t event, DMAUsage hint);
258 
259 /** The asynchronous IRQ handler
260  *
261  * @param obj The I2C object which holds the transfer information
262  * @return Event flags if a transfer termination condition was met, otherwise return 0.
263  */
264 uint32_t i2c_irq_handler_asynch(i2c_t *obj);
265 
266 /** Attempts to determine if the I2C peripheral is already in use
267  *
268  * @param obj The I2C object
269  * @return Non-zero if the I2C module is active or zero if it is not
270  */
271 uint8_t i2c_active(i2c_t *obj);
272 
273 /** Abort asynchronous transfer
274  *
275  * This function does not perform any check - that should happen in upper layers.
276  * @param obj The I2C object
277  */
278 void i2c_abort_asynch(i2c_t *obj);
279 
280 #endif
281 
282 /**@}*/
283 
284 #ifdef __cplusplus
285 }
286 #endif
287 
288 #endif
289 
290 #endif
291 
292 /** @}*/
void i2c_abort_asynch(i2c_t *obj)
Abort asynchronous transfer.
const PinMap * i2c_master_scl_pinmap(void)
Get the pins that support I2C SCL.
void i2c_slave_mode(i2c_t *obj, int enable_slave)
Configure I2C as slave or master.
const PinMap * i2c_master_sda_pinmap(void)
Get the pins that support I2C SDA.
void i2c_init(i2c_t *obj, PinName sda, PinName scl)
Initialize the I2C peripheral.
Generic buffer structure.
Definition: buffer.h:27
int i2c_slave_read(i2c_t *obj, char *data, int length)
Configure I2C as slave or master.
uint8_t i2c_active(i2c_t *obj)
Attempts to determine if the I2C peripheral is already in use.
void i2c_transfer_asynch(i2c_t *obj, const void *tx, size_t tx_length, void *rx, size_t rx_length, uint32_t address, uint32_t stop, uint32_t handler, uint32_t event, DMAUsage hint)
Start I2C asynchronous transfer.
const PinMap * i2c_slave_sda_pinmap(void)
Get the pins that support I2C SDA.
const PinMap * i2c_slave_scl_pinmap(void)
Get the pins that support I2C SCL.
Asynch I2C HAL structure.
Definition: i2c_api.h:49
int i2c_byte_read(i2c_t *obj, int last)
Read one byte.
int i2c_slave_receive(i2c_t *obj)
Check to see if the I2C slave has been addressed.
int i2c_write(i2c_t *obj, int address, const char *data, int length, int stop)
Blocking sending data.
int i2c_byte_write(i2c_t *obj, int data)
Write one byte.
uint32_t i2c_irq_handler_asynch(i2c_t *obj)
The asynchronous IRQ handler.
int i2c_stop(i2c_t *obj)
Send STOP command.
int i2c_start(i2c_t *obj)
Send START command.
void i2c_reset(i2c_t *obj)
Reset I2C peripheral.
void i2c_slave_address(i2c_t *obj, int idx, uint32_t address, uint32_t mask)
Configure I2C address.
Definition: pinmap.h:31
void i2c_frequency(i2c_t *obj, int hz)
Configure the I2C frequency.
int i2c_slave_write(i2c_t *obj, const char *data, int length)
Configure I2C as slave or master.
int i2c_read(i2c_t *obj, int address, char *data, int length, int stop)
Blocking reading data.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.