Line data Source code
1 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 : * @since 1.0
19 : * @version 1.0.0
20 : * @ingroup io_interfaces
21 : * @{
22 : */
23 :
24 : #include <errno.h>
25 :
26 : #include <zephyr/types.h>
27 : #include <zephyr/device.h>
28 : #include <zephyr/kernel.h>
29 : #include <zephyr/sys/slist.h>
30 : #include <zephyr/rtio/rtio.h>
31 :
32 : #ifdef __cplusplus
33 : extern "C" {
34 : #endif
35 :
36 : /*
37 : * The following #defines are used to configure the I2C controller.
38 : */
39 :
40 : /** I2C Standard Speed: 100 kHz */
41 1 : #define I2C_SPEED_STANDARD (0x1U)
42 :
43 : /** I2C Fast Speed: 400 kHz */
44 1 : #define I2C_SPEED_FAST (0x2U)
45 :
46 : /** I2C Fast Plus Speed: 1 MHz */
47 1 : #define I2C_SPEED_FAST_PLUS (0x3U)
48 :
49 : /** I2C High Speed: 3.4 MHz */
50 1 : #define I2C_SPEED_HIGH (0x4U)
51 :
52 : /** I2C Ultra Fast Speed: 5 MHz */
53 1 : #define I2C_SPEED_ULTRA (0x5U)
54 :
55 : /** Device Tree specified speed */
56 1 : #define I2C_SPEED_DT (0x7U)
57 :
58 0 : #define I2C_SPEED_SHIFT (1U)
59 0 : #define I2C_SPEED_SET(speed) (((speed) << I2C_SPEED_SHIFT) \
60 : & I2C_SPEED_MASK)
61 0 : #define I2C_SPEED_MASK (0x7U << I2C_SPEED_SHIFT) /* 3 bits */
62 0 : #define I2C_SPEED_GET(cfg) (((cfg) & I2C_SPEED_MASK) \
63 : >> I2C_SPEED_SHIFT)
64 :
65 : /** Use 10-bit addressing. DEPRECATED - Use I2C_MSG_ADDR_10_BITS instead. */
66 1 : #define I2C_ADDR_10_BITS BIT(0)
67 :
68 : /** Peripheral to act as Controller. */
69 1 : #define I2C_MODE_CONTROLLER BIT(4)
70 :
71 : /**
72 : * @brief Complete I2C DT information
73 : *
74 : * @param bus is the I2C bus
75 : * @param addr is the target address
76 : */
77 1 : struct i2c_dt_spec {
78 0 : const struct device *bus;
79 0 : uint16_t addr;
80 : };
81 :
82 : /**
83 : * @brief Structure initializer for i2c_dt_spec from devicetree (on I3C bus)
84 : *
85 : * This helper macro expands to a static initializer for a <tt>struct
86 : * i2c_dt_spec</tt> by reading the relevant bus and address data from
87 : * the devicetree.
88 : *
89 : * @param node_id Devicetree node identifier for the I2C device whose
90 : * struct i2c_dt_spec to create an initializer for
91 : */
92 1 : #define I2C_DT_SPEC_GET_ON_I3C(node_id) \
93 : .bus = DEVICE_DT_GET(DT_BUS(node_id)), \
94 : .addr = DT_PROP_BY_IDX(node_id, reg, 0)
95 :
96 : /**
97 : * @brief Structure initializer for i2c_dt_spec from devicetree (on I2C bus)
98 : *
99 : * This helper macro expands to a static initializer for a <tt>struct
100 : * i2c_dt_spec</tt> by reading the relevant bus and address data from
101 : * the devicetree.
102 : *
103 : * @param node_id Devicetree node identifier for the I2C device whose
104 : * struct i2c_dt_spec to create an initializer for
105 : */
106 1 : #define I2C_DT_SPEC_GET_ON_I2C(node_id) \
107 : .bus = DEVICE_DT_GET(DT_BUS(node_id)), \
108 : .addr = DT_REG_ADDR(node_id)
109 :
110 : /**
111 : * @brief Structure initializer for i2c_dt_spec from devicetree
112 : *
113 : * This helper macro expands to a static initializer for a <tt>struct
114 : * i2c_dt_spec</tt> by reading the relevant bus and address data from
115 : * the devicetree.
116 : *
117 : * @param node_id Devicetree node identifier for the I2C device whose
118 : * struct i2c_dt_spec to create an initializer for
119 : */
120 1 : #define I2C_DT_SPEC_GET(node_id) \
121 : { \
122 : COND_CODE_1(DT_ON_BUS(node_id, i3c), \
123 : (I2C_DT_SPEC_GET_ON_I3C(node_id)), \
124 : (I2C_DT_SPEC_GET_ON_I2C(node_id))) \
125 : }
126 :
127 : /**
128 : * @brief Structure initializer for i2c_dt_spec from devicetree instance
129 : *
130 : * This is equivalent to
131 : * <tt>I2C_DT_SPEC_GET(DT_DRV_INST(inst))</tt>.
132 : *
133 : * @param inst Devicetree instance number
134 : */
135 1 : #define I2C_DT_SPEC_INST_GET(inst) \
136 : I2C_DT_SPEC_GET(DT_DRV_INST(inst))
137 :
138 :
139 : /*
140 : * I2C_MSG_* are I2C Message flags.
141 : */
142 :
143 : /** Write message to I2C bus. */
144 1 : #define I2C_MSG_WRITE (0U << 0U)
145 :
146 : /** Read message from I2C bus. */
147 1 : #define I2C_MSG_READ BIT(0)
148 :
149 : /** @cond INTERNAL_HIDDEN */
150 : #define I2C_MSG_RW_MASK BIT(0)
151 : /** @endcond */
152 :
153 : /** Send STOP after this message. */
154 1 : #define I2C_MSG_STOP BIT(1)
155 :
156 : /** RESTART I2C transaction for this message.
157 : *
158 : * @note Not all I2C drivers have or require explicit support for this
159 : * feature. Some drivers require this be present on a read message
160 : * that follows a write, or vice-versa. Some drivers will merge
161 : * adjacent fragments into a single transaction using this flag; some
162 : * will not. */
163 1 : #define I2C_MSG_RESTART BIT(2)
164 :
165 : /** Use 10-bit addressing for this message.
166 : *
167 : * @note Not all SoC I2C implementations support this feature. */
168 1 : #define I2C_MSG_ADDR_10_BITS BIT(3)
169 :
170 : /**
171 : * @brief One I2C Message.
172 : *
173 : * This defines one I2C message to transact on the I2C bus.
174 : *
175 : * @note Some of the configurations supported by this API may not be
176 : * supported by specific SoC I2C hardware implementations, in
177 : * particular features related to bus transactions intended to read or
178 : * write data from different buffers within a single transaction.
179 : * Invocations of i2c_transfer() may not indicate an error when an
180 : * unsupported configuration is encountered. In some cases drivers
181 : * will generate separate transactions for each message fragment, with
182 : * or without presence of @ref I2C_MSG_RESTART in #flags.
183 : */
184 1 : struct i2c_msg {
185 : /** Data buffer in bytes */
186 1 : uint8_t *buf;
187 :
188 : /** Length of buffer in bytes */
189 1 : uint32_t len;
190 :
191 : /** Flags for this message */
192 1 : uint8_t flags;
193 : };
194 :
195 : /**
196 : * @brief I2C callback for asynchronous transfer requests
197 : *
198 : * @param dev I2C device which is notifying of transfer completion or error
199 : * @param result Result code of the transfer request. 0 is success, -errno for failure.
200 : * @param data Transfer requester supplied data which is passed along to the callback.
201 : */
202 1 : typedef void (*i2c_callback_t)(const struct device *dev, int result, void *data);
203 :
204 : /**
205 : * @cond INTERNAL_HIDDEN
206 : *
207 : * These are for internal use only, so skip these in
208 : * public documentation.
209 : */
210 : struct i2c_target_config;
211 :
212 : typedef int (*i2c_api_configure_t)(const struct device *dev,
213 : uint32_t dev_config);
214 : typedef int (*i2c_api_get_config_t)(const struct device *dev,
215 : uint32_t *dev_config);
216 : typedef int (*i2c_api_full_io_t)(const struct device *dev,
217 : struct i2c_msg *msgs,
218 : uint8_t num_msgs,
219 : uint16_t addr);
220 : typedef int (*i2c_api_target_register_t)(const struct device *dev,
221 : struct i2c_target_config *cfg);
222 : typedef int (*i2c_api_target_unregister_t)(const struct device *dev,
223 : struct i2c_target_config *cfg);
224 : #ifdef CONFIG_I2C_CALLBACK
225 : typedef int (*i2c_api_transfer_cb_t)(const struct device *dev,
226 : struct i2c_msg *msgs,
227 : uint8_t num_msgs,
228 : uint16_t addr,
229 : i2c_callback_t cb,
230 : void *userdata);
231 : #endif /* CONFIG_I2C_CALLBACK */
232 : #if defined(CONFIG_I2C_RTIO) || defined(__DOXYGEN__)
233 :
234 : /**
235 : * @typedef i2c_api_iodev_submit
236 : * @brief Callback API for submitting work to a I2C device with RTIO
237 : */
238 : typedef void (*i2c_api_iodev_submit)(const struct device *dev,
239 : struct rtio_iodev_sqe *iodev_sqe);
240 : #endif /* CONFIG_I2C_RTIO */
241 :
242 : typedef int (*i2c_api_recover_bus_t)(const struct device *dev);
243 :
244 : __subsystem struct i2c_driver_api {
245 : i2c_api_configure_t configure;
246 : i2c_api_get_config_t get_config;
247 : i2c_api_full_io_t transfer;
248 : i2c_api_target_register_t target_register;
249 : i2c_api_target_unregister_t target_unregister;
250 : #ifdef CONFIG_I2C_CALLBACK
251 : i2c_api_transfer_cb_t transfer_cb;
252 : #endif
253 : #ifdef CONFIG_I2C_RTIO
254 : i2c_api_iodev_submit iodev_submit;
255 : #endif
256 : i2c_api_recover_bus_t recover_bus;
257 : };
258 :
259 : typedef int (*i2c_target_api_register_t)(const struct device *dev);
260 : typedef int (*i2c_target_api_unregister_t)(const struct device *dev);
261 :
262 : __subsystem struct i2c_target_driver_api {
263 : i2c_target_api_register_t driver_register;
264 : i2c_target_api_unregister_t driver_unregister;
265 : };
266 :
267 : /**
268 : * @endcond
269 : */
270 :
271 : /** Target device responds to 10-bit addressing. */
272 1 : #define I2C_TARGET_FLAGS_ADDR_10_BITS BIT(0)
273 :
274 : /** @brief Function called when a write to the device is initiated.
275 : *
276 : * This function is invoked by the controller when the bus completes a
277 : * start condition for a write operation to the address associated
278 : * with a particular device.
279 : *
280 : * A success return shall cause the controller to ACK the next byte
281 : * received. An error return shall cause the controller to NACK the
282 : * next byte received.
283 : *
284 : * @param config the configuration structure associated with the
285 : * device to which the operation is addressed.
286 : *
287 : * @return 0 if the write is accepted, or a negative error code.
288 : */
289 1 : typedef int (*i2c_target_write_requested_cb_t)(
290 : struct i2c_target_config *config);
291 :
292 : /** @brief Function called when a write to the device is continued.
293 : *
294 : * This function is invoked by the controller when it completes
295 : * reception of a byte of data in an ongoing write operation to the
296 : * device.
297 : *
298 : * A success return shall cause the controller to ACK the next byte
299 : * received. An error return shall cause the controller to NACK the
300 : * next byte received.
301 : *
302 : * @param config the configuration structure associated with the
303 : * device to which the operation is addressed.
304 : *
305 : * @param val the byte received by the controller.
306 : *
307 : * @return 0 if more data can be accepted, or a negative error
308 : * code.
309 : */
310 1 : typedef int (*i2c_target_write_received_cb_t)(
311 : struct i2c_target_config *config, uint8_t val);
312 :
313 : /** @brief Function called when a read from the device is initiated.
314 : *
315 : * This function is invoked by the controller when the bus completes a
316 : * start condition for a read operation from the address associated
317 : * with a particular device.
318 : *
319 : * The value returned in @p *val will be transmitted. A success
320 : * return shall cause the controller to react to additional read
321 : * operations. An error return shall cause the controller to ignore
322 : * bus operations until a new start condition is received.
323 : *
324 : * @param config the configuration structure associated with the
325 : * device to which the operation is addressed.
326 : *
327 : * @param val pointer to storage for the first byte of data to return
328 : * for the read request.
329 : *
330 : * @return 0 if more data can be requested, or a negative error code.
331 : */
332 1 : typedef int (*i2c_target_read_requested_cb_t)(
333 : struct i2c_target_config *config, uint8_t *val);
334 :
335 : /** @brief Function called when a read from the device is continued.
336 : *
337 : * This function is invoked by the controller when the bus is ready to
338 : * provide additional data for a read operation from the address
339 : * associated with the device device.
340 : *
341 : * The value returned in @p *val will be transmitted. A success
342 : * return shall cause the controller to react to additional read
343 : * operations. An error return shall cause the controller to ignore
344 : * bus operations until a new start condition is received.
345 : *
346 : * @param config the configuration structure associated with the
347 : * device to which the operation is addressed.
348 : *
349 : * @param val pointer to storage for the next byte of data to return
350 : * for the read request.
351 : *
352 : * @return 0 if data has been provided, or a negative error code.
353 : */
354 1 : typedef int (*i2c_target_read_processed_cb_t)(
355 : struct i2c_target_config *config, uint8_t *val);
356 :
357 : #ifdef CONFIG_I2C_TARGET_BUFFER_MODE
358 : /** @brief Function called when a write to the device is completed.
359 : *
360 : * This function is invoked by the controller when it completes
361 : * reception of data from the source buffer to the destination
362 : * buffer in an ongoing write operation to the device.
363 : *
364 : * @param config the configuration structure associated with the
365 : * device to which the operation is addressed.
366 : *
367 : * @param ptr pointer to the buffer that contains the data to be transferred.
368 : *
369 : * @param len the length of the data to be transferred.
370 : */
371 : typedef void (*i2c_target_buf_write_received_cb_t)(
372 : struct i2c_target_config *config, uint8_t *ptr, uint32_t len);
373 :
374 : /** @brief Function called when a read from the device is initiated.
375 : *
376 : * This function is invoked by the controller when the bus is ready to
377 : * provide additional data by buffer for a read operation from the address
378 : * associated with the device.
379 : *
380 : * The value returned in @p **ptr and @p *len will be transmitted. A success
381 : * return shall cause the controller to react to additional read operations.
382 : * An error return shall cause the controller to ignore bus operations until
383 : * a new start condition is received.
384 : *
385 : * @param config the configuration structure associated with the
386 : * device to which the operation is addressed.
387 : *
388 : * @param ptr pointer to storage for the address of data buffer to return
389 : * for the read request.
390 : *
391 : * @param len pointer to storage for the length of the data to be transferred
392 : * for the read request.
393 : *
394 : * @return 0 if data has been provided, or a negative error code.
395 : */
396 : typedef int (*i2c_target_buf_read_requested_cb_t)(
397 : struct i2c_target_config *config, uint8_t **ptr, uint32_t *len);
398 : #endif
399 :
400 : /** @brief Function called when a stop condition is observed after a
401 : * start condition addressed to a particular device.
402 : *
403 : * This function is invoked by the controller when the bus is ready to
404 : * provide additional data for a read operation from the address
405 : * associated with the device device. After the function returns the
406 : * controller shall enter a state where it is ready to react to new
407 : * start conditions.
408 : *
409 : * @param config the configuration structure associated with the
410 : * device to which the operation is addressed.
411 : *
412 : * @return Ignored.
413 : */
414 1 : typedef int (*i2c_target_stop_cb_t)(struct i2c_target_config *config);
415 :
416 : /** @brief Structure providing callbacks to be implemented for devices
417 : * that supports the I2C target API.
418 : *
419 : * This structure may be shared by multiple devices that implement the
420 : * same API at different addresses on the bus.
421 : */
422 1 : struct i2c_target_callbacks {
423 0 : i2c_target_write_requested_cb_t write_requested;
424 0 : i2c_target_read_requested_cb_t read_requested;
425 0 : i2c_target_write_received_cb_t write_received;
426 0 : i2c_target_read_processed_cb_t read_processed;
427 : #ifdef CONFIG_I2C_TARGET_BUFFER_MODE
428 : i2c_target_buf_write_received_cb_t buf_write_received;
429 : i2c_target_buf_read_requested_cb_t buf_read_requested;
430 : #endif
431 0 : i2c_target_stop_cb_t stop;
432 : };
433 :
434 : /** @brief Structure describing a device that supports the I2C
435 : * target API.
436 : *
437 : * Instances of this are passed to the i2c_target_register() and
438 : * i2c_target_unregister() functions to indicate addition and removal
439 : * of a target device, respective.
440 : *
441 : * Fields other than @c node must be initialized by the module that
442 : * implements the device behavior prior to passing the object
443 : * reference to i2c_target_register().
444 : */
445 1 : struct i2c_target_config {
446 : /** Private, do not modify */
447 1 : sys_snode_t node;
448 :
449 : /** Flags for the target device defined by I2C_TARGET_FLAGS_* constants */
450 1 : uint8_t flags;
451 :
452 : /** Address for this target device */
453 1 : uint16_t address;
454 :
455 : /** Callback functions */
456 1 : const struct i2c_target_callbacks *callbacks;
457 : };
458 :
459 : /**
460 : * @brief Validate that I2C bus is ready.
461 : *
462 : * @param spec I2C specification from devicetree
463 : *
464 : * @retval true if the I2C bus is ready for use.
465 : * @retval false if the I2C bus is not ready for use.
466 : */
467 1 : static inline bool i2c_is_ready_dt(const struct i2c_dt_spec *spec)
468 : {
469 : /* Validate bus is ready */
470 : return device_is_ready(spec->bus);
471 : }
472 :
473 : /**
474 : * @brief Check if the current message is a read operation
475 : *
476 : * @param msg The message to check
477 : * @return true if the I2C message is a read operation
478 : * @return false if the I2C message is a write operation
479 : */
480 1 : static inline bool i2c_is_read_op(const struct i2c_msg *msg)
481 : {
482 : return (msg->flags & I2C_MSG_READ) == I2C_MSG_READ;
483 : }
484 :
485 : /**
486 : * @brief Check if the current message includes a stop.
487 : *
488 : * @param msg The message to check
489 : * @return true if the I2C message includes a stop
490 : * @return false if the I2C message includes a stop
491 : */
492 1 : static inline bool i2c_is_stop_op(const struct i2c_msg *msg)
493 : {
494 : return (msg->flags & I2C_MSG_STOP) == I2C_MSG_STOP;
495 : }
496 :
497 : /**
498 : * @brief Dump out an I2C message
499 : *
500 : * Dumps out a list of I2C messages. For any that are writes (W), the data is
501 : * displayed in hex. Setting dump_read will dump the data for read messages too,
502 : * which only makes sense when called after the messages have been processed.
503 : *
504 : * It looks something like this (with name "testing"):
505 : *
506 : * @code
507 : * D: I2C msg: testing, addr=56
508 : * D: W len=01: 06
509 : * D: W len=0e:
510 : * D: contents:
511 : * D: 00 01 02 03 04 05 06 07 |........
512 : * D: 08 09 0a 0b 0c 0d |......
513 : * D: W len=01: 0f
514 : * D: R len=01: 6c
515 : * @endcode
516 : *
517 : * @param dev Target for the messages being sent. Its name will be printed in the log.
518 : * @param msgs Array of messages to dump.
519 : * @param num_msgs Number of messages to dump.
520 : * @param addr Address of the I2C target device.
521 : * @param dump_read Dump data from I2C reads, otherwise only writes have data dumped.
522 : */
523 1 : void i2c_dump_msgs_rw(const struct device *dev, const struct i2c_msg *msgs, uint8_t num_msgs,
524 : uint16_t addr, bool dump_read);
525 :
526 : /**
527 : * @brief Dump out an I2C message, before it is executed.
528 : *
529 : * This is equivalent to:
530 : *
531 : * i2c_dump_msgs_rw(dev, msgs, num_msgs, addr, false);
532 : *
533 : * The read messages' data isn't dumped.
534 : *
535 : * @param dev Target for the messages being sent. Its name will be printed in the log.
536 : * @param msgs Array of messages to dump.
537 : * @param num_msgs Number of messages to dump.
538 : * @param addr Address of the I2C target device.
539 : */
540 1 : static inline void i2c_dump_msgs(const struct device *dev, const struct i2c_msg *msgs,
541 : uint8_t num_msgs, uint16_t addr)
542 : {
543 : i2c_dump_msgs_rw(dev, msgs, num_msgs, addr, false);
544 : }
545 :
546 : #if defined(CONFIG_I2C_STATS) || defined(__DOXYGEN__)
547 :
548 : #include <zephyr/stats/stats.h>
549 :
550 : /** @cond INTERNAL_HIDDEN */
551 :
552 : STATS_SECT_START(i2c)
553 : STATS_SECT_ENTRY32(bytes_read)
554 : STATS_SECT_ENTRY32(bytes_written)
555 : STATS_SECT_ENTRY32(message_count)
556 : STATS_SECT_ENTRY32(transfer_call_count)
557 : STATS_SECT_END;
558 :
559 : STATS_NAME_START(i2c)
560 : STATS_NAME(i2c, bytes_read)
561 : STATS_NAME(i2c, bytes_written)
562 : STATS_NAME(i2c, message_count)
563 : STATS_NAME(i2c, transfer_call_count)
564 : STATS_NAME_END(i2c);
565 :
566 : /** @endcond */
567 :
568 :
569 : /**
570 : * @brief I2C specific device state which allows for i2c device class specific additions
571 : */
572 1 : struct i2c_device_state {
573 0 : struct device_state devstate;
574 0 : struct stats_i2c stats;
575 : };
576 :
577 : /**
578 : * @brief Updates the i2c stats for i2c transfers
579 : *
580 : * @param dev I2C device to update stats for
581 : * @param msgs Array of struct i2c_msg
582 : * @param num_msgs Number of i2c_msgs
583 : */
584 1 : static inline void i2c_xfer_stats(const struct device *dev, struct i2c_msg *msgs,
585 : uint8_t num_msgs)
586 : {
587 : struct i2c_device_state *state =
588 : CONTAINER_OF(dev->state, struct i2c_device_state, devstate);
589 : uint32_t bytes_read = 0U;
590 : uint32_t bytes_written = 0U;
591 :
592 : STATS_INC(state->stats, transfer_call_count);
593 : STATS_INCN(state->stats, message_count, num_msgs);
594 : for (uint8_t i = 0U; i < num_msgs; i++) {
595 : if (msgs[i].flags & I2C_MSG_READ) {
596 : bytes_read += msgs[i].len;
597 : } else {
598 : bytes_written += msgs[i].len;
599 : }
600 : }
601 : STATS_INCN(state->stats, bytes_read, bytes_read);
602 : STATS_INCN(state->stats, bytes_written, bytes_written);
603 : }
604 :
605 : /** @cond INTERNAL_HIDDEN */
606 :
607 : /**
608 : * @brief Define a statically allocated and section assigned i2c device state
609 : */
610 : #define Z_I2C_DEVICE_STATE_DEFINE(dev_id) \
611 : static struct i2c_device_state Z_DEVICE_STATE_NAME(dev_id) \
612 : __attribute__((__section__(".z_devstate")))
613 :
614 : /**
615 : * @brief Define an i2c device init wrapper function
616 : *
617 : * This does device instance specific initialization of common data (such as stats)
618 : * and calls the given init_fn
619 : */
620 : #define Z_I2C_INIT_FN(dev_id, init_fn) \
621 : static inline int UTIL_CAT(dev_id, _init)(const struct device *dev) \
622 : { \
623 : struct i2c_device_state *state = \
624 : CONTAINER_OF(dev->state, struct i2c_device_state, devstate); \
625 : stats_init(&state->stats.s_hdr, STATS_SIZE_32, 4, \
626 : STATS_NAME_INIT_PARMS(i2c)); \
627 : stats_register(dev->name, &(state->stats.s_hdr)); \
628 : if (!is_null_no_warn(init_fn)) { \
629 : return init_fn(dev); \
630 : } \
631 : \
632 : return 0; \
633 : }
634 :
635 : /** @endcond */
636 :
637 : /**
638 : * @brief Like DEVICE_DT_DEINIT_DEFINE() with I2C specifics.
639 : *
640 : * @details Defines a device which implements the I2C API. May
641 : * generate a custom device_state container struct and init_fn
642 : * wrapper when needed depending on I2C @kconfig{CONFIG_I2C_STATS}.
643 : *
644 : * @param node_id The devicetree node identifier.
645 : *
646 : * @param init_fn Name of the init function of the driver. Can be `NULL`.
647 : *
648 : * @param deinit_fn Name of the deinit function of the driver. Can be `NULL`.
649 : *
650 : * @param pm PM device resources reference (NULL if device does not use PM).
651 : *
652 : * @param data Pointer to the device's private data.
653 : *
654 : * @param config The address to the structure containing the
655 : * configuration information for this instance of the driver.
656 : *
657 : * @param level The initialization level. See SYS_INIT() for
658 : * details.
659 : *
660 : * @param prio Priority within the selected initialization level. See
661 : * SYS_INIT() for details.
662 : *
663 : * @param api Provides an initial pointer to the API function struct
664 : * used by the driver. Can be NULL.
665 : */
666 : #define I2C_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, deinit_fn, pm, \
667 1 : data, config, level, prio, api, ...)\
668 : Z_I2C_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id)); \
669 : Z_I2C_INIT_FN(Z_DEVICE_DT_DEV_ID(node_id), init_fn) \
670 : Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id), \
671 : DEVICE_DT_NAME(node_id), \
672 : &UTIL_CAT(Z_DEVICE_DT_DEV_ID(node_id), _init), \
673 : deinit_fn, Z_DEVICE_DT_FLAGS(node_id), pm, data,\
674 : config, level, prio, api, \
675 : &(Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)).devstate), \
676 : __VA_ARGS__)
677 :
678 : #else /* CONFIG_I2C_STATS */
679 :
680 : static inline void i2c_xfer_stats(const struct device *dev, struct i2c_msg *msgs,
681 : uint8_t num_msgs)
682 : {
683 : ARG_UNUSED(dev);
684 : ARG_UNUSED(msgs);
685 : ARG_UNUSED(num_msgs);
686 : }
687 :
688 : #define I2C_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, deinit_fn, pm, \
689 : data, config, level, prio, api, ...)\
690 : DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, deinit_fn, pm, data, \
691 : config, level, prio, api, __VA_ARGS__)
692 :
693 : #endif /* CONFIG_I2C_STATS */
694 :
695 : /**
696 : * @brief Like I2C_DEVICE_DT_DEINIT_DEFINE() but without deinit_fn
697 : */
698 : #define I2C_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, \
699 1 : prio, api, ...) \
700 : I2C_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, NULL, pm, data, \
701 : config, level, prio, api, \
702 : __VA_ARGS__)
703 :
704 : /**
705 : * @brief Like I2C_DEVICE_DT_DEINIT_DEFINE() for an instance of a DT_DRV_COMPAT compatible
706 : *
707 : * @param inst instance number. This is replaced by
708 : * <tt>DT_DRV_COMPAT(inst)</tt> in the call to I2C_DEVICE_DT_DEINIT_DEFINE().
709 : *
710 : * @param ... other parameters as expected by I2C_DEVICE_DT_DEINIT_DEFINE().
711 : */
712 1 : #define I2C_DEVICE_DT_INST_DEINIT_DEFINE(inst, ...) \
713 : I2C_DEVICE_DT_DEINIT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
714 :
715 : /**
716 : * @brief Like I2C_DEVICE_DT_DEFINE() for an instance of a DT_DRV_COMPAT compatible
717 : *
718 : * @param inst instance number. This is replaced by
719 : * <tt>DT_DRV_COMPAT(inst)</tt> in the call to I2C_DEVICE_DT_DEFINE().
720 : *
721 : * @param ... other parameters as expected by I2C_DEVICE_DT_DEFINE().
722 : */
723 1 : #define I2C_DEVICE_DT_INST_DEFINE(inst, ...) \
724 : I2C_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
725 :
726 : /**
727 : * @brief Configure operation of a host controller.
728 : *
729 : * @param dev Pointer to the device structure for the driver instance.
730 : * @param dev_config Bit-packed 32-bit value to the device runtime configuration
731 : * for the I2C controller.
732 : *
733 : * @retval 0 If successful.
734 : * @retval -EIO General input / output error, failed to configure device.
735 : */
736 1 : __syscall int i2c_configure(const struct device *dev, uint32_t dev_config);
737 :
738 : static inline int z_impl_i2c_configure(const struct device *dev,
739 : uint32_t dev_config)
740 : {
741 : const struct i2c_driver_api *api =
742 : (const struct i2c_driver_api *)dev->api;
743 :
744 : return api->configure(dev, dev_config);
745 : }
746 :
747 : /**
748 : * @brief Configure operation of a host controller.
749 : *
750 : * This is equivalent to:
751 : *
752 : * i2c_configure(spec->bus, dev_config);
753 : *
754 : * @param spec I2C specification from devicetree.
755 : * @param dev_config Bit-packed 32-bit value to the device runtime configuration
756 : * for the I2C controller.
757 : *
758 : * @return a value from i2c_configure()
759 : */
760 1 : static inline int i2c_configure_dt(const struct i2c_dt_spec *spec,
761 : uint32_t dev_config)
762 : {
763 : return i2c_configure(spec->bus, dev_config);
764 : }
765 :
766 : /**
767 : * @brief Get configuration of a host controller.
768 : *
769 : * This routine provides a way to get current configuration. It is allowed to
770 : * call the function before i2c_configure, because some I2C ports can be
771 : * configured during init process. However, if the I2C port is not configured,
772 : * i2c_get_config returns an error.
773 : *
774 : * i2c_get_config can return cached config or probe hardware, but it has to be
775 : * up to date with current configuration.
776 : *
777 : * @param dev Pointer to the device structure for the driver instance.
778 : * @param dev_config Pointer to return bit-packed 32-bit value of
779 : * the I2C controller configuration.
780 : *
781 : * @retval 0 If successful.
782 : * @retval -EIO General input / output error.
783 : * @retval -ERANGE Configured I2C frequency is invalid.
784 : * @retval -ENOSYS If get config is not implemented
785 : */
786 1 : __syscall int i2c_get_config(const struct device *dev, uint32_t *dev_config);
787 :
788 : static inline int z_impl_i2c_get_config(const struct device *dev, uint32_t *dev_config)
789 : {
790 : const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;
791 :
792 : if (api->get_config == NULL) {
793 : return -ENOSYS;
794 : }
795 :
796 : return api->get_config(dev, dev_config);
797 : }
798 :
799 : /**
800 : * @brief Perform data transfer to another I2C device in controller mode.
801 : *
802 : * This routine provides a generic interface to perform data transfer
803 : * to another I2C device synchronously. Use i2c_read()/i2c_write()
804 : * for simple read or write.
805 : *
806 : * The array of message @a msgs must not be NULL. The number of
807 : * message @a num_msgs may be zero,in which case no transfer occurs.
808 : *
809 : * @note Not all scatter/gather transactions can be supported by all
810 : * drivers. As an example, a gather write (multiple consecutive
811 : * `i2c_msg` buffers all configured for `I2C_MSG_WRITE`) may be packed
812 : * into a single transaction by some drivers, but others may emit each
813 : * fragment as a distinct write transaction, which will not produce
814 : * the same behavior. See the documentation of `struct i2c_msg` for
815 : * limitations on support for multi-message bus transactions.
816 : *
817 : * @note The last message in the scatter/gather transaction implies a STOP
818 : * whether or not it is explicitly set. This ensures the bus is in a good
819 : * state for the next transaction which may be from a different call context.
820 : *
821 : * @param dev Pointer to the device structure for an I2C controller
822 : * driver configured in controller mode.
823 : * @param msgs Array of messages to transfer.
824 : * @param num_msgs Number of messages to transfer.
825 : * @param addr Address of the I2C target device.
826 : *
827 : * @retval 0 If successful.
828 : * @retval -EIO General input / output error.
829 : */
830 1 : __syscall int i2c_transfer(const struct device *dev,
831 : struct i2c_msg *msgs, uint8_t num_msgs,
832 : uint16_t addr);
833 :
834 : static inline int z_impl_i2c_transfer(const struct device *dev,
835 : struct i2c_msg *msgs, uint8_t num_msgs,
836 : uint16_t addr)
837 : {
838 : const struct i2c_driver_api *api =
839 : (const struct i2c_driver_api *)dev->api;
840 :
841 : if (!num_msgs) {
842 : return 0;
843 : }
844 :
845 : if (!IS_ENABLED(CONFIG_I2C_ALLOW_NO_STOP_TRANSACTIONS)) {
846 : msgs[num_msgs - 1].flags |= I2C_MSG_STOP;
847 : }
848 :
849 : int res = api->transfer(dev, msgs, num_msgs, addr);
850 :
851 : i2c_xfer_stats(dev, msgs, num_msgs);
852 :
853 : if (IS_ENABLED(CONFIG_I2C_DUMP_MESSAGES)) {
854 : i2c_dump_msgs_rw(dev, msgs, num_msgs, addr, true);
855 : }
856 :
857 : return res;
858 : }
859 :
860 : #if defined(CONFIG_I2C_CALLBACK) || defined(__DOXYGEN__)
861 :
862 : /**
863 : * @brief Perform data transfer to another I2C device in controller mode.
864 : *
865 : * This routine provides a generic interface to perform data transfer
866 : * to another I2C device asynchronously with a callback completion.
867 : *
868 : * @see i2c_transfer()
869 : * @funcprops \isr_ok
870 : *
871 : * @param dev Pointer to the device structure for an I2C controller
872 : * driver configured in controller mode.
873 : * @param msgs Array of messages to transfer, must live until callback completes.
874 : * @param num_msgs Number of messages to transfer.
875 : * @param addr Address of the I2C target device.
876 : * @param cb Function pointer for completion callback.
877 : * @param userdata Userdata passed to callback.
878 : *
879 : * @retval 0 If successful.
880 : * @retval -EIO General input / output error.
881 : * @retval -ENOSYS If transfer async is not implemented
882 : * @retval -EWOULDBLOCK If the device is temporarily busy doing another transfer
883 : */
884 1 : static inline int i2c_transfer_cb(const struct device *dev,
885 : struct i2c_msg *msgs,
886 : uint8_t num_msgs,
887 : uint16_t addr,
888 : i2c_callback_t cb,
889 : void *userdata)
890 : {
891 : const struct i2c_driver_api *api =
892 : (const struct i2c_driver_api *)dev->api;
893 :
894 : if (api->transfer_cb == NULL) {
895 : return -ENOSYS;
896 : }
897 :
898 : if (!num_msgs) {
899 : cb(dev, 0, userdata);
900 : return 0;
901 : }
902 :
903 : if (!IS_ENABLED(CONFIG_I2C_ALLOW_NO_STOP_TRANSACTIONS)) {
904 : msgs[num_msgs - 1].flags |= I2C_MSG_STOP;
905 : }
906 :
907 : return api->transfer_cb(dev, msgs, num_msgs, addr, cb, userdata);
908 : }
909 :
910 : /**
911 : * @brief Perform data transfer to another I2C device in master mode asynchronously.
912 : *
913 : * This is equivalent to:
914 : *
915 : * i2c_transfer_cb(spec->bus, msgs, num_msgs, spec->addr, cb, userdata);
916 : *
917 : * @param spec I2C specification from devicetree.
918 : * @param msgs Array of messages to transfer.
919 : * @param num_msgs Number of messages to transfer.
920 : * @param cb Function pointer for completion callback.
921 : * @param userdata Userdata passed to callback.
922 : *
923 : * @return a value from i2c_transfer_cb()
924 : */
925 1 : static inline int i2c_transfer_cb_dt(const struct i2c_dt_spec *spec,
926 : struct i2c_msg *msgs,
927 : uint8_t num_msgs,
928 : i2c_callback_t cb,
929 : void *userdata)
930 : {
931 : return i2c_transfer_cb(spec->bus, msgs, num_msgs, spec->addr, cb, userdata);
932 : }
933 :
934 : /**
935 : * @brief Write then read data from an I2C device asynchronously.
936 : *
937 : * This supports the common operation "this is what I want", "now give
938 : * it to me" transaction pair through a combined write-then-read bus
939 : * transaction but using i2c_transfer_cb. This helper function expects
940 : * caller to pass a message pointer with 2 and only 2 size.
941 : *
942 : * @param dev Pointer to the device structure for an I2C controller
943 : * driver configured in master mode.
944 : * @param msgs Array of messages to transfer.
945 : * @param num_msgs Number of messages to transfer.
946 : * @param addr Address of the I2C device
947 : * @param write_buf Pointer to the data to be written
948 : * @param num_write Number of bytes to write
949 : * @param read_buf Pointer to storage for read data
950 : * @param num_read Number of bytes to read
951 : * @param cb Function pointer for completion callback.
952 : * @param userdata Userdata passed to callback.
953 : *
954 : * @retval 0 if successful
955 : * @retval negative on error.
956 : */
957 1 : static inline int i2c_write_read_cb(const struct device *dev, struct i2c_msg *msgs,
958 : uint8_t num_msgs, uint16_t addr, const void *write_buf,
959 : size_t num_write, void *read_buf, size_t num_read,
960 : i2c_callback_t cb, void *userdata)
961 : {
962 : if ((msgs == NULL) || (num_msgs != 2)) {
963 : return -EINVAL;
964 : }
965 :
966 : msgs[0].buf = (uint8_t *)write_buf;
967 : msgs[0].len = num_write;
968 : msgs[0].flags = I2C_MSG_WRITE;
969 :
970 : msgs[1].buf = (uint8_t *)read_buf;
971 : msgs[1].len = num_read;
972 : msgs[1].flags = I2C_MSG_RESTART | I2C_MSG_READ | I2C_MSG_STOP;
973 :
974 : return i2c_transfer_cb(dev, msgs, num_msgs, addr, cb, userdata);
975 : }
976 :
977 : /**
978 : * @brief Write then read data from an I2C device asynchronously.
979 : *
980 : * This is equivalent to:
981 : *
982 : * i2c_write_read_cb(spec->bus, msgs, num_msgs,
983 : * spec->addr, write_buf,
984 : * num_write, read_buf, num_read);
985 : *
986 : * @param spec I2C specification from devicetree.
987 : * @param msgs Array of messages to transfer.
988 : * @param num_msgs Number of messages to transfer.
989 : * @param write_buf Pointer to the data to be written
990 : * @param num_write Number of bytes to write
991 : * @param read_buf Pointer to storage for read data
992 : * @param num_read Number of bytes to read
993 : * @param cb Function pointer for completion callback.
994 : * @param userdata Userdata passed to callback.
995 : *
996 : * @return a value from i2c_write_read_cb()
997 : */
998 1 : static inline int i2c_write_read_cb_dt(const struct i2c_dt_spec *spec, struct i2c_msg *msgs,
999 : uint8_t num_msgs, const void *write_buf, size_t num_write,
1000 : void *read_buf, size_t num_read, i2c_callback_t cb,
1001 : void *userdata)
1002 : {
1003 : return i2c_write_read_cb(spec->bus, msgs, num_msgs, spec->addr, write_buf, num_write,
1004 : read_buf, num_read, cb, userdata);
1005 : }
1006 :
1007 : #if defined(CONFIG_POLL) || defined(__DOXYGEN__)
1008 :
1009 : /** @cond INTERNAL_HIDDEN */
1010 : void z_i2c_transfer_signal_cb(const struct device *dev, int result, void *userdata);
1011 : /** @endcond */
1012 :
1013 : /**
1014 : * @brief Perform data transfer to another I2C device in controller mode.
1015 : *
1016 : * This routine provides a generic interface to perform data transfer
1017 : * to another I2C device asynchronously with a k_poll_signal completion.
1018 : *
1019 : * @see i2c_transfer_cb()
1020 : * @funcprops \isr_ok
1021 : *
1022 : * @param dev Pointer to the device structure for an I2C controller
1023 : * driver configured in controller mode.
1024 : * @param msgs Array of messages to transfer, must live until callback completes.
1025 : * @param num_msgs Number of messages to transfer.
1026 : * @param addr Address of the I2C target device.
1027 : * @param sig Signal to notify of transfer completion.
1028 : *
1029 : * @retval 0 If successful.
1030 : * @retval -EIO General input / output error.
1031 : * @retval -ENOSYS If transfer async is not implemented
1032 : * @retval -EWOULDBLOCK If the device is temporarily busy doing another transfer
1033 : */
1034 1 : static inline int i2c_transfer_signal(const struct device *dev,
1035 : struct i2c_msg *msgs,
1036 : uint8_t num_msgs,
1037 : uint16_t addr,
1038 : struct k_poll_signal *sig)
1039 : {
1040 : const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;
1041 :
1042 : if (api->transfer_cb == NULL) {
1043 : return -ENOSYS;
1044 : }
1045 :
1046 : return api->transfer_cb(dev, msgs, num_msgs, addr, z_i2c_transfer_signal_cb, sig);
1047 : }
1048 :
1049 : #endif /* CONFIG_POLL */
1050 :
1051 : #endif /* CONFIG_I2C_CALLBACK */
1052 :
1053 :
1054 : #if defined(CONFIG_I2C_RTIO) || defined(__DOXYGEN__)
1055 :
1056 : /**
1057 : * @brief Fallback submit implementation
1058 : *
1059 : * This implementation will schedule a blocking I2C transaction on the bus via the RTIO work
1060 : * queue. It is only used if the I2C driver did not implement the iodev_submit function.
1061 : *
1062 : * @param dev Pointer to the device structure for an I2C controller driver.
1063 : * @param iodev_sqe Prepared submissions queue entry connected to an iodev
1064 : * defined by I2C_DT_IODEV_DEFINE.
1065 : */
1066 1 : void i2c_iodev_submit_fallback(const struct device *dev, struct rtio_iodev_sqe *iodev_sqe);
1067 :
1068 : /**
1069 : * @brief Submit request(s) to an I2C device with RTIO
1070 : *
1071 : * @param iodev_sqe Prepared submissions queue entry connected to an iodev
1072 : * defined by I2C_DT_IODEV_DEFINE.
1073 : */
1074 1 : static inline void i2c_iodev_submit(struct rtio_iodev_sqe *iodev_sqe)
1075 : {
1076 : const struct i2c_dt_spec *dt_spec = (const struct i2c_dt_spec *)iodev_sqe->sqe.iodev->data;
1077 : const struct device *dev = dt_spec->bus;
1078 : const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;
1079 :
1080 : if (api->iodev_submit == NULL) {
1081 : rtio_iodev_sqe_err(iodev_sqe, -ENOSYS);
1082 : return;
1083 : }
1084 : api->iodev_submit(dt_spec->bus, iodev_sqe);
1085 : }
1086 :
1087 0 : extern const struct rtio_iodev_api i2c_iodev_api;
1088 :
1089 0 : #define I2C_CAT2(x, y) x ## y
1090 :
1091 : /**
1092 : * @brief Define an iodev for a given dt node on the bus
1093 : *
1094 : * These do not need to be shared globally but doing so
1095 : * will save a small amount of memory.
1096 : *
1097 : * @param name Symbolic name of the iodev to define
1098 : * @param node_id Devicetree node identifier
1099 : */
1100 1 : #define I2C_DT_IODEV_DEFINE(name, node_id) \
1101 : const struct i2c_dt_spec _i2c_dt_spec_##name = \
1102 : I2C_DT_SPEC_GET(node_id); \
1103 : RTIO_IODEV_DEFINE(name, &i2c_iodev_api, (void *)&_i2c_dt_spec_##name)
1104 :
1105 : /**
1106 : * @brief Define an iodev for a given i2c device on a bus
1107 : *
1108 : * These do not need to be shared globally but doing so
1109 : * will save a small amount of memory.
1110 : *
1111 : * @param name Symbolic name of the iodev to define
1112 : * @param _bus Node ID for I2C bus
1113 : * @param _addr I2C target address
1114 : */
1115 1 : #define I2C_IODEV_DEFINE(name, _bus, _addr) \
1116 : const struct i2c_dt_spec I2C_CAT2(_i2c_dt_spec_, name) = { \
1117 : .bus = DEVICE_DT_GET(_bus), \
1118 : .addr = _addr, \
1119 : }; \
1120 : RTIO_IODEV_DEFINE(name, &i2c_iodev_api, (void *)&I2C_CAT2(_i2c_dt_spec_, name))
1121 :
1122 : /**
1123 : * @brief Validate that I2C bus is ready.
1124 : *
1125 : * @param i2c_iodev I2C iodev defined with I2C_DT_IODEV_DEFINE
1126 : *
1127 : * @retval true if the I2C bus is ready for use.
1128 : * @retval false if the I2C bus is not ready for use.
1129 : */
1130 1 : static inline bool i2c_is_ready_iodev(const struct rtio_iodev *i2c_iodev)
1131 : {
1132 : struct i2c_dt_spec *spec = (struct i2c_dt_spec *)i2c_iodev->data;
1133 :
1134 : return i2c_is_ready_dt(spec);
1135 : }
1136 :
1137 : /**
1138 : * @brief Copy the i2c_msgs into a set of RTIO requests
1139 : *
1140 : * @param r RTIO context
1141 : * @param iodev RTIO IODev to target for the submissions
1142 : * @param msgs Array of messages
1143 : * @param num_msgs Number of i2c msgs in array
1144 : *
1145 : * @retval sqe Last submission in the queue added
1146 : * @retval NULL Not enough memory in the context to copy the requests
1147 : */
1148 1 : struct rtio_sqe *i2c_rtio_copy(struct rtio *r,
1149 : struct rtio_iodev *iodev,
1150 : const struct i2c_msg *msgs,
1151 : uint8_t num_msgs);
1152 :
1153 : /**
1154 : * @brief Copy the register address and data to a SQE
1155 : *
1156 : * @param r RTIO context
1157 : * @param iodev RTIO IODev to target for the submissions
1158 : * @param reg_addr target register address
1159 : * @param data data to be written
1160 : *
1161 : * @retval sqe Last submission in the queue added
1162 : * @retval NULL Not enough memory in the context to copy the requests
1163 : */
1164 1 : struct rtio_sqe *i2c_rtio_copy_reg_write_byte(struct rtio *r, struct rtio_iodev *iodev,
1165 : uint8_t reg_addr, uint8_t data);
1166 :
1167 : /**
1168 : * @brief acquire and configure a i2c burst read transmission
1169 : *
1170 : * @param r RTIO context
1171 : * @param iodev RTIO IODev to target for the submissions
1172 : * @param start_addr target register address
1173 : * @param buf Memory pool that stores the retrieved data.
1174 : * @param num_bytes Number of bytes to read.
1175 : *
1176 : * @retval sqe Last submission in the queue added
1177 : * @retval NULL Not enough memory in the context to copy the requests
1178 : */
1179 1 : struct rtio_sqe *i2c_rtio_copy_reg_burst_read(struct rtio *r, struct rtio_iodev *iodev,
1180 : uint8_t start_addr, void *buf, size_t num_bytes);
1181 :
1182 : #endif /* CONFIG_I2C_RTIO */
1183 :
1184 : /**
1185 : * @brief Perform data transfer to another I2C device in controller mode.
1186 : *
1187 : * This is equivalent to:
1188 : *
1189 : * i2c_transfer(spec->bus, msgs, num_msgs, spec->addr);
1190 : *
1191 : * @param spec I2C specification from devicetree.
1192 : * @param msgs Array of messages to transfer.
1193 : * @param num_msgs Number of messages to transfer.
1194 : *
1195 : * @return a value from i2c_transfer()
1196 : */
1197 1 : static inline int i2c_transfer_dt(const struct i2c_dt_spec *spec,
1198 : struct i2c_msg *msgs, uint8_t num_msgs)
1199 : {
1200 : return i2c_transfer(spec->bus, msgs, num_msgs, spec->addr);
1201 : }
1202 :
1203 : /**
1204 : * @brief Recover the I2C bus
1205 : *
1206 : * Attempt to recover the I2C bus.
1207 : *
1208 : * @param dev Pointer to the device structure for an I2C controller
1209 : * driver configured in controller mode.
1210 : * @retval 0 If successful
1211 : * @retval -EBUSY If bus is not clear after recovery attempt.
1212 : * @retval -EIO General input / output error.
1213 : * @retval -ENOSYS If bus recovery is not implemented
1214 : */
1215 1 : __syscall int i2c_recover_bus(const struct device *dev);
1216 :
1217 : static inline int z_impl_i2c_recover_bus(const struct device *dev)
1218 : {
1219 : const struct i2c_driver_api *api =
1220 : (const struct i2c_driver_api *)dev->api;
1221 :
1222 : if (api->recover_bus == NULL) {
1223 : return -ENOSYS;
1224 : }
1225 :
1226 : return api->recover_bus(dev);
1227 : }
1228 :
1229 : /**
1230 : * @brief Registers the provided config as Target device of a controller.
1231 : *
1232 : * Enable I2C target mode for the 'dev' I2C bus driver using the provided
1233 : * 'config' struct containing the functions and parameters to send bus
1234 : * events. The I2C target will be registered at the address provided as 'address'
1235 : * struct member. Addressing mode - 7 or 10 bit - depends on the 'flags'
1236 : * struct member. Any I2C bus events related to the target mode will be passed
1237 : * onto I2C target device driver via a set of callback functions provided in
1238 : * the 'callbacks' struct member.
1239 : *
1240 : * Most of the existing hardware allows simultaneous support for controller
1241 : * and target mode. This is however not guaranteed.
1242 : *
1243 : * @param dev Pointer to the device structure for an I2C controller
1244 : * driver configured in target mode.
1245 : * @param cfg Config struct with functions and parameters used by the I2C driver
1246 : * to send bus events
1247 : *
1248 : * @retval 0 Is successful
1249 : * @retval -EINVAL If parameters are invalid
1250 : * @retval -EIO General input / output error.
1251 : * @retval -ENOSYS If target mode is not implemented
1252 : */
1253 1 : static inline int i2c_target_register(const struct device *dev,
1254 : struct i2c_target_config *cfg)
1255 : {
1256 : const struct i2c_driver_api *api =
1257 : (const struct i2c_driver_api *)dev->api;
1258 :
1259 : if (api->target_register == NULL) {
1260 : return -ENOSYS;
1261 : }
1262 :
1263 : return api->target_register(dev, cfg);
1264 : }
1265 :
1266 : /**
1267 : * @brief Unregisters the provided config as Target device
1268 : *
1269 : * This routine disables I2C target mode for the 'dev' I2C bus driver using
1270 : * the provided 'config' struct containing the functions and parameters
1271 : * to send bus events.
1272 : *
1273 : * @param dev Pointer to the device structure for an I2C controller
1274 : * driver configured in target mode.
1275 : * @param cfg Config struct with functions and parameters used by the I2C driver
1276 : * to send bus events
1277 : *
1278 : * @retval 0 Is successful
1279 : * @retval -EINVAL If parameters are invalid
1280 : * @retval -ENOSYS If target mode is not implemented
1281 : */
1282 1 : static inline int i2c_target_unregister(const struct device *dev,
1283 : struct i2c_target_config *cfg)
1284 : {
1285 : const struct i2c_driver_api *api =
1286 : (const struct i2c_driver_api *)dev->api;
1287 :
1288 : if (api->target_unregister == NULL) {
1289 : return -ENOSYS;
1290 : }
1291 :
1292 : return api->target_unregister(dev, cfg);
1293 : }
1294 :
1295 : /**
1296 : * @brief Instructs the I2C Target device to register itself to the I2C Controller
1297 : *
1298 : * This routine instructs the I2C Target device to register itself to the I2C
1299 : * Controller via its parent controller's i2c_target_register() API.
1300 : *
1301 : * @param dev Pointer to the device structure for the I2C target
1302 : * device (not itself an I2C controller).
1303 : *
1304 : * @retval 0 Is successful
1305 : * @retval -EINVAL If parameters are invalid
1306 : * @retval -EIO General input / output error.
1307 : */
1308 1 : __syscall int i2c_target_driver_register(const struct device *dev);
1309 :
1310 : static inline int z_impl_i2c_target_driver_register(const struct device *dev)
1311 : {
1312 : const struct i2c_target_driver_api *api =
1313 : (const struct i2c_target_driver_api *)dev->api;
1314 :
1315 : return api->driver_register(dev);
1316 : }
1317 :
1318 : /**
1319 : * @brief Instructs the I2C Target device to unregister itself from the I2C
1320 : * Controller
1321 : *
1322 : * This routine instructs the I2C Target device to unregister itself from the I2C
1323 : * Controller via its parent controller's i2c_target_register() API.
1324 : *
1325 : * @param dev Pointer to the device structure for the I2C target
1326 : * device (not itself an I2C controller).
1327 : *
1328 : * @retval 0 Is successful
1329 : * @retval -EINVAL If parameters are invalid
1330 : */
1331 1 : __syscall int i2c_target_driver_unregister(const struct device *dev);
1332 :
1333 : static inline int z_impl_i2c_target_driver_unregister(const struct device *dev)
1334 : {
1335 : const struct i2c_target_driver_api *api =
1336 : (const struct i2c_target_driver_api *)dev->api;
1337 :
1338 : return api->driver_unregister(dev);
1339 : }
1340 :
1341 : /*
1342 : * Derived i2c APIs -- all implemented in terms of i2c_transfer()
1343 : */
1344 :
1345 : /**
1346 : * @brief Write a set amount of data to an I2C device.
1347 : *
1348 : * This routine writes a set amount of data synchronously.
1349 : *
1350 : * @param dev Pointer to the device structure for an I2C controller
1351 : * driver configured in controller mode.
1352 : * @param buf Memory pool from which the data is transferred.
1353 : * @param num_bytes Number of bytes to write.
1354 : * @param addr Address to the target I2C device for writing.
1355 : *
1356 : * @retval 0 If successful.
1357 : * @retval -EIO General input / output error.
1358 : */
1359 1 : static inline int i2c_write(const struct device *dev, const uint8_t *buf,
1360 : uint32_t num_bytes, uint16_t addr)
1361 : {
1362 : struct i2c_msg msg;
1363 :
1364 : msg.buf = (uint8_t *)buf;
1365 : msg.len = num_bytes;
1366 : msg.flags = I2C_MSG_WRITE | I2C_MSG_STOP;
1367 :
1368 : return i2c_transfer(dev, &msg, 1, addr);
1369 : }
1370 :
1371 : /**
1372 : * @brief Write a set amount of data to an I2C device.
1373 : *
1374 : * This is equivalent to:
1375 : *
1376 : * i2c_write(spec->bus, buf, num_bytes, spec->addr);
1377 : *
1378 : * @param spec I2C specification from devicetree.
1379 : * @param buf Memory pool from which the data is transferred.
1380 : * @param num_bytes Number of bytes to write.
1381 : *
1382 : * @return a value from i2c_write()
1383 : */
1384 1 : static inline int i2c_write_dt(const struct i2c_dt_spec *spec,
1385 : const uint8_t *buf, uint32_t num_bytes)
1386 : {
1387 : return i2c_write(spec->bus, buf, num_bytes, spec->addr);
1388 : }
1389 :
1390 : /**
1391 : * @brief Read a set amount of data from an I2C device.
1392 : *
1393 : * This routine reads a set amount of data synchronously.
1394 : *
1395 : * @param dev Pointer to the device structure for an I2C controller
1396 : * driver configured in controller mode.
1397 : * @param buf Memory pool that stores the retrieved data.
1398 : * @param num_bytes Number of bytes to read.
1399 : * @param addr Address of the I2C device being read.
1400 : *
1401 : * @retval 0 If successful.
1402 : * @retval -EIO General input / output error.
1403 : */
1404 1 : static inline int i2c_read(const struct device *dev, uint8_t *buf,
1405 : uint32_t num_bytes, uint16_t addr)
1406 : {
1407 : struct i2c_msg msg;
1408 :
1409 : msg.buf = buf;
1410 : msg.len = num_bytes;
1411 : msg.flags = I2C_MSG_READ | I2C_MSG_STOP;
1412 :
1413 : return i2c_transfer(dev, &msg, 1, addr);
1414 : }
1415 :
1416 : /**
1417 : * @brief Read a set amount of data from an I2C device.
1418 : *
1419 : * This is equivalent to:
1420 : *
1421 : * i2c_read(spec->bus, buf, num_bytes, spec->addr);
1422 : *
1423 : * @param spec I2C specification from devicetree.
1424 : * @param buf Memory pool that stores the retrieved data.
1425 : * @param num_bytes Number of bytes to read.
1426 : *
1427 : * @return a value from i2c_read()
1428 : */
1429 1 : static inline int i2c_read_dt(const struct i2c_dt_spec *spec,
1430 : uint8_t *buf, uint32_t num_bytes)
1431 : {
1432 : return i2c_read(spec->bus, buf, num_bytes, spec->addr);
1433 : }
1434 :
1435 : /**
1436 : * @brief Write then read data from an I2C device.
1437 : *
1438 : * This supports the common operation "this is what I want", "now give
1439 : * it to me" transaction pair through a combined write-then-read bus
1440 : * transaction.
1441 : *
1442 : * @param dev Pointer to the device structure for an I2C controller
1443 : * driver configured in controller mode.
1444 : * @param addr Address of the I2C device
1445 : * @param write_buf Pointer to the data to be written
1446 : * @param num_write Number of bytes to write
1447 : * @param read_buf Pointer to storage for read data
1448 : * @param num_read Number of bytes to read
1449 : *
1450 : * @retval 0 if successful
1451 : * @retval negative on error.
1452 : */
1453 1 : static inline int i2c_write_read(const struct device *dev, uint16_t addr,
1454 : const void *write_buf, size_t num_write,
1455 : void *read_buf, size_t num_read)
1456 : {
1457 : struct i2c_msg msg[2];
1458 :
1459 : msg[0].buf = (uint8_t *)write_buf;
1460 : msg[0].len = num_write;
1461 : msg[0].flags = I2C_MSG_WRITE;
1462 :
1463 : msg[1].buf = (uint8_t *)read_buf;
1464 : msg[1].len = num_read;
1465 : msg[1].flags = I2C_MSG_RESTART | I2C_MSG_READ | I2C_MSG_STOP;
1466 :
1467 : return i2c_transfer(dev, msg, 2, addr);
1468 : }
1469 :
1470 : /**
1471 : * @brief Write then read data from an I2C device.
1472 : *
1473 : * This is equivalent to:
1474 : *
1475 : * i2c_write_read(spec->bus, spec->addr,
1476 : * write_buf, num_write,
1477 : * read_buf, num_read);
1478 : *
1479 : * @param spec I2C specification from devicetree.
1480 : * @param write_buf Pointer to the data to be written
1481 : * @param num_write Number of bytes to write
1482 : * @param read_buf Pointer to storage for read data
1483 : * @param num_read Number of bytes to read
1484 : *
1485 : * @return a value from i2c_write_read()
1486 : */
1487 1 : static inline int i2c_write_read_dt(const struct i2c_dt_spec *spec,
1488 : const void *write_buf, size_t num_write,
1489 : void *read_buf, size_t num_read)
1490 : {
1491 : return i2c_write_read(spec->bus, spec->addr,
1492 : write_buf, num_write,
1493 : read_buf, num_read);
1494 : }
1495 :
1496 : /**
1497 : * @brief Read multiple bytes from an internal address of an I2C device.
1498 : *
1499 : * This routine reads multiple bytes from an internal address of an
1500 : * I2C device synchronously.
1501 : *
1502 : * Instances of this may be replaced by i2c_write_read().
1503 : *
1504 : * @param dev Pointer to the device structure for an I2C controller
1505 : * driver configured in controller mode.
1506 : * @param dev_addr Address of the I2C device for reading.
1507 : * @param start_addr Internal address from which the data is being read.
1508 : * @param buf Memory pool that stores the retrieved data.
1509 : * @param num_bytes Number of bytes being read.
1510 : *
1511 : * @retval 0 If successful.
1512 : * @retval -EIO General input / output error.
1513 : */
1514 1 : static inline int i2c_burst_read(const struct device *dev,
1515 : uint16_t dev_addr,
1516 : uint8_t start_addr,
1517 : uint8_t *buf,
1518 : uint32_t num_bytes)
1519 : {
1520 : return i2c_write_read(dev, dev_addr,
1521 : &start_addr, sizeof(start_addr),
1522 : buf, num_bytes);
1523 : }
1524 :
1525 : /**
1526 : * @brief Read multiple bytes from an internal address of an I2C device.
1527 : *
1528 : * This is equivalent to:
1529 : *
1530 : * i2c_burst_read(spec->bus, spec->addr, start_addr, buf, num_bytes);
1531 : *
1532 : * @param spec I2C specification from devicetree.
1533 : * @param start_addr Internal address from which the data is being read.
1534 : * @param buf Memory pool that stores the retrieved data.
1535 : * @param num_bytes Number of bytes to read.
1536 : *
1537 : * @return a value from i2c_burst_read()
1538 : */
1539 1 : static inline int i2c_burst_read_dt(const struct i2c_dt_spec *spec,
1540 : uint8_t start_addr,
1541 : uint8_t *buf,
1542 : uint32_t num_bytes)
1543 : {
1544 : return i2c_burst_read(spec->bus, spec->addr,
1545 : start_addr, buf, num_bytes);
1546 : }
1547 :
1548 : /**
1549 : * @brief Write multiple bytes to an internal address of an I2C device.
1550 : *
1551 : * This routine writes multiple bytes to an internal address of an
1552 : * I2C device synchronously.
1553 : *
1554 : * @warning The combined write synthesized by this API may not be
1555 : * supported on all I2C devices. Uses of this API may be made more
1556 : * portable by replacing them with calls to i2c_write() passing a
1557 : * buffer containing the combined address and data.
1558 : *
1559 : * @param dev Pointer to the device structure for an I2C controller
1560 : * driver configured in controller mode.
1561 : * @param dev_addr Address of the I2C device for writing.
1562 : * @param start_addr Internal address to which the data is being written.
1563 : * @param buf Memory pool from which the data is transferred.
1564 : * @param num_bytes Number of bytes being written.
1565 : *
1566 : * @retval 0 If successful.
1567 : * @retval -EIO General input / output error.
1568 : */
1569 1 : static inline int i2c_burst_write(const struct device *dev,
1570 : uint16_t dev_addr,
1571 : uint8_t start_addr,
1572 : const uint8_t *buf,
1573 : uint32_t num_bytes)
1574 : {
1575 : struct i2c_msg msg[2];
1576 :
1577 : msg[0].buf = &start_addr;
1578 : msg[0].len = 1U;
1579 : msg[0].flags = I2C_MSG_WRITE;
1580 :
1581 : msg[1].buf = (uint8_t *)buf;
1582 : msg[1].len = num_bytes;
1583 : msg[1].flags = I2C_MSG_WRITE | I2C_MSG_STOP;
1584 :
1585 : return i2c_transfer(dev, msg, 2, dev_addr);
1586 : }
1587 :
1588 : /**
1589 : * @brief Write multiple bytes to an internal address of an I2C device.
1590 : *
1591 : * This is equivalent to:
1592 : *
1593 : * i2c_burst_write(spec->bus, spec->addr, start_addr, buf, num_bytes);
1594 : *
1595 : * @param spec I2C specification from devicetree.
1596 : * @param start_addr Internal address to which the data is being written.
1597 : * @param buf Memory pool from which the data is transferred.
1598 : * @param num_bytes Number of bytes being written.
1599 : *
1600 : * @return a value from i2c_burst_write()
1601 : */
1602 1 : static inline int i2c_burst_write_dt(const struct i2c_dt_spec *spec,
1603 : uint8_t start_addr,
1604 : const uint8_t *buf,
1605 : uint32_t num_bytes)
1606 : {
1607 : return i2c_burst_write(spec->bus, spec->addr,
1608 : start_addr, buf, num_bytes);
1609 : }
1610 :
1611 : /**
1612 : * @brief Read internal register of an I2C device.
1613 : *
1614 : * This routine reads the value of an 8-bit internal register of an I2C
1615 : * device synchronously.
1616 : *
1617 : * @param dev Pointer to the device structure for an I2C controller
1618 : * driver configured in controller mode.
1619 : * @param dev_addr Address of the I2C device for reading.
1620 : * @param reg_addr Address of the internal register being read.
1621 : * @param value Memory pool that stores the retrieved register value.
1622 : *
1623 : * @retval 0 If successful.
1624 : * @retval -EIO General input / output error.
1625 : */
1626 1 : static inline int i2c_reg_read_byte(const struct device *dev,
1627 : uint16_t dev_addr,
1628 : uint8_t reg_addr, uint8_t *value)
1629 : {
1630 : return i2c_write_read(dev, dev_addr,
1631 : ®_addr, sizeof(reg_addr),
1632 : value, sizeof(*value));
1633 : }
1634 :
1635 : /**
1636 : * @brief Read internal register of an I2C device.
1637 : *
1638 : * This is equivalent to:
1639 : *
1640 : * i2c_reg_read_byte(spec->bus, spec->addr, reg_addr, value);
1641 : *
1642 : * @param spec I2C specification from devicetree.
1643 : * @param reg_addr Address of the internal register being read.
1644 : * @param value Memory pool that stores the retrieved register value.
1645 : *
1646 : * @return a value from i2c_reg_read_byte()
1647 : */
1648 1 : static inline int i2c_reg_read_byte_dt(const struct i2c_dt_spec *spec,
1649 : uint8_t reg_addr, uint8_t *value)
1650 : {
1651 : return i2c_reg_read_byte(spec->bus, spec->addr, reg_addr, value);
1652 : }
1653 :
1654 : /**
1655 : * @brief Write internal register of an I2C device.
1656 : *
1657 : * This routine writes a value to an 8-bit internal register of an I2C
1658 : * device synchronously.
1659 : *
1660 : * @note This function internally combines the register and value into
1661 : * a single bus transaction.
1662 : *
1663 : * @param dev Pointer to the device structure for an I2C controller
1664 : * driver configured in controller mode.
1665 : * @param dev_addr Address of the I2C device for writing.
1666 : * @param reg_addr Address of the internal register being written.
1667 : * @param value Value to be written to internal register.
1668 : *
1669 : * @retval 0 If successful.
1670 : * @retval -EIO General input / output error.
1671 : */
1672 1 : static inline int i2c_reg_write_byte(const struct device *dev,
1673 : uint16_t dev_addr,
1674 : uint8_t reg_addr, uint8_t value)
1675 : {
1676 : uint8_t tx_buf[2] = {reg_addr, value};
1677 :
1678 : return i2c_write(dev, tx_buf, 2, dev_addr);
1679 : }
1680 :
1681 : /**
1682 : * @brief Write internal register of an I2C device.
1683 : *
1684 : * This is equivalent to:
1685 : *
1686 : * i2c_reg_write_byte(spec->bus, spec->addr, reg_addr, value);
1687 : *
1688 : * @param spec I2C specification from devicetree.
1689 : * @param reg_addr Address of the internal register being written.
1690 : * @param value Value to be written to internal register.
1691 : *
1692 : * @return a value from i2c_reg_write_byte()
1693 : */
1694 1 : static inline int i2c_reg_write_byte_dt(const struct i2c_dt_spec *spec,
1695 : uint8_t reg_addr, uint8_t value)
1696 : {
1697 : return i2c_reg_write_byte(spec->bus, spec->addr, reg_addr, value);
1698 : }
1699 :
1700 : /**
1701 : * @brief Update internal register of an I2C device.
1702 : *
1703 : * This routine updates the value of a set of bits from an 8-bit internal
1704 : * register of an I2C device synchronously.
1705 : *
1706 : * @note If the calculated new register value matches the value that
1707 : * was read this function will not generate a write operation.
1708 : *
1709 : * @param dev Pointer to the device structure for an I2C controller
1710 : * driver configured in controller mode.
1711 : * @param dev_addr Address of the I2C device for updating.
1712 : * @param reg_addr Address of the internal register being updated.
1713 : * @param mask Bitmask for updating internal register.
1714 : * @param value Value for updating internal register.
1715 : *
1716 : * @retval 0 If successful.
1717 : * @retval -EIO General input / output error.
1718 : */
1719 1 : static inline int i2c_reg_update_byte(const struct device *dev,
1720 : uint8_t dev_addr,
1721 : uint8_t reg_addr, uint8_t mask,
1722 : uint8_t value)
1723 : {
1724 : uint8_t old_value, new_value;
1725 : int rc;
1726 :
1727 : rc = i2c_reg_read_byte(dev, dev_addr, reg_addr, &old_value);
1728 : if (rc != 0) {
1729 : return rc;
1730 : }
1731 :
1732 : new_value = (old_value & ~mask) | (value & mask);
1733 : if (new_value == old_value) {
1734 : return 0;
1735 : }
1736 :
1737 : return i2c_reg_write_byte(dev, dev_addr, reg_addr, new_value);
1738 : }
1739 :
1740 : /**
1741 : * @brief Update internal register of an I2C device.
1742 : *
1743 : * This is equivalent to:
1744 : *
1745 : * i2c_reg_update_byte(spec->bus, spec->addr, reg_addr, mask, value);
1746 : *
1747 : * @param spec I2C specification from devicetree.
1748 : * @param reg_addr Address of the internal register being updated.
1749 : * @param mask Bitmask for updating internal register.
1750 : * @param value Value for updating internal register.
1751 : *
1752 : * @return a value from i2c_reg_update_byte()
1753 : */
1754 1 : static inline int i2c_reg_update_byte_dt(const struct i2c_dt_spec *spec,
1755 : uint8_t reg_addr, uint8_t mask,
1756 : uint8_t value)
1757 : {
1758 : return i2c_reg_update_byte(spec->bus, spec->addr,
1759 : reg_addr, mask, value);
1760 : }
1761 :
1762 : #ifdef __cplusplus
1763 : }
1764 : #endif
1765 :
1766 : /**
1767 : * @}
1768 : */
1769 :
1770 : #include <zephyr/syscalls/i2c.h>
1771 :
1772 : #endif /* ZEPHYR_INCLUDE_DRIVERS_I2C_H_ */
|
