1 /**
2 * @file
3 *
4 * @brief Public APIs for the I2C drivers.
5 */
6
7 /*
8 * Copyright (c) 2015 Intel Corporation
9 *
10 * SPDX-License-Identifier: Apache-2.0
11 */
12 #ifndef ZEPHYR_INCLUDE_DRIVERS_I2C_H_
13 #define ZEPHYR_INCLUDE_DRIVERS_I2C_H_
14
15 /**
16 * @brief I2C Interface
17 * @defgroup i2c_interface I2C Interface
18 * @ingroup io_interfaces
19 * @{
20 */
21
22 #include <zephyr/types.h>
23 #include <device.h>
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 /*
30 * The following #defines are used to configure the I2C controller.
31 */
32
33 /** I2C Standard Speed: 100 kHz */
34 #define I2C_SPEED_STANDARD (0x1U)
35
36 /** I2C Fast Speed: 400 kHz */
37 #define I2C_SPEED_FAST (0x2U)
38
39 /** I2C Fast Plus Speed: 1 MHz */
40 #define I2C_SPEED_FAST_PLUS (0x3U)
41
42 /** I2C High Speed: 3.4 MHz */
43 #define I2C_SPEED_HIGH (0x4U)
44
45 /** I2C Ultra Fast Speed: 5 MHz */
46 #define I2C_SPEED_ULTRA (0x5U)
47
48 #define I2C_SPEED_SHIFT (1U)
49 #define I2C_SPEED_SET(speed) (((speed) << I2C_SPEED_SHIFT) \
50 & I2C_SPEED_MASK)
51 #define I2C_SPEED_MASK (0x7U << I2C_SPEED_SHIFT) /* 3 bits */
52 #define I2C_SPEED_GET(cfg) (((cfg) & I2C_SPEED_MASK) \
53 >> I2C_SPEED_SHIFT)
54
55 /** Use 10-bit addressing. DEPRECATED - Use I2C_MSG_ADDR_10_BITS instead. */
56 #define I2C_ADDR_10_BITS BIT(0)
57
58 /** Controller to act as Master. */
59 #define I2C_MODE_MASTER BIT(4)
60
61 /**
62 * @brief Complete I2C DT information
63 *
64 * @param bus is the I2C bus
65 * @param addr is the slave address
66 */
67 struct i2c_dt_spec {
68 const struct device *bus;
69 uint16_t addr;
70 };
71
72 /**
73 * @brief Structure initializer for i2c_dt_spec from devicetree
74 *
75 * This helper macro expands to a static initializer for a <tt>struct
76 * i2c_dt_spec</tt> by reading the relevant bus and address data from
77 * the devicetree.
78 *
79 * @param node_id Devicetree node identifier for the I2C device whose
80 * struct i2c_dt_spec to create an initializer for
81 */
82 #define I2C_DT_SPEC_GET(node_id) \
83 { \
84 .bus = DEVICE_DT_GET(DT_BUS(node_id)), \
85 .addr = DT_REG_ADDR(node_id) \
86 }
87
88 /**
89 * @brief Structure initializer for i2c_dt_spec from devicetree instance
90 *
91 * This is equivalent to
92 * <tt>I2C_DT_SPEC_GET(DT_DRV_INST(inst))</tt>.
93 *
94 * @param inst Devicetree instance number
95 */
96 #define I2C_DT_SPEC_INST_GET(inst) \
97 I2C_DT_SPEC_GET(DT_DRV_INST(inst))
98
99
100 /*
101 * I2C_MSG_* are I2C Message flags.
102 */
103
104 /** Write message to I2C bus. */
105 #define I2C_MSG_WRITE (0U << 0U)
106
107 /** Read message from I2C bus. */
108 #define I2C_MSG_READ BIT(0)
109
110 /** @cond INTERNAL_HIDDEN */
111 #define I2C_MSG_RW_MASK BIT(0)
112 /** @endcond */
113
114 /** Send STOP after this message. */
115 #define I2C_MSG_STOP BIT(1)
116
117 /** RESTART I2C transaction for this message.
118 *
119 * @note Not all I2C drivers have or require explicit support for this
120 * feature. Some drivers require this be present on a read message
121 * that follows a write, or vice-versa. Some drivers will merge
122 * adjacent fragments into a single transaction using this flag; some
123 * will not. */
124 #define I2C_MSG_RESTART BIT(2)
125
126 /** Use 10-bit addressing for this message.
127 *
128 * @note Not all SoC I2C implementations support this feature. */
129 #define I2C_MSG_ADDR_10_BITS BIT(3)
130
131 /**
132 * @brief One I2C Message.
133 *
134 * This defines one I2C message to transact on the I2C bus.
135 *
136 * @note Some of the configurations supported by this API may not be
137 * supported by specific SoC I2C hardware implementations, in
138 * particular features related to bus transactions intended to read or
139 * write data from different buffers within a single transaction.
140 * Invocations of i2c_transfer() may not indicate an error when an
141 * unsupported configuration is encountered. In some cases drivers
142 * will generate separate transactions for each message fragment, with
143 * or without presence of @ref I2C_MSG_RESTART in #flags.
144 */
145 struct i2c_msg {
146 /** Data buffer in bytes */
147 uint8_t *buf;
148
149 /** Length of buffer in bytes */
150 uint32_t len;
151
152 /** Flags for this message */
153 uint8_t flags;
154 };
155
156 /**
157 * @cond INTERNAL_HIDDEN
158 *
159 * These are for internal use only, so skip these in
160 * public documentation.
161 */
162 struct i2c_slave_config;
163
164 typedef int (*i2c_api_configure_t)(const struct device *dev,
165 uint32_t dev_config);
166 typedef int (*i2c_api_full_io_t)(const struct device *dev,
167 struct i2c_msg *msgs,
168 uint8_t num_msgs,
169 uint16_t addr);
170 typedef int (*i2c_api_slave_register_t)(const struct device *dev,
171 struct i2c_slave_config *cfg);
172 typedef int (*i2c_api_slave_unregister_t)(const struct device *dev,
173 struct i2c_slave_config *cfg);
174 typedef int (*i2c_api_recover_bus_t)(const struct device *dev);
175
176 __subsystem struct i2c_driver_api {
177 i2c_api_configure_t configure;
178 i2c_api_full_io_t transfer;
179 i2c_api_slave_register_t slave_register;
180 i2c_api_slave_unregister_t slave_unregister;
181 i2c_api_recover_bus_t recover_bus;
182 };
183
184 typedef int (*i2c_slave_api_register_t)(const struct device *dev);
185 typedef int (*i2c_slave_api_unregister_t)(const struct device *dev);
186
187 struct i2c_slave_driver_api {
188 i2c_slave_api_register_t driver_register;
189 i2c_slave_api_unregister_t driver_unregister;
190 };
191
192 /**
193 * @endcond
194 */
195
196 /** Slave device responds to 10-bit addressing. */
197 #define I2C_SLAVE_FLAGS_ADDR_10_BITS BIT(0)
198
199 /** @brief Function called when a write to the device is initiated.
200 *
201 * This function is invoked by the controller when the bus completes a
202 * start condition for a write operation to the address associated
203 * with a particular device.
204 *
205 * A success return shall cause the controller to ACK the next byte
206 * received. An error return shall cause the controller to NACK the
207 * next byte received.
208 *
209 * @param config the configuration structure associated with the
210 * device to which the operation is addressed.
211 *
212 * @return 0 if the write is accepted, or a negative error code.
213 */
214 typedef int (*i2c_slave_write_requested_cb_t)(
215 struct i2c_slave_config *config);
216
217 /** @brief Function called when a write to the device is continued.
218 *
219 * This function is invoked by the controller when it completes
220 * reception of a byte of data in an ongoing write operation to the
221 * device.
222 *
223 * A success return shall cause the controller to ACK the next byte
224 * received. An error return shall cause the controller to NACK the
225 * next byte received.
226 *
227 * @param config the configuration structure associated with the
228 * device to which the operation is addressed.
229 *
230 * @param val the byte received by the controller.
231 *
232 * @return 0 if more data can be accepted, or a negative error
233 * code.
234 */
235 typedef int (*i2c_slave_write_received_cb_t)(
236 struct i2c_slave_config *config, uint8_t val);
237
238 /** @brief Function called when a read from the device is initiated.
239 *
240 * This function is invoked by the controller when the bus completes a
241 * start condition for a read operation from the address associated
242 * with a particular device.
243 *
244 * The value returned in @p *val will be transmitted. A success
245 * return shall cause the controller to react to additional read
246 * operations. An error return shall cause the controller to ignore
247 * bus operations until a new start condition is received.
248 *
249 * @param config the configuration structure associated with the
250 * device to which the operation is addressed.
251 *
252 * @param val pointer to storage for the first byte of data to return
253 * for the read request.
254 *
255 * @return 0 if more data can be requested, or a negative error code.
256 */
257 typedef int (*i2c_slave_read_requested_cb_t)(
258 struct i2c_slave_config *config, uint8_t *val);
259
260 /** @brief Function called when a read from the device is continued.
261 *
262 * This function is invoked by the controller when the bus is ready to
263 * provide additional data for a read operation from the address
264 * associated with the device device.
265 *
266 * The value returned in @p *val will be transmitted. A success
267 * return shall cause the controller to react to additional read
268 * operations. An error return shall cause the controller to ignore
269 * bus operations until a new start condition is received.
270 *
271 * @param config the configuration structure associated with the
272 * device to which the operation is addressed.
273 *
274 * @param val pointer to storage for the next byte of data to return
275 * for the read request.
276 *
277 * @return 0 if data has been provided, or a negative error code.
278 */
279 typedef int (*i2c_slave_read_processed_cb_t)(
280 struct i2c_slave_config *config, uint8_t *val);
281
282 /** @brief Function called when a stop condition is observed after a
283 * start condition addressed to a particular device.
284 *
285 * This function is invoked by the controller when the bus is ready to
286 * provide additional data for a read operation from the address
287 * associated with the device device. After the function returns the
288 * controller shall enter a state where it is ready to react to new
289 * start conditions.
290 *
291 * @param config the configuration structure associated with the
292 * device to which the operation is addressed.
293 *
294 * @return Ignored.
295 */
296 typedef int (*i2c_slave_stop_cb_t)(struct i2c_slave_config *config);
297
298 /** @brief Structure providing callbacks to be implemented for devices
299 * that supports the I2C slave API.
300 *
301 * This structure may be shared by multiple devices that implement the
302 * same API at different addresses on the bus.
303 */
304 struct i2c_slave_callbacks {
305 i2c_slave_write_requested_cb_t write_requested;
306 i2c_slave_read_requested_cb_t read_requested;
307 i2c_slave_write_received_cb_t write_received;
308 i2c_slave_read_processed_cb_t read_processed;
309 i2c_slave_stop_cb_t stop;
310 };
311
312 /** @brief Structure describing a device that supports the I2C
313 * slave API.
314 *
315 * Instances of this are passed to the i2c_slave_register() and
316 * i2c_slave_unregister() functions to indicate addition and removal
317 * of a slave device, respective.
318 *
319 * Fields other than @c node must be initialized by the module that
320 * implements the device behavior prior to passing the object
321 * reference to i2c_slave_register().
322 */
323 struct i2c_slave_config {
324 /** Private, do not modify */
325 sys_snode_t node;
326
327 /** Flags for the slave device defined by I2C_SLAVE_FLAGS_* constants */
328 uint8_t flags;
329
330 /** Address for this slave device */
331 uint16_t address;
332
333 /** Callback functions */
334 const struct i2c_slave_callbacks *callbacks;
335 };
336
337 /**
338 * @brief Configure operation of a host controller.
339 *
340 * @param dev Pointer to the device structure for the driver instance.
341 * @param dev_config Bit-packed 32-bit value to the device runtime configuration
342 * for the I2C controller.
343 *
344 * @retval 0 If successful.
345 * @retval -EIO General input / output error, failed to configure device.
346 */
347 __syscall int i2c_configure(const struct device *dev, uint32_t dev_config);
348
z_impl_i2c_configure(const struct device * dev,uint32_t dev_config)349 static inline int z_impl_i2c_configure(const struct device *dev,
350 uint32_t dev_config)
351 {
352 const struct i2c_driver_api *api =
353 (const struct i2c_driver_api *)dev->api;
354
355 return api->configure(dev, dev_config);
356 }
357
358 /**
359 * @brief Perform data transfer to another I2C device in master mode.
360 *
361 * This routine provides a generic interface to perform data transfer
362 * to another I2C device synchronously. Use i2c_read()/i2c_write()
363 * for simple read or write.
364 *
365 * The array of message @a msgs must not be NULL. The number of
366 * message @a num_msgs may be zero,in which case no transfer occurs.
367 *
368 * @note Not all scatter/gather transactions can be supported by all
369 * drivers. As an example, a gather write (multiple consecutive
370 * `i2c_msg` buffers all configured for `I2C_MSG_WRITE`) may be packed
371 * into a single transaction by some drivers, but others may emit each
372 * fragment as a distinct write transaction, which will not produce
373 * the same behavior. See the documentation of `struct i2c_msg` for
374 * limitations on support for multi-message bus transactions.
375 *
376 * @param dev Pointer to the device structure for an I2C controller
377 * driver configured in master mode.
378 * @param msgs Array of messages to transfer.
379 * @param num_msgs Number of messages to transfer.
380 * @param addr Address of the I2C target device.
381 *
382 * @retval 0 If successful.
383 * @retval -EIO General input / output error.
384 */
385 __syscall int i2c_transfer(const struct device *dev,
386 struct i2c_msg *msgs, uint8_t num_msgs,
387 uint16_t addr);
388
z_impl_i2c_transfer(const struct device * dev,struct i2c_msg * msgs,uint8_t num_msgs,uint16_t addr)389 static inline int z_impl_i2c_transfer(const struct device *dev,
390 struct i2c_msg *msgs, uint8_t num_msgs,
391 uint16_t addr)
392 {
393 const struct i2c_driver_api *api =
394 (const struct i2c_driver_api *)dev->api;
395
396 return api->transfer(dev, msgs, num_msgs, addr);
397 }
398
399 /**
400 * @brief Perform data transfer to another I2C device in master mode.
401 *
402 * This is equivalent to:
403 *
404 * i2c_transfer(spec->bus, msgs, num_msgs, spec->addr);
405 *
406 * @param spec I2C specification from devicetree.
407 * @param msgs Array of messages to transfer.
408 * @param num_msgs Number of messages to transfer.
409 *
410 * @return a value from i2c_transfer()
411 */
i2c_transfer_dt(const struct i2c_dt_spec * spec,struct i2c_msg * msgs,uint8_t num_msgs)412 static inline int i2c_transfer_dt(const struct i2c_dt_spec *spec,
413 struct i2c_msg *msgs, uint8_t num_msgs)
414 {
415 return i2c_transfer(spec->bus, msgs, num_msgs, spec->addr);
416 }
417
418 /**
419 * @brief Recover the I2C bus
420 *
421 * Attempt to recover the I2C bus.
422 *
423 * @param dev Pointer to the device structure for an I2C controller
424 * driver configured in master mode.
425 * @retval 0 If successful
426 * @retval -EBUSY If bus is not clear after recovery attempt.
427 * @retval -EIO General input / output error.
428 * @retval -ENOSYS If bus recovery is not implemented
429 */
430 __syscall int i2c_recover_bus(const struct device *dev);
431
z_impl_i2c_recover_bus(const struct device * dev)432 static inline int z_impl_i2c_recover_bus(const struct device *dev)
433 {
434 const struct i2c_driver_api *api =
435 (const struct i2c_driver_api *)dev->api;
436
437 if (api->recover_bus == NULL) {
438 return -ENOSYS;
439 }
440
441 return api->recover_bus(dev);
442 }
443
444 /**
445 * @brief Registers the provided config as Slave device of a controller.
446 *
447 * Enable I2C slave mode for the 'dev' I2C bus driver using the provided
448 * 'config' struct containing the functions and parameters to send bus
449 * events. The I2C slave will be registered at the address provided as 'address'
450 * struct member. Addressing mode - 7 or 10 bit - depends on the 'flags'
451 * struct member. Any I2C bus events related to the slave mode will be passed
452 * onto I2C slave device driver via a set of callback functions provided in
453 * the 'callbacks' struct member.
454 *
455 * Most of the existing hardware allows simultaneous support for master
456 * and slave mode. This is however not guaranteed.
457 *
458 * @param dev Pointer to the device structure for an I2C controller
459 * driver configured in slave mode.
460 * @param cfg Config struct with functions and parameters used by the I2C driver
461 * to send bus events
462 *
463 * @retval 0 Is successful
464 * @retval -EINVAL If parameters are invalid
465 * @retval -EIO General input / output error.
466 * @retval -ENOSYS If slave mode is not implemented
467 */
i2c_slave_register(const struct device * dev,struct i2c_slave_config * cfg)468 static inline int i2c_slave_register(const struct device *dev,
469 struct i2c_slave_config *cfg)
470 {
471 const struct i2c_driver_api *api =
472 (const struct i2c_driver_api *)dev->api;
473
474 if (api->slave_register == NULL) {
475 return -ENOSYS;
476 }
477
478 return api->slave_register(dev, cfg);
479 }
480
481 /**
482 * @brief Unregisters the provided config as Slave device
483 *
484 * This routine disables I2C slave mode for the 'dev' I2C bus driver using
485 * the provided 'config' struct containing the functions and parameters
486 * to send bus events.
487 *
488 * @param dev Pointer to the device structure for an I2C controller
489 * driver configured in slave mode.
490 * @param cfg Config struct with functions and parameters used by the I2C driver
491 * to send bus events
492 *
493 * @retval 0 Is successful
494 * @retval -EINVAL If parameters are invalid
495 * @retval -ENOSYS If slave mode is not implemented
496 */
i2c_slave_unregister(const struct device * dev,struct i2c_slave_config * cfg)497 static inline int i2c_slave_unregister(const struct device *dev,
498 struct i2c_slave_config *cfg)
499 {
500 const struct i2c_driver_api *api =
501 (const struct i2c_driver_api *)dev->api;
502
503 if (api->slave_unregister == NULL) {
504 return -ENOSYS;
505 }
506
507 return api->slave_unregister(dev, cfg);
508 }
509
510 /**
511 * @brief Instructs the I2C Slave device to register itself to the I2C Controller
512 *
513 * This routine instructs the I2C Slave device to register itself to the I2C
514 * Controller via its parent controller's i2c_slave_register() API.
515 *
516 * @param dev Pointer to the device structure for the I2C slave
517 * device (not itself an I2C controller).
518 *
519 * @retval 0 Is successful
520 * @retval -EINVAL If parameters are invalid
521 * @retval -EIO General input / output error.
522 */
523 __syscall int i2c_slave_driver_register(const struct device *dev);
524
z_impl_i2c_slave_driver_register(const struct device * dev)525 static inline int z_impl_i2c_slave_driver_register(const struct device *dev)
526 {
527 const struct i2c_slave_driver_api *api =
528 (const struct i2c_slave_driver_api *)dev->api;
529
530 return api->driver_register(dev);
531 }
532
533 /**
534 * @brief Instructs the I2C Slave device to unregister itself from the I2C
535 * Controller
536 *
537 * This routine instructs the I2C Slave device to unregister itself from the I2C
538 * Controller via its parent controller's i2c_slave_register() API.
539 *
540 * @param dev Pointer to the device structure for the I2C slave
541 * device (not itself an I2C controller).
542 *
543 * @retval 0 Is successful
544 * @retval -EINVAL If parameters are invalid
545 */
546 __syscall int i2c_slave_driver_unregister(const struct device *dev);
547
z_impl_i2c_slave_driver_unregister(const struct device * dev)548 static inline int z_impl_i2c_slave_driver_unregister(const struct device *dev)
549 {
550 const struct i2c_slave_driver_api *api =
551 (const struct i2c_slave_driver_api *)dev->api;
552
553 return api->driver_unregister(dev);
554 }
555
556 /*
557 * Derived i2c APIs -- all implemented in terms of i2c_transfer()
558 */
559
560 /**
561 * @brief Write a set amount of data to an I2C device.
562 *
563 * This routine writes a set amount of data synchronously.
564 *
565 * @param dev Pointer to the device structure for an I2C controller
566 * driver configured in master mode.
567 * @param buf Memory pool from which the data is transferred.
568 * @param num_bytes Number of bytes to write.
569 * @param addr Address to the target I2C device for writing.
570 *
571 * @retval 0 If successful.
572 * @retval -EIO General input / output error.
573 */
i2c_write(const struct device * dev,const uint8_t * buf,uint32_t num_bytes,uint16_t addr)574 static inline int i2c_write(const struct device *dev, const uint8_t *buf,
575 uint32_t num_bytes, uint16_t addr)
576 {
577 struct i2c_msg msg;
578
579 msg.buf = (uint8_t *)buf;
580 msg.len = num_bytes;
581 msg.flags = I2C_MSG_WRITE | I2C_MSG_STOP;
582
583 return i2c_transfer(dev, &msg, 1, addr);
584 }
585
586 /**
587 * @brief Write a set amount of data to an I2C device.
588 *
589 * This is equivalent to:
590 *
591 * i2c_write(spec->bus, buf, num_bytes, spec->addr);
592 *
593 * @param spec I2C specification from devicetree.
594 * @param buf Memory pool from which the data is transferred.
595 * @param num_bytes Number of bytes to write.
596 *
597 * @return a value from i2c_write()
598 */
i2c_write_dt(const struct i2c_dt_spec * spec,const uint8_t * buf,uint32_t num_bytes)599 static inline int i2c_write_dt(const struct i2c_dt_spec *spec,
600 const uint8_t *buf, uint32_t num_bytes)
601 {
602 return i2c_write(spec->bus, buf, num_bytes, spec->addr);
603 }
604
605 /**
606 * @brief Read a set amount of data from an I2C device.
607 *
608 * This routine reads a set amount of data synchronously.
609 *
610 * @param dev Pointer to the device structure for an I2C controller
611 * driver configured in master mode.
612 * @param buf Memory pool that stores the retrieved data.
613 * @param num_bytes Number of bytes to read.
614 * @param addr Address of the I2C device being read.
615 *
616 * @retval 0 If successful.
617 * @retval -EIO General input / output error.
618 */
i2c_read(const struct device * dev,uint8_t * buf,uint32_t num_bytes,uint16_t addr)619 static inline int i2c_read(const struct device *dev, uint8_t *buf,
620 uint32_t num_bytes, uint16_t addr)
621 {
622 struct i2c_msg msg;
623
624 msg.buf = buf;
625 msg.len = num_bytes;
626 msg.flags = I2C_MSG_READ | I2C_MSG_STOP;
627
628 return i2c_transfer(dev, &msg, 1, addr);
629 }
630
631 /**
632 * @brief Read a set amount of data from an I2C device.
633 *
634 * This is equivalent to:
635 *
636 * i2c_read(spec->bus, buf, num_bytes, spec->addr);
637 *
638 * @param spec I2C specification from devicetree.
639 * @param buf Memory pool that stores the retrieved data.
640 * @param num_bytes Number of bytes to read.
641 *
642 * @return a value from i2c_read()
643 */
i2c_read_dt(const struct i2c_dt_spec * spec,uint8_t * buf,uint32_t num_bytes)644 static inline int i2c_read_dt(const struct i2c_dt_spec *spec,
645 uint8_t *buf, uint32_t num_bytes)
646 {
647 return i2c_read(spec->bus, buf, num_bytes, spec->addr);
648 }
649
650 /**
651 * @brief Write then read data from an I2C device.
652 *
653 * This supports the common operation "this is what I want", "now give
654 * it to me" transaction pair through a combined write-then-read bus
655 * transaction.
656 *
657 * @param dev Pointer to the device structure for an I2C controller
658 * driver configured in master mode.
659 * @param addr Address of the I2C device
660 * @param write_buf Pointer to the data to be written
661 * @param num_write Number of bytes to write
662 * @param read_buf Pointer to storage for read data
663 * @param num_read Number of bytes to read
664 *
665 * @retval 0 if successful
666 * @retval negative on error.
667 */
i2c_write_read(const struct device * dev,uint16_t addr,const void * write_buf,size_t num_write,void * read_buf,size_t num_read)668 static inline int i2c_write_read(const struct device *dev, uint16_t addr,
669 const void *write_buf, size_t num_write,
670 void *read_buf, size_t num_read)
671 {
672 struct i2c_msg msg[2];
673
674 msg[0].buf = (uint8_t *)write_buf;
675 msg[0].len = num_write;
676 msg[0].flags = I2C_MSG_WRITE;
677
678 msg[1].buf = (uint8_t *)read_buf;
679 msg[1].len = num_read;
680 msg[1].flags = I2C_MSG_RESTART | I2C_MSG_READ | I2C_MSG_STOP;
681
682 return i2c_transfer(dev, msg, 2, addr);
683 }
684
685 /**
686 * @brief Write then read data from an I2C device.
687 *
688 * This is equivalent to:
689 *
690 * i2c_write_read(spec->bus, spec->addr,
691 * write_buf, num_write,
692 * read_buf, num_read);
693 *
694 * @param spec I2C specification from devicetree.
695 * @param write_buf Pointer to the data to be written
696 * @param num_write Number of bytes to write
697 * @param read_buf Pointer to storage for read data
698 * @param num_read Number of bytes to read
699 *
700 * @return a value from i2c_write_read()
701 */
i2c_write_read_dt(const struct i2c_dt_spec * spec,const void * write_buf,size_t num_write,void * read_buf,size_t num_read)702 static inline int i2c_write_read_dt(const struct i2c_dt_spec *spec,
703 const void *write_buf, size_t num_write,
704 void *read_buf, size_t num_read)
705 {
706 return i2c_write_read(spec->bus, spec->addr,
707 write_buf, num_write,
708 read_buf, num_read);
709 }
710
711 /**
712 * @brief Read multiple bytes from an internal address of an I2C device.
713 *
714 * This routine reads multiple bytes from an internal address of an
715 * I2C device synchronously.
716 *
717 * Instances of this may be replaced by i2c_write_read().
718 *
719 * @param dev Pointer to the device structure for an I2C controller
720 * driver configured in master mode.
721 * @param dev_addr Address of the I2C device for reading.
722 * @param start_addr Internal address from which the data is being read.
723 * @param buf Memory pool that stores the retrieved data.
724 * @param num_bytes Number of bytes being read.
725 *
726 * @retval 0 If successful.
727 * @retval -EIO General input / output error.
728 */
i2c_burst_read(const struct device * dev,uint16_t dev_addr,uint8_t start_addr,uint8_t * buf,uint32_t num_bytes)729 static inline int i2c_burst_read(const struct device *dev,
730 uint16_t dev_addr,
731 uint8_t start_addr,
732 uint8_t *buf,
733 uint32_t num_bytes)
734 {
735 return i2c_write_read(dev, dev_addr,
736 &start_addr, sizeof(start_addr),
737 buf, num_bytes);
738 }
739
740 /**
741 * @brief Read multiple bytes from an internal address of an I2C device.
742 *
743 * This is equivalent to:
744 *
745 * i2c_burst_read(spec->bus, spec->addr, start_addr, buf, num_bytes);
746 *
747 * @param spec I2C specification from devicetree.
748 * @param start_addr Internal address from which the data is being read.
749 * @param buf Memory pool that stores the retrieved data.
750 * @param num_bytes Number of bytes to read.
751 *
752 * @return a value from i2c_burst_read()
753 */
i2c_burst_read_dt(const struct i2c_dt_spec * spec,uint8_t start_addr,uint8_t * buf,uint32_t num_bytes)754 static inline int i2c_burst_read_dt(const struct i2c_dt_spec *spec,
755 uint8_t start_addr,
756 uint8_t *buf,
757 uint32_t num_bytes)
758 {
759 return i2c_burst_read(spec->bus, spec->addr,
760 start_addr, buf, num_bytes);
761 }
762
763 /**
764 * @brief Write multiple bytes to an internal address of an I2C device.
765 *
766 * This routine writes multiple bytes to an internal address of an
767 * I2C device synchronously.
768 *
769 * @warning The combined write synthesized by this API may not be
770 * supported on all I2C devices. Uses of this API may be made more
771 * portable by replacing them with calls to i2c_write() passing a
772 * buffer containing the combined address and data.
773 *
774 * @param dev Pointer to the device structure for an I2C controller
775 * driver configured in master mode.
776 * @param dev_addr Address of the I2C device for writing.
777 * @param start_addr Internal address to which the data is being written.
778 * @param buf Memory pool from which the data is transferred.
779 * @param num_bytes Number of bytes being written.
780 *
781 * @retval 0 If successful.
782 * @retval -EIO General input / output error.
783 */
i2c_burst_write(const struct device * dev,uint16_t dev_addr,uint8_t start_addr,const uint8_t * buf,uint32_t num_bytes)784 static inline int i2c_burst_write(const struct device *dev,
785 uint16_t dev_addr,
786 uint8_t start_addr,
787 const uint8_t *buf,
788 uint32_t num_bytes)
789 {
790 struct i2c_msg msg[2];
791
792 msg[0].buf = &start_addr;
793 msg[0].len = 1U;
794 msg[0].flags = I2C_MSG_WRITE;
795
796 msg[1].buf = (uint8_t *)buf;
797 msg[1].len = num_bytes;
798 msg[1].flags = I2C_MSG_WRITE | I2C_MSG_STOP;
799
800 return i2c_transfer(dev, msg, 2, dev_addr);
801 }
802
803 /**
804 * @brief Write multiple bytes to an internal address of an I2C device.
805 *
806 * This is equivalent to:
807 *
808 * i2c_burst_write(spec->bus, spec->addr, start_addr, buf, num_bytes);
809 *
810 * @param spec I2C specification from devicetree.
811 * @param start_addr Internal address to which the data is being written.
812 * @param buf Memory pool from which the data is transferred.
813 * @param num_bytes Number of bytes being written.
814 *
815 * @return a value from i2c_burst_write()
816 */
i2c_burst_write_dt(const struct i2c_dt_spec * spec,uint8_t start_addr,const uint8_t * buf,uint32_t num_bytes)817 static inline int i2c_burst_write_dt(const struct i2c_dt_spec *spec,
818 uint8_t start_addr,
819 const uint8_t *buf,
820 uint32_t num_bytes)
821 {
822 return i2c_burst_write(spec->bus, spec->addr,
823 start_addr, buf, num_bytes);
824 }
825
826 /**
827 * @brief Read internal register of an I2C device.
828 *
829 * This routine reads the value of an 8-bit internal register of an I2C
830 * device synchronously.
831 *
832 * @param dev Pointer to the device structure for an I2C controller
833 * driver configured in master mode.
834 * @param dev_addr Address of the I2C device for reading.
835 * @param reg_addr Address of the internal register being read.
836 * @param value Memory pool that stores the retrieved register value.
837 *
838 * @retval 0 If successful.
839 * @retval -EIO General input / output error.
840 */
i2c_reg_read_byte(const struct device * dev,uint16_t dev_addr,uint8_t reg_addr,uint8_t * value)841 static inline int i2c_reg_read_byte(const struct device *dev,
842 uint16_t dev_addr,
843 uint8_t reg_addr, uint8_t *value)
844 {
845 return i2c_write_read(dev, dev_addr,
846 ®_addr, sizeof(reg_addr),
847 value, sizeof(*value));
848 }
849
850 /**
851 * @brief Read internal register of an I2C device.
852 *
853 * This is equivalent to:
854 *
855 * i2c_reg_read_byte(spec->bus, spec->addr, reg_addr, value);
856 *
857 * @param spec I2C specification from devicetree.
858 * @param reg_addr Address of the internal register being read.
859 * @param value Memory pool that stores the retrieved register value.
860 *
861 * @return a value from i2c_reg_read_byte()
862 */
i2c_reg_read_byte_dt(const struct i2c_dt_spec * spec,uint8_t reg_addr,uint8_t * value)863 static inline int i2c_reg_read_byte_dt(const struct i2c_dt_spec *spec,
864 uint8_t reg_addr, uint8_t *value)
865 {
866 return i2c_reg_read_byte(spec->bus, spec->addr, reg_addr, value);
867 }
868
869 /**
870 * @brief Write internal register of an I2C device.
871 *
872 * This routine writes a value to an 8-bit internal register of an I2C
873 * device synchronously.
874 *
875 * @note This function internally combines the register and value into
876 * a single bus transaction.
877 *
878 * @param dev Pointer to the device structure for an I2C controller
879 * driver configured in master mode.
880 * @param dev_addr Address of the I2C device for writing.
881 * @param reg_addr Address of the internal register being written.
882 * @param value Value to be written to internal register.
883 *
884 * @retval 0 If successful.
885 * @retval -EIO General input / output error.
886 */
i2c_reg_write_byte(const struct device * dev,uint16_t dev_addr,uint8_t reg_addr,uint8_t value)887 static inline int i2c_reg_write_byte(const struct device *dev,
888 uint16_t dev_addr,
889 uint8_t reg_addr, uint8_t value)
890 {
891 uint8_t tx_buf[2] = {reg_addr, value};
892
893 return i2c_write(dev, tx_buf, 2, dev_addr);
894 }
895
896 /**
897 * @brief Write internal register of an I2C device.
898 *
899 * This is equivalent to:
900 *
901 * i2c_reg_write_byte(spec->bus, spec->addr, reg_addr, value);
902 *
903 * @param spec I2C specification from devicetree.
904 * @param reg_addr Address of the internal register being written.
905 * @param value Value to be written to internal register.
906 *
907 * @return a value from i2c_reg_write_byte()
908 */
i2c_reg_write_byte_dt(const struct i2c_dt_spec * spec,uint8_t reg_addr,uint8_t value)909 static inline int i2c_reg_write_byte_dt(const struct i2c_dt_spec *spec,
910 uint8_t reg_addr, uint8_t value)
911 {
912 return i2c_reg_write_byte(spec->bus, spec->addr, reg_addr, value);
913 }
914
915 /**
916 * @brief Update internal register of an I2C device.
917 *
918 * This routine updates the value of a set of bits from an 8-bit internal
919 * register of an I2C device synchronously.
920 *
921 * @note If the calculated new register value matches the value that
922 * was read this function will not generate a write operation.
923 *
924 * @param dev Pointer to the device structure for an I2C controller
925 * driver configured in master mode.
926 * @param dev_addr Address of the I2C device for updating.
927 * @param reg_addr Address of the internal register being updated.
928 * @param mask Bitmask for updating internal register.
929 * @param value Value for updating internal register.
930 *
931 * @retval 0 If successful.
932 * @retval -EIO General input / output error.
933 */
i2c_reg_update_byte(const struct device * dev,uint8_t dev_addr,uint8_t reg_addr,uint8_t mask,uint8_t value)934 static inline int i2c_reg_update_byte(const struct device *dev,
935 uint8_t dev_addr,
936 uint8_t reg_addr, uint8_t mask,
937 uint8_t value)
938 {
939 uint8_t old_value, new_value;
940 int rc;
941
942 rc = i2c_reg_read_byte(dev, dev_addr, reg_addr, &old_value);
943 if (rc != 0) {
944 return rc;
945 }
946
947 new_value = (old_value & ~mask) | (value & mask);
948 if (new_value == old_value) {
949 return 0;
950 }
951
952 return i2c_reg_write_byte(dev, dev_addr, reg_addr, new_value);
953 }
954
955 /**
956 * @brief Update internal register of an I2C device.
957 *
958 * This is equivalent to:
959 *
960 * i2c_reg_update_byte(spec->bus, spec->addr, reg_addr, mask, value);
961 *
962 * @param spec I2C specification from devicetree.
963 * @param reg_addr Address of the internal register being updated.
964 * @param mask Bitmask for updating internal register.
965 * @param value Value for updating internal register.
966 *
967 * @return a value from i2c_reg_update_byte()
968 */
i2c_reg_update_byte_dt(const struct i2c_dt_spec * spec,uint8_t reg_addr,uint8_t mask,uint8_t value)969 static inline int i2c_reg_update_byte_dt(const struct i2c_dt_spec *spec,
970 uint8_t reg_addr, uint8_t mask,
971 uint8_t value)
972 {
973 return i2c_reg_update_byte(spec->bus, spec->addr,
974 reg_addr, mask, value);
975 }
976
977 /**
978 * @brief Dump out an I2C message
979 *
980 * Dumps out a list of I2C messages. For any that are writes (W), the data is
981 * displayed in hex.
982 *
983 * It looks something like this (with name "testing"):
984 *
985 * D: I2C msg: testing, addr=56
986 * D: W len=01:
987 * D: contents:
988 * D: 06 |.
989 * D: W len=0e:
990 * D: contents:
991 * D: 00 01 02 03 04 05 06 07 |........
992 * D: 08 09 0a 0b 0c 0d |......
993 *
994 * @param name Name of this dump, displayed at the top.
995 * @param msgs Array of messages to dump.
996 * @param num_msgs Number of messages to dump.
997 * @param addr Address of the I2C target device.
998 */
999 void i2c_dump_msgs(const char *name, const struct i2c_msg *msgs,
1000 uint8_t num_msgs, uint16_t addr);
1001
1002 struct i2c_client_config {
1003 char *i2c_master;
1004 uint16_t i2c_addr;
1005 };
1006
1007 #define I2C_DECLARE_CLIENT_CONFIG struct i2c_client_config i2c_client
1008
1009 #define I2C_CLIENT(_master, _addr) \
1010 .i2c_client = { \
1011 .i2c_master = (_master), \
1012 .i2c_addr = (_addr), \
1013 }
1014
1015 #define I2C_GET_MASTER(_conf) ((_conf)->i2c_client.i2c_master)
1016 #define I2C_GET_ADDR(_conf) ((_conf)->i2c_client.i2c_addr)
1017
1018 #ifdef __cplusplus
1019 }
1020 #endif
1021
1022 /**
1023 * @}
1024 */
1025
1026 #include <syscalls/i2c.h>
1027
1028 #endif /* ZEPHYR_INCLUDE_DRIVERS_I2C_H_ */
1029
