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

(a649ec5)

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"

Go to the source code of this file.

Data Structures

struct  dif_i2c
 A handle to i2c. More...
 

Typedefs

typedef struct dif_i2c dif_i2c_t
 A handle to i2c. More...
 
typedef enum dif_i2c_alert dif_i2c_alert_t
 A i2c alert type.
 
typedef enum dif_i2c_irq dif_i2c_irq_t
 A i2c interrupt request type.
 
typedef uint32_t dif_i2c_irq_state_snapshot_t
 A snapshot of the state of the interrupts for this IP. More...
 
typedef uint32_t dif_i2c_irq_enable_snapshot_t
 A snapshot of the enablement state of the interrupts for this IP. More...
 

Enumerations

enum  dif_i2c_alert { kDifI2cAlertFatalFault = 0 }
 A i2c alert type. More...
 
enum  dif_i2c_irq {
  kDifI2cIrqFmtThreshold = 0,
  kDifI2cIrqRxThreshold = 1,
  kDifI2cIrqAcqThreshold = 2,
  kDifI2cIrqRxOverflow = 3,
  kDifI2cIrqControllerHalt = 4,
  kDifI2cIrqSclInterference = 5,
  kDifI2cIrqSdaInterference = 6,
  kDifI2cIrqStretchTimeout = 7,
  kDifI2cIrqSdaUnstable = 8,
  kDifI2cIrqCmdComplete = 9,
  kDifI2cIrqTxStretch = 10,
  kDifI2cIrqTxThreshold = 11,
  kDifI2cIrqAcqStretch = 12,
  kDifI2cIrqUnexpStop = 13,
  kDifI2cIrqHostTimeout = 14
}
 A i2c interrupt request type. More...
 

Functions

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_init (mmio_region_t base_addr, dif_i2c_t *i2c)
 Creates a new handle for a(n) i2c peripheral. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_alert_force (const dif_i2c_t *i2c, dif_i2c_alert_t alert)
 Forces a particular alert, causing it to be escalated as if the hardware had raised it. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_get_type (const dif_i2c_t *i2c, dif_i2c_irq_t irq, dif_irq_type_t *type)
 Returns the type of a given interrupt (i.e., event or status) for this IP. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_get_state (const dif_i2c_t *i2c, dif_i2c_irq_state_snapshot_t *snapshot)
 Returns the state of all interrupts (i.e., pending or not) for this IP. More...
 
OT_WARN_UNUSED_RESULT dif_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...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_acknowledge_state (const dif_i2c_t *i2c, dif_i2c_irq_state_snapshot_t snapshot)
 Acknowledges all interrupts that were pending at the time of the state snapshot. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_acknowledge_all (const dif_i2c_t *i2c)
 Acknowledges all interrupts, indicating to the hardware that all interrupts have been successfully serviced. More...
 
OT_WARN_UNUSED_RESULT dif_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...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_force (const dif_i2c_t *i2c, dif_i2c_irq_t irq, const bool val)
 Forces a particular interrupt, causing it to be serviced as if hardware had asserted it. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_get_enabled (const dif_i2c_t *i2c, dif_i2c_irq_t irq, dif_toggle_t *state)
 Checks whether a particular interrupt is currently enabled or disabled. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_set_enabled (const dif_i2c_t *i2c, dif_i2c_irq_t irq, dif_toggle_t state)
 Sets whether a particular interrupt is currently enabled or disabled. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_disable_all (const dif_i2c_t *i2c, dif_i2c_irq_enable_snapshot_t *snapshot)
 Disables all interrupts, optionally snapshotting all enable states for later restoration. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_restore_all (const dif_i2c_t *i2c, const dif_i2c_irq_enable_snapshot_t *snapshot)
 Restores interrupts from the given (enable) snapshot. More...
 

Detailed Description

I2C Device Interface Functions

Definition in file dif_i2c_autogen.h.


Data Structure Documentation

◆ dif_i2c

struct dif_i2c

A handle to i2c.

This type should be treated as opaque by users.

Definition at line 32 of file dif_i2c_autogen.h.

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

