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 "hw/top/dt/dt_i2c.h"

Go to the source code of this file.

Data Structures
struct	dif_i2c
	A handle to i2c. More...

Macros
#define	kDifI2cIrqFmtThreshold kDtI2cIrqFmtThreshold
	A i2c interrupt request type.

#define	kDifI2cIrqRxThreshold kDtI2cIrqRxThreshold
	Host mode interrupt: asserted whilst the RX FIFO level is above the high threshold.

#define	kDifI2cIrqAcqThreshold kDtI2cIrqAcqThreshold
	Target mode interrupt: asserted whilst the ACQ FIFO level is above the high threshold.

#define	kDifI2cIrqRxOverflow kDtI2cIrqRxOverflow
	Host mode interrupt: raised if the RX FIFO has overflowed.

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

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

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

#define	kDifI2cIrqStretchTimeout kDtI2cIrqStretchTimeout
	Host mode interrupt: raised if target stretches the clock beyond the allowed timeout period.

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

#define	kDifI2cIrqCmdComplete kDtI2cIrqCmdComplete
	Host and target mode interrupt.

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

#define	kDifI2cIrqTxThreshold kDtI2cIrqTxThreshold
	Target mode interrupt: asserted whilst the TX FIFO level is below the low threshold.

#define	kDifI2cIrqAcqStretch kDtI2cIrqAcqStretch
	Target mode interrupt: raised if the target is stretching clocks due to full ACQ FIFO or zero count in !

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

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

Typedefs
typedef struct dif_i2c	dif_i2c_t
	A handle to i2c.

typedef enum dif_i2c_alert	dif_i2c_alert_t
	A i2c alert type.

typedef dt_i2c_irq_t	dif_i2c_irq_t

typedef uint32_t	dif_i2c_irq_state_snapshot_t
	A snapshot of the state of the interrupts for this IP.

typedef uint32_t	dif_i2c_irq_enable_snapshot_t
	A snapshot of the enablement state of the interrupts for this IP.

Enumerations
enum	dif_i2c_alert { kDifI2cAlertFatalFault = 0 }
	A i2c alert 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.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_init_from_dt (dt_i2c_t dt, dif_i2c_t *i2c)
	Creates a new handle for a(n) i2c peripheral.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_get_dt (const dif_i2c_t i2c, dt_i2c_t dt)
	Get the DT handle from this DIF.

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.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_irq_get_type (const dif_i2c_t i2c, dif_i2c_irq_t, dif_irq_type_t type)
	Returns the type of a given interrupt (i.e., event or status) for this IP.

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.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_irq_is_pending (const dif_i2c_t i2c, dif_i2c_irq_t, bool is_pending)
	Returns whether a particular interrupt is currently pending.

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.

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.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_irq_acknowledge (const dif_i2c_t *i2c, dif_i2c_irq_t)
	Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_irq_force (const dif_i2c_t *i2c, dif_i2c_irq_t, const bool val)
	Forces a particular interrupt, causing it to be serviced as if hardware had asserted it.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_irq_get_enabled (const dif_i2c_t i2c, dif_i2c_irq_t, dif_toggle_t state)
	Checks whether a particular interrupt is currently enabled or disabled.

OT_WARN_UNUSED_RESULT dif_result_t	dif_i2c_irq_set_enabled (const dif_i2c_t *i2c, dif_i2c_irq_t, dif_toggle_t state)
	Sets whether a particular interrupt is currently enabled or disabled.

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.

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.

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

Data Fields
mmio_region_t	base_addr	The base address for the i2c hardware registers.
dt_i2c_t	dt	The instance, set to `kDtI2cCount` if not initialized through `dif_i2c_init_from_dt`.

Macro Definition Documentation

◆ kDifI2cIrqAcqStretch

#define kDifI2cIrqAcqStretch kDtI2cIrqAcqStretch

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.

Definition at line 182 of file dif_i2c_autogen.h.

◆ kDifI2cIrqAcqThreshold

#define kDifI2cIrqAcqThreshold kDtI2cIrqAcqThreshold

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

