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

(dcee03a)

I2C Device Interface Functions More...

#include <stdbool.h>
#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_warn_unused_result.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_params
 Hardware instantiation parameters for I2C. More...
 
struct  dif_i2c_config
 Runtime configuration for I2C. More...
 
struct  dif_i2c
 A handle to I2C. More...
 
struct  dif_i2c_fmt_flags
 Flags for a formatted I2C byte, used by the dif_i2c_write_byte_raw() function. More...
 

Typedefs

typedef enum dif_i2c_toggle dif_i2c_toggle_t
 A toggle state: enabled, or disabled. More...
 
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_params dif_i2c_params_t
 Hardware instantiation parameters for I2C. More...
 
typedef struct dif_i2c_config dif_i2c_config_t
 Runtime configuration for I2C. More...
 
typedef struct dif_i2c dif_i2c_t
 A handle to I2C. More...
 
typedef enum dif_i2c_result dif_i2c_result_t
 The result of a I2C operation.
 
typedef enum dif_i2c_irq dif_i2c_irq_t
 Represents an I2C-related interrupt type.
 
typedef uint32_t dif_i2c_irq_snapshot_t
 A snapshot of the entablement state of the interrupts 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_fmt dif_i2c_fmt_t
 Available formatting codes for dif_i2c_write_byte_raw(). More...
 

Enumerations

enum  dif_i2c_toggle {
  kDifI2cToggleEnabled,
  kDifI2cToggleDisabled
}
 A toggle state: enabled, or disabled. More...
 
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_result {
  kDifI2cOk = 0,
  kDifI2cError = 1,
  kDifI2cBadArg = 2
}
 The result of a I2C operation. More...
 
enum  dif_i2c_irq {
  kDifI2cIrqFmtWatermarkUnderflow = 0,
  kDifI2cIrqRxWatermarkOverflow,
  kDifI2cIrqFmtFifoOverflow,
  kDifI2cIrqRxFifoOverflow,
  kDifI2cIrqNak,
  kDifI2cIrqSclInterference,
  kDifI2cIrqSdaInterference,
  kDifI2cIrqClockStretchTimeout,
  kDifI2cIrqSdaUnstable
}
 Represents an I2C-related interrupt type. 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_fmt {
  kDifI2cFmtStart,
  kDifI2cFmtTx,
  kDifI2cFmtTxStop,
  kDifI2cFmtRx,
  kDifI2cFmtRxContinue,
  kDifI2cFmtRxStop
}
 Available formatting codes for dif_i2c_write_byte_raw(). More...
 

Functions

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_compute_timing (dif_i2c_timing_config_t timing_config, dif_i2c_config_t *config)
 Computes timing parameters for an I2C device and stores them in config. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_init (dif_i2c_params_t params, dif_i2c_t *i2c)
 Creates a new handle for I2C. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_configure (const dif_i2c_t *i2c, dif_i2c_config_t config)
 Configures I2C with runtime information. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_is_pending (const dif_i2c_t *i2c, dif_i2c_irq_t irq, bool *is_pending)
 Returns whether a particular interrupt is currently pending. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_acknowledge (const dif_i2c_t *i2c, dif_i2c_irq_t irq)
 Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_get_enabled (const dif_i2c_t *i2c, dif_i2c_irq_t irq, dif_i2c_toggle_t *state)
 Checks whether a particular interrupt is currently enabled or disabled. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_set_enabled (const dif_i2c_t *i2c, dif_i2c_irq_t irq, dif_i2c_toggle_t state)
 Sets whether a particular interrupt is currently enabled or disabled. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_force (const dif_i2c_t *i2c, dif_i2c_irq_t irq)
 Forces a particular interrupt, causing it to be serviced as if hardware had asserted it. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_disable_all (const dif_i2c_t *i2c, dif_i2c_irq_snapshot_t *snapshot)
 Disables all interrupts, optionally snapshotting all toggle state for later restoration. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_restore_all (const dif_i2c_t *i2c, const dif_i2c_irq_snapshot_t *snapshot)
 Restores interrupts from the given snapshot. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_reset_rx_fifo (const dif_i2c_t *i2c)
 Resets the state of the RX FIFO, essentially dropping all received bytes. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_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...
 
DIF_WARN_UNUSED_RESULT dif_i2c_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 for the RX and FMT FIFOs, which will fire the respective interrupts when each fifo exceeds, or falls below, the set level. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_host_set_enabled (const dif_i2c_t *i2c, dif_i2c_toggle_t state)
 Enables or disables the "Host I2C" functionality, effectively turning the I2C device on or off. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_override_set_enabled (const dif_i2c_t *i2c, dif_i2c_toggle_t state)
 Enables or disables the "override mode". More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_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...
 
