I2C Device Interface Functions More...

#include <stdbool.h>
#include <stdint.h>
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_i2c_autogen.h"

Data Structures
struct	dif_i2c_timing_config
	Timing configuration parameters for I2C. More...

struct	dif_i2c_id
	Configuration for the addressing behavior of the I2C, can be disabled or configured to look for multiple addresses by masking certain bits. More...

struct	dif_i2c_config
	Runtime configuration for I2C. More...

struct	dif_i2c_fmt_flags
	Flags for a formatted I2C byte, used by the `dif_i2c_write_byte_raw()` function. More...

struct	dif_i2c_status
	Flags representing the status of an I2C block. More...

struct	dif_i2c_controller_halt_events

struct	dif_i2c_target_tx_halt_events

Typedefs
typedef enum dif_i2c_speed	dif_i2c_speed_t
	Represents a speed setting for an I2C component: standard, fast, and fast plus, corresponding to 100 kbaud, 400 kbaud, and 1 Mbaud, respectively.

typedef struct dif_i2c_timing_config	dif_i2c_timing_config_t
	Timing configuration parameters for I2C.

typedef struct dif_i2c_id	dif_i2c_id_t
	Configuration for the addressing behavior of the I2C, can be disabled or configured to look for multiple addresses by masking certain bits.

typedef struct dif_i2c_config	dif_i2c_config_t
	Runtime configuration for I2C.

typedef uint16_t	dif_i2c_level_t
	Represents a watermark or data level for one of the I2C FIFOs.

typedef struct dif_i2c_fmt_flags	dif_i2c_fmt_flags_t
	Flags for a formatted I2C byte, used by the `dif_i2c_write_byte_raw()` function.

typedef enum dif_i2c_signal	dif_i2c_signal_t
	The I2C Target device records the following signals with received data.

typedef enum dif_i2c_fmt	dif_i2c_fmt_t
	Available formatting codes for `dif_i2c_write_byte_raw()`.

typedef struct dif_i2c_status	dif_i2c_status_t
	Flags representing the status of an I2C block.

typedef struct dif_i2c_controller_halt_events	dif_i2c_controller_halt_events_t

typedef struct dif_i2c_target_tx_halt_events	dif_i2c_target_tx_halt_events_t

typedef enum dif_i2c_scl_timeout	dif_i2c_scl_timeout_t

Enumerations
enum	dif_i2c_speed { kDifI2cSpeedStandard , kDifI2cSpeedFast , kDifI2cSpeedFastPlus }
	Represents a speed setting for an I2C component: standard, fast, and fast plus, corresponding to 100 kbaud, 400 kbaud, and 1 Mbaud, respectively. More...

enum	{ kDifI2cInputDelayCycles = 4 }

enum	dif_i2c_signal { kDifI2cSignalStart = 1 , kDifI2cSignalStop = 2 , kDifI2cSignalRepeat = 3 , kDifI2cSignalNack = 4 , kDifI2cSignalNackStart = 5 , kDifI2cSignalNackStop = 6 , kDifI2cSignalNone = 0 }
	The I2C Target device records the following signals with received data. More...

enum	dif_i2c_fmt { kDifI2cFmtStart , kDifI2cFmtTx , kDifI2cFmtTxStop , kDifI2cFmtRx , kDifI2cFmtRxContinue , kDifI2cFmtRxStop }
	Available formatting codes for `dif_i2c_write_byte_raw()`. More...

