Software APIs
Data Structures | Typedefs | Enumerations | Functions
dif_i2c.h File Reference

(be90e39)

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"

Go to the source code of this file.

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...
 

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. More...
 
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. More...
 
typedef struct dif_i2c_config dif_i2c_config_t
 Runtime configuration for I2C. More...
 
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(). More...
 
typedef struct dif_i2c_status dif_i2c_status_t
 Flags representing the status of an I2C block.
 

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  dif_i2c_signal {
  kDifI2cSignalStart = 1,
  kDifI2cSignalStop = 2,
  kDifI2cSignalRepeat = 3,
  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...
 

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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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". More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_enable_clock_stretching_timeout (const dif_i2c_t *i2c, dif_toggle_t enable, uint32_t cycles)
 Enables clock stretching timeout after a number of I2C block clock cycles when I2C block is configured as host. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_set_device_id (const dif_i2c_t *i2c, dif_i2c_id_t *id0, dif_i2c_id_t *id1)
 Sets the I2C device to listen for a pair of masked addresses. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_set_host_timeout (const dif_i2c_t *i2c, uint32_t duration)
 Set host timeout. More...
 

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 55 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 98 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 127 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 153 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 (surfaced as the kDifi2cIrqNak 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 274 of file dif_i2c.h.

Data Fields
bool acq_fifo_empty Aquire FIFO is empty and will remain so until I2C Device recieves 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.

Typedef Documentation

◆ 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_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

◆ 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 223 of file dif_i2c.h.

◆ 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.

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.

Definition at line 191 of file dif_i2c.h.

◆ 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_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
i2chandle.
[out]byte,Datareceived in the transaction, Could be the address or junk
[out]signal,Signalreceived in the transaction
Returns
The result of the operation.

Definition at line 592 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_configConfiguration values for producing timing parameters.
[out]configI2C configuration to which to apply the computed parameters.
Returns
The result of the operation.

Definition at line 114 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
i2cAn I2C handle.
configRuntime configuration parameters.
Returns
The result of the operation.

Definition at line 168 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
i2cAn I2C handle.
stateThe new toggle state for the device functionality.
Returns
The result of the operation.

Definition at line 323 of file dif_i2c.c.

◆ dif_i2c_enable_clock_stretching_timeout()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_enable_clock_stretching_timeout ( const dif_i2c_t i2c,
dif_toggle_t  enable,
uint32_t  cycles 
)

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

Parameters
i2cAn I2C handle,
enablethe timeout
cyclesHow many cycles to wait before timing out
Returns
The result of the operation.

Definition at line 609 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
i2cAn I2C handle.
[out]fmt_fifo_levelThe number of unsent FMT bytes; may be NULL.
[out]rx_fifo_levelThe number of unread RX bytes; may be NULL.
[out]tx_fifo_levelThe number of unread TX bytes; may be NULL.
[out]acq_fifo_levelThe number of unread ACQ bytes; may be NULL.
Returns
The result of the operation.

Definition at line 412 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
i2cAn I2C handle.
[out]statusI2C 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_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
i2cAn I2C handle.
stateThe new toggle state for the host functionality.
Returns
The result of the operation.

Definition at line 305 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
i2cAn I2C handle.
stateThe new toggle state for the host functionality.
Returns
The result of the operation.

Definition at line 341 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
i2cAn I2C handle.
sclThe value to drive SCL to.
sdaThe value to drive SDA to.
Returns
The result of the operation.

Definition at line 376 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
i2cAn I2C handle.
[out]scl_samplesSCL sample bits; may be NULL.
[out]sda_samplesSDA sample bits; may be NULL.
Returns
The result of the operation.

Definition at line 391 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
i2cAn I2C handle.
stateThe new toggle state for override mode.'
Returns
The result of the operation.

Definition at line 358 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
i2cAn I2C handle.
[out]byteThe popped byte; may be NULL.
Returns
The result of the operation.

Definition at line 448 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
i2cAn I2C handle.
[out]sizeThe size of the buffer.
[out]bufferA buffer to receive the bytes read.
Returns
The result of the operation.

Definition at line 461 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
i2cAn I2c handle.
Returns
The result of the operation.

Definition at line 247 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
i2cAn I2c handle.
Returns
The result of the operation.

Definition at line 223 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
i2cAn I2c handle.
Returns
The result of the operation.

Definition at line 211 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
i2cAn I2c handle.
Returns
The result of the operation.

Definition at line 235 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,
dif_i2c_id_t id0,
dif_i2c_id_t id1 
)

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

Parameters
i2chandle,
id0address and mask pair to listen for can be null
id1address and mask pair to listen for can be null
Returns
The result of the operation.

Definition at line 628 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
i2chandle,
durationin clock counts
Returns
The result of the operation.

Definition at line 659 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
i2cAn I2C handle.
rx_levelThe desired watermark level for the RX FIFO.
fmt_levelThe desired watermark level for the FMT FIFO.
Returns
The result of the operation.

Definition at line 259 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
i2cAn I2C handle.
tx_levelThe desired watermark level for the TX FIFO.
acq_levelThe desired watermark level for the ACQ FIFO.
Returns
The result of the operation.

Definition at line 282 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
i2chandle.
byteto write to FIFO
Returns
The result of the operation.

Definition at line 580 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
i2cAn I2C handle.
byteThe value to push onto the FIFO.
codeThe code to use for this write.
suppress_nak_irqWhether 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 533 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
i2cAn I2C handle.
byteThe value to push onto the FIFO.
flagsThe flags to use for this write.
Returns
The result of the operation.

Definition at line 519 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
i2cAn I2C handle.
sizeThe number of bytes to push onto the FIFO.
bytesBuffer with the values to push onto the FIFO.
flagsThe format flags to use for this write.
Returns
The result of the operation.

Definition at line 500 of file dif_i2c.c.