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