enum	dif_i2c_scl_timeout { kDifI2cSclTimeoutDisabled = 0 , kDifI2cSclTimeoutStretch , kDifI2cSclTimeoutBus }

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_get_status (const dif_i2c_t i2c, dif_i2c_status_t status)
	Get I2C status.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_get_controller_halt_events (const dif_i2c_t i2c, dif_i2c_controller_halt_events_t events)
	Get the events that contributed to the controller halting, if any.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_clear_controller_halt_events (const dif_i2c_t *i2c, dif_i2c_controller_halt_events_t events)
	Clear the selected events that contributed to the controller halting, if any.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_get_target_tx_halt_events (const dif_i2c_t i2c, dif_i2c_target_tx_halt_events_t events)
	Get the events that are contributing or would contribute to the target halting and stretching the clock on a read.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_clear_target_tx_halt_events (const dif_i2c_t *i2c, dif_i2c_target_tx_halt_events_t events)
	Clear the selected events that are contributing or would contribute to the target halting and stretching the clock on a read.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_compute_timing (dif_i2c_timing_config_t timing_config, dif_i2c_config_t *config)
	Computes timing parameters for an I2C host and stores them in `config`.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_configure (const dif_i2c_t *i2c, dif_i2c_config_t config)
	Configures I2C with runtime information.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_reset_rx_fifo (const dif_i2c_t *i2c)
	Resets the state of the RX FIFO, essentially dropping all received bytes for the host.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_reset_fmt_fifo (const dif_i2c_t *i2c)
	Resets the state of the FMT FIFO, essentially dropping all scheduled operations.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_reset_tx_fifo (const dif_i2c_t *i2c)
	Resets the state of the TX FIFO, essentially dropping all scheduled responses.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_reset_acq_fifo (const dif_i2c_t *i2c)
	Resets the state of the ACQ FIFO, essentially dropping all received bytes for the target device.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_set_host_watermarks (const dif_i2c_t *i2c, dif_i2c_level_t rx_level, dif_i2c_level_t fmt_level)
	Sets watermarks for the RX and FMT FIFOs, which will assert the corresponding interrupts whenever the levels in the FIFOs are above (RX) and below (FMT) the set levels.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_set_target_watermarks (const dif_i2c_t *i2c, dif_i2c_level_t tx_level, dif_i2c_level_t acq_level)
	Sets watermarks for the TX and ACQ FIFOs, which will assert the corresponding interrupts whenever the levels in the FIFOs are below (TX) and above (ACQ) the set levels.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_host_set_enabled (const dif_i2c_t *i2c, dif_toggle_t state)
	Enables or disables the "Host I2C" functionality, This function should be called to enable the device once timings, interrupts, and watermarks are all configured.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_device_set_enabled (const dif_i2c_t *i2c, dif_toggle_t state)
	Enables or disables the "Device I2C" functionality, This function should be called to enable the device once address, and interrupts are all configured.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_line_loopback_set_enabled (const dif_i2c_t *i2c, dif_toggle_t state)
	Enables or disables the Line Loopback functionality, This function should be called to assist debugging by setting the i2c block or host to use received transactions to populate outgoing transactions.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_addr_nack_set_enabled (const dif_i2c_t *i2c, dif_toggle_t state)
	Enables or disables the functionality to NACK when timing out on an address (N)ACK phase stretch.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_ack_ctrl_set_enabled (const dif_i2c_t *i2c, dif_toggle_t state)
	Enables or disables the ACK Control Mode functionality.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_multi_controller_monitor_set_enabled (const dif_i2c_t *i2c, dif_toggle_t state)
	Enables or disables the bus monitor's multi-controller functionality.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_target_tx_stretch_ctrl_set_enabled (const dif_i2c_t *i2c, dif_toggle_t state)
	Enables or disables the target FSM's stretch control for the start of read transactions.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_override_set_enabled (const dif_i2c_t *i2c, dif_toggle_t state)
	Enables or disables the "override mode".

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_override_drive_pins (const dif_i2c_t *i2c, bool scl, bool sda)
	Drives the SCL and SDA pins to the given values when "override mode" is enabled.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_override_sample_pins (const dif_i2c_t i2c, uint16_t scl_samples, uint16_t *sda_samples)
	Returns oversampling of the last 16 values of the SCL and SDA pins, with the zeroth bit being the most recent.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_get_fifo_levels (const dif_i2c_t i2c, dif_i2c_level_t fmt_fifo_level, dif_i2c_level_t rx_fifo_level, dif_i2c_level_t tx_fifo_level, dif_i2c_level_t *acq_fifo_level)
	Returns the current levels, i.e., number of entries, in the FMT, RX, TX and ACQ FIFOs.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_get_auto_ack_count (const dif_i2c_t i2c, uint16_t count)
	Read the current value of the Auto ACK Counter.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_set_auto_ack_count (const dif_i2c_t *i2c, uint16_t count)
	Reloads the Auto ACK Counter with the provided value.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_nack_transaction (const dif_i2c_t *i2c)
	Instruct the I2C Target module to issue a NACK for the current transaction.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_get_pending_acq_byte (const dif_i2c_t i2c, uint8_t data)
	Get the pending data byte when stretching due to Auto Ack Count exhaustion.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_read_byte (const dif_i2c_t i2c, uint8_t byte)
	Pops an entry (a byte) off of the RX FIFO.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_read_bytes (const dif_i2c_t i2c, size_t size, uint8_t buffer)
	Reads off a chunk of bytes from the RX FIFO.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_write_byte_raw (const dif_i2c_t *i2c, uint8_t byte, dif_i2c_fmt_flags_t flags)
	Pushes a raw write entry onto the FMT FIFO, consisting of a byte and format flags.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_write_bytes_raw (const dif_i2c_t i2c, size_t size, const uint8_t bytes, dif_i2c_fmt_flags_t flags)
	Writes a chunk of raw bytes and format flags onto the FMT FIFO.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_write_byte (const dif_i2c_t *i2c, uint8_t byte, dif_i2c_fmt_t code, bool suppress_nak_irq)
	Pushes a write entry onto the FMT FIFO, consisting of a byte and a format code.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_transmit_byte (const dif_i2c_t *i2c, uint8_t byte)
	Pushes a byte into the TX FIFO to make it available when this I2C block responds to an I2C Read as a target device.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_acquire_byte (const dif_i2c_t i2c, uint8_t byte, dif_i2c_signal_t *signal)
	Read acquired data from the ACQ FIFO, including record of starts, stops, address and written data.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_enable_clock_timeout (const dif_i2c_t *i2c, dif_i2c_scl_timeout_t timeout_type, uint32_t cycles)
	Enables clock timeout after a number of I2C block clock cycles when I2C block is configured as host.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_set_device_id (const dif_i2c_t i2c, const dif_i2c_id_t id0, const dif_i2c_id_t *id1)
	Sets the I2C device to listen for a pair of masked addresses.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_set_host_timeout (const dif_i2c_t *i2c, uint32_t duration)
	Set host timeout.

Detailed Description

I2C Device Interface Functions

Definition in file dif_i2c.h.

Data Structure Documentation

◆ dif_i2c_timing_config

struct dif_i2c_timing_config

Timing configuration parameters for I2C.

While the I2C device requires ten parameters to describe its timing configuration, the degrees of freedom of those parameters is constrained to the ones in this struct.

See dif_i2c_compute_timing()

Definition at line 65 of file dif_i2c.h.

