Software APIs
dif_i2c.h
Go to the documentation of this file.
1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_I2C_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_I2C_H_
7
8/**
9 * @file
10 * @brief <a href="/hw/ip/i2c/doc/">I2C</a> Device Interface Functions
11 */
12
13#include <stdbool.h>
14#include <stdint.h>
15
19
20#include "sw/device/lib/dif/autogen/dif_i2c_autogen.h"
21
22#ifdef __cplusplus
23extern "C" {
24#endif // __cplusplus
25
26/**
27 * Represents a speed setting for an I2C component: standard, fast, and
28 * fast plus, corresponding to 100 kbaud, 400 kbaud, and 1 Mbaud,
29 * respectively.
30 */
31typedef enum dif_i2c_speed {
32 /**
33 * Standard speed, 100 kilobaud.
34 */
36 /**
37 * Fast speed, 400 kilobaud.
38 */
40 /**
41 * Fast plus speed, 1 megabaud.
42 */
45
46// TODO(#23786) The i2c IP has a parameter (InputDelayCycles), use this when
47// topgen supports exposing it in the headers.
48enum {
49 /**
50 * Input Delay Cycles; for clock stretching detection to work, the SCL high
51 * and low time must be at least 4 cycles.
52 */
54};
55
56/**
57 * Timing configuration parameters for I2C.
58 *
59 * While the I2C device requires ten parameters to describe its timing
60 * configuration, the degrees of freedom of those parameters is constrained to
61 * the ones in this struct.
62 *
63 * See `dif_i2c_compute_timing()`
64 */
65typedef struct dif_i2c_timing_config {
66 /**
67 * The lowest speed at which an I2C target connected to this host will
68 * operate.
69 *
70 * In other words, this is the maximum speed at which the host can operate
71 * without going over what the target devices can handle.
72 */
74 /**
75 * The period of the clock driving this device, in nanoseconds.
76 *
77 * This value should not be zero, since it is used as a divisor for
78 * division.
79 */
81 /**
82 * The expected time it takes for the I2C bus signal to rise, in nanoseconds.
83 *
84 * This value is dependent on properties of the hardware's interconnect, and
85 * not under actual firmware control.
86 */
88 /**
89 * The expected time for the bus signal to fall, similar to `sda_rise_nanos`.
90 */
92 /**
93 * The desired period of the SCL line, in nanoseconds.
94 *
95 * Normally, this should just be `1'000'000 / lowest_target_device_speed`,
96 * but the period may be larger if desired.
97 *
98 * Setting this value to zero will result in the minimum period being used.
99 */
102
103/**
104 * Configuration for the addressing behavior of the I2C, can be disabled or
105 * configured to look for multiple addresses by masking certain bits. A mask of
106 * 0x7f will match only a single address.
107 */
108typedef struct dif_i2c_id {
109 /**
110 * Mask the recieved I2C address before checking for a match. Received Address
111 * & mask must equal the programmed address to activate I2C Device. If Address
112 * & ~mask != 0, this will not match any addresses. A mask of 0x7f will cause
113 * device to only respond to an exact match. The mask is 7 bits and LSB
114 * aligned.
115 */
116 uint8_t mask;
117 /**
118 * The 7-bit I2C address that should be matched after masking to cause the
119 * activated I2C Target device to begin to act in a transaction. Address is
120 * LSB aligned.
121 */
122 uint8_t address;
124
125/**
126 * Runtime configuration for I2C.
127 *
128 * This struct describes runtime timing parameters. Computing these values is
129 * somewhat complicated, so these fields should be initialized using the
130 * `dif_i2c_compute_timing()` function. A caller is, however, free to compute
131 * these values themselves if they prefer, so long as the I2C spec is
132 * respected.
133 *
134 * These values correspond to those in Table 10 of the I2C spec, and are given
135 * in units of input clock cycles.
136 */
137typedef struct dif_i2c_config {
138 uint16_t scl_time_high_cycles;
139 uint16_t scl_time_low_cycles;
140 uint16_t rise_cycles;
141 uint16_t fall_cycles;
142 uint16_t start_signal_setup_cycles;
143 uint16_t start_signal_hold_cycles;
144 uint16_t data_signal_setup_cycles;
145 uint16_t data_signal_hold_cycles;
146 uint16_t stop_signal_setup_cycles;
147 /**
148 * This parameter is referred to in the I2C documents as the
149 * "bus free time".
150 */
153
154/**
155 * Represents a watermark or data level for one of the I2C FIFOs.
156 */
157typedef uint16_t dif_i2c_level_t;
158
159/**
160 * Flags for a formatted I2C byte, used by the `dif_i2c_write_byte_raw()`
161 * function.
162 */
163typedef struct dif_i2c_fmt_flags {
164 /**
165 * Causes a start signal to be sent before the byte.
166 *
167 * If a start has been issued during the current transaction, this will issue
168 * a repeated start.
169 */
170 bool start;
171 /**
172 * Causes a stop signal to be sent after the byte.
173 *
174 * This flag cannot be set when both `read` and `read_cont` are set.
175 */
176 bool stop;
177 /**
178 * Causes the byte to be interpreted as an unsigned number of bytes to read
179 * from the target; 0 is interpreted as 256.
180 */
181 bool read;
182 /**
183 * Requires `read` to be set; if so, once the final byte associated with this
184 * read is received, it will be acknowledged, allowing the read operation to
185 * continue.
186 */
188 /**
189 * By default, the hardware expects an ACK after every byte sent, and raises
190 * an exception (contributing to the `kDifi2cIrqControllerHalt` interrupt).
191 * This flag disables that behavior.
192 *
193 * This flag cannot be set along with `read` or `read_cont`.
194 */
197
198/**
199 * The I2C Target device records the following signals with received data
200 */
201typedef enum dif_i2c_signal {
202 /**
203 * The associated byte was received with a START signal, and should be the
204 * matching address and R/W bit
205 */
207 /**
208 * The associated byte was received after a STOP signal, so the transaction is
209 * over and the byte is junk
210 */
212 /**
213 * The associated byte was received with a repeated START signal and
214 * represents the address for the subsequent transaction.
215 */
217 /**
218 * The associated data byte was NACK'd.
219 */
221 /**
222 * There was a stretch timeout on the associated address byte, leading to
223 * NACKing all subsequent incoming bytes for the rest of the transaction (and
224 * returning 0xFF bytes on any subsequent reads in that transaction).
225 */
227 /**
228 * A STOP signal was received to end a transaction that experienced a stretch
229 * timeout or other I/O error condition.
230 */
232 /**
233 * There's no associated STOP or START signal this is just a byte that's been
234 * written to the I2C target in an ongoing transaction, and it was ACK'd.
235 */
238
239/**
240 * Available formatting codes for `dif_i2c_write_byte_raw()`.
241 *
242 * Each code describes how to interpret the `byte` parameter, referred to below
243 * as "the byte".
244 *
245 * It is the caller's responsibility to observe the state transitions in the
246 * comments below.
247 */
248typedef enum dif_i2c_fmt {
249 /**
250 * Start a transaction. This sends a START signal followed by the byte.
251 * The byte sent will form (potentially part of) the target address for the
252 * transaction.
253 *
254 * May be followed by any format code.
255 */
257 /**
258 * Transmit byte. This simply sends the byte. It may need to be used in
259 * conjunction with `Start` to send a multi-byte target address.
260 *
261 * May be followed by any format code.
262 */
264 /**
265 * Transmit byte and stop. This sends the byte, and then sends a stop
266 * signal, completing a transaction.
267 *
268 * Only `Start` may follow this code.
269 */
271 /**
272 * Request `n` bytes, where `n` is the byte interpreted as an unsigned
273 * integer; a byte value of `0` will be interpreted as requesting `256`
274 * bytes. This will NAK the last byte.
275 *
276 * Only `Start` may follow this code (this code does not stop a transaction;
277 * see `RxStop`).
278 */
280 /**
281 * Request `n` bytes, same as `Rx`, but ACK the last byte so that more data
282 * can be requested.
283 *
284 * May be followed by `RxContinue`, `Rx`, or `RxStop`.
285 */
287 /**
288 * Request `n` bytes, same as `Rx`, but, after NAKing the last byte, send a
289 * stop signal to end the transaction.
290 *
291 * Only `Start` may follow this code.
292 */
295
296/**
297 * Flags representing the status of an I2C block
298 */
299typedef struct dif_i2c_status {
300 /**
301 * Enable Host, I2C block has been initialized and enabled to act as a host,
302 * consuming entries from the FMT FIFO to perform I2C transactions, and
303 * writing the results of I2C Reads to the RX FIFO
304 */
306 /**
307 * Enable Target, I2C block has been initialized and enabled to act as a
308 * target device, using the TX FIFO to respond to I2C Reads and the ACQ FIFO
309 * to store data received from I2C Writes
310 */
312 /**
313 * Line Loopback enabled
314 */
316 /**
317 * ACK Control Mode enabled
318 */
320 /**
321 * Format FIFO is full, SW cannot write commands to transact into the FIFO
322 * until I2C host is able to act on the contents.
323 */
325 /**
326 * RX FIFO is full, I2C cannot continue to read data until SW reads from the
327 * FIFO.
328 */
330 /**
331 * Format FIFO is empty, I2C host will stop transacting until the FIFO is
332 * written to.
333 */
335 /**
336 * RX FIFO Empty, Software has handled all bytes read by the I2C Host.
337 */
339 /**
340 * I2C Host is not carrying out a transaction
341 */
343 /**
344 * I2C Device is not carrying out a transaction
345 */
347 /**
348 * TX FIFO Full, I2C device must respond to I2C reads or have the FIFO cleared
349 * before SW can write to the FIFO.
350 */
352 /**
353 * Acquire FIFO is full of data from I2C writes to the target device. Software
354 * must handle data before I2C device can continue
355 */
357 /**
358 * TX FIFO is empty, device is unprepared to respond to I2C Reads until SW
359 * writes to FIFO
360 */
362 /**
363 * Acquire FIFO is empty and will remain so until I2C Device receives a Write
364 */
366 /**
367 * Target is stretching due to the Auto ACK Counter expiring.
368 */
371
372/**
373 * Get I2C status.
374 *
375 * @param i2c An I2C handle.
376 * @param[out] status I2C status as understood by the block.
377 * @return The result of the operation.
378 */
381
383 /** Received a NACK from the target. */
385 /** Failed to handle a NACK before the handling timeout. */
387 /**
388 * The bus timed out due to SCL held low for too long while the controller was
389 * transmitting.
390 */
392 /**
393 * The controller was unable to transmit a symbol and lost arbitration.
394 */
396} dif_i2c_controller_halt_events_t;
397
398/**
399 * Get the events that contributed to the controller halting, if any.
400 *
401 * @param i2c handle,
402 * @param[out] events The events causing the controller FSM to halt.
403 * @return The result of the operation.
404 */
407 const dif_i2c_t *i2c, dif_i2c_controller_halt_events_t *events);
408
409/**
410 * Clear the selected events that contributed to the controller halting, if any.
411 *
412 * @param i2c handle,
413 * @param events The events to clear.
414 * @return The result of the operation.
415 */
418 const dif_i2c_t *i2c, dif_i2c_controller_halt_events_t events);
419
421 /** Received a new read transfer, and TX stretch controls were enabled. */
423 /** The bus timed out during a read transfer. */
425 /**
426 * The target was unable to transmit a symbol and lost arbitration. For
427 * targets, a loss of arbitration might be an ordinary mechanism in specific
428 * contexts, such as broadcast commands.
429 */
431} dif_i2c_target_tx_halt_events_t;
432
433/**
434 * Get the events that are contributing or would contribute to the target
435 * halting and stretching the clock on a read.
436 *
437 * @param i2c handle,
438 * @param[out] events The events causing the target FSM to stretch on reads.
439 * @return The result of the operation.
440 */
443 const dif_i2c_t *i2c, dif_i2c_target_tx_halt_events_t *events);
444
445/**
446 * Clear the selected events that are contributing or would contribute to the
447 * target halting and stretching the clock on a read.
448 *
449 * @param i2c handle,
450 * @param events The events to clear.
451 * @return The result of the operation.
452 */
455 const dif_i2c_t *i2c, dif_i2c_target_tx_halt_events_t events);
456
457/**
458 * Computes timing parameters for an I2C host and stores them in `config`.
459 *
460 * Timing is based on requirements for devices attached to OpenTitan
461 *
462 * The values returned may be tweaked by callers that require finer control over
463 * some of the calculations, such as how the allocation of a lengthened SCL
464 * period.
465 *
466 * @param timing_config Configuration values for producing timing parameters.
467 * @param[out] config I2C configuration to which to apply the computed
468 * parameters.
469 * @return The result of the operation.
470 */
473 dif_i2c_config_t *config);
474
475/**
476 * Configures I2C with runtime information.
477 *
478 * This function should need to be called once for the lifetime of `handle`.
479 *
480 * @param i2c An I2C handle.
481 * @param config Runtime configuration parameters.
482 * @return The result of the operation.
483 */
486
487/**
488 * Resets the state of the RX FIFO, essentially dropping all received bytes for
489 * the host.
490 *
491 * @param i2c An I2c handle.
492 * @return The result of the operation.
493 */
496
497/**
498 * Resets the state of the FMT FIFO, essentially dropping all scheduled
499 * operations.
500 *
501 * @param i2c An I2c handle.
502 * @return The result of the operation.
503 */
506
507/**
508 * Resets the state of the TX FIFO, essentially dropping all scheduled
509 * responses.
510 *
511 * @param i2c An I2c handle.
512 * @return The result of the operation.
513 */
516
517/**
518 * Resets the state of the ACQ FIFO, essentially dropping all received bytes for
519 * the target device.
520 *
521 * @param i2c An I2c handle.
522 * @return The result of the operation.
523 */
526
527/**
528 * Sets watermarks for the RX and FMT FIFOs, which will assert the
529 * corresponding interrupts whenever the levels in the FIFOs are above (RX)
530 * and below (FMT) the set levels.
531 *
532 * @param i2c An I2C handle.
533 * @param rx_level The desired watermark level for the RX FIFO.
534 * @param fmt_level The desired watermark level for the FMT FIFO.
535 * @return The result of the operation.
536 */
539 dif_i2c_level_t rx_level,
540 dif_i2c_level_t fmt_level);
541
542/**
543 * Sets watermarks for the TX and ACQ FIFOs, which will assert the
544 * corresponding interrupts whenever the levels in the FIFOs are below (TX)
545 * and above (ACQ) the set levels.
546 *
547 * @param i2c An I2C handle.
548 * @param tx_level The desired watermark level for the TX FIFO.
549 * @param acq_level The desired watermark level for the ACQ FIFO.
550 * @return The result of the operation.
551 */
554 dif_i2c_level_t tx_level,
555 dif_i2c_level_t acq_level);
556
557/**
558 * Enables or disables the "Host I2C" functionality,
559 * This function should be called to enable the device
560 * once timings, interrupts, and watermarks are all configured.
561 *
562 * @param i2c An I2C handle.
563 * @param state The new toggle state for the host functionality.
564 * @return The result of the operation.
565 */
568
569/**
570 * Enables or disables the "Device I2C" functionality,
571 * This function should be called to enable the device
572 * once address, and interrupts are all configured.
573 *
574 * @param i2c An I2C handle.
575 * @param state The new toggle state for the device functionality.
576 * @return The result of the operation.
577 */
580 dif_toggle_t state);
581
582/**
583 * Enables or disables the Line Loopback functionality,
584 * This function should be called to assist debugging by setting the i2c block
585 * or host to use received transactions to populate outgoing transactions.
586 *
587 * @param i2c An I2C handle.
588 * @param state The new toggle state for the host functionality.
589 * @return The result of the operation.
590 */
593 dif_toggle_t state);
594
595/**
596 * Enables or disables the functionality to NACK when timing out on an address
597 * (N)ACK phase stretch.
598 * This function should be called prior to enabling the i2c target module.
599 *
600 * @param i2c An I2C handle.
601 * @param state The new toggle state for the device functionality.
602 * @return The result of the operation.
603 */
606 dif_toggle_t state);
607
608/**
609 * Enables or disables the ACK Control Mode functionality.
610 *
611 * This function should be called prior to enabling the i2c target module.
612 *
613 * @param i2c An I2C handle.
614 * @param state The new toggle state for the device functionality.
615 * @return The result of the operation.
616 */
619 dif_toggle_t state);
620
621/**
622 * Enables or disables the bus monitor's multi-controller functionality.
623 *
624 * This function should be called prior to enabling the host or target.
625 *
626 * @param i2c An I2C handle.
627 * @param state The new toggle state for the device functionality.
628 * @return The result of the operation.
629 */
632 dif_toggle_t state);
633
634/**
635 * Enables or disables the target FSM's stretch control for the start of read
636 * transactions.
637 *
638 * This function should be called prior to enabling the target.
639 *
640 * @param i2c An I2C handle.
641 * @param state The new toggle state for the device functionality.
642 * @return The result of the operation.
643 */
646 dif_toggle_t state);
647/**
648 * Enables or disables the "override mode". In override mode, software is able
649 * to directly control the driven values of the SCL and SDA lines using
650 * `dif_i2c_override_drive_pins()`.
651 *
652 * @param i2c An I2C handle.
653 * @param state The new toggle state for override mode.'
654 * @return The result of the operation.
655 */
658 dif_toggle_t state);
659
660/**
661 * Drives the SCL and SDA pins to the given values when "override mode" is
662 * enabled.
663 *
664 * @param i2c An I2C handle.
665 * @param scl The value to drive SCL to.
666 * @param sda The value to drive SDA to.
667 * @return The result of the operation.
668 */
671 bool sda);
672
673/**
674 * Returns oversampling of the last 16 values of the SCL and SDA pins, with the
675 * zeroth bit being the most recent.
676 *
677 * @param i2c An I2C handle.
678 * @param[out] scl_samples SCL sample bits; may be `NULL`.
679 * @param[out] sda_samples SDA sample bits; may be `NULL`.
680 * @return The result of the operation.
681 */
684 uint16_t *scl_samples,
685 uint16_t *sda_samples);
686
687/**
688 * Returns the current levels, i.e., number of entries, in the FMT, RX, TX and
689 * ACQ FIFOs.
690 * These values represent the number of entries pending for send by host
691 * hardware, entries pending for read by host software, entries pending for send
692 * by device hardware, and entries pending for read by device software
693 * respectively.
694 *
695 * @param i2c An I2C handle.
696 * @param[out] fmt_fifo_level The number of unsent FMT bytes; may be `NULL`.
697 * @param[out] rx_fifo_level The number of unread RX bytes; may be `NULL`.
698 * @param[out] tx_fifo_level The number of unread TX bytes; may be `NULL`.
699 * @param[out] acq_fifo_level The number of unread ACQ bytes; may be `NULL`.
700 * @return The result of the operation.
701 */
704 dif_i2c_level_t *fmt_fifo_level,
705 dif_i2c_level_t *rx_fifo_level,
706 dif_i2c_level_t *tx_fifo_level,
707 dif_i2c_level_t *acq_fifo_level);
708
709/**
710 * Read the current value of the Auto ACK Counter.
711 *
712 * The counter is only active if ACK Control Mode is enabled.
713 *
714 * The Auto ACK Counter represents the remaining number of bytes the Target
715 * module will ACK automatically, so long as the ACQ FIFO has capacity.
716 *
717 * @param i2c An I2C handle.
718 * @param count[out] The number of additional bytes to ACK in the current
719 * transfer.
720 * @return The result of the operation.
721 */
723dif_result_t dif_i2c_get_auto_ack_count(const dif_i2c_t *i2c, uint16_t *count);
724
725/**
726 * Reloads the Auto ACK Counter with the provided value.
727 *
728 * The count will only be accepted if the I2C target module is currently
729 * stretching the clock, and the count is currently 0. In other words, the
730 * target module is stretching because the Auto ACK Count was exhausted.
731 *
732 * In addition, the counter is only active if ACK Control Mode is enabled.
733 *
734 * Set the value to 1 to ACK only the current pending data byte. Increase the
735 * `count` argument for each additional byte desired to be automatically ACK'd,
736 * assuming the ACQ FIFO has capacity.
737 *
738 * @param i2c An I2C handle.
739 * @param count The number of additional bytes to ACK in the current transfer.
740 * @return The result of the operation.
741 */
743dif_result_t dif_i2c_set_auto_ack_count(const dif_i2c_t *i2c, uint16_t count);
744
745/**
746 * Instruct the I2C Target module to issue a NACK for the current transaction.
747 *
748 * Only takes effect if the Target module is stretching the clock because the
749 * Auto ACK Count has expired. ACK Control Mode must be enabled.
750 *
751 * @param i2c An I2C handle.
752 * @return The result of the operation.
753 */
756
757/**
758 * Get the pending data byte when stretching due to Auto Ack Count exhaustion.
759 *
760 * This value is only valid if ACK Control Mode is enabled.
761 *
762 * @param i2c An I2C handle.
763 * @param[out] data The data pending for (N)ACK.
764 * @return The result of the operation.
765 */
767dif_result_t dif_i2c_get_pending_acq_byte(const dif_i2c_t *i2c, uint8_t *data);
768
769/**
770 * Pops an entry (a byte) off of the RX FIFO. Passing in `NULL` to the out-param
771 * will still trigger a byte pop.
772 *
773 * @param i2c An I2C handle.
774 * @param[out] byte The popped byte; may be `NULL`.
775 * @return The result of the operation.
776 */
778dif_result_t dif_i2c_read_byte(const dif_i2c_t *i2c, uint8_t *byte);
779
780/**
781 * Reads off a chunk of bytes from the RX FIFO.
782 *
783 * @param i2c An I2C handle.
784 * @param[out] size The size of the buffer.
785 * @param[out] buffer A buffer to receive the bytes read.
786 * @return The result of the operation.
787 */
789dif_result_t dif_i2c_read_bytes(const dif_i2c_t *i2c, size_t size,
790 uint8_t *buffer);
791
792/**
793 * Pushes a raw write entry onto the FMT FIFO, consisting of a byte and format
794 * flags. This function can be called in sequence to enqueue an I2C
795 * transmission.
796 *
797 * Callers should prefer `dif_i2c_write_byte()` instead, since that function
798 * provides clearer semantics. This function should only really be used for
799 * testing or troubleshooting a device.
800 *
801 * @param i2c An I2C handle.
802 * @param byte The value to push onto the FIFO.
803 * @param flags The flags to use for this write.
804 * @return The result of the operation.
805 */
807dif_result_t dif_i2c_write_byte_raw(const dif_i2c_t *i2c, uint8_t byte,
808 dif_i2c_fmt_flags_t flags);
809
810/**
811 * Writes a chunk of raw bytes and format flags onto the FMT FIFO.
812 *
813 * @param i2c An I2C handle.
814 * @param size The number of bytes to push onto the FIFO.
815 * @param bytes Buffer with the values to push onto the FIFO.
816 * @param flags The format flags to use for this write.
817 * @return The result of the operation.
818 */
820dif_result_t dif_i2c_write_bytes_raw(const dif_i2c_t *i2c, size_t size,
821 const uint8_t *bytes,
822 dif_i2c_fmt_flags_t flags);
823
824/**
825 * Pushes a write entry onto the FMT FIFO, consisting of a byte and a format
826 * code. This function can be called in sequence to enqueue an I2C
827 * transmission.
828 *
829 * @param i2c An I2C handle.
830 * @param byte The value to push onto the FIFO.
831 * @param code The code to use for this write.
832 * @param suppress_nak_irq Whether to supress the NAK IRQ for this one byte.
833 * May not be used in combination with `Rx` codes.
834 * @return The result of the operation.
835 */
837dif_result_t dif_i2c_write_byte(const dif_i2c_t *i2c, uint8_t byte,
838 dif_i2c_fmt_t code, bool suppress_nak_irq);
839
840/**
841 * Pushes a byte into the TX FIFO to make it available when this I2C block
842 * responds to an I2C Read as a target device.
843 *
844 * @param i2c handle.
845 * @param byte to write to FIFO
846 * @return The result of the operation.
847 */
849dif_result_t dif_i2c_transmit_byte(const dif_i2c_t *i2c, uint8_t byte);
850
851/**
852 * Read acquired data from the ACQ FIFO, including record of starts, stops,
853 * address and written data
854 *
855 * @param i2c handle.
856 * @param[out] byte, Data received in the transaction, Could be the address or
857 * junk
858 * @param[out] signal, Signal received in the transaction
859 * @return The result of the operation.
860 */
862dif_result_t dif_i2c_acquire_byte(const dif_i2c_t *i2c, uint8_t *byte,
863 dif_i2c_signal_t *signal);
864
866 /** To disable the clock timeout */
868 /** To select the stretch timeout */
870 /** To select the bus timeout (continuous SCL low) */
872} dif_i2c_scl_timeout_t;
873
874/**
875 * Enables clock timeout after a number of I2C block clock cycles
876 * when I2C block is configured as host.
877 *
878 * If `kDifI2cSclTimeoutDisabled` is selected, the clock timeout is disabled.
879 *
880 * If a `kDifI2cSclTimeoutStretch` timeout is selected, the target stretching
881 * timeout function is enabled and the bus timeout is disabled. The timeout
882 * duration is the maximum time a target is allowed to stretch the clock for
883 * any given bit when this i2c controller is transmitting.
884 *
885 * If a `kDifI2cSclTimeoutBus` timeout is selected, the bus timeout function is
886 * enabled, and the target stretching timeout is disabled. The timeout duration
887 * is the maximum time the clock may remain continuously low, even if it is this
888 * i2c controller or target that is pulling SCL low. The bus timeout should be
889 * selected for SMBus compatibility.
890 *
891 * @param i2c An I2C handle,
892 * @param timeout_type Whether to enable the timeout and which one
893 * @param cycles How many cycles to wait before timing out
894 * @return The result of the operation.
895 */
898 dif_i2c_scl_timeout_t timeout_type,
899 uint32_t cycles);
900
901/**
902 * Sets the I2C device to listen for a pair of masked addresses
903 *
904 * @param i2c handle,
905 * @param id0 address and mask pair to listen for can be null
906 * @param id1 address and mask pair to listen for can be null
907 * @return The result of the operation.
908 */
911 const dif_i2c_id_t *id0,
912 const dif_i2c_id_t *id1);
913
914/**
915 * Set host timeout. When OT is acting as target device, set the number of
916 * counts after which to trigger a host_timeout interrupt
917 *
918 * @param i2c handle,
919 * @param duration in clock counts
920 * @return The result of the operation.
921 */
923dif_result_t dif_i2c_set_host_timeout(const dif_i2c_t *i2c, uint32_t duration);
924
925#ifdef __cplusplus
926} // extern "C"
927#endif // __cplusplus
928
929#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_I2C_H_