Typedef Documentation

◆ dif_i2c_irq_enable_snapshot_t

A snapshot of the enablement state of the interrupts for this IP.

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 253 of file dif_i2c_autogen.h.

◆ dif_i2c_irq_state_snapshot_t

typedef uint32_t dif_i2c_irq_state_snapshot_t

A snapshot of the state of the interrupts for this IP.

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

Definition at line 163 of file dif_i2c_autogen.h.

◆ dif_i2c_t

typedef struct dif_i2c dif_i2c_t

A handle to i2c.

This type should be treated as opaque by users.

Enumeration Type Documentation

◆ dif_i2c_alert

A i2c alert type.

Enumerator
kDifI2cAlertFatalFault 

This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.

Definition at line 54 of file dif_i2c_autogen.h.

◆ dif_i2c_irq

A i2c interrupt request type.

Enumerator
kDifI2cIrqFmtThreshold 

Host mode interrupt: asserted whilst the FMT FIFO level is below the low threshold.

This is a level status interrupt.

kDifI2cIrqRxThreshold 

Host mode interrupt: asserted whilst the RX FIFO level is above the high threshold.

This is a level status interrupt.

kDifI2cIrqAcqThreshold 

Target mode interrupt: asserted whilst the ACQ FIFO level is above the high threshold.

This is a level status interrupt.

kDifI2cIrqRxOverflow 

Host mode interrupt: raised if the RX FIFO has overflowed.

kDifI2cIrqControllerHalt 

Host mode interrupt: raised if the controller FSM is halted, such as on an unexpected NACK or lost arbitration.

Check !!CONTROLLER_EVENTS for the reason. The interrupt will be released when the bits in !!CONTROLLER_EVENTS are cleared.

kDifI2cIrqSclInterference 

Host mode interrupt: raised if the SCL line drops early (not supported without clock synchronization).

kDifI2cIrqSdaInterference 

Host mode interrupt: raised if the SDA line goes low when host is trying to assert high.

kDifI2cIrqStretchTimeout 

Host mode interrupt: raised if target stretches the clock beyond the allowed timeout period.

kDifI2cIrqSdaUnstable 

Host mode interrupt: raised if the target does not assert a constant value of SDA during transmission.

kDifI2cIrqCmdComplete 

Host and target mode interrupt.

In host mode, raised if the host issues a repeated START or terminates the transaction by issuing STOP. In target mode, raised if the external host issues a STOP or repeated START.

kDifI2cIrqTxStretch 

Target mode interrupt: raised if the target is stretching clocks for a read command.

This is a level status interrupt.

kDifI2cIrqTxThreshold 

Target mode interrupt: asserted whilst the TX FIFO level is below the low threshold.

This is a level status interrupt.

kDifI2cIrqAcqStretch 

Target mode interrupt: raised if the target is stretching clocks due to full ACQ FIFO or zero count in !!TARGET_ACK_CTRL.NBYTES (if enabled).

This is a level status interrupt.

kDifI2cIrqUnexpStop 

Target mode interrupt: raised if STOP is received without a preceding NACK during an external host read.

kDifI2cIrqHostTimeout 

Target mode interrupt: raised if the host stops sending the clock during an ongoing transaction.

Definition at line 76 of file dif_i2c_autogen.h.

Function Documentation

◆ dif_i2c_alert_force()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_alert_force ( const dif_i2c_t i2c,
dif_i2c_alert_t  alert 
)

Forces a particular alert, causing it to be escalated as if the hardware had raised it.

Parameters
i2cA i2c handle.
alertThe alert to force.
Returns
The result of the operation.

Definition at line 27 of file dif_i2c_autogen.c.

◆ dif_i2c_init()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_init ( mmio_region_t  base_addr,
dif_i2c_t i2c 
)

Creates a new handle for a(n) i2c peripheral.

This function does not actuate the hardware.

Parameters
base_addrThe MMIO base address of the i2c peripheral.
[out]i2cOut param for the initialized handle.
Returns
The result of the operation.

Definition at line 17 of file dif_i2c_autogen.c.