Data Fields
uint32_t	clock_period_nanos	The period of the clock driving this device, in nanoseconds. This value should not be zero, since it is used as a divisor for division.
dif_i2c_speed_t	lowest_target_device_speed	The lowest speed at which an I2C target connected to this host will operate. In other words, this is the maximum speed at which the host can operate without going over what the target devices can handle.
uint32_t	scl_period_nanos	The desired period of the SCL line, in nanoseconds. Normally, this should just be `1'000'000 / lowest_target_device_speed`, but the period may be larger if desired. Setting this value to zero will result in the minimum period being used.
uint32_t	sda_fall_nanos	The expected time for the bus signal to fall, similar to `sda_rise_nanos`.
uint32_t	sda_rise_nanos	The expected time it takes for the I2C bus signal to rise, in nanoseconds. This value is dependent on properties of the hardware's interconnect, and not under actual firmware control.

◆ dif_i2c_id

struct dif_i2c_id

Configuration for the addressing behavior of the I2C, can be disabled or configured to look for multiple addresses by masking certain bits.

A mask of 0x7f will match only a single address.

Definition at line 108 of file dif_i2c.h.

Data Fields
uint8_t	address	The 7-bit I2C address that should be matched after masking to cause the activated I2C Target device to begin to act in a transaction. Address is LSB aligned.
uint8_t	mask	Mask the recieved I2C address before checking for a match. Received Address & mask must equal the programmed address to activate I2C Device. If Address & ~mask != 0, this will not match any addresses. A mask of 0x7f will cause device to only respond to an exact match. The mask is 7 bits and LSB aligned.

◆ dif_i2c_config

struct dif_i2c_config

Runtime configuration for I2C.

This struct describes runtime timing parameters. Computing these values is somewhat complicated, so these fields should be initialized using the dif_i2c_compute_timing() function. A caller is, however, free to compute these values themselves if they prefer, so long as the I2C spec is respected.

These values correspond to those in Table 10 of the I2C spec, and are given in units of input clock cycles.

Definition at line 137 of file dif_i2c.h.

Data Fields
uint16_t	data_signal_hold_cycles
uint16_t	data_signal_setup_cycles
uint16_t	fall_cycles
uint16_t	rise_cycles
uint16_t	scl_time_high_cycles
uint16_t	scl_time_low_cycles
uint16_t	start_signal_hold_cycles
uint16_t	start_signal_setup_cycles
uint16_t	stop_signal_hold_cycles	This parameter is referred to in the I2C documents as the "bus free time".
uint16_t	stop_signal_setup_cycles

◆ dif_i2c_fmt_flags

struct dif_i2c_fmt_flags

Flags for a formatted I2C byte, used by the dif_i2c_write_byte_raw() function.

Definition at line 163 of file dif_i2c.h.

Data Fields
bool	read	Causes the byte to be interpreted as an unsigned number of bytes to read from the target; 0 is interpreted as 256.
bool	read_cont	Requires `read` to be set; if so, once the final byte associated with this read is received, it will be acknowledged, allowing the read operation to continue.
bool	start	Causes a start signal to be sent before the byte. If a start has been issued during the current transaction, this will issue a repeated start.
bool	stop	Causes a stop signal to be sent after the byte. This flag cannot be set when both `read` and `read_cont` are set.
bool	suppress_nak_irq	By default, the hardware expects an ACK after every byte sent, and raises an exception (contributing to the `kDifi2cIrqControllerHalt` interrupt). This flag disables that behavior. This flag cannot be set along with `read` or `read_cont`.

◆ dif_i2c_status

struct dif_i2c_status

Flags representing the status of an I2C block.

Definition at line 299 of file dif_i2c.h.

Data Fields
bool	ack_control_en	ACK Control Mode enabled.
bool	ack_ctrl_stretch	Target is stretching due to the Auto ACK Counter expiring.
bool	acq_fifo_empty	Acquire FIFO is empty and will remain so until I2C Device receives a Write.
bool	acq_fifo_full	Acquire FIFO is full of data from I2C writes to the target device. Software must handle data before I2C device can continue
bool	enable_host	Enable Host, I2C block has been initialized and enabled to act as a host, consuming entries from the FMT FIFO to perform I2C transactions, and writing the results of I2C Reads to the RX FIFO.
bool	enable_target	Enable Target, I2C block has been initialized and enabled to act as a target device, using the TX FIFO to respond to I2C Reads and the ACQ FIFO to store data received from I2C Writes.
bool	fmt_fifo_empty	Format FIFO is empty, I2C host will stop transacting until the FIFO is written to.
bool	fmt_fifo_full	Format FIFO is full, SW cannot write commands to transact into the FIFO until I2C host is able to act on the contents.
bool	host_idle	I2C Host is not carrying out a transaction.
bool	line_loopback	Line Loopback enabled.
bool	rx_fifo_empty	RX FIFO Empty, Software has handled all bytes read by the I2C Host.
bool	rx_fifo_full	RX FIFO is full, I2C cannot continue to read data until SW reads from the FIFO.
bool	target_idle	I2C Device is not carrying out a transaction.
bool	tx_fifo_empty	TX FIFO is empty, device is unprepared to respond to I2C Reads until SW writes to FIFO.
bool	tx_fifo_full	TX FIFO Full, I2C device must respond to I2C reads or have the FIFO cleared before SW can write to the FIFO.

◆ dif_i2c_controller_halt_events

struct dif_i2c_controller_halt_events

Definition at line 382 of file dif_i2c.h.