This is a level status interrupt.

Definition at line 142 of file dif_i2c_autogen.h.

◆ kDifI2cIrqCmdComplete

#define kDifI2cIrqCmdComplete kDtI2cIrqCmdComplete

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.

Definition at line 170 of file dif_i2c_autogen.h.

◆ kDifI2cIrqControllerHalt

#define kDifI2cIrqControllerHalt kDtI2cIrqControllerHalt

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.

Definition at line 150 of file dif_i2c_autogen.h.

◆ kDifI2cIrqFmtThreshold

#define kDifI2cIrqFmtThreshold kDtI2cIrqFmtThreshold

A i2c interrupt request type.

DEPRECATED Use dt_i2c_irq_t instead. This enumeration exists solely for the transition to dt-based interrupt numbers and will be removed in the future.

The following are defines to keep the types consistent with DT. Host mode interrupt: asserted whilst the FMT FIFO level is below the low threshold. This is a level status interrupt.

Definition at line 134 of file dif_i2c_autogen.h.

◆ kDifI2cIrqHostTimeout

#define kDifI2cIrqHostTimeout kDtI2cIrqHostTimeout

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

Definition at line 190 of file dif_i2c_autogen.h.

◆ kDifI2cIrqRxOverflow

#define kDifI2cIrqRxOverflow kDtI2cIrqRxOverflow

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

Definition at line 146 of file dif_i2c_autogen.h.

◆ kDifI2cIrqRxThreshold

#define kDifI2cIrqRxThreshold kDtI2cIrqRxThreshold

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

This is a level status interrupt.

Definition at line 138 of file dif_i2c_autogen.h.

◆ kDifI2cIrqSclInterference

#define kDifI2cIrqSclInterference kDtI2cIrqSclInterference

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

Definition at line 154 of file dif_i2c_autogen.h.

◆ kDifI2cIrqSdaInterference

#define kDifI2cIrqSdaInterference kDtI2cIrqSdaInterference

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

Definition at line 158 of file dif_i2c_autogen.h.

◆ kDifI2cIrqSdaUnstable

#define kDifI2cIrqSdaUnstable kDtI2cIrqSdaUnstable

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

Definition at line 166 of file dif_i2c_autogen.h.

◆ kDifI2cIrqStretchTimeout

#define kDifI2cIrqStretchTimeout kDtI2cIrqStretchTimeout

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

Definition at line 162 of file dif_i2c_autogen.h.

◆ kDifI2cIrqTxStretch

#define kDifI2cIrqTxStretch kDtI2cIrqTxStretch

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

This is a level status interrupt.

Definition at line 174 of file dif_i2c_autogen.h.

◆ kDifI2cIrqTxThreshold

#define kDifI2cIrqTxThreshold kDtI2cIrqTxThreshold

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

This is a level status interrupt.

Definition at line 178 of file dif_i2c_autogen.h.

◆ kDifI2cIrqUnexpStop

#define kDifI2cIrqUnexpStop kDtI2cIrqUnexpStop

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

Definition at line 186 of file dif_i2c_autogen.h.

Typedef Documentation

◆ dif_i2c_irq_enable_snapshot_t

typedef uint32_t 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 300 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 198 of file dif_i2c_autogen.h.

◆ dif_i2c_irq_t

typedef dt_i2c_irq_t dif_i2c_irq_t

Definition at line 120 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

enum 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 98 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

i2c	A i2c handle.
alert	The alert to force.

Returns: The result of the operation.

Definition at line 62 of file dif_i2c_autogen.c.

◆ dif_i2c_get_dt()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_get_dt	(	const dif_i2c_t *	i2c,
		dt_i2c_t *	dt )

Get the DT handle from this DIF.

If this DIF was initialized by dif_i2c_init_from_dt(dt, ..) then this function will return dt. Otherwise it will return an error.

Parameters

	i2c	A i2c handle.
[out]	dt	DT handle.

Returns: kDifBadArg if the DIF has no DT information, kDifOk otherwise.