◆ dif_i2c_irq_acknowledge()

OT_WARN_UNUSED_RESULT dif_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
i2cA i2c handle.
irqAn interrupt request.
Returns
The result of the operation.

Definition at line 185 of file dif_i2c_autogen.c.

◆ dif_i2c_irq_acknowledge_all()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_acknowledge_all ( const dif_i2c_t i2c)

Acknowledges all interrupts, indicating to the hardware that all interrupts have been successfully serviced.

Parameters
i2cA i2c handle.
Returns
The result of the operation.

Definition at line 172 of file dif_i2c_autogen.c.

◆ dif_i2c_irq_acknowledge_state()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_acknowledge_state ( const dif_i2c_t i2c,
dif_i2c_irq_state_snapshot_t  snapshot 
)

Acknowledges all interrupts that were pending at the time of the state snapshot.

Parameters
i2cA i2c handle.
snapshotInterrupt state snapshot.
Returns
The result of the operation.

Definition at line 139 of file dif_i2c_autogen.c.

◆ dif_i2c_irq_disable_all()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_disable_all ( const dif_i2c_t i2c,
dif_i2c_irq_enable_snapshot_t snapshot 
)

Disables all interrupts, optionally snapshotting all enable states for later restoration.

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

Definition at line 267 of file dif_i2c_autogen.c.

◆ dif_i2c_irq_force()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_force ( const dif_i2c_t i2c,
dif_i2c_irq_t  irq,
const bool  val 
)

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

Parameters
i2cA i2c handle.
irqAn interrupt request.
valValue to be set.
Returns
The result of the operation.

Definition at line 204 of file dif_i2c_autogen.c.

◆ dif_i2c_irq_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_get_enabled ( const dif_i2c_t i2c,
dif_i2c_irq_t  irq,
dif_toggle_t state 
)

Checks whether a particular interrupt is currently enabled or disabled.

Parameters
i2cA i2c handle.
irqAn interrupt request.
[out]stateOut-param toggle state of the interrupt.
Returns
The result of the operation.

Definition at line 223 of file dif_i2c_autogen.c.

◆ dif_i2c_irq_get_state()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_get_state ( const dif_i2c_t i2c,
dif_i2c_irq_state_snapshot_t snapshot 
)

Returns the state of all interrupts (i.e., pending or not) for this IP.

Parameters
i2cA i2c handle.
[out]snapshotOut-param for interrupt state snapshot.
Returns
The result of the operation.

Definition at line 126 of file dif_i2c_autogen.c.

◆ dif_i2c_irq_get_type()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_get_type ( const dif_i2c_t i2c,
dif_i2c_irq_t  irq,
dif_irq_type_t type 
)

Returns the type of a given interrupt (i.e., event or status) for this IP.

Parameters
i2cA i2c handle.
irqAn interrupt request.
[out]typeOut-param for the interrupt type.
Returns
The result of the operation.

Definition at line 114 of file dif_i2c_autogen.c.

◆ dif_i2c_irq_is_pending()

OT_WARN_UNUSED_RESULT dif_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
i2cA i2c handle.
irqAn interrupt request.
[out]is_pendingOut-param for whether the interrupt is pending.
Returns
The result of the operation.

Definition at line 152 of file dif_i2c_autogen.c.

◆ dif_i2c_irq_restore_all()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_restore_all ( const dif_i2c_t i2c,
const dif_i2c_irq_enable_snapshot_t snapshot 
)

Restores interrupts from the given (enable) snapshot.

Parameters
i2cA i2c handle.
snapshotA snapshot to restore from.
Returns
The result of the operation.

Definition at line 287 of file dif_i2c_autogen.c.

◆ dif_i2c_irq_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_irq_set_enabled ( const dif_i2c_t i2c,
dif_i2c_irq_t  irq,
dif_toggle_t  state 
)

Sets whether a particular interrupt is currently enabled or disabled.

Parameters
i2cA i2c handle.
irqAn interrupt request.
stateThe new toggle state for the interrupt.
Returns
The result of the operation.

Definition at line 244 of file dif_i2c_autogen.c.