Data Fields
bool	arbitration_lost	The controller was unable to transmit a symbol and lost arbitration.
bool	bus_timeout	The bus timed out due to SCL held low for too long while the controller was transmitting.
bool	nack_received	Received a NACK from the target.
bool	unhandled_nack_timeout	Failed to handle a NACK before the handling timeout.

◆ dif_i2c_target_tx_halt_events

struct dif_i2c_target_tx_halt_events

Definition at line 420 of file dif_i2c.h.

Data Fields
bool	arbitration_lost	The target was unable to transmit a symbol and lost arbitration. For targets, a loss of arbitration might be an ordinary mechanism in specific contexts, such as broadcast commands.
bool	bus_timeout	The bus timed out during a read transfer.
bool	tx_pending	Received a new read transfer, and TX stretch controls were enabled.

Typedef Documentation

◆ dif_i2c_config_t

typedef struct dif_i2c_config dif_i2c_config_t

Runtime configuration for I2C.

This struct describes runtime timing parameters. Computing these values is somewhat complicated, so these fields should be initialized using the dif_i2c_compute_timing() function. A caller is, however, free to compute these values themselves if they prefer, so long as the I2C spec is respected.

These values correspond to those in Table 10 of the I2C spec, and are given in units of input clock cycles.

◆ dif_i2c_fmt_t

typedef enum dif_i2c_fmt dif_i2c_fmt_t

Available formatting codes for dif_i2c_write_byte_raw().

Each code describes how to interpret the byte parameter, referred to below as "the byte".

It is the caller's responsibility to observe the state transitions in the comments below.

◆ dif_i2c_id_t

typedef struct dif_i2c_id dif_i2c_id_t

Configuration for the addressing behavior of the I2C, can be disabled or configured to look for multiple addresses by masking certain bits.

A mask of 0x7f will match only a single address.

◆ dif_i2c_level_t

typedef uint16_t dif_i2c_level_t

Represents a watermark or data level for one of the I2C FIFOs.

Definition at line 157 of file dif_i2c.h.

◆ dif_i2c_timing_config_t

typedef struct dif_i2c_timing_config dif_i2c_timing_config_t

Timing configuration parameters for I2C.

While the I2C device requires ten parameters to describe its timing configuration, the degrees of freedom of those parameters is constrained to the ones in this struct.

See dif_i2c_compute_timing()

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
kDifI2cInputDelayCycles	Input Delay Cycles; for clock stretching detection to work, the SCL high and low time must be at least 4 cycles.

Definition at line 48 of file dif_i2c.h.

◆ dif_i2c_fmt

enum dif_i2c_fmt

Available formatting codes for dif_i2c_write_byte_raw().

Each code describes how to interpret the byte parameter, referred to below as "the byte".

It is the caller's responsibility to observe the state transitions in the comments below.

Enumerator
kDifI2cFmtStart	Start a transaction. This sends a START signal followed by the byte. The byte sent will form (potentially part of) the target address for the transaction. May be followed by any format code.
kDifI2cFmtTx	Transmit byte. This simply sends the byte. It may need to be used in conjunction with `Start` to send a multi-byte target address. May be followed by any format code.
kDifI2cFmtTxStop	Transmit byte and stop. This sends the byte, and then sends a stop signal, completing a transaction. Only `Start` may follow this code.
kDifI2cFmtRx	Request `n` bytes, where `n` is the byte interpreted as an unsigned integer; a byte value of `0` will be interpreted as requesting `256` bytes. This will NAK the last byte. Only `Start` may follow this code (this code does not stop a transaction; see `RxStop`).
kDifI2cFmtRxContinue	Request `n` bytes, same as `Rx`, but ACK the last byte so that more data can be requested. May be followed by `RxContinue`, `Rx`, or `RxStop`.
kDifI2cFmtRxStop	Request `n` bytes, same as `Rx`, but, after NAKing the last byte, send a stop signal to end the transaction. Only `Start` may follow this code.

Definition at line 248 of file dif_i2c.h.

◆ dif_i2c_scl_timeout

enum dif_i2c_scl_timeout

Enumerator
kDifI2cSclTimeoutDisabled	To disable the clock timeout.
kDifI2cSclTimeoutStretch	To select the stretch timeout.
kDifI2cSclTimeoutBus	To select the bus timeout (continuous SCL low)

Definition at line 865 of file dif_i2c.h.

◆ dif_i2c_signal

enum dif_i2c_signal

The I2C Target device records the following signals with received data.

Enumerator
kDifI2cSignalStart	The associated byte was received with a START signal, and should be the matching address and R/W bit.
kDifI2cSignalStop	The associated byte was received after a STOP signal, so the transaction is over and the byte is junk.
kDifI2cSignalRepeat	The associated byte was received with a repeated START signal and represents the address for the subsequent transaction.
kDifI2cSignalNack	The associated data byte was NACK'd.
kDifI2cSignalNackStart	There was a stretch timeout on the associated address byte, leading to NACKing all subsequent incoming bytes for the rest of the transaction (and returning 0xFF bytes on any subsequent reads in that transaction).
kDifI2cSignalNackStop	A STOP signal was received to end a transaction that experienced a stretch timeout or other I/O error condition.
kDifI2cSignalNone	There's no associated STOP or START signal this is just a byte that's been written to the I2C target in an ongoing transaction, and it was ACK'd.

Definition at line 201 of file dif_i2c.h.

◆ dif_i2c_speed

