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