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 enum dif_i2c_watermark_level | dif_i2c_level_t |
Represents a valid watermark 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_watermark_level { kDifI2cLevel1Byte = 0, kDifI2cLevel4Byte, kDifI2cLevel8Byte, kDifI2cLevel16Byte, kDifI2cLevel30Byte } |
Represents a valid watermark level for one of the I2C FIFOs. 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_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 fire the respective interrupts when each fifo exceeds, or falls below, the set level. 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, uint8_t *fmt_fifo_level, uint8_t *rx_fifo_level, uint8_t *tx_fifo_level, uint8_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_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_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... | |
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.
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 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. |
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.
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.
struct dif_i2c_fmt_flags |
Flags for a formatted I2C byte, used by the dif_i2c_write_byte_raw()
function.
struct dif_i2c_status |
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.
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.
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.
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.
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.
enum dif_i2c_signal |
The I2C Target device records the following signals with received data.
enum dif_i2c_speed |
Represents a valid watermark level for one of the I2C FIFOs.
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.
i2c | handle. | |
[out] | byte,Data | received in the transaction, Could be the address or junk |
[out] | signal,Signal | received in the transaction |
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.
timing_config | Configuration values for producing timing parameters. | |
[out] | config | I2C configuration to which to apply the computed parameters. |
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_configure | ( | const dif_i2c_t * | i2c, |
dif_i2c_config_t | config | ||
) |
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.
i2c | An I2C handle. |
state | The new toggle state for the device functionality. |
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 | ||
) |
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_get_fifo_levels | ( | const dif_i2c_t * | i2c, |
uint8_t * | fmt_fifo_level, | ||
uint8_t * | rx_fifo_level, | ||
uint8_t * | tx_fifo_level, | ||
uint8_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.
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 . |
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_get_status | ( | const dif_i2c_t * | i2c, |
dif_i2c_status_t * | status | ||
) |
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.
i2c | An I2C handle. |
state | The new toggle state for the host functionality. |
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.
i2c | An I2C handle. |
state | The new toggle state for the host functionality. |
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_override_drive_pins | ( | const dif_i2c_t * | i2c, |
bool | scl, | ||
bool | sda | ||
) |
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.
i2c | An I2C handle. | |
[out] | scl_samples | SCL sample bits; may be NULL . |
[out] | sda_samples | SDA sample bits; may be NULL . |
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()
.
i2c | An I2C handle. |
state | The new toggle state for override mode.' |
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_read_byte | ( | const dif_i2c_t * | i2c, |
uint8_t * | byte | ||
) |
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_reset_acq_fifo | ( | const dif_i2c_t * | i2c | ) |
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_reset_fmt_fifo | ( | const dif_i2c_t * | i2c | ) |
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_reset_rx_fifo | ( | const dif_i2c_t * | i2c | ) |
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_reset_tx_fifo | ( | const dif_i2c_t * | i2c | ) |
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 | ||
) |
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_set_host_timeout | ( | const dif_i2c_t * | i2c, |
uint32_t | duration | ||
) |
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_set_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 fire the respective interrupts when each fifo exceeds, or falls below, the set level.
Note that the 30-byte level is only supported for the RX FIFO: trying to use it with the FMT FIFO is an error.
i2c | An I2C handle. |
rx_level | The desired watermark level for the RX FIFO. |
fmt_level | The desired watermark level for the FMT FIFO. |
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_transmit_byte | ( | const dif_i2c_t * | i2c, |
uint8_t | 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.
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. |
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.
i2c | An I2C handle. |
byte | The value to push onto the FIFO. |
flags | The flags to use for this write. |