enum dif_i2c_speed

Represents a speed setting for an I2C component: standard, fast, and fast plus, corresponding to 100 kbaud, 400 kbaud, and 1 Mbaud, respectively.

Enumerator
kDifI2cSpeedStandard	Standard speed, 100 kilobaud.
kDifI2cSpeedFast	Fast speed, 400 kilobaud.
kDifI2cSpeedFastPlus	Fast plus speed, 1 megabaud.

Definition at line 31 of file dif_i2c.h.

Function Documentation

◆ dif_i2c_ack_ctrl_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_ack_ctrl_set_enabled	(	const dif_i2c_t *	i2c,
		dif_toggle_t	state )

Enables or disables the ACK Control Mode functionality.

This function should be called prior to enabling the i2c target module.

Parameters

i2c	An I2C handle.
state	The new toggle state for the device functionality.

Returns: The result of the operation.

Definition at line 458 of file dif_i2c.c.

◆ dif_i2c_acquire_byte()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_acquire_byte	(	const dif_i2c_t *	i2c,
		uint8_t *	byte,
		dif_i2c_signal_t *	signal )

Read acquired data from the ACQ FIFO, including record of starts, stops, address and written data.

Parameters

	i2c	handle.
[out]	byte,Data	received in the transaction, Could be the address or junk
[out]	signal,Signal	received in the transaction

Returns: The result of the operation.

Definition at line 797 of file dif_i2c.c.

◆ dif_i2c_addr_nack_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_addr_nack_set_enabled	(	const dif_i2c_t *	i2c,
		dif_toggle_t	state )

Enables or disables the functionality to NACK when timing out on an address (N)ACK phase stretch.

This function should be called prior to enabling the i2c target module.

Parameters

i2c	An I2C handle.
state	The new toggle state for the device functionality.

Returns: The result of the operation.

Definition at line 440 of file dif_i2c.c.

◆ dif_i2c_clear_controller_halt_events()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_clear_controller_halt_events	(	const dif_i2c_t *	i2c,
		dif_i2c_controller_halt_events_t	events )

Clear the selected events that contributed to the controller halting, if any.

Parameters

i2c	handle,
events	The events to clear.

Returns: The result of the operation.

Definition at line 82 of file dif_i2c.c.

◆ dif_i2c_clear_target_tx_halt_events()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_clear_target_tx_halt_events	(	const dif_i2c_t *	i2c,
		dif_i2c_target_tx_halt_events_t	events )

Clear the selected events that are contributing or would contribute to the target halting and stretching the clock on a read.

Parameters

i2c	handle,
events	The events to clear.

Returns: The result of the operation.

Definition at line 117 of file dif_i2c.c.

◆ dif_i2c_compute_timing()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_compute_timing	(	dif_i2c_timing_config_t	timing_config,
		dif_i2c_config_t *	config )

Computes timing parameters for an I2C host and stores them in config.

Timing is based on requirements for devices attached to OpenTitan

The values returned may be tweaked by callers that require finer control over some of the calculations, such as how the allocation of a lengthened SCL period.

Parameters

	timing_config	Configuration values for producing timing parameters.
[out]	config	I2C configuration to which to apply the computed parameters.

Returns: The result of the operation.

Definition at line 186 of file dif_i2c.c.

◆ dif_i2c_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_configure	(	const dif_i2c_t *	i2c,
		dif_i2c_config_t	config )

Configures I2C with runtime information.

This function should need to be called once for the lifetime of handle.

Parameters

i2c	An I2C handle.
config	Runtime configuration parameters.

Returns: The result of the operation.

Definition at line 249 of file dif_i2c.c.

◆ dif_i2c_device_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_device_set_enabled	(	const dif_i2c_t *	i2c,
		dif_toggle_t	state )

Enables or disables the "Device I2C" functionality, This function should be called to enable the device once address, and interrupts are all configured.

Parameters

i2c	An I2C handle.
state	The new toggle state for the device functionality.

Returns: The result of the operation.

Definition at line 404 of file dif_i2c.c.

◆ dif_i2c_enable_clock_timeout()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_enable_clock_timeout	(	const dif_i2c_t *	i2c,
		dif_i2c_scl_timeout_t	timeout_type,
		uint32_t	cycles )

Enables clock timeout after a number of I2C block clock cycles when I2C block is configured as host.

If kDifI2cSclTimeoutDisabled is selected, the clock timeout is disabled.

If a kDifI2cSclTimeoutStretch timeout is selected, the target stretching timeout function is enabled and the bus timeout is disabled. The timeout duration is the maximum time a target is allowed to stretch the clock for any given bit when this i2c controller is transmitting.

If a kDifI2cSclTimeoutBus timeout is selected, the bus timeout function is enabled, and the target stretching timeout is disabled. The timeout duration is the maximum time the clock may remain continuously low, even if it is this i2c controller or target that is pulling SCL low. The bus timeout should be selected for SMBus compatibility.

Parameters

i2c	An I2C handle,
timeout_type	Whether to enable the timeout and which one
cycles	How many cycles to wait before timing out

Returns: The result of the operation.

Definition at line 814 of file dif_i2c.c.

◆ dif_i2c_get_auto_ack_count()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_get_auto_ack_count	(	const dif_i2c_t *	i2c,
		uint16_t *	count )

Read the current value of the Auto ACK Counter.

The counter is only active if ACK Control Mode is enabled.

The Auto ACK Counter represents the remaining number of bytes the Target module will ACK automatically, so long as the ACQ FIFO has capacity.