DIF_WARN_UNUSED_RESULT dif_i2c_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...
 
DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_get_fifo_levels (const dif_i2c_t *i2c, uint8_t *fmt_fifo_level, uint8_t *rx_fifo_level)
 Returns the current levels, i.e., number of entries, in the FMT and RX FIFOs. More...
 
DIF_WARN_UNUSED_RESULT dif_i2c_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...
 
DIF_WARN_UNUSED_RESULT dif_i2c_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...
 
DIF_WARN_UNUSED_RESULT dif_i2c_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...
 

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 69 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_params

struct dif_i2c_params

Hardware instantiation parameters for I2C.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

Definition at line 114 of file dif_i2c.h.

Data Fields
mmio_region_t base_addr The base address for the I2C hardware registers.

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

struct dif_i2c

A handle to I2C.

This type should be treated as opaque by users.

Definition at line 155 of file dif_i2c.h.

Data Fields
dif_i2c_params_t params

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

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_irq_snapshot_t

typedef uint32_t dif_i2c_irq_snapshot_t

A snapshot of the entablement state of the interrupts for I2C.

This is an opaque type, to be used with the dif_i2c_irq_disable_all() and dif_i2c_irq_restore_all() functions.

Definition at line 226 of file dif_i2c.h.

◆ dif_i2c_params_t

Hardware instantiation parameters for I2C.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

◆ dif_i2c_t

typedef struct dif_i2c dif_i2c_t

A handle to I2C.

This type should be treated as opaque by users.

◆ 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()

◆ dif_i2c_toggle_t

A toggle state: enabled, or disabled.

This enum may be used instead of a bool when describing an enabled/disabled state.

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

◆ dif_i2c_irq

Represents an I2C-related interrupt type.

Enumerator
kDifI2cIrqFmtWatermarkUnderflow 

Fired when the FMT FIFO underflows its watermark.

kDifI2cIrqRxWatermarkOverflow 

Fired when the RX FIFO overflows its watermark.

kDifI2cIrqFmtFifoOverflow 

Fired when the FMT FIFO overflows.

kDifI2cIrqRxFifoOverflow 

Fired when the RX FIFO overflows.

kDifI2cIrqNak 

Fired when there is no ACK in response to an address or data write.

kDifI2cIrqSclInterference 

Fired when the SCL line seems to have interference.

kDifI2cIrqSdaInterference 

Fired when the SDA line seems to have interference.

kDifI2cIrqClockStretchTimeout 

Fired when the target stretches the clock beyond the allowed period.

kDifI2cIrqSdaUnstable 

Fired when the target does not maintain a stable SDA line.

Definition at line 181 of file dif_i2c.h.

◆ dif_i2c_result

The result of a I2C operation.

Enumerator
kDifI2cOk 

Indicates that the operation succeeded.

kDifI2cError 

Indicates some unspecified failure.

kDifI2cBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

Definition at line 160 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 45 of file dif_i2c.h.

◆ dif_i2c_toggle

A toggle state: enabled, or disabled.

This enum may be used instead of a bool when describing an enabled/disabled state.

Enumerator
kDifI2cToggleDisabled 

The "disabled" state.

Definition at line 29 of file dif_i2c.h.

◆ dif_i2c_watermark_level

Represents a valid watermark level for one of the I2C FIFOs.

Enumerator
kDifI2cLevel1Byte 

A one-byte watermark.

kDifI2cLevel4Byte 

A four-byte watermark.

kDifI2cLevel8Byte 

An eight-byte watermark.

kDifI2cLevel16Byte 

A sixteen-byte watermark.

kDifI2cLevel30Byte 

A thirty-byte watermark.

Note that this watermark is only supported for RX, and not for FMT.

Definition at line 231 of file dif_i2c.h.

Function Documentation

◆ dif_i2c_compute_timing()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_compute_timing ( dif_i2c_timing_config_t  timing_config,
dif_i2c_config_t config 
)

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

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 77 of file dif_i2c.c.

◆ dif_i2c_configure()

DIF_WARN_UNUSED_RESULT dif_i2c_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 138 of file dif_i2c.c.

◆ dif_i2c_get_fifo_levels()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_get_fifo_levels ( const dif_i2c_t i2c,
uint8_t *  fmt_fifo_level,
uint8_t *  rx_fifo_level 
)

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

These values represent the number of entries pending for send by hardware, and entries pending for read by 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.
Returns
The result of the operation.

Definition at line 518 of file dif_i2c.c.

◆ dif_i2c_host_set_enabled()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_host_set_enabled ( const dif_i2c_t i2c,
dif_i2c_toggle_t  state 
)

Enables or disables the "Host I2C" functionality, effectively turning the I2C device on or off.

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 433 of file dif_i2c.c.

