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_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 pm PM device resources reference (NULL if device does not use PM).
649 : *
650 : * @param data Pointer to the device's private data.
651 : *
652 : * @param config The address to the structure containing the
653 : * configuration information for this instance of the driver.
654 : *
655 : * @param level The initialization level. See SYS_INIT() for
656 : * details.
657 : *
658 : * @param prio Priority within the selected initialization level. See
659 : * SYS_INIT() for details.
660 : *
661 : * @param api Provides an initial pointer to the API function struct
662 : * used by the driver. Can be NULL.
663 : */
664 : #define I2C_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, \
665 1 : prio, api, ...) \
666 : Z_I2C_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id)); \
667 : Z_I2C_INIT_FN(Z_DEVICE_DT_DEV_ID(node_id), init_fn) \
668 : Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id), \
669 : DEVICE_DT_NAME(node_id), \
670 : &UTIL_CAT(Z_DEVICE_DT_DEV_ID(node_id), _init), \
671 : pm, data, config, level, prio, api, \
672 : &(Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)).devstate), \
673 : __VA_ARGS__)
674 :
675 : #else /* CONFIG_I2C_STATS */
676 :
677 : static inline void i2c_xfer_stats(const struct device *dev, struct i2c_msg *msgs,
678 : uint8_t num_msgs)
679 : {
680 : ARG_UNUSED(dev);
681 : ARG_UNUSED(msgs);
682 : ARG_UNUSED(num_msgs);
683 : }
684 :
685 : #define I2C_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, \
686 : prio, api, ...) \
687 : DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, \
688 : prio, api, __VA_ARGS__)
689 :
690 : #endif /* CONFIG_I2C_STATS */
691 :
692 : /**
693 : * @brief Like I2C_DEVICE_DT_DEFINE() for an instance of a DT_DRV_COMPAT compatible
694 : *
695 : * @param inst instance number. This is replaced by
696 : * <tt>DT_DRV_COMPAT(inst)</tt> in the call to I2C_DEVICE_DT_DEFINE().
697 : *
698 : * @param ... other parameters as expected by I2C_DEVICE_DT_DEFINE().
699 : */
700 1 : #define I2C_DEVICE_DT_INST_DEFINE(inst, ...) \
701 : I2C_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
702 :
703 :
704 : /**
705 : * @brief Configure operation of a host controller.
706 : *
707 : * @param dev Pointer to the device structure for the driver instance.
708 : * @param dev_config Bit-packed 32-bit value to the device runtime configuration
709 : * for the I2C controller.
710 : *
711 : * @retval 0 If successful.
712 : * @retval -EIO General input / output error, failed to configure device.
713 : */
714 1 : __syscall int i2c_configure(const struct device *dev, uint32_t dev_config);
715 :
716 : static inline int z_impl_i2c_configure(const struct device *dev,
717 : uint32_t dev_config)
718 : {
719 : const struct i2c_driver_api *api =
720 : (const struct i2c_driver_api *)dev->api;
721 :
722 : return api->configure(dev, dev_config);
723 : }
724 :
725 : /**
726 : * @brief Get configuration of a host controller.
727 : *
728 : * This routine provides a way to get current configuration. It is allowed to
729 : * call the function before i2c_configure, because some I2C ports can be
730 : * configured during init process. However, if the I2C port is not configured,
731 : * i2c_get_config returns an error.
732 : *
733 : * i2c_get_config can return cached config or probe hardware, but it has to be
734 : * up to date with current configuration.
735 : *
736 : * @param dev Pointer to the device structure for the driver instance.
737 : * @param dev_config Pointer to return bit-packed 32-bit value of
738 : * the I2C controller configuration.
739 : *
740 : * @retval 0 If successful.
741 : * @retval -EIO General input / output error.
742 : * @retval -ERANGE Configured I2C frequency is invalid.
743 : * @retval -ENOSYS If get config is not implemented
744 : */
745 1 : __syscall int i2c_get_config(const struct device *dev, uint32_t *dev_config);
746 :
747 : static inline int z_impl_i2c_get_config(const struct device *dev, uint32_t *dev_config)
748 : {
749 : const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;
750 :
751 : if (api->get_config == NULL) {
752 : return -ENOSYS;
753 : }
754 :
755 : return api->get_config(dev, dev_config);
756 : }
757 :
758 : /**
759 : * @brief Perform data transfer to another I2C device in controller mode.
760 : *
761 : * This routine provides a generic interface to perform data transfer
762 : * to another I2C device synchronously. Use i2c_read()/i2c_write()
763 : * for simple read or write.
764 : *
765 : * The array of message @a msgs must not be NULL. The number of
766 : * message @a num_msgs may be zero,in which case no transfer occurs.
767 : *
768 : * @note Not all scatter/gather transactions can be supported by all
769 : * drivers. As an example, a gather write (multiple consecutive
770 : * `i2c_msg` buffers all configured for `I2C_MSG_WRITE`) may be packed
771 : * into a single transaction by some drivers, but others may emit each
772 : * fragment as a distinct write transaction, which will not produce
773 : * the same behavior. See the documentation of `struct i2c_msg` for
774 : * limitations on support for multi-message bus transactions.
775 : *
776 : * @note The last message in the scatter/gather transaction implies a STOP
777 : * whether or not it is explicitly set. This ensures the bus is in a good
778 : * state for the next transaction which may be from a different call context.
779 : *
780 : * @param dev Pointer to the device structure for an I2C controller
781 : * driver configured in controller mode.
782 : * @param msgs Array of messages to transfer.
783 : * @param num_msgs Number of messages to transfer.
784 : * @param addr Address of the I2C target device.
785 : *
786 : * @retval 0 If successful.
787 : * @retval -EIO General input / output error.
788 : */
789 1 : __syscall int i2c_transfer(const struct device *dev,
790 : struct i2c_msg *msgs, uint8_t num_msgs,
791 : uint16_t addr);
792 :
793 : static inline int z_impl_i2c_transfer(const struct device *dev,
794 : struct i2c_msg *msgs, uint8_t num_msgs,
795 : uint16_t addr)
796 : {
797 : const struct i2c_driver_api *api =
798 : (const struct i2c_driver_api *)dev->api;
799 :
800 : if (!num_msgs) {
801 : return 0;
802 : }
803 :
804 : if (!IS_ENABLED(CONFIG_I2C_ALLOW_NO_STOP_TRANSACTIONS)) {
805 : msgs[num_msgs - 1].flags |= I2C_MSG_STOP;
806 : }
807 :
808 : int res = api->transfer(dev, msgs, num_msgs, addr);
809 :
810 : i2c_xfer_stats(dev, msgs, num_msgs);
811 :
812 : if (IS_ENABLED(CONFIG_I2C_DUMP_MESSAGES)) {
813 : i2c_dump_msgs_rw(dev, msgs, num_msgs, addr, true);
814 : }
815 :
816 : return res;
817 : }
818 :
819 : #if defined(CONFIG_I2C_CALLBACK) || defined(__DOXYGEN__)
820 :
821 : /**
822 : * @brief Perform data transfer to another I2C device in controller mode.
823 : *
824 : * This routine provides a generic interface to perform data transfer
825 : * to another I2C device asynchronously with a callback completion.
826 : *
827 : * @see i2c_transfer()
828 : * @funcprops \isr_ok
829 : *
830 : * @param dev Pointer to the device structure for an I2C controller
831 : * driver configured in controller mode.
832 : * @param msgs Array of messages to transfer, must live until callback completes.
833 : * @param num_msgs Number of messages to transfer.
834 : * @param addr Address of the I2C target device.
835 : * @param cb Function pointer for completion callback.
836 : * @param userdata Userdata passed to callback.
837 : *
838 : * @retval 0 If successful.
839 : * @retval -EIO General input / output error.
840 : * @retval -ENOSYS If transfer async is not implemented
841 : * @retval -EWOULDBLOCK If the device is temporarily busy doing another transfer
842 : */
843 1 : static inline int i2c_transfer_cb(const struct device *dev,
844 : struct i2c_msg *msgs,
845 : uint8_t num_msgs,
846 : uint16_t addr,
847 : i2c_callback_t cb,
848 : void *userdata)
849 : {
850 : const struct i2c_driver_api *api =
851 : (const struct i2c_driver_api *)dev->api;
852 :
853 : if (api->transfer_cb == NULL) {
854 : return -ENOSYS;
855 : }
856 :
857 : if (!num_msgs) {
858 : cb(dev, 0, userdata);
859 : return 0;
860 : }
861 :
862 : if (!IS_ENABLED(CONFIG_I2C_ALLOW_NO_STOP_TRANSACTIONS)) {
863 : msgs[num_msgs - 1].flags |= I2C_MSG_STOP;
864 : }
865 :
866 : return api->transfer_cb(dev, msgs, num_msgs, addr, cb, userdata);
867 : }
868 :
869 : /**
870 : * @brief Perform data transfer to another I2C device in master mode asynchronously.
871 : *
872 : * This is equivalent to:
873 : *
874 : * i2c_transfer_cb(spec->bus, msgs, num_msgs, spec->addr, cb, userdata);
875 : *
876 : * @param spec I2C specification from devicetree.
877 : * @param msgs Array of messages to transfer.
878 : * @param num_msgs Number of messages to transfer.
879 : * @param cb Function pointer for completion callback.
880 : * @param userdata Userdata passed to callback.
881 : *
882 : * @return a value from i2c_transfer_cb()
883 : */
884 1 : static inline int i2c_transfer_cb_dt(const struct i2c_dt_spec *spec,
885 : struct i2c_msg *msgs,
886 : uint8_t num_msgs,
887 : i2c_callback_t cb,
888 : void *userdata)
889 : {
890 : return i2c_transfer_cb(spec->bus, msgs, num_msgs, spec->addr, cb, userdata);
891 : }
892 :
893 : /**
894 : * @brief Write then read data from an I2C device asynchronously.
895 : *
896 : * This supports the common operation "this is what I want", "now give
897 : * it to me" transaction pair through a combined write-then-read bus
898 : * transaction but using i2c_transfer_cb. This helper function expects
899 : * caller to pass a message pointer with 2 and only 2 size.
900 : *
901 : * @param dev Pointer to the device structure for an I2C controller
902 : * driver configured in master mode.
903 : * @param msgs Array of messages to transfer.
904 : * @param num_msgs Number of messages to transfer.
905 : * @param addr Address of the I2C device
906 : * @param write_buf Pointer to the data to be written
907 : * @param num_write Number of bytes to write
908 : * @param read_buf Pointer to storage for read data
909 : * @param num_read Number of bytes to read
910 : * @param cb Function pointer for completion callback.
911 : * @param userdata Userdata passed to callback.
912 : *
913 : * @retval 0 if successful
914 : * @retval negative on error.
915 : */
916 1 : static inline int i2c_write_read_cb(const struct device *dev, struct i2c_msg *msgs,
917 : uint8_t num_msgs, uint16_t addr, const void *write_buf,
918 : size_t num_write, void *read_buf, size_t num_read,
919 : i2c_callback_t cb, void *userdata)
920 : {
921 : if ((msgs == NULL) || (num_msgs != 2)) {
922 : return -EINVAL;
923 : }
924 :
925 : msgs[0].buf = (uint8_t *)write_buf;
926 : msgs[0].len = num_write;
927 : msgs[0].flags = I2C_MSG_WRITE;
928 :
929 : msgs[1].buf = (uint8_t *)read_buf;
930 : msgs[1].len = num_read;
931 : msgs[1].flags = I2C_MSG_RESTART | I2C_MSG_READ | I2C_MSG_STOP;
932 :
933 : return i2c_transfer_cb(dev, msgs, num_msgs, addr, cb, userdata);
934 : }
935 :
936 : /**
937 : * @brief Write then read data from an I2C device asynchronously.
938 : *
939 : * This is equivalent to:
940 : *
941 : * i2c_write_read_cb(spec->bus, msgs, num_msgs,
942 : * spec->addr, write_buf,
943 : * num_write, read_buf, num_read);
944 : *
945 : * @param spec I2C specification from devicetree.
946 : * @param msgs Array of messages to transfer.
947 : * @param num_msgs Number of messages to transfer.
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 : * @return a value from i2c_write_read_cb()
956 : */
957 1 : static inline int i2c_write_read_cb_dt(const struct i2c_dt_spec *spec, struct i2c_msg *msgs,
958 : uint8_t num_msgs, const void *write_buf, size_t num_write,
959 : void *read_buf, size_t num_read, i2c_callback_t cb,
960 : void *userdata)
961 : {
962 : return i2c_write_read_cb(spec->bus, msgs, num_msgs, spec->addr, write_buf, num_write,
963 : read_buf, num_read, cb, userdata);
964 : }
965 :
966 : #if defined(CONFIG_POLL) || defined(__DOXYGEN__)
967 :
968 : /** @cond INTERNAL_HIDDEN */
969 : void z_i2c_transfer_signal_cb(const struct device *dev, int result, void *userdata);
970 : /** @endcond */
971 :
972 : /**
973 : * @brief Perform data transfer to another I2C device in controller mode.
974 : *
975 : * This routine provides a generic interface to perform data transfer
976 : * to another I2C device asynchronously with a k_poll_signal completion.
977 : *
978 : * @see i2c_transfer_cb()
979 : * @funcprops \isr_ok
980 : *
981 : * @param dev Pointer to the device structure for an I2C controller
982 : * driver configured in controller mode.
983 : * @param msgs Array of messages to transfer, must live until callback completes.
984 : * @param num_msgs Number of messages to transfer.
985 : * @param addr Address of the I2C target device.
986 : * @param sig Signal to notify of transfer completion.
987 : *
988 : * @retval 0 If successful.
989 : * @retval -EIO General input / output error.
990 : * @retval -ENOSYS If transfer async is not implemented
991 : * @retval -EWOULDBLOCK If the device is temporarily busy doing another transfer
992 : */
993 1 : static inline int i2c_transfer_signal(const struct device *dev,
994 : struct i2c_msg *msgs,
995 : uint8_t num_msgs,
996 : uint16_t addr,
997 : struct k_poll_signal *sig)
998 : {
999 : const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;
1000 :
1001 : if (api->transfer_cb == NULL) {
1002 : return -ENOSYS;
1003 : }
1004 :
1005 : return api->transfer_cb(dev, msgs, num_msgs, addr, z_i2c_transfer_signal_cb, sig);
1006 : }
1007 :
1008 : #endif /* CONFIG_POLL */
1009 :
1010 : #endif /* CONFIG_I2C_CALLBACK */
1011 :
1012 :
1013 : #if defined(CONFIG_I2C_RTIO) || defined(__DOXYGEN__)
1014 :
1015 : /**
1016 : * @brief Fallback submit implementation
1017 : *
1018 : * This implementation will schedule a blocking I2C transaction on the bus via the RTIO work
1019 : * queue. It is only used if the I2C driver did not implement the iodev_submit function.
1020 : *
1021 : * @param dev Pointer to the device structure for an I2C controller driver.
1022 : * @param iodev_sqe Prepared submissions queue entry connected to an iodev
1023 : * defined by I2C_DT_IODEV_DEFINE.
1024 : */
1025 1 : void i2c_iodev_submit_fallback(const struct device *dev, struct rtio_iodev_sqe *iodev_sqe);
1026 :
1027 : /**
1028 : * @brief Submit request(s) to an I2C device with RTIO
1029 : *
1030 : * @param iodev_sqe Prepared submissions queue entry connected to an iodev
1031 : * defined by I2C_DT_IODEV_DEFINE.
1032 : */
1033 1 : static inline void i2c_iodev_submit(struct rtio_iodev_sqe *iodev_sqe)
1034 : {
1035 : const struct i2c_dt_spec *dt_spec = (const struct i2c_dt_spec *)iodev_sqe->sqe.iodev->data;
1036 : const struct device *dev = dt_spec->bus;
1037 : const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;
1038 :
1039 : if (api->iodev_submit == NULL) {
1040 : rtio_iodev_sqe_err(iodev_sqe, -ENOSYS);
1041 : return;
1042 : }
1043 : api->iodev_submit(dt_spec->bus, iodev_sqe);
1044 : }
1045 :
1046 0 : extern const struct rtio_iodev_api i2c_iodev_api;
1047 :
1048 : /**
1049 : * @brief Define an iodev for a given dt node on the bus
1050 : *
1051 : * These do not need to be shared globally but doing so
1052 : * will save a small amount of memory.
1053 : *
1054 : * @param name Symbolic name of the iodev to define
1055 : * @param node_id Devicetree node identifier
1056 : */
1057 1 : #define I2C_DT_IODEV_DEFINE(name, node_id) \
1058 : const struct i2c_dt_spec _i2c_dt_spec_##name = \
1059 : I2C_DT_SPEC_GET(node_id); \
1060 : RTIO_IODEV_DEFINE(name, &i2c_iodev_api, (void *)&_i2c_dt_spec_##name)
1061 :
1062 : /**
1063 : * @brief Define an iodev for a given i2c device on a bus
1064 : *
1065 : * These do not need to be shared globally but doing so
1066 : * will save a small amount of memory.
1067 : *
1068 : * @param name Symbolic name of the iodev to define
1069 : * @param _bus Node ID for I2C bus
1070 : * @param _addr I2C target address
1071 : */
1072 1 : #define I2C_IODEV_DEFINE(name, _bus, _addr) \
1073 : const struct i2c_dt_spec _i2c_dt_spec_##name = { \
1074 : .bus = DEVICE_DT_GET(_bus), \
1075 : .addr = _addr, \
1076 : }; \
1077 : RTIO_IODEV_DEFINE(name, &i2c_iodev_api, (void *)&_i2c_dt_spec_##name)
1078 :
1079 : /**
1080 : * @brief Copy the i2c_msgs into a set of RTIO requests
1081 : *
1082 : * @param r RTIO context
1083 : * @param iodev RTIO IODev to target for the submissions
1084 : * @param msgs Array of messages
1085 : * @param num_msgs Number of i2c msgs in array
1086 : *
1087 : * @retval sqe Last submission in the queue added
1088 : * @retval NULL Not enough memory in the context to copy the requests
1089 : */
1090 1 : struct rtio_sqe *i2c_rtio_copy(struct rtio *r,
1091 : struct rtio_iodev *iodev,
1092 : const struct i2c_msg *msgs,
1093 : uint8_t num_msgs);
1094 :
1095 : #endif /* CONFIG_I2C_RTIO */
1096 :
1097 : /**
1098 : * @brief Perform data transfer to another I2C device in controller mode.
1099 : *
1100 : * This is equivalent to:
1101 : *
1102 : * i2c_transfer(spec->bus, msgs, num_msgs, spec->addr);
1103 : *
1104 : * @param spec I2C specification from devicetree.
1105 : * @param msgs Array of messages to transfer.
1106 : * @param num_msgs Number of messages to transfer.
1107 : *
1108 : * @return a value from i2c_transfer()
1109 : */
1110 1 : static inline int i2c_transfer_dt(const struct i2c_dt_spec *spec,
1111 : struct i2c_msg *msgs, uint8_t num_msgs)
1112 : {
1113 : return i2c_transfer(spec->bus, msgs, num_msgs, spec->addr);
1114 : }
1115 :
1116 : /**
1117 : * @brief Recover the I2C bus
1118 : *
1119 : * Attempt to recover the I2C bus.
1120 : *
1121 : * @param dev Pointer to the device structure for an I2C controller
1122 : * driver configured in controller mode.
1123 : * @retval 0 If successful
1124 : * @retval -EBUSY If bus is not clear after recovery attempt.
1125 : * @retval -EIO General input / output error.
1126 : * @retval -ENOSYS If bus recovery is not implemented
1127 : */
1128 1 : __syscall int i2c_recover_bus(const struct device *dev);
1129 :
1130 : static inline int z_impl_i2c_recover_bus(const struct device *dev)
1131 : {
1132 : const struct i2c_driver_api *api =
1133 : (const struct i2c_driver_api *)dev->api;
1134 :
1135 : if (api->recover_bus == NULL) {
1136 : return -ENOSYS;
1137 : }
1138 :
1139 : return api->recover_bus(dev);
1140 : }
1141 :
1142 : /**
1143 : * @brief Registers the provided config as Target device of a controller.
1144 : *
1145 : * Enable I2C target mode for the 'dev' I2C bus driver using the provided
1146 : * 'config' struct containing the functions and parameters to send bus
1147 : * events. The I2C target will be registered at the address provided as 'address'
1148 : * struct member. Addressing mode - 7 or 10 bit - depends on the 'flags'
1149 : * struct member. Any I2C bus events related to the target mode will be passed
1150 : * onto I2C target device driver via a set of callback functions provided in
1151 : * the 'callbacks' struct member.
1152 : *
1153 : * Most of the existing hardware allows simultaneous support for controller
1154 : * and target mode. This is however not guaranteed.
1155 : *
1156 : * @param dev Pointer to the device structure for an I2C controller
1157 : * driver configured in target mode.
1158 : * @param cfg Config struct with functions and parameters used by the I2C driver
1159 : * to send bus events
1160 : *
1161 : * @retval 0 Is successful
1162 : * @retval -EINVAL If parameters are invalid
1163 : * @retval -EIO General input / output error.
1164 : * @retval -ENOSYS If target mode is not implemented
1165 : */
1166 1 : static inline int i2c_target_register(const struct device *dev,
1167 : struct i2c_target_config *cfg)
1168 : {
1169 : const struct i2c_driver_api *api =
1170 : (const struct i2c_driver_api *)dev->api;
1171 :
1172 : if (api->target_register == NULL) {
1173 : return -ENOSYS;
1174 : }
1175 :
1176 : return api->target_register(dev, cfg);
1177 : }
1178 :
1179 : /**
1180 : * @brief Unregisters the provided config as Target device
1181 : *
1182 : * This routine disables I2C target mode for the 'dev' I2C bus driver using
1183 : * the provided 'config' struct containing the functions and parameters
1184 : * to send bus events.
1185 : *
1186 : * @param dev Pointer to the device structure for an I2C controller
1187 : * driver configured in target mode.
1188 : * @param cfg Config struct with functions and parameters used by the I2C driver
1189 : * to send bus events
1190 : *
1191 : * @retval 0 Is successful
1192 : * @retval -EINVAL If parameters are invalid
1193 : * @retval -ENOSYS If target mode is not implemented
1194 : */
1195 1 : static inline int i2c_target_unregister(const struct device *dev,
1196 : struct i2c_target_config *cfg)
1197 : {
1198 : const struct i2c_driver_api *api =
1199 : (const struct i2c_driver_api *)dev->api;
1200 :
1201 : if (api->target_unregister == NULL) {
1202 : return -ENOSYS;
1203 : }
1204 :
1205 : return api->target_unregister(dev, cfg);
1206 : }
1207 :
1208 : /**
1209 : * @brief Instructs the I2C Target device to register itself to the I2C Controller
1210 : *
1211 : * This routine instructs the I2C Target device to register itself to the I2C
1212 : * Controller via its parent controller's i2c_target_register() API.
1213 : *
1214 : * @param dev Pointer to the device structure for the I2C target
1215 : * device (not itself an I2C controller).
1216 : *
1217 : * @retval 0 Is successful
1218 : * @retval -EINVAL If parameters are invalid
1219 : * @retval -EIO General input / output error.
1220 : */
1221 1 : __syscall int i2c_target_driver_register(const struct device *dev);
1222 :
1223 : static inline int z_impl_i2c_target_driver_register(const struct device *dev)
1224 : {
1225 : const struct i2c_target_driver_api *api =
1226 : (const struct i2c_target_driver_api *)dev->api;
1227 :
1228 : return api->driver_register(dev);
1229 : }
1230 :
1231 : /**
1232 : * @brief Instructs the I2C Target device to unregister itself from the I2C
1233 : * Controller
1234 : *
1235 : * This routine instructs the I2C Target device to unregister itself from the I2C
1236 : * Controller via its parent controller's i2c_target_register() API.
1237 : *
1238 : * @param dev Pointer to the device structure for the I2C target
1239 : * device (not itself an I2C controller).
1240 : *
1241 : * @retval 0 Is successful
1242 : * @retval -EINVAL If parameters are invalid
1243 : */
1244 1 : __syscall int i2c_target_driver_unregister(const struct device *dev);
1245 :
1246 : static inline int z_impl_i2c_target_driver_unregister(const struct device *dev)
1247 : {
1248 : const struct i2c_target_driver_api *api =
1249 : (const struct i2c_target_driver_api *)dev->api;
1250 :
1251 : return api->driver_unregister(dev);
1252 : }
1253 :
1254 : /*
1255 : * Derived i2c APIs -- all implemented in terms of i2c_transfer()
1256 : */
1257 :
1258 : /**
1259 : * @brief Write a set amount of data to an I2C device.
1260 : *
1261 : * This routine writes a set amount of data synchronously.
1262 : *
1263 : * @param dev Pointer to the device structure for an I2C controller
1264 : * driver configured in controller mode.
1265 : * @param buf Memory pool from which the data is transferred.
1266 : * @param num_bytes Number of bytes to write.
1267 : * @param addr Address to the target I2C device for writing.
1268 : *
1269 : * @retval 0 If successful.
1270 : * @retval -EIO General input / output error.
1271 : */
1272 1 : static inline int i2c_write(const struct device *dev, const uint8_t *buf,
1273 : uint32_t num_bytes, uint16_t addr)
1274 : {
1275 : struct i2c_msg msg;
1276 :
1277 : msg.buf = (uint8_t *)buf;
1278 : msg.len = num_bytes;
1279 : msg.flags = I2C_MSG_WRITE | I2C_MSG_STOP;
1280 :
1281 : return i2c_transfer(dev, &msg, 1, addr);
1282 : }
1283 :
1284 : /**
1285 : * @brief Write a set amount of data to an I2C device.
1286 : *
1287 : * This is equivalent to:
1288 : *
1289 : * i2c_write(spec->bus, buf, num_bytes, spec->addr);
1290 : *
1291 : * @param spec I2C specification from devicetree.
1292 : * @param buf Memory pool from which the data is transferred.
1293 : * @param num_bytes Number of bytes to write.
1294 : *
1295 : * @return a value from i2c_write()
1296 : */
1297 1 : static inline int i2c_write_dt(const struct i2c_dt_spec *spec,
1298 : const uint8_t *buf, uint32_t num_bytes)
1299 : {
1300 : return i2c_write(spec->bus, buf, num_bytes, spec->addr);
1301 : }
1302 :
1303 : /**
1304 : * @brief Read a set amount of data from an I2C device.
1305 : *
1306 : * This routine reads a set amount of data synchronously.
1307 : *
1308 : * @param dev Pointer to the device structure for an I2C controller
1309 : * driver configured in controller mode.
1310 : * @param buf Memory pool that stores the retrieved data.
1311 : * @param num_bytes Number of bytes to read.
1312 : * @param addr Address of the I2C device being read.
1313 : *
1314 : * @retval 0 If successful.
1315 : * @retval -EIO General input / output error.
1316 : */
1317 1 : static inline int i2c_read(const struct device *dev, uint8_t *buf,
1318 : uint32_t num_bytes, uint16_t addr)
1319 : {
1320 : struct i2c_msg msg;
1321 :
1322 : msg.buf = buf;
1323 : msg.len = num_bytes;
1324 : msg.flags = I2C_MSG_READ | I2C_MSG_STOP;
1325 :
1326 : return i2c_transfer(dev, &msg, 1, addr);
1327 : }
1328 :
1329 : /**
1330 : * @brief Read a set amount of data from an I2C device.
1331 : *
1332 : * This is equivalent to:
1333 : *
1334 : * i2c_read(spec->bus, buf, num_bytes, spec->addr);
1335 : *
1336 : * @param spec I2C specification from devicetree.
1337 : * @param buf Memory pool that stores the retrieved data.
1338 : * @param num_bytes Number of bytes to read.
1339 : *
1340 : * @return a value from i2c_read()
1341 : */
1342 1 : static inline int i2c_read_dt(const struct i2c_dt_spec *spec,
1343 : uint8_t *buf, uint32_t num_bytes)
1344 : {
1345 : return i2c_read(spec->bus, buf, num_bytes, spec->addr);
1346 : }
1347 :
1348 : /**
1349 : * @brief Write then read data from an I2C device.
1350 : *
1351 : * This supports the common operation "this is what I want", "now give
1352 : * it to me" transaction pair through a combined write-then-read bus
1353 : * transaction.
1354 : *
1355 : * @param dev Pointer to the device structure for an I2C controller
1356 : * driver configured in controller mode.
1357 : * @param addr Address of the I2C device
1358 : * @param write_buf Pointer to the data to be written
1359 : * @param num_write Number of bytes to write
1360 : * @param read_buf Pointer to storage for read data
1361 : * @param num_read Number of bytes to read
1362 : *
1363 : * @retval 0 if successful
1364 : * @retval negative on error.
1365 : */
1366 1 : static inline int i2c_write_read(const struct device *dev, uint16_t addr,
1367 : const void *write_buf, size_t num_write,
1368 : void *read_buf, size_t num_read)
1369 : {
1370 : struct i2c_msg msg[2];
1371 :
1372 : msg[0].buf = (uint8_t *)write_buf;
1373 : msg[0].len = num_write;
1374 : msg[0].flags = I2C_MSG_WRITE;
1375 :
1376 : msg[1].buf = (uint8_t *)read_buf;
1377 : msg[1].len = num_read;
1378 : msg[1].flags = I2C_MSG_RESTART | I2C_MSG_READ | I2C_MSG_STOP;
1379 :
1380 : return i2c_transfer(dev, msg, 2, addr);
1381 : }
1382 :
1383 : /**
1384 : * @brief Write then read data from an I2C device.
1385 : *
1386 : * This is equivalent to:
1387 : *
1388 : * i2c_write_read(spec->bus, spec->addr,
1389 : * write_buf, num_write,
1390 : * read_buf, num_read);
1391 : *
1392 : * @param spec I2C specification from devicetree.
1393 : * @param write_buf Pointer to the data to be written
1394 : * @param num_write Number of bytes to write
1395 : * @param read_buf Pointer to storage for read data
1396 : * @param num_read Number of bytes to read
1397 : *
1398 : * @return a value from i2c_write_read()
1399 : */
1400 1 : static inline int i2c_write_read_dt(const struct i2c_dt_spec *spec,
1401 : const void *write_buf, size_t num_write,
1402 : void *read_buf, size_t num_read)
1403 : {
1404 : return i2c_write_read(spec->bus, spec->addr,
1405 : write_buf, num_write,
1406 : read_buf, num_read);
1407 : }
1408 :
1409 : /**
1410 : * @brief Read multiple bytes from an internal address of an I2C device.
1411 : *
1412 : * This routine reads multiple bytes from an internal address of an
1413 : * I2C device synchronously.
1414 : *
1415 : * Instances of this may be replaced by i2c_write_read().
1416 : *
1417 : * @param dev Pointer to the device structure for an I2C controller
1418 : * driver configured in controller mode.
1419 : * @param dev_addr Address of the I2C device for reading.
1420 : * @param start_addr Internal address from which the data is being read.
1421 : * @param buf Memory pool that stores the retrieved data.
1422 : * @param num_bytes Number of bytes being read.
1423 : *
1424 : * @retval 0 If successful.
1425 : * @retval -EIO General input / output error.
1426 : */
1427 1 : static inline int i2c_burst_read(const struct device *dev,
1428 : uint16_t dev_addr,
1429 : uint8_t start_addr,
1430 : uint8_t *buf,
1431 : uint32_t num_bytes)
1432 : {
1433 : return i2c_write_read(dev, dev_addr,
1434 : &start_addr, sizeof(start_addr),
1435 : buf, num_bytes);
1436 : }
1437 :
1438 : /**
1439 : * @brief Read multiple bytes from an internal address of an I2C device.
1440 : *
1441 : * This is equivalent to:
1442 : *
1443 : * i2c_burst_read(spec->bus, spec->addr, start_addr, buf, num_bytes);
1444 : *
1445 : * @param spec I2C specification from devicetree.
1446 : * @param start_addr Internal address from which the data is being read.
1447 : * @param buf Memory pool that stores the retrieved data.
1448 : * @param num_bytes Number of bytes to read.
1449 : *
1450 : * @return a value from i2c_burst_read()
1451 : */
1452 1 : static inline int i2c_burst_read_dt(const struct i2c_dt_spec *spec,
1453 : uint8_t start_addr,
1454 : uint8_t *buf,
1455 : uint32_t num_bytes)
1456 : {
1457 : return i2c_burst_read(spec->bus, spec->addr,
1458 : start_addr, buf, num_bytes);
1459 : }
1460 :
1461 : /**
1462 : * @brief Write multiple bytes to an internal address of an I2C device.
1463 : *
1464 : * This routine writes multiple bytes to an internal address of an
1465 : * I2C device synchronously.
1466 : *
1467 : * @warning The combined write synthesized by this API may not be
1468 : * supported on all I2C devices. Uses of this API may be made more
1469 : * portable by replacing them with calls to i2c_write() passing a
1470 : * buffer containing the combined address and data.
1471 : *
1472 : * @param dev Pointer to the device structure for an I2C controller
1473 : * driver configured in controller mode.
1474 : * @param dev_addr Address of the I2C device for writing.
1475 : * @param start_addr Internal address to which the data is being written.
1476 : * @param buf Memory pool from which the data is transferred.
1477 : * @param num_bytes Number of bytes being written.
1478 : *
1479 : * @retval 0 If successful.
1480 : * @retval -EIO General input / output error.
1481 : */
1482 1 : static inline int i2c_burst_write(const struct device *dev,
1483 : uint16_t dev_addr,
1484 : uint8_t start_addr,
1485 : const uint8_t *buf,
1486 : uint32_t num_bytes)
1487 : {
1488 : struct i2c_msg msg[2];
1489 :
1490 : msg[0].buf = &start_addr;
1491 : msg[0].len = 1U;
1492 : msg[0].flags = I2C_MSG_WRITE;
1493 :
1494 : msg[1].buf = (uint8_t *)buf;
1495 : msg[1].len = num_bytes;
1496 : msg[1].flags = I2C_MSG_WRITE | I2C_MSG_STOP;
1497 :
1498 : return i2c_transfer(dev, msg, 2, dev_addr);
1499 : }
1500 :
1501 : /**
1502 : * @brief Write multiple bytes to an internal address of an I2C device.
1503 : *
1504 : * This is equivalent to:
1505 : *
1506 : * i2c_burst_write(spec->bus, spec->addr, start_addr, buf, num_bytes);
1507 : *
1508 : * @param spec I2C specification from devicetree.
1509 : * @param start_addr Internal address to which the data is being written.
1510 : * @param buf Memory pool from which the data is transferred.
1511 : * @param num_bytes Number of bytes being written.
1512 : *
1513 : * @return a value from i2c_burst_write()
1514 : */
1515 1 : static inline int i2c_burst_write_dt(const struct i2c_dt_spec *spec,
1516 : uint8_t start_addr,
1517 : const uint8_t *buf,
1518 : uint32_t num_bytes)
1519 : {
1520 : return i2c_burst_write(spec->bus, spec->addr,
1521 : start_addr, buf, num_bytes);
1522 : }
1523 :
1524 : /**
1525 : * @brief Read internal register of an I2C device.
1526 : *
1527 : * This routine reads the value of an 8-bit internal register of an I2C
1528 : * device synchronously.
1529 : *
1530 : * @param dev Pointer to the device structure for an I2C controller
1531 : * driver configured in controller mode.
1532 : * @param dev_addr Address of the I2C device for reading.
1533 : * @param reg_addr Address of the internal register being read.
1534 : * @param value Memory pool that stores the retrieved register value.
1535 : *
1536 : * @retval 0 If successful.
1537 : * @retval -EIO General input / output error.
1538 : */
1539 1 : static inline int i2c_reg_read_byte(const struct device *dev,
1540 : uint16_t dev_addr,
1541 : uint8_t reg_addr, uint8_t *value)
1542 : {
1543 : return i2c_write_read(dev, dev_addr,
1544 : ®_addr, sizeof(reg_addr),
1545 : value, sizeof(*value));
1546 : }
1547 :
1548 : /**
1549 : * @brief Read internal register of an I2C device.
1550 : *
1551 : * This is equivalent to:
1552 : *
1553 : * i2c_reg_read_byte(spec->bus, spec->addr, reg_addr, value);
1554 : *
1555 : * @param spec I2C specification from devicetree.
1556 : * @param reg_addr Address of the internal register being read.
1557 : * @param value Memory pool that stores the retrieved register value.
1558 : *
1559 : * @return a value from i2c_reg_read_byte()
1560 : */
1561 1 : static inline int i2c_reg_read_byte_dt(const struct i2c_dt_spec *spec,
1562 : uint8_t reg_addr, uint8_t *value)
1563 : {
1564 : return i2c_reg_read_byte(spec->bus, spec->addr, reg_addr, value);
1565 : }
1566 :
1567 : /**
1568 : * @brief Write internal register of an I2C device.
1569 : *
1570 : * This routine writes a value to an 8-bit internal register of an I2C
1571 : * device synchronously.
1572 : *
1573 : * @note This function internally combines the register and value into
1574 : * a single bus transaction.
1575 : *
1576 : * @param dev Pointer to the device structure for an I2C controller
1577 : * driver configured in controller mode.
1578 : * @param dev_addr Address of the I2C device for writing.
1579 : * @param reg_addr Address of the internal register being written.
1580 : * @param value Value to be written to internal register.
1581 : *
1582 : * @retval 0 If successful.
1583 : * @retval -EIO General input / output error.
1584 : */
1585 1 : static inline int i2c_reg_write_byte(const struct device *dev,
1586 : uint16_t dev_addr,
1587 : uint8_t reg_addr, uint8_t value)
1588 : {
1589 : uint8_t tx_buf[2] = {reg_addr, value};
1590 :
1591 : return i2c_write(dev, tx_buf, 2, dev_addr);
1592 : }
1593 :
1594 : /**
1595 : * @brief Write internal register of an I2C device.
1596 : *
1597 : * This is equivalent to:
1598 : *
1599 : * i2c_reg_write_byte(spec->bus, spec->addr, reg_addr, value);
1600 : *
1601 : * @param spec I2C specification from devicetree.
1602 : * @param reg_addr Address of the internal register being written.
1603 : * @param value Value to be written to internal register.
1604 : *
1605 : * @return a value from i2c_reg_write_byte()
1606 : */
1607 1 : static inline int i2c_reg_write_byte_dt(const struct i2c_dt_spec *spec,
1608 : uint8_t reg_addr, uint8_t value)
1609 : {
1610 : return i2c_reg_write_byte(spec->bus, spec->addr, reg_addr, value);
1611 : }
1612 :
1613 : /**
1614 : * @brief Update internal register of an I2C device.
1615 : *
1616 : * This routine updates the value of a set of bits from an 8-bit internal
1617 : * register of an I2C device synchronously.
1618 : *
1619 : * @note If the calculated new register value matches the value that
1620 : * was read this function will not generate a write operation.
1621 : *
1622 : * @param dev Pointer to the device structure for an I2C controller
1623 : * driver configured in controller mode.
1624 : * @param dev_addr Address of the I2C device for updating.
1625 : * @param reg_addr Address of the internal register being updated.
1626 : * @param mask Bitmask for updating internal register.
1627 : * @param value Value for updating internal register.
1628 : *
1629 : * @retval 0 If successful.
1630 : * @retval -EIO General input / output error.
1631 : */
1632 1 : static inline int i2c_reg_update_byte(const struct device *dev,
1633 : uint8_t dev_addr,
1634 : uint8_t reg_addr, uint8_t mask,
1635 : uint8_t value)
1636 : {
1637 : uint8_t old_value, new_value;
1638 : int rc;
1639 :
1640 : rc = i2c_reg_read_byte(dev, dev_addr, reg_addr, &old_value);
1641 : if (rc != 0) {
1642 : return rc;
1643 : }
1644 :
1645 : new_value = (old_value & ~mask) | (value & mask);
1646 : if (new_value == old_value) {
1647 : return 0;
1648 : }
1649 :
1650 : return i2c_reg_write_byte(dev, dev_addr, reg_addr, new_value);
1651 : }
1652 :
1653 : /**
1654 : * @brief Update internal register of an I2C device.
1655 : *
1656 : * This is equivalent to:
1657 : *
1658 : * i2c_reg_update_byte(spec->bus, spec->addr, reg_addr, mask, value);
1659 : *
1660 : * @param spec I2C specification from devicetree.
1661 : * @param reg_addr Address of the internal register being updated.
1662 : * @param mask Bitmask for updating internal register.
1663 : * @param value Value for updating internal register.
1664 : *
1665 : * @return a value from i2c_reg_update_byte()
1666 : */
1667 1 : static inline int i2c_reg_update_byte_dt(const struct i2c_dt_spec *spec,
1668 : uint8_t reg_addr, uint8_t mask,
1669 : uint8_t value)
1670 : {
1671 : return i2c_reg_update_byte(spec->bus, spec->addr,
1672 : reg_addr, mask, value);
1673 : }
1674 :
1675 : #ifdef __cplusplus
1676 : }
1677 : #endif
1678 :
1679 : /**
1680 : * @}
1681 : */
1682 :
1683 : #include <zephyr/syscalls/i2c.h>
1684 :
1685 : #endif /* ZEPHYR_INCLUDE_DRIVERS_I2C_H_ */
|