Parameters

i2c	An I2C handle.
count[out]	The number of additional bytes to ACK in the current transfer.

Returns: The result of the operation.

Definition at line 603 of file dif_i2c.c.

◆ dif_i2c_get_controller_halt_events()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_get_controller_halt_events	(	const dif_i2c_t *	i2c,
		dif_i2c_controller_halt_events_t *	events )

Get the events that contributed to the controller halting, if any.

Parameters

	i2c	handle,
[out]	events	The events causing the controller FSM to halt.

Returns: The result of the operation.

Definition at line 64 of file dif_i2c.c.

◆ dif_i2c_get_fifo_levels()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_get_fifo_levels	(	const dif_i2c_t *	i2c,
		dif_i2c_level_t *	fmt_fifo_level,
		dif_i2c_level_t *	rx_fifo_level,
		dif_i2c_level_t *	tx_fifo_level,
		dif_i2c_level_t *	acq_fifo_level )

Returns the current levels, i.e., number of entries, in the FMT, RX, TX and ACQ FIFOs.

These values represent the number of entries pending for send by host hardware, entries pending for read by host software, entries pending for send by device hardware, and entries pending for read by device software respectively.

Parameters

	i2c	An I2C handle.
[out]	fmt_fifo_level	The number of unsent FMT bytes; may be `NULL`.
[out]	rx_fifo_level	The number of unread RX bytes; may be `NULL`.
[out]	tx_fifo_level	The number of unread TX bytes; may be `NULL`.
[out]	acq_fifo_level	The number of unread ACQ bytes; may be `NULL`.

Returns: The result of the operation.

Definition at line 567 of file dif_i2c.c.

◆ dif_i2c_get_pending_acq_byte()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_get_pending_acq_byte	(	const dif_i2c_t *	i2c,
		uint8_t *	data )

Get the pending data byte when stretching due to Auto Ack Count exhaustion.

This value is only valid if ACK Control Mode is enabled.

Parameters

	i2c	An I2C handle.
[out]	data	The data pending for (N)ACK.

Returns: The result of the operation.

Definition at line 642 of file dif_i2c.c.

◆ dif_i2c_get_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_get_status	(	const dif_i2c_t *	i2c,
		dif_i2c_status_t *	status )

Get I2C status.

Parameters

	i2c	An I2C handle.
[out]	status	I2C status as understood by the block.

Returns: The result of the operation.

Get I2C status.

Definition at line 36 of file dif_i2c.c.

◆ dif_i2c_get_target_tx_halt_events()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_get_target_tx_halt_events	(	const dif_i2c_t *	i2c,
		dif_i2c_target_tx_halt_events_t *	events )

Get the events that are contributing or would contribute to the target halting and stretching the clock on a read.

Parameters

	i2c	handle,
[out]	events	The events causing the target FSM to stretch on reads.

Returns: The result of the operation.

Definition at line 101 of file dif_i2c.c.

◆ dif_i2c_host_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_host_set_enabled	(	const dif_i2c_t *	i2c,
		dif_toggle_t	state )

Enables or disables the "Host I2C" functionality, This function should be called to enable the device once timings, interrupts, and watermarks are all configured.

Parameters

i2c	An I2C handle.
state	The new toggle state for the host functionality.

Returns: The result of the operation.

Definition at line 386 of file dif_i2c.c.

◆ dif_i2c_line_loopback_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_line_loopback_set_enabled	(	const dif_i2c_t *	i2c,
		dif_toggle_t	state )

Enables or disables the Line Loopback functionality, This function should be called to assist debugging by setting the i2c block or host to use received transactions to populate outgoing transactions.

Parameters

i2c	An I2C handle.
state	The new toggle state for the host functionality.

Returns: The result of the operation.

Definition at line 422 of file dif_i2c.c.

◆ dif_i2c_multi_controller_monitor_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_multi_controller_monitor_set_enabled	(	const dif_i2c_t *	i2c,
		dif_toggle_t	state )

Enables or disables the bus monitor's multi-controller functionality.

This function should be called prior to enabling the host or target.

Parameters

i2c	An I2C handle.
state	The new toggle state for the device functionality.

Returns: The result of the operation.

Definition at line 476 of file dif_i2c.c.

◆ dif_i2c_nack_transaction()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_nack_transaction ( const dif_i2c_t * i2c )

Instruct the I2C Target module to issue a NACK for the current transaction.

Only takes effect if the Target module is stretching the clock because the Auto ACK Count has expired. ACK Control Mode must be enabled.

Parameters

i2c	An I2C handle.

Returns: The result of the operation.

Definition at line 631 of file dif_i2c.c.

◆ dif_i2c_override_drive_pins()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_override_drive_pins	(	const dif_i2c_t *	i2c,
		bool	scl,
		bool	sda )

Drives the SCL and SDA pins to the given values when "override mode" is enabled.

Parameters

i2c	An I2C handle.
scl	The value to drive SCL to.
sda	The value to drive SDA to.

Returns: The result of the operation.

Definition at line 531 of file dif_i2c.c.

◆ dif_i2c_override_sample_pins()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_override_sample_pins	(	const dif_i2c_t *	i2c,
		uint16_t *	scl_samples,
		uint16_t *	sda_samples )

Returns oversampling of the last 16 values of the SCL and SDA pins, with the zeroth bit being the most recent.

Parameters

	i2c	An I2C handle.
