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 typedef struct {
68  int peripheral;
69  PinName sda_pin;
70  int sda_function;
71  PinName scl_pin;
72  int scl_function;
73 } i2c_pinmap_t;
74 
75 #ifdef __cplusplus
76 extern "C" {
77 #endif
78 
79 /**
80  * \defgroup hal_GeneralI2C I2C Configuration Functions
81  *
82  * # Defined behavior
83  * * ::i2c_init initializes i2c_t control structure
84  * * ::i2c_init configures the pins used by I2C
85  * * ::i2c_free returns the pins owned by the I2C object to their reset state
86  * * ::i2c_frequency configure the I2C frequency
87  * * ::i2c_start sends START command
88  * * ::i2c_read reads `length` bytes from the I2C slave specified by `address` to the `data` buffer
89  * * ::i2c_read reads generates a stop condition on the bus at the end of the transfer if `stop` parameter is non-zero
90  * * ::i2c_read reads returns the number of symbols received from the bus
91  * * ::i2c_write writes `length` bytes to the I2C slave specified by `address` from the `data` buffer
92  * * ::i2c_write generates a stop condition on the bus at the end of the transfer if `stop` parameter is non-zero
93  * * ::i2c_write returns zero on success, error code otherwise
94  * * ::i2c_reset resets the I2C peripheral
95  * * ::i2c_byte_read reads and return one byte from the specfied I2C slave
96  * * ::i2c_byte_read uses `last` parameter to inform the slave that all bytes have been read
97  * * ::i2c_byte_write writes one byte to the specified I2C slave
98  * * ::i2c_byte_write returns 0 if NAK was received, 1 if ACK was received, 2 for timeout
99  * * ::i2c_slave_mode enables/disables I2S slave mode
100  * * ::i2c_slave_receive returns: 1 - read addresses, 2 - write to all slaves, 3 write addressed, 0 - the slave has not been addressed
101  * * ::i2c_slave_read reads `length` bytes from the I2C master to the `data` buffer
102  * * ::i2c_slave_read returns non-zero if a value is available, 0 otherwise
103  * * ::i2c_slave_write writes `length` bytes to the I2C master from the `data` buffer
104  * * ::i2c_slave_write returns non-zero if a value is available, 0 otherwise
105  * * ::i2c_slave_address configures I2C slave address
106  * * ::i2c_transfer_asynch starts I2C asynchronous transfer
107  * * ::i2c_transfer_asynch writes `tx_length` bytes to the I2C slave specified by `address` from the `tx` buffer
108  * * ::i2c_transfer_asynch reads `rx_length` bytes from the I2C slave specified by `address` to the `rx` buffer
109  * * ::i2c_transfer_asynch generates a stop condition on the bus at the end of the transfer if `stop` parameter is non-zero
110  * * The callback given to ::i2c_transfer_asynch is invoked when the transfer completes
111  * * ::i2c_transfer_asynch specifies the logical OR of events to be registered
112  * * The ::i2c_transfer_asynch function may use the `DMAUsage` hint to select the appropriate async algorithm
113  * * ::i2c_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise returns 0.
114  * * ::i2c_active returns non-zero if the I2C module is active or 0 if it is not
115  * * ::i2c_abort_asynch aborts an on-going async transfer
116  *
117  * # Undefined behavior
118  * * Calling ::i2c_init multiple times on the same `i2c_t`
119  * * Calling any function other than ::i2c_init on a non-initialized `i2c_t`
120  * * Initialising the `I2C` peripheral with invalid `SDA` and `SCL` pins.
121  * * Passing pins that cannot be on the same peripheral
122  * * Passing an invalid pointer as `obj` to any function
123  * * Use of a `null` pointer as an argument to any function.
124  * * Initialising the peripheral in slave mode if slave mode is not supported
125  * * Operating the peripheral in slave mode without first specifying and address using ::i2c_slave_address
126  * * Setting an address using i2c_slave_address after initialising the peripheral in master mode
127  * * Setting an address to an `I2C` reserved value
128  * * Specifying an invalid address when calling any `read` or `write` functions
129  * * Setting the length of the transfer or receive buffers to larger than the buffers are
130  * * Passing an invalid pointer as `handler`
131  * * Calling ::i2c_abort_async when no transfer is currently in progress
132  *
133  *
134  * @{
135  */
136 
137 /**
138  * \defgroup hal_GeneralI2C_tests I2C hal tests
139  * The I2C HAL tests ensure driver conformance to defined behaviour.
140  *
141  * To run the I2C hal tests use the command:
142  *
143  * mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-i2c
144  *
145  */
146 
147 /** Initialize the I2C peripheral. It sets the default parameters for I2C
148  * peripheral, and configures its specifieds pins.
149  *
150  * @param obj The I2C object
151  * @param pinmap Pinmap pointer to structure which holds static pinmap
152  */
153 void i2c_init_direct(i2c_t *obj, const i2c_pinmap_t *pinmap);
154 
155 /** Initialize the I2C peripheral. It sets the default parameters for I2C
156  * peripheral, and configures its specifieds pins.
157  *
158  * @param obj The I2C object
159  * @param sda The sda pin
160  * @param scl The scl pin
161  */
162 void i2c_init(i2c_t *obj, PinName sda, PinName scl);
163 
164 /** Release a I2C object
165  *
166  * Return the pins owned by the I2C object to their reset state
167  * @param obj The I2C object to deinitialize
168  */
169 void i2c_free(i2c_t *obj);
170 
171 /** Configure the I2C frequency
172  *
173  * @param obj The I2C object
174  * @param hz Frequency in Hz
175  */
176 void i2c_frequency(i2c_t *obj, int hz);
177 
178 /** Send START command
179  *
180  * @param obj The I2C object
181  */
182 int i2c_start(i2c_t *obj);
183 
184 /** Send STOP command
185  *
186  * @param obj The I2C object
187  */
188 int i2c_stop(i2c_t *obj);
189 
190 /** Blocking reading data
191  *
192  * @param obj The I2C object
193  * @param address 7-bit address (last bit is 1)
194  * @param data The buffer for receiving
195  * @param length Number of bytes to read
196  * @param stop Stop to be generated after the transfer is done
197  * @return Number of read bytes
198  */
199 int i2c_read(i2c_t *obj, int address, char *data, int length, int stop);
200 
201 /** Blocking sending data
202  *
203  * @param obj The I2C object
204  * @param address 7-bit address (last bit is 0)
205  * @param data The buffer for sending
206  * @param length Number of bytes to write
207  * @param stop Stop to be generated after the transfer is done
208  * @return
209  * zero or non-zero - Number of written bytes
210  * negative - I2C_ERROR_XXX status
211  */
212 int i2c_write(i2c_t *obj, int address, const char *data, int length, int stop);
213 
214 /** Reset I2C peripheral. TODO: The action here. Most of the implementation sends stop()
215  *
216  * @param obj The I2C object
217  */
218 void i2c_reset(i2c_t *obj);
219 
220 /** Read one byte
221  *
222  * @param obj The I2C object
223  * @param last Acknoledge
224  * @return The read byte
225  */
226 int i2c_byte_read(i2c_t *obj, int last);
227 
228 /** Write one byte
229  *
230  * @param obj The I2C object
231  * @param data Byte to be written
232  * @return 0 if NAK was received, 1 if ACK was received, 2 for timeout.
233  */
234 int i2c_byte_write(i2c_t *obj, int data);
235 
236 /** Get the pins that support I2C SDA
237  *
238  * Return a PinMap array of pins that support I2C SDA in
239  * master mode. The array is terminated with {NC, NC, 0}.
240  *
241  * @return PinMap array
242  */
243 const PinMap *i2c_master_sda_pinmap(void);
244 
245 /** Get the pins that support I2C SCL
246  *
247  * Return a PinMap array of pins that support I2C SCL in
248  * master mode. The array is terminated with {NC, NC, 0}.
249  *
250  * @return PinMap array
251  */
252 const PinMap *i2c_master_scl_pinmap(void);
253 
254 /** Get the pins that support I2C SDA
255  *
256  * Return a PinMap array of pins that support I2C SDA in
257  * slave mode. The array is terminated with {NC, NC, 0}.
258  *
259  * @return PinMap array
260  */
261 const PinMap *i2c_slave_sda_pinmap(void);
262 
263 /** Get the pins that support I2C SCL
264  *
265  * Return a PinMap array of pins that support I2C SCL in
266  * slave mode. The array is terminated with {NC, NC, 0}.
267  *
268  * @return PinMap array
269  */
270 const PinMap *i2c_slave_scl_pinmap(void);
271 
272 /**@}*/
273 
274 #if DEVICE_I2CSLAVE
275 
276 /**
277  * \defgroup SynchI2C Synchronous I2C Hardware Abstraction Layer for slave
278  * @{
279  */
280 
281 /** Configure I2C as slave or master.
282  * @param obj The I2C object
283  * @param enable_slave Enable i2c hardware so you can receive events with ::i2c_slave_receive
284  * @return non-zero if a value is available
285  */
286 void i2c_slave_mode(i2c_t *obj, int enable_slave);
287 
288 /** Check to see if the I2C slave has been addressed.
289  * @param obj The I2C object
290  * @return The status - 1 - read addresses, 2 - write to all slaves,
291  * 3 write addressed, 0 - the slave has not been addressed
292  */
293 int i2c_slave_receive(i2c_t *obj);
294 
295 /** Configure I2C as slave or master.
296  * @param obj The I2C object
297  * @param data The buffer for receiving
298  * @param length Number of bytes to read
299  * @return non-zero if a value is available
300  */
301 int i2c_slave_read(i2c_t *obj, char *data, int length);
302 
303 /** Configure I2C as slave or master.
304  * @param obj The I2C object
305  * @param data The buffer for sending
306  * @param length Number of bytes to write
307  * @return non-zero if a value is available
308  */
309 int i2c_slave_write(i2c_t *obj, const char *data, int length);
310 
311 /** Configure I2C address.
312  * @param obj The I2C object
313  * @param idx Currently not used
314  * @param address The address to be set
315  * @param mask Currently not used
316  */
317 void i2c_slave_address(i2c_t *obj, int idx, uint32_t address, uint32_t mask);
318 
319 #endif
320 
321 /**@}*/
322 
323 #if DEVICE_I2C_ASYNCH
324 
325 /**
326  * \defgroup hal_AsynchI2C Asynchronous I2C Hardware Abstraction Layer
327  * @{
328  */
329 
330 /** Start I2C asynchronous transfer
331  *
332  * @param obj The I2C object
333  * @param tx The transmit buffer
334  * @param tx_length The number of bytes to transmit
335  * @param rx The receive buffer
336  * @param rx_length The number of bytes to receive
337  * @param address The address to be set - 7bit or 9bit
338  * @param stop If true, stop will be generated after the transfer is done
339  * @param handler The I2C IRQ handler to be set
340  * @param event Event mask for the transfer. See \ref hal_I2CEvents
341  * @param hint DMA hint usage
342  */
343 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);
344 
345 /** The asynchronous IRQ handler
346  *
347  * @param obj The I2C object which holds the transfer information
348  * @return Event flags if a transfer termination condition was met, otherwise return 0.
349  */
350 uint32_t i2c_irq_handler_asynch(i2c_t *obj);
351 
352 /** Attempts to determine if the I2C peripheral is already in use
353  *
354  * @param obj The I2C object
355  * @return Non-zero if the I2C module is active or zero if it is not
356  */
357 uint8_t i2c_active(i2c_t *obj);
358 
359 /** Abort asynchronous transfer
360  *
361  * This function does not perform any check - that should happen in upper layers.
362  * @param obj The I2C object
363  */
364 void i2c_abort_asynch(i2c_t *obj);
365 
366 #endif
367 
368 /**@}*/
369 
370 #ifdef __cplusplus
371 }
372 #endif
373 
374 #endif
375 
376 #endif
377 
378 /** @}*/
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.
void i2c_free(i2c_t *obj)
Release a I2C object.
int i2c_read(i2c_t *obj, int address, char *data, int length, int stop)
Blocking reading data.
void i2c_init_direct(i2c_t *obj, const i2c_pinmap_t *pinmap)
Initialize the I2C peripheral.
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.