◆ dif_i2c_init()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_init ( dif_i2c_params_t  params,
dif_i2c_t i2c 
)

Creates a new handle for I2C.

This function does not actuate the hardware.

Parameters
paramsHardware instantiation parameters.
[out]i2cOut param for the initialized handle.
Returns
The result of the operation.

Definition at line 128 of file dif_i2c.c.

◆ dif_i2c_irq_acknowledge()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_acknowledge ( const dif_i2c_t i2c,
dif_i2c_irq_t  irq 
)

Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced.

Parameters
i2cAn I2C handle.
irqAn interrupt type.
Returns
The result of the operation.

Definition at line 320 of file dif_i2c.c.

◆ dif_i2c_irq_disable_all()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_disable_all ( const dif_i2c_t i2c,
dif_i2c_irq_snapshot_t snapshot 
)

Disables all interrupts, optionally snapshotting all toggle state for later restoration.

Parameters
i2cAn I2C handle.
[out]snapshotOut-param for the snapshot; may be NULL.
Returns
The result of the operation.

Definition at line 405 of file dif_i2c.c.

◆ dif_i2c_irq_force()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_force ( const dif_i2c_t i2c,
dif_i2c_irq_t  irq 
)

Forces a particular interrupt, causing it to be serviced as if hardware had asserted it.

Parameters
i2cAn I2C handle.
irqAn interrupt type.
Returns
The result of the operation.

Definition at line 389 of file dif_i2c.c.

◆ dif_i2c_irq_get_enabled()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_get_enabled ( const dif_i2c_t i2c,
dif_i2c_irq_t  irq,
dif_i2c_toggle_t state 
)

Checks whether a particular interrupt is currently enabled or disabled.

Parameters
i2cAn I2C handle.
irqAn interrupt type.
[out]stateOut-param toggle state of the interrupt.
Returns
The result of the operation.

Definition at line 337 of file dif_i2c.c.

◆ dif_i2c_irq_is_pending()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_is_pending ( const dif_i2c_t i2c,
dif_i2c_irq_t  irq,
bool *  is_pending 
)

Returns whether a particular interrupt is currently pending.

Parameters
i2cAn I2C handle.
irqAn interrupt type.
[out]is_pendingOut-param for whether the interrupt is pending.
Returns
The result of the operation.

Definition at line 302 of file dif_i2c.c.

◆ dif_i2c_irq_restore_all()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_restore_all ( const dif_i2c_t i2c,
const dif_i2c_irq_snapshot_t snapshot 
)

Restores interrupts from the given snapshot.

This function can be used with dif_i2c_irq_disable_all() to temporary interrupt save-and-restore.

Parameters
i2cAn I2C handle.
snapshotA snapshot to restore from.
Returns
The result of the operation.

Definition at line 421 of file dif_i2c.c.

◆ dif_i2c_irq_set_enabled()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_irq_set_enabled ( const dif_i2c_t i2c,
dif_i2c_irq_t  irq,
dif_i2c_toggle_t  state 
)

Sets whether a particular interrupt is currently enabled or disabled.

Parameters
i2cAn I2C handle.
irqAn interrupt type.
stateThe new toggle state for the interrupt.
Returns
The result of the operation.

Definition at line 357 of file dif_i2c.c.

◆ dif_i2c_override_drive_pins()

DIF_WARN_UNUSED_RESULT dif_i2c_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 483 of file dif_i2c.c.

◆ dif_i2c_override_sample_pins()

DIF_WARN_UNUSED_RESULT dif_i2c_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 498 of file dif_i2c.c.

◆ dif_i2c_override_set_enabled()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_override_set_enabled ( const dif_i2c_t i2c,
dif_i2c_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 458 of file dif_i2c.c.

◆ dif_i2c_read_byte()

DIF_WARN_UNUSED_RESULT dif_i2c_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 538 of file dif_i2c.c.

◆ dif_i2c_reset_fmt_fifo()

DIF_WARN_UNUSED_RESULT dif_i2c_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 195 of file dif_i2c.c.

◆ dif_i2c_reset_rx_fifo()

DIF_WARN_UNUSED_RESULT dif_i2c_result_t dif_i2c_reset_rx_fifo ( const dif_i2c_t i2c)

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

Parameters
i2cAn I2c handle.
Returns
The result of the operation.

Definition at line 182 of file dif_i2c.c.

◆ dif_i2c_set_watermarks()

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

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 208 of file dif_i2c.c.

◆ dif_i2c_write_byte()

DIF_WARN_UNUSED_RESULT dif_i2c_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 583 of file dif_i2c.c.

◆ dif_i2c_write_byte_raw()

DIF_WARN_UNUSED_RESULT dif_i2c_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 552 of file dif_i2c.c.