[out]	scl_samples	SCL sample bits; may be `NULL`.
[out]	sda_samples	SDA sample bits; may be `NULL`.

Returns: The result of the operation.

Definition at line 546 of file dif_i2c.c.

◆ dif_i2c_override_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_override_set_enabled	(	const dif_i2c_t *	i2c,
		dif_toggle_t	state )

Enables or disables the "override mode".

In override mode, software is able to directly control the driven values of the SCL and SDA lines using dif_i2c_override_drive_pins().

Parameters

i2c	An I2C handle.
state	The new toggle state for override mode.'

Returns: The result of the operation.

Definition at line 513 of file dif_i2c.c.

◆ dif_i2c_read_byte()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_read_byte	(	const dif_i2c_t *	i2c,
		uint8_t *	byte )

Pops an entry (a byte) off of the RX FIFO.

Passing in NULL to the out-param will still trigger a byte pop.

Parameters

	i2c	An I2C handle.
[out]	byte	The popped byte; may be `NULL`.

Returns: The result of the operation.

Definition at line 653 of file dif_i2c.c.

◆ dif_i2c_read_bytes()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_read_bytes	(	const dif_i2c_t *	i2c,
		size_t	size,
		uint8_t *	buffer )

Reads off a chunk of bytes from the RX FIFO.

Parameters

	i2c	An I2C handle.
[out]	size	The size of the buffer.
[out]	buffer	A buffer to receive the bytes read.

Returns: The result of the operation.

Definition at line 666 of file dif_i2c.c.

◆ dif_i2c_reset_acq_fifo()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_reset_acq_fifo ( const dif_i2c_t * i2c )

Resets the state of the ACQ FIFO, essentially dropping all received bytes for the target device.

Parameters

i2c	An I2c handle.

Returns: The result of the operation.

Definition at line 328 of file dif_i2c.c.

◆ dif_i2c_reset_fmt_fifo()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_reset_fmt_fifo ( const dif_i2c_t * i2c )

Resets the state of the FMT FIFO, essentially dropping all scheduled operations.

Parameters

i2c	An I2c handle.

Returns: The result of the operation.

Definition at line 304 of file dif_i2c.c.

◆ dif_i2c_reset_rx_fifo()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_reset_rx_fifo ( const dif_i2c_t * i2c )

Resets the state of the RX FIFO, essentially dropping all received bytes for the host.

Parameters

i2c	An I2c handle.

Returns: The result of the operation.

Definition at line 292 of file dif_i2c.c.

◆ dif_i2c_reset_tx_fifo()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_reset_tx_fifo ( const dif_i2c_t * i2c )

Resets the state of the TX FIFO, essentially dropping all scheduled responses.

Parameters

i2c	An I2c handle.

Returns: The result of the operation.

Definition at line 316 of file dif_i2c.c.

◆ dif_i2c_set_auto_ack_count()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_set_auto_ack_count	(	const dif_i2c_t *	i2c,
		uint16_t	count )

Reloads the Auto ACK Counter with the provided value.

The count will only be accepted if the I2C target module is currently stretching the clock, and the count is currently 0. In other words, the target module is stretching because the Auto ACK Count was exhausted.

In addition, the counter is only active if ACK Control Mode is enabled.

Set the value to 1 to ACK only the current pending data byte. Increase the count argument for each additional byte desired to be automatically ACK'd, assuming the ACQ FIFO has capacity.

Parameters

i2c	An I2C handle.
count	The number of additional bytes to ACK in the current transfer.

Returns: The result of the operation.

Definition at line 616 of file dif_i2c.c.

◆ dif_i2c_set_device_id()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_set_device_id	(	const dif_i2c_t *	i2c,
		const dif_i2c_id_t *	id0,
		const dif_i2c_id_t *	id1 )

Sets the I2C device to listen for a pair of masked addresses.

Parameters

i2c	handle,
id0	address and mask pair to listen for can be null
id1	address and mask pair to listen for can be null

Returns: The result of the operation.

Definition at line 848 of file dif_i2c.c.

◆ dif_i2c_set_host_timeout()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_set_host_timeout	(	const dif_i2c_t *	i2c,
		uint32_t	duration )

Set host timeout.

When OT is acting as target device, set the number of counts after which to trigger a host_timeout interrupt

Parameters

i2c	handle,
duration	in clock counts

Returns: The result of the operation.

Definition at line 880 of file dif_i2c.c.

◆ dif_i2c_set_host_watermarks()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_set_host_watermarks	(	const dif_i2c_t *	i2c,
		dif_i2c_level_t	rx_level,
		dif_i2c_level_t	fmt_level )

Sets watermarks for the RX and FMT FIFOs, which will assert the corresponding interrupts whenever the levels in the FIFOs are above (RX) and below (FMT) the set levels.

Parameters

i2c	An I2C handle.
rx_level	The desired watermark level for the RX FIFO.
fmt_level	The desired watermark level for the FMT FIFO.

Returns: The result of the operation.

Definition at line 340 of file dif_i2c.c.

◆ dif_i2c_set_target_watermarks()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_set_target_watermarks	(	const dif_i2c_t *	i2c,
		dif_i2c_level_t	tx_level,
		dif_i2c_level_t	acq_level )

Sets watermarks for the TX and ACQ FIFOs, which will assert the corresponding interrupts whenever the levels in the FIFOs are below (TX) and above (ACQ) the set levels.

Parameters

i2c	An I2C handle.
tx_level	The desired watermark level for the TX FIFO.
acq_level	The desired watermark level for the ACQ FIFO.