Definition at line 52 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_addr	The MMIO base address of the i2c peripheral.
[out]	i2c	Out param for the initialized handle.

Returns: The result of the operation.

DEPRECATED This function exists solely for the transition to dt-based DIFs and will be removed in the future.

Definition at line 25 of file dif_i2c_autogen.c.

◆ dif_i2c_init_from_dt()

OT_WARN_UNUSED_RESULT dif_result_t dif_i2c_init_from_dt	(	dt_i2c_t	dt,
		dif_i2c_t *	i2c )

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

This function does not actuate the hardware.

Parameters

	dt	The devicetable description of the device.
[out]	i2c	Out param for the initialized handle.

Returns: The result of the operation.

Definition at line 39 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

i2c	A i2c handle.
irq	An interrupt request.

Returns: The result of the operation.

Definition at line 265 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

i2c	A i2c handle.

Returns: The result of the operation.

Definition at line 246 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

i2c	A i2c handle.
snapshot	Interrupt state snapshot.

Returns: The result of the operation.

Definition at line 204 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

	i2c	A i2c handle.
[out]	snapshot	Out-param for the snapshot; may be `NULL`.

Returns: The result of the operation.

Definition at line 373 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

i2c	A i2c handle.
irq	An interrupt request.
val	Value to be set.

Returns: The result of the operation.

Definition at line 290 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

	i2c	A i2c handle.
	irq	An interrupt request.
[out]	state	Out-param toggle state of the interrupt.

Returns: The result of the operation.

Definition at line 315 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

	i2c	A i2c handle.
[out]	snapshot	Out-param for interrupt state snapshot.

Returns: The result of the operation.

Definition at line 187 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

	i2c	A i2c handle.
	irq	An interrupt request.
[out]	type	Out-param for the interrupt type.

Returns: The result of the operation.

Definition at line 168 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

	i2c	A i2c handle.
	irq	An interrupt request.
[out]	is_pending	Out-param for whether the interrupt is pending.

Returns: The result of the operation.

Definition at line 221 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

i2c	A i2c handle.
snapshot	A snapshot to restore from.

Returns: The result of the operation.

Definition at line 400 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

i2c	A i2c handle.
irq	An interrupt request.
state	The new toggle state for the interrupt.

Returns: The result of the operation.

Definition at line 342 of file dif_i2c_autogen.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_i2c

Macro Definition Documentation

◆ kDifI2cIrqAcqStretch

◆ kDifI2cIrqAcqThreshold

◆ kDifI2cIrqCmdComplete

◆ kDifI2cIrqControllerHalt

◆ kDifI2cIrqFmtThreshold

◆ kDifI2cIrqHostTimeout

◆ kDifI2cIrqRxOverflow

◆ kDifI2cIrqRxThreshold

◆ kDifI2cIrqSclInterference

◆ kDifI2cIrqSdaInterference

◆ kDifI2cIrqSdaUnstable

◆ kDifI2cIrqStretchTimeout

◆ kDifI2cIrqTxStretch

◆ kDifI2cIrqTxThreshold

◆ kDifI2cIrqUnexpStop

Typedef Documentation

◆ dif_i2c_irq_enable_snapshot_t

◆ dif_i2c_irq_state_snapshot_t

◆ dif_i2c_irq_t

◆ dif_i2c_t

Enumeration Type Documentation

◆ dif_i2c_alert

Function Documentation

◆ dif_i2c_alert_force()

◆ dif_i2c_get_dt()

◆ dif_i2c_init()

◆ dif_i2c_init_from_dt()

◆ dif_i2c_irq_acknowledge()

◆ dif_i2c_irq_acknowledge_all()

◆ dif_i2c_irq_acknowledge_state()

◆ dif_i2c_irq_disable_all()

◆ dif_i2c_irq_force()

◆ dif_i2c_irq_get_enabled()

◆ dif_i2c_irq_get_state()

◆ dif_i2c_irq_get_type()

◆ dif_i2c_irq_is_pending()

◆ dif_i2c_irq_restore_all()

◆ dif_i2c_irq_set_enabled()