Returns: The result of the operation.

Definition at line 363 of file dif_i2c.c.

◆ dif_i2c_target_tx_stretch_ctrl_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_target_tx_stretch_ctrl_set_enabled	(	const dif_i2c_t *	i2c,
		dif_toggle_t	state )

Enables or disables the target FSM's stretch control for the start of read transactions.

This function should be called prior to enabling the target.

Parameters

i2c	An I2C handle.
state	The new toggle state for the device functionality.

Returns: The result of the operation.

Definition at line 495 of file dif_i2c.c.

◆ dif_i2c_transmit_byte()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_transmit_byte	(	const dif_i2c_t *	i2c,
		uint8_t	byte )

Pushes a byte into the TX FIFO to make it available when this I2C block responds to an I2C Read as a target device.

Parameters

i2c	handle.
byte	to write to FIFO

Returns: The result of the operation.

Definition at line 785 of file dif_i2c.c.

◆ dif_i2c_write_byte()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_write_byte	(	const dif_i2c_t *	i2c,
		uint8_t	byte,
		dif_i2c_fmt_t	code,
		bool	suppress_nak_irq )

Pushes a write entry onto the FMT FIFO, consisting of a byte and a format code.

This function can be called in sequence to enqueue an I2C transmission.

Parameters

i2c	An I2C handle.
byte	The value to push onto the FIFO.
code	The code to use for this write.
suppress_nak_irq	Whether to supress the NAK IRQ for this one byte. May not be used in combination with `Rx` codes.

Returns: The result of the operation.

Definition at line 738 of file dif_i2c.c.

◆ dif_i2c_write_byte_raw()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_write_byte_raw	(	const dif_i2c_t *	i2c,
		uint8_t	byte,
		dif_i2c_fmt_flags_t	flags )

Pushes a raw write entry onto the FMT FIFO, consisting of a byte and format flags.

This function can be called in sequence to enqueue an I2C transmission.

Callers should prefer dif_i2c_write_byte() instead, since that function provides clearer semantics. This function should only really be used for testing or troubleshooting a device.

Parameters

i2c	An I2C handle.
byte	The value to push onto the FIFO.
flags	The flags to use for this write.

Returns: The result of the operation.

Definition at line 724 of file dif_i2c.c.

◆ dif_i2c_write_bytes_raw()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_write_bytes_raw	(	const dif_i2c_t *	i2c,
		size_t	size,
		const uint8_t *	bytes,
		dif_i2c_fmt_flags_t	flags )

Writes a chunk of raw bytes and format flags onto the FMT FIFO.

Parameters

i2c	An I2C handle.
size	The number of bytes to push onto the FIFO.
bytes	Buffer with the values to push onto the FIFO.
flags	The format flags to use for this write.

Returns: The result of the operation.

Definition at line 705 of file dif_i2c.c.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_i2c_timing_config

◆ dif_i2c_id

◆ dif_i2c_config

◆ dif_i2c_fmt_flags

◆ dif_i2c_status

◆ dif_i2c_controller_halt_events

◆ dif_i2c_target_tx_halt_events

Typedef Documentation

◆ dif_i2c_config_t

◆ dif_i2c_fmt_t

◆ dif_i2c_id_t

◆ dif_i2c_level_t

◆ dif_i2c_timing_config_t

Enumeration Type Documentation

◆ anonymous enum

◆ dif_i2c_fmt

◆ dif_i2c_scl_timeout

◆ dif_i2c_signal

◆ dif_i2c_speed

Function Documentation

◆ dif_i2c_ack_ctrl_set_enabled()

◆ dif_i2c_acquire_byte()

◆ dif_i2c_addr_nack_set_enabled()

◆ dif_i2c_clear_controller_halt_events()

◆ dif_i2c_clear_target_tx_halt_events()

◆ dif_i2c_compute_timing()

◆ dif_i2c_configure()

◆ dif_i2c_device_set_enabled()

◆ dif_i2c_enable_clock_timeout()

◆ dif_i2c_get_auto_ack_count()

◆ dif_i2c_get_controller_halt_events()

◆ dif_i2c_get_fifo_levels()

◆ dif_i2c_get_pending_acq_byte()

◆ dif_i2c_get_status()

◆ dif_i2c_get_target_tx_halt_events()

◆ dif_i2c_host_set_enabled()

◆ dif_i2c_line_loopback_set_enabled()

◆ dif_i2c_multi_controller_monitor_set_enabled()

◆ dif_i2c_nack_transaction()

◆ dif_i2c_override_drive_pins()

◆ dif_i2c_override_sample_pins()

◆ dif_i2c_override_set_enabled()

◆ dif_i2c_read_byte()

◆ dif_i2c_read_bytes()

◆ dif_i2c_reset_acq_fifo()

◆ dif_i2c_reset_fmt_fifo()

◆ dif_i2c_reset_rx_fifo()

◆ dif_i2c_reset_tx_fifo()

◆ dif_i2c_set_auto_ack_count()

◆ dif_i2c_set_device_id()

◆ dif_i2c_set_host_timeout()

◆ dif_i2c_set_host_watermarks()

◆ dif_i2c_set_target_watermarks()

◆ dif_i2c_target_tx_stretch_ctrl_set_enabled()

◆ dif_i2c_transmit_byte()

◆ dif_i2c_write_byte()

◆ dif_i2c_write_byte_raw()

◆ dif_i2c_write_bytes_raw()