RTEMS  5.1
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions

Modules

 DMA Interface
 
 General Call
 
 Interrupt and Status Conditions
 
 RX FIFO Management
 
 SDA Hold Time Configuration
 
 TX FIFO Management
 

Data Structures

struct  ALT_I2C_DEV_s
 
struct  ALT_I2C_MASTER_CONFIG_s
 
struct  ALT_I2C_SLAVE_CONFIG_s
 

Macros

#define alt_i2c_cfg_to_speed(i2c_dev, speed_in_hz, cfg)   alt_i2c_master_config_speed_get((i2c_dev), (cfg), (speed_in_hz))
 
#define alt_i2c_speed_to_cfg(i2c_dev, speed_in_hz, cfg)   alt_i2c_master_config_speed_set((i2c_dev), (cfg), (speed_in_hz))
 

Typedefs

typedef enum ALT_I2C_TRANSFER_TYPE_e ALT_I2C_TRANSFER_TYPE_t
 
typedef struct ALT_I2C_DEV_s ALT_I2C_DEV_t
 
typedef enum ALT_I2C_CTLR_e ALT_I2C_CTLR_t
 
typedef enum ALT_I2C_MODE_e ALT_I2C_MODE_t
 
typedef enum ALT_I2C_SPEED_e ALT_I2C_SPEED_t
 
typedef enum ALT_I2C_ADDR_MODE_e ALT_I2C_ADDR_MODE_t
 
typedef enum ALT_I2C_STATUS_e ALT_I2C_STATUS_t
 
typedef enum ALT_I2C_TX_ABORT_CAUSE_e ALT_I2C_TX_ABORT_CAUSE_t
 
typedef struct ALT_I2C_MASTER_CONFIG_s ALT_I2C_MASTER_CONFIG_t
 
typedef struct ALT_I2C_SLAVE_CONFIG_s ALT_I2C_SLAVE_CONFIG_t
 

Enumerations

enum  ALT_I2C_TRANSFER_TYPE_e {
  ALT_I2C_TRANSFER_NONE = 0, ALT_I2C_TRANSFER_START = 1, ALT_I2C_TRANSFER_COMPLETE = 2, ALT_I2C_TRANSFER_READ = 3,
  ALT_I2C_TRANSFER_WRITE = 4
}
 
enum  ALT_I2C_CTLR_e { ALT_I2C_I2C0 = (int)ALT_I2C0_OFST, ALT_I2C_I2C1 = (int)ALT_I2C1_OFST, ALT_I2C_I2C2 = (int)ALT_I2C2_OFST, ALT_I2C_I2C3 = (int)ALT_I2C3_OFST }
 
enum  ALT_I2C_MODE_e { ALT_I2C_MODE_SLAVE = ALT_I2C_CON_MST_MOD_E_DIS, ALT_I2C_MODE_MASTER = ALT_I2C_CON_MST_MOD_E_EN }
 
enum  ALT_I2C_SPEED_e { ALT_I2C_SPEED_STANDARD = ALT_I2C_CON_SPEED_E_STANDARD, ALT_I2C_SPEED_FAST = ALT_I2C_CON_SPEED_E_FAST }
 
enum  ALT_I2C_ADDR_MODE_e { ALT_I2C_ADDR_MODE_7_BIT = ALT_I2C_TAR_IC_10BITADDR_MST_E_START7, ALT_I2C_ADDR_MODE_10_BIT = ALT_I2C_TAR_IC_10BITADDR_MST_E_START10 }
 
enum  ALT_I2C_STATUS_e {
  ALT_I2C_STATUS_RX_UNDER = 1UL << 0, ALT_I2C_STATUS_RX_OVER = 1UL << 1, ALT_I2C_STATUS_RX_FULL = 1UL << 2, ALT_I2C_STATUS_TX_OVER = 1UL << 3,
  ALT_I2C_STATUS_TX_EMPTY = 1UL << 4, ALT_I2C_STATUS_RD_REQ = 1UL << 5, ALT_I2C_STATUS_TX_ABORT = 1UL << 6, ALT_I2C_STATUS_RX_DONE = 1UL << 7,
  ALT_I2C_STATUS_ACTIVITY = 1UL << 8, ALT_I2C_STATUS_STOP_DET = 1UL << 9, ALT_I2C_STATUS_START_DET = 1UL << 10, ALT_I2C_STATUS_INT_CALL = 1UL << 11,
  ALT_I2C_STATUS_INT_ALL = 0xFFF
}
 
enum  ALT_I2C_TX_ABORT_CAUSE_e {
  ALT_I2C_TX_ABORT_CAUSE_7B_ADDR_NOACK = 1UL << 0, ALT_I2C_TX_ABORT_CAUSE_10ADDR1_NOACK = 1UL << 1, ALT_I2C_TX_ABORT_CAUSE_10ADDR2_NOACK = 1UL << 2, ALT_I2C_TX_ABORT_CAUSE_TXDATA_NOACK = 1UL << 3,
  ALT_I2C_TX_ABORT_CAUSE_GCALL_NOACK = 1UL << 4, ALT_I2C_TX_ABORT_CAUSE_GCALL_RD = 1UL << 5, ALT_I2C_TX_ABORT_CAUSE_HS_ACKDET = 1UL << 6, ALT_I2C_TX_ABORT_CAUSE_SBYTE_ACKDET = 1UL << 7,
  ALT_I2C_TX_ABORT_CAUSE_HS_NORSTRT = 1UL << 8, ALT_I2C_TX_ABORT_CAUSE_SBYTE_NORSTRT = 1UL << 9, ALT_I2C_TX_ABORT_CAUSE_10B_RD_NORSTRT = 1UL << 10, ALT_I2C_TX_ABORT_CAUSE_MST_DIS = 1UL << 11,
  ALT_I2C_TX_ABORT_CAUSE_ARB_LOST = 1UL << 12, ALT_I2C_TX_ABORT_CAUSE_SLVFLUSH_TXFIFO = 1UL << 13, ALT_I2C_TX_ABORT_CAUSE_SLV_ARBLOST = 1UL << 14, ALT_I2C_TX_ABORT_CAUSE_SLVRD_INTX = 1UL << 15
}
 

Functions

ALT_STATUS_CODE alt_i2c_init (const ALT_I2C_CTLR_t i2c, ALT_I2C_DEV_t *i2c_dev)
 
ALT_STATUS_CODE alt_i2c_reset (ALT_I2C_DEV_t *i2c_dev)
 
ALT_STATUS_CODE alt_i2c_uninit (ALT_I2C_DEV_t *i2c_dev)
 
ALT_STATUS_CODE alt_i2c_disable (ALT_I2C_DEV_t *i2c_dev)
 
ALT_STATUS_CODE alt_i2c_enable (ALT_I2C_DEV_t *i2c_dev)
 
ALT_STATUS_CODE alt_i2c_is_enabled (ALT_I2C_DEV_t *i2c_dev)
 
ALT_STATUS_CODE alt_i2c_master_config_get (ALT_I2C_DEV_t *i2c_dev, ALT_I2C_MASTER_CONFIG_t *cfg)
 
ALT_STATUS_CODE alt_i2c_master_config_set (ALT_I2C_DEV_t *i2c_dev, const ALT_I2C_MASTER_CONFIG_t *cfg)
 
ALT_STATUS_CODE alt_i2c_master_config_speed_get (ALT_I2C_DEV_t *i2c_dev, const ALT_I2C_MASTER_CONFIG_t *cfg, uint32_t *speed_in_hz)
 
ALT_STATUS_CODE alt_i2c_master_config_speed_set (ALT_I2C_DEV_t *i2c_dev, ALT_I2C_MASTER_CONFIG_t *cfg, uint32_t speed_in_hz)
 
ALT_STATUS_CODE alt_i2c_slave_config_get (ALT_I2C_DEV_t *i2c_dev, ALT_I2C_SLAVE_CONFIG_t *cfg)
 
ALT_STATUS_CODE alt_i2c_slave_config_set (ALT_I2C_DEV_t *i2c_dev, const ALT_I2C_SLAVE_CONFIG_t *cfg)
 
ALT_STATUS_CODE alt_i2c_op_mode_get (ALT_I2C_DEV_t *i2c_dev, ALT_I2C_MODE_t *mode)
 
ALT_STATUS_CODE alt_i2c_op_mode_set (ALT_I2C_DEV_t *i2c_dev, const ALT_I2C_MODE_t mode)
 
ALT_STATUS_CODE alt_i2c_is_busy (ALT_I2C_DEV_t *i2c_dev)
 
ALT_STATUS_CODE alt_i2c_read (ALT_I2C_DEV_t *i2c_dev, uint8_t *val)
 
ALT_STATUS_CODE alt_i2c_write (ALT_I2C_DEV_t *i2c_dev, const uint8_t val)
 
ALT_STATUS_CODE alt_i2c_slave_receive (ALT_I2C_DEV_t *i2c_dev, uint8_t *data)
 
ALT_STATUS_CODE alt_i2c_slave_transmit (ALT_I2C_DEV_t *i2c_dev, const uint8_t data)
 
ALT_STATUS_CODE alt_i2c_slave_bulk_transmit (ALT_I2C_DEV_t *i2c_dev, const void *data, const size_t size)
 
ALT_STATUS_CODE alt_i2c_master_target_get (ALT_I2C_DEV_t *i2c_dev, uint32_t *target_addr)
 
ALT_STATUS_CODE alt_i2c_master_target_set (ALT_I2C_DEV_t *i2c_dev, uint32_t target_addr)
 
ALT_STATUS_CODE alt_i2c_master_transmit (ALT_I2C_DEV_t *i2c_dev, const void *data, const size_t size, const bool issue_restart, const bool issue_stop)
 
ALT_STATUS_CODE alt_i2c_master_receive (ALT_I2C_DEV_t *i2c_dev, void *data, const size_t size, const bool issue_restart, const bool issue_stop)
 
ALT_STATUS_CODE alt_i2c_issue_read (ALT_I2C_DEV_t *i2c_dev, const bool issue_restart, const bool issue_stop)
 
ALT_STATUS_CODE alt_i2c_issue_write (ALT_I2C_DEV_t *i2c_dev, const uint8_t value, const bool issue_restart, const bool issue_stop)
 

Detailed Description

This module defines an API for configuring and managing the HPS I2C controllers.

The I2C controller provides support for a communication link between integrated circuits on a board. It is a simple two-wire bus which consists of a serial data line (SDA) and a serial clock (SCL) for use in applications such as temperature sensors and voltage level translators to EEPROMs, A/D and D/A converters, CODECs, and many types of microprocessors.

The Hard Processor System (HPS) provides four I2C controllers to enable system software to communicate serially with I2C buses. Each I2C controller can operate in master or slave mode, and support standard mode of up to 100 kilobits per second (Kbps) or fast mode of up to 400 Kbps. These I2C controllers are instances of the Synopsys DesignWare APB I2C (DW_apb_i2c) controller.

NOTE: Each I2C controller must be programmed to operate in either master or slave mode only. Operating as a master and slave simultaneously is not supported.

Features of the I2C Controller:

For a complete details on the configuration and operation of I2C controller, consult the following references:

Macro Definition Documentation

◆ alt_i2c_cfg_to_speed

#define alt_i2c_cfg_to_speed (   i2c_dev,
  speed_in_hz,
  cfg 
)    alt_i2c_master_config_speed_get((i2c_dev), (cfg), (speed_in_hz))

Definition included for backwards compatibility.

◆ alt_i2c_speed_to_cfg

#define alt_i2c_speed_to_cfg (   i2c_dev,
  speed_in_hz,
  cfg 
)    alt_i2c_master_config_speed_set((i2c_dev), (cfg), (speed_in_hz))

Definition included for backwards compatibility.

Typedef Documentation

◆ ALT_I2C_ADDR_MODE_t

This type enumerates the two addressing modes formats supported by the I2C controller.

The I2C controller does not support mixed address format - that is, a 7-bit address transaction followed by a 10-bit address transaction or vice versa - combined format transactions.

◆ ALT_I2C_CTLR_t

This type enumerates the HPS I2C controller instances.

◆ ALT_I2C_MASTER_CONFIG_t

This type defines a structure for configuration of the SCL high and low counts to ensure proper I/O timing with the device interface.

The SCL count values are only relevant if the I2C controller is enabled to as an I2C master. The SCL count values are ignored when the I2C controller is enabled as an I2C slave.

See: Clock Frequency Configuration section of Chapter 20. I2C Controller in the Cyclone V Device Handbook Volume 3: Hard Processor System Technical Reference Manual for a complete discussion of calculation of the proper SCL clock high and low times.

◆ ALT_I2C_MODE_t

This type enumerates the modes that the I2C controller may operate in.

NOTE: Each I2C controller must be programmed to operate in either master or slave mode only. Operating as a master and slave simultaneously is not supported.

◆ ALT_I2C_SLAVE_CONFIG_t

This type defines a structure for configuration of the I2C controller when it is operating in slave mode.

◆ ALT_I2C_SPEED_t

This type enumerates the I2C controller operational speed modes.

The I2C controller can operate in standard mode (with data rates 0 to 100 Kbps) or fast mode (with data rates less than or equal to 400 Kbps). Additionally, fast mode devices are downward compatible. For instance, fast mode devices can communicate with standard mode devices in 0 to 100 Kbps I2C bus system. However, standard mode devices are not upward compatible and should not be incorporated in a fast-mode I2C bus system as they cannot follow the higher transfer rate and therefore unpredictable states would occur.

This setting is relevant only if one is operating the I2C in master mode.

◆ ALT_I2C_STATUS_t

This type enumerates interrupt status conditions for the I2C controller.

◆ ALT_I2C_TRANSFER_TYPE_t

This type definition enumerates the operational state of I2C by transfer operation.

◆ ALT_I2C_TX_ABORT_CAUSE_t

This type enumerates the source causes of a ALT_I2C_STATUS_TX_ABORT condition.

The active ALT_I2C_TX_ABORT_CAUSE_t source conditions are cleared when alt_i2c_int_clear() with is called ALT_I2C_STATUS_TX_ABORT in the mask or alt_i2c_int_clear() is called with ALT_I2C_STATUS_ALL in the mask.

Enumeration Type Documentation

◆ ALT_I2C_ADDR_MODE_e

This type enumerates the two addressing modes formats supported by the I2C controller.

The I2C controller does not support mixed address format - that is, a 7-bit address transaction followed by a 10-bit address transaction or vice versa - combined format transactions.

Enumerator
ALT_I2C_ADDR_MODE_7_BIT 

7-Bit Address Format

ALT_I2C_ADDR_MODE_10_BIT 

10-Bit Address Format

◆ ALT_I2C_CTLR_e

This type enumerates the HPS I2C controller instances.

Enumerator
ALT_I2C_I2C0 

I2C0 instance.

ALT_I2C_I2C1 

I2C1 instance.

ALT_I2C_I2C2 

I2C2 instance.

ALT_I2C_I2C3 

I2C3 instance.

◆ ALT_I2C_MODE_e

This type enumerates the modes that the I2C controller may operate in.

NOTE: Each I2C controller must be programmed to operate in either master or slave mode only. Operating as a master and slave simultaneously is not supported.

Enumerator
ALT_I2C_MODE_SLAVE 

Slave Mode

ALT_I2C_MODE_MASTER 

Master Mode

◆ ALT_I2C_SPEED_e

This type enumerates the I2C controller operational speed modes.

The I2C controller can operate in standard mode (with data rates 0 to 100 Kbps) or fast mode (with data rates less than or equal to 400 Kbps). Additionally, fast mode devices are downward compatible. For instance, fast mode devices can communicate with standard mode devices in 0 to 100 Kbps I2C bus system. However, standard mode devices are not upward compatible and should not be incorporated in a fast-mode I2C bus system as they cannot follow the higher transfer rate and therefore unpredictable states would occur.

This setting is relevant only if one is operating the I2C in master mode.

Enumerator
ALT_I2C_SPEED_STANDARD 

Standard mode (0 to 100 Kbps)

ALT_I2C_SPEED_FAST 

Fast mode (<= 400 Kbps)

◆ ALT_I2C_STATUS_e

This type enumerates interrupt status conditions for the I2C controller.

Enumerator
ALT_I2C_STATUS_RX_UNDER 

Set if the processor attempts to read the receive buffer when it is empty. If the I2C controller is disabled, this status keeps maintains its state until the master or slave state machines go into idle, then this interrupt is cleared.

ALT_I2C_STATUS_RX_OVER 

Set if the receive buffer is completely filled to capacity and an additional byte is received from an external I2C device. The I2C controller acknowledges this, but any data bytes received after the FIFO is full are discarded. If the I2C controller is disabled, this status maintains its statue until the master or slave state machines go into idle, then this interrupt is cleared.

ALT_I2C_STATUS_RX_FULL 

Set when the receive buffer reaches or goes above the RX_TL threshold. It is automatically cleared by hardware when buffer level goes below the threshold. If the I2C controller is disabled, the RX FIFO is flushed and held in reset; therefore the RX FIFO is not full. So this bit is cleared once the I2C controller is disabled, regardless of the activity that continues.

ALT_I2C_STATUS_TX_OVER 

Set during transmit if the transmit buffer is filled to capacity and the processor attempts to issue another I2C command. When the I2C controller is disabled, this bit maintains its state until the master or slave state machines go into idle, then this interrupt is cleared.

ALT_I2C_STATUS_TX_EMPTY 

This bit is set to 1 when the transmit buffer is at or below the configured threshold value. It is automatically cleared by hardware when the buffer level goes above the threshold. When the I2C controller is disabled, the TX FIFO is flushed and held in reset. The TX FIFO appears as if it has no data in it, so this bit is set to 1, provided there is activity in the master or slave state machines. When there is no longer activity, then this bit is set to 0.

ALT_I2C_STATUS_RD_REQ 

This bit is set to 1 when I2C is acting as a slave and another I2C master is attempting to read data from the I2C. The I2C holds the bus in a wait state until this interrupt is serviced, which means that the slave has been addressed by a remote master that is asking for data to be transferred. The processor must respond to this interrupt and then write the requested data. This bit is set to 0 just after the processor by calling alt_i2c_int_clear() with ALT_I2C_STATUS_RD_REQ in the mask..

ALT_I2C_STATUS_TX_ABORT 

This bit indicates if I2C, as an I2C transmitter, is unable to complete the intended actions on the contents of the transmit FIFO. This situation can occur both as an I2C master or an I2C slave, and is referred to as a 'transmit abort'. When this bit is set to 1, the IC_TX_ABRT_SOURCE register indicates the reason why the transmit abort takes places.

NOTE: The I2C flushes/resets/empties the TX FIFO whenever this bit is set. The TX FIFO remains in this flushed state until the register alt_i2c_int_clear() with ALT_I2C_STATUS_TX_ABORT in the mask is called. Once this happens, the TX FIFO is then ready to accept more data bytes from the APB interface.

ALT_I2C_STATUS_RX_DONE 

When the I2C is acting as a slave-transmitter, this bit is set to 1 if the master does not acknowledge a transmitted byte. This occurs on the last byte of the transmission, indicating that the transmission is done.

ALT_I2C_STATUS_ACTIVITY 

This bit captures I2C activity and stays set until it is cleared. There are four ways to clear it:

Once this bit is set, it stays set unless one of the four methods is used to clear it. Even if the I2C module is idle, this bit remains set until cleared, indicating that there was activity on the bus.

ALT_I2C_STATUS_STOP_DET 

Indicates whether a STOP condition has occurred on the I2C interface regardless of whether I2C is operating in slave or master mode.

ALT_I2C_STATUS_START_DET 

Indicates whether a START or RESTART condition has occurred on the I2C interface regardless of whether I2C is operating in slave or master mode.

ALT_I2C_STATUS_INT_CALL 

Set only when a General Call address is received and it is acknowledged. It stays set until it is cleared either by disabling I2C or when alt_i2c_int_clear() with ALT_I2C_STATUS_CALL in the mask is called. I2C stores the received data in the Rx buffer.

ALT_I2C_STATUS_INT_ALL 

All Combined and Individual Interrupts. This enumeration value can be used to clear, disable, and enable the combined interrupt and all individual interrupt status conditions. As a side effect, when passed to alt_i2c_int_clear(), clears the source causes (ALT_I2C_TX_ABORT_CAUSE_t) of the ALT_I2C_STATUS_TX_ABORT condition.

◆ ALT_I2C_TRANSFER_TYPE_e

This type definition enumerates the operational state of I2C by transfer operation.

Enumerator
ALT_I2C_TRANSFER_NONE 

No transfer operation

ALT_I2C_TRANSFER_START 

Start detect

ALT_I2C_TRANSFER_COMPLETE 

All operations done

ALT_I2C_TRANSFER_READ 

Read operation is active

ALT_I2C_TRANSFER_WRITE 

Write operation is active

◆ ALT_I2C_TX_ABORT_CAUSE_e

This type enumerates the source causes of a ALT_I2C_STATUS_TX_ABORT condition.

The active ALT_I2C_TX_ABORT_CAUSE_t source conditions are cleared when alt_i2c_int_clear() with is called ALT_I2C_STATUS_TX_ABORT in the mask or alt_i2c_int_clear() is called with ALT_I2C_STATUS_ALL in the mask.

Enumerator
ALT_I2C_TX_ABORT_CAUSE_7B_ADDR_NOACK 

Master Abort 7 Bit Address - If set (1), Master is in 7-bit addressing mode and the address sent was not acknowledged by any slave.

Role of I2C: Master-Transmitter or Master-Receiver

ALT_I2C_TX_ABORT_CAUSE_10ADDR1_NOACK 

Master Abort 10 Bit Address Byte 1 - If set (1), Master is in 10-bit address mode and the first 10-bit address byte was not acknowledged by any slave.

Role of I2C: Master-Transmitter or Master-Receiver

ALT_I2C_TX_ABORT_CAUSE_10ADDR2_NOACK 

Master Abort 10 Bit Address Byte 2 - If set (1), Master is in 10-bit address mode and the second address byte of the 10-bit address was not acknowledged by any slave

Role of I2C: Master-Transmitter or Master-Receiver

ALT_I2C_TX_ABORT_CAUSE_TXDATA_NOACK 

Master Abort TX NOACK Bit - If set (1), Master has received an acknowledgement for the address, but when it sent data byte(s) following the address, it did not receive an acknowledge from the remote slave(s). This is a master-mode only bit.

Role of I2C: Master-Transmitter.

ALT_I2C_TX_ABORT_CAUSE_GCALL_NOACK 

Master Abort GC Noack Bit - If set (1), I2C controller in master mode sent a General Call and no slave on the bus acknowledged the General Call.

Role of I2C: Master-Transmitter.

ALT_I2C_TX_ABORT_CAUSE_GCALL_RD 

Master Abort GC Read Bit - If set (1), I2C controller in master mode sent a General Call but the user programmed the byte following the General Call to be a read from the bus (IC_DATA_CMD[9] is set to 1).

Role of I2C: Master-Transmitter.

ALT_I2C_TX_ABORT_CAUSE_HS_ACKDET 

Master HS MC Ack - If set (1), Master is in High Speed mode and the High Speed Master code was acknowledged (wrong behavior).

Role of I2C: Master.

ALT_I2C_TX_ABORT_CAUSE_SBYTE_ACKDET 

Master Abort START Byte - If set (1), Master has sent a START Byte and the START Byte was acknowledged (wrong behavior).

Role of I2C: Master.

ALT_I2C_TX_ABORT_CAUSE_HS_NORSTRT 

Master HS Restart Disabled - If set (1), the restart is disabled (IC_RESTART_EN bit (IC_CON[5]) = 0) and the user is trying to use the master to transfer data in High Speed mode.

Role of I2C: Master-Transmitter or Master-Receiver

ALT_I2C_TX_ABORT_CAUSE_SBYTE_NORSTRT 

Master Abort START No Restart - To clear, the source of the ABRT_SBYTE_NORSTRT must be fixed first; restart must be enabled (IC_CON[5]=1), the SPECIAL bit must be cleared (IC_TAR[11]), or the GC_OR_START bit must be cleared (IC_TAR[10]). Once the source of the ABRT_SBYTE_NORSTRT is fixed, then this bit can be cleared in the same manner as other bits in this register. If the source of the ABRT_SBYTE_NORSTRT is not fixed before attempting to clear this bit, bit 9 clears for one cycle and then gets re-asserted.

If set (1), the restart is disabled (IC_RESTART_EN bit (IC_CON[5]) = 0) and the user is trying to send a START Byte.

Role of I2C: Master.

ALT_I2C_TX_ABORT_CAUSE_10B_RD_NORSTRT 

Master Abort 10 Bit No Restart - If set (1), the restart is disabled (IC_RESTART_EN bit (IC_CON[5]) = 0) and the master sends a read command in 10-bit addressing mode.

Role of I2C: Master Receiver.

ALT_I2C_TX_ABORT_CAUSE_MST_DIS 

Master Operation with Master Disabled - If set (1), user tries to initiate a Master operation with the Master mode disabled.

Role of I2C: Master or Slave-Receiver.

ALT_I2C_TX_ABORT_CAUSE_ARB_LOST 

Master Abort Arbitration Lost - If set (1), master has lost arbitration, or if IC_TX_ABRT_SOURCE[14] is also set, then the slave transmitter has lost arbitration. Note: I2C can be both master and slave at the same time.

Role of I2C: Master or Slave-Transmitter.

ALT_I2C_TX_ABORT_CAUSE_SLVFLUSH_TXFIFO 

Slave Abort Flush TXFIFO - If set (1), Slave has received a read command and some data exists in the TX FIFO so the slave issues a TX_ABRT interrupt to flush old data in TX FIFO.

Role of I2C: Slave-Transmitter.

ALT_I2C_TX_ABORT_CAUSE_SLV_ARBLOST 

Slave Abort Arbitration Lost - If set (1), Slave lost the bus while transmitting data to a remote master. IC_TX_ABRT_SOURCE[12] is set at the same time.

Note: Even though the slave never owns the bus, something could go wrong on the bus. This is a fail safe check. For instance, during a data transmission at the low-to-high transition of SCL, if what is on the data bus is not what is supposed to be transmitted, then DW_apb_i2c no longer own the bus.

Role of I2C: Slave-Transmitter.

ALT_I2C_TX_ABORT_CAUSE_SLVRD_INTX 

Slave Abort Read TX - If set (1), when the processor side responds to a slave mode request for data to be transmitted to a remote master and user writes a 1 in CMD (bit 8) of IC_DATA_CMD register.

Role of I2C: Slave-Transmitter.

Function Documentation

◆ alt_i2c_disable()

ALT_STATUS_CODE alt_i2c_disable ( ALT_I2C_DEV_t i2c_dev)

Disables the I2C controller.

When the I2C controller is disabled, the following occurs:

  • The TX FIFO and RX FIFO get flushed.
  • The I2C interrupt status conditions remain active until the I2C controller goes into IDLE state.

If the controller is transmitting, it stops as well as deletes the contents of the transmit buffer after the current transfer is complete. If the module is receiving, the controller stops the current transfer at the end of the current byte and does not acknowledge the transfer.

Parameters
i2c_devA pointer to the I2C controller device block instance.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_enable()

ALT_STATUS_CODE alt_i2c_enable ( ALT_I2C_DEV_t i2c_dev)

Enables the I2C controller.

Parameters
i2c_devA pointer to the I2C controller device block instance.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_init()

ALT_STATUS_CODE alt_i2c_init ( const ALT_I2C_CTLR_t  i2c,
ALT_I2C_DEV_t i2c_dev 
)

Initialize the specified I2C controller instance for use and return a device handle referencing it.

Parameters
i2cThe HPS I2C controller instance to initialize.
i2c_devA pointer to the I2C controller device block instance.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_is_busy()

ALT_STATUS_CODE alt_i2c_is_busy ( ALT_I2C_DEV_t i2c_dev)

Returns ALT_E_TRUE if the I2C controller is busy. The I2C controller is busy if either the Slave Finite State Machine (FSM) is not in the IDLE state or the Master Finite State Machine (FSM) is not in the IDLE state.

Parameters
i2c_devA pointer to the I2C controller device block instance.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_is_enabled()

ALT_STATUS_CODE alt_i2c_is_enabled ( ALT_I2C_DEV_t i2c_dev)

Returns ALT_E_TRUE if the I2C controller is enabled.

Parameters
i2c_devA pointer to the I2C controller device block instance.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_issue_read()

ALT_STATUS_CODE alt_i2c_issue_read ( ALT_I2C_DEV_t i2c_dev,
const bool  issue_restart,
const bool  issue_stop 
)

This function causes the I2C controller master to issue a READ request on the bus. This function is typically used during master-receiver transfers.

The I2C controller must be in master mode before calling this function.

Parameters
i2c_devA pointer to the I2C controller device block instance.
issue_restartThis parameter controls whether a RESTART is issued before the byte is sent or received. If:
  • true - if restart_enabled in ALT_I2C_MASTER_CONFIG_t is true, a RESTART is issued before the data is sent/received (according to the value of CMD), regardless of whether or not the transfer direction is changing from the previous command; if restart_enabled is false, a STOP followed by a START is issued instead.
  • false - If restart_enabled in ALT_I2C_MASTER_CONFIG_t is true, a RESTART is issued only if the transfer direction is changing from the previous command; if restart_enabled is false, a STOP followed by a START is issued instead.
issue_stopThis parameter controls whether a STOP is issued after the byte is sent or received. If:
  • true - STOP is issued after this byte, regardless of whether or not the Tx FIFO is empty. If the Tx FIFO is not empty, the master immediately tries to start a new transfer by issuing a START and arbitrating for the bus.
  • false - STOP is not issued after this byte, regardless of whether or not the Tx FIFO is empty. If the Tx FIFO is not empty, the master continues the current transfer by sending/receiving data bytes according to the value of the CMD bit. If the Tx FIFO is empty, the master holds the SCL line low and stalls the bus until a new command is available in the Tx FIFO.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_issue_write()

ALT_STATUS_CODE alt_i2c_issue_write ( ALT_I2C_DEV_t i2c_dev,
const uint8_t  value,
const bool  issue_restart,
const bool  issue_stop 
)

This function causes the I2C controller master to issue a send byte on the bus. This function is typically used during master-transmitter/slave-transmitter transfers.

The I2C controller must be in master mode before calling this function.

Parameters
i2c_devA pointer to the I2C controller device block instance.
valueThe data item to be transmitted.
issue_restartThis parameter controls whether a RESTART is issued before the byte is sent or received. If:
  • true - if restart_enabled in ALT_I2C_MASTER_CONFIG_t is true, a RESTART is issued before the data is sent/received (according to the value of CMD), regardless of whether or not the transfer direction is changing from the previous command; if restart_enabled is false, a STOP followed by a START is issued instead.
  • false - If restart_enabled in ALT_I2C_MASTER_CONFIG_t is true, a RESTART is issued only if the transfer direction is changing from the previous command; if restart_enabled is false, a STOP followed by a START is issued instead.
issue_stopThis parameter controls whether a STOP is issued after the byte is sent or received. If:
  • true - STOP is issued after this byte, regardless of whether or not the Tx FIFO is empty. If the Tx FIFO is not empty, the master immediately tries to start a new transfer by issuing a START and arbitrating for the bus.
  • false - STOP is not issued after this byte, regardless of whether or not the Tx FIFO is empty. If the Tx FIFO is not empty, the master continues the current transfer by sending/receiving data bytes according to the value of the CMD bit. If the Tx FIFO is empty, the master holds the SCL line low and stalls the bus until a new command is available in the Tx FIFO.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_master_config_get()

ALT_STATUS_CODE alt_i2c_master_config_get ( ALT_I2C_DEV_t i2c_dev,
ALT_I2C_MASTER_CONFIG_t cfg 
)

Gets the current configuration of the I2C controller when operating in master mode.

Parameters
i2c_devA pointer to the I2C controller device block instance.
cfg[out] Pointer to a ALT_I2C_MASTER_CONFIG_t structure for holding the returned I2C master mode configuration parameters.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_master_config_set()

ALT_STATUS_CODE alt_i2c_master_config_set ( ALT_I2C_DEV_t i2c_dev,
const ALT_I2C_MASTER_CONFIG_t cfg 
)

Sets the configuration of the I2C controller with operational parameters for operating in master mode.

Parameters
i2c_devA pointer to the I2C controller device block instance.
cfgPointer to a ALT_I2C_MASTER_CONFIG_t structure holding the desired I2C master mode operational parameters.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_master_config_speed_get()

ALT_STATUS_CODE alt_i2c_master_config_speed_get ( ALT_I2C_DEV_t i2c_dev,
const ALT_I2C_MASTER_CONFIG_t cfg,
uint32_t *  speed_in_hz 
)

This is a utility function that returns the speed based on parameters of the I2C master configuration.

Parameters
i2c_devA pointer to the I2C controller device block instance.
cfgA pointer to the master confugurations.
speed_in_hz[out] Speed (Hz) of the I2C bus currently configured at.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_master_config_speed_set()

ALT_STATUS_CODE alt_i2c_master_config_speed_set ( ALT_I2C_DEV_t i2c_dev,
ALT_I2C_MASTER_CONFIG_t cfg,
uint32_t  speed_in_hz 
)

This is a utility function that computes parameters for the I2C master configuration that best matches the speed requested.

Parameters
i2c_devA pointer to the I2C controller device block instance.
cfgA pointer to the master confugurations.
speed_in_hzSpeed (Hz) of the I2C bus to configure.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_master_receive()

ALT_STATUS_CODE alt_i2c_master_receive ( ALT_I2C_DEV_t i2c_dev,
void *  data,
const size_t  size,
const bool  issue_restart,
const bool  issue_stop 
)

This function acts in the role of a master-receiver by receiving one or more data bytes transmitted from a slave in response to read requests issued from this master.

This function causes the master to issue the required number of read requests to the slave and read the received data bytes from the Rx FIFO.

The issue_restart and issue_stop parameters apply to the final read request transaction in the num_data_entries sequence required to fulfill the aggregate receive request.

This API is not suitable for being called in an interrupt context as it may wait for certain controller states before completing.

The I2C controller must be in master mode before calling this function.

Parameters
i2c_devA pointer to the I2C controller device block instance.
data[out] The data buffer to receive the requested size bytes.
sizeThe size of the data buffer to read from the RX FIFO.
issue_restartThis parameter controls whether a RESTART is issued before the byte is sent or received. If:
  • true - if restart_enabled in ALT_I2C_MASTER_CONFIG_t is true, a RESTART is issued before the data is sent/received (according to the value of CMD), regardless of whether or not the transfer direction is changing from the previous command; if restart_enabled is false, a STOP followed by a START is issued instead.
  • false - If restart_enabled in ALT_I2C_MASTER_CONFIG_t is true, a RESTART is issued only if the transfer direction is changing from the previous command; if restart_enabled is false, a STOP followed by a START is issued instead.
issue_stopThis parameter controls whether a STOP is issued after the byte is sent or received. If:
  • true - STOP is issued after this byte, regardless of whether or not the Tx FIFO is empty. If the Tx FIFO is not empty, the master immediately tries to start a new transfer by issuing a START and arbitrating for the bus.
  • false - STOP is not issued after this byte, regardless of whether or not the Tx FIFO is empty. If the Tx FIFO is not empty, the master continues the current transfer by sending/receiving data bytes according to the value of the CMD bit. If the Tx FIFO is empty, the master holds the SCL line low and stalls the bus until a new command is available in the Tx FIFO.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_master_target_get()

ALT_STATUS_CODE alt_i2c_master_target_get ( ALT_I2C_DEV_t i2c_dev,
uint32_t *  target_addr 
)

This function returns the current target address.

The I2C controller must be in master mode before calling this function.

Parameters
i2c_devA pointer to the I2C controller device block instance.
target_addr[out] The 7 or 10 bit slave target address.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code.

◆ alt_i2c_master_target_set()

ALT_STATUS_CODE alt_i2c_master_target_set ( ALT_I2C_DEV_t i2c_dev,
uint32_t  target_addr 
)

This function updates the target slave address for any upcoming I2C bus IO.

This API is not suitlabe for being called in an interrupt context as it will wait for the TX FIFO to flush before applying the changes. If the TX FIFO is known to be empty and the controller idle, then it can be safely called.

The I2C controller must be in master mode before calling this function.

Parameters
i2c_devA pointer to the I2C controller device block instance.
target_addrThe 7 or 10 bit slave target address.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code.

◆ alt_i2c_master_transmit()

ALT_STATUS_CODE alt_i2c_master_transmit ( ALT_I2C_DEV_t i2c_dev,
const void *  data,
const size_t  size,
const bool  issue_restart,
const bool  issue_stop 
)

This function acts in the role of a master-transmitter by issuing a write command and transmitting data to the I2C bus.

This API is not suitable for being called in an interrupt context as it may wait for certain controller states before completing.

The I2C controller must be in master mode before calling this function.

Parameters
i2c_devA pointer to the I2C controller device block instance.
dataA pointer to a data buffer to transmit
sizeThe size of the data buffer in bytes to place in the TX FIFO.
issue_restartThis parameter controls whether a RESTART is issued before the byte is sent or received. If:
  • true - if restart_enabled in ALT_I2C_MASTER_CONFIG_t is true, a RESTART is issued before the data is sent/received (according to the value of CMD), regardless of whether or not the transfer direction is changing from the previous command; if restart_enabled is false, a STOP followed by a START is issued instead.
  • false - If restart_enabled in ALT_I2C_MASTER_CONFIG_t is true, a RESTART is issued only if the transfer direction is changing from the previous command; if restart_enabled is false, a STOP followed by a START is issued instead.
issue_stopThis parameter controls whether a STOP is issued after the byte is sent or received. If:
  • true - STOP is issued after this byte, regardless of whether or not the Tx FIFO is empty. If the Tx FIFO is not empty, the master immediately tries to start a new transfer by issuing a START and arbitrating for the bus.
  • false - STOP is not issued after this byte, regardless of whether or not the Tx FIFO is empty. If the Tx FIFO is not empty, the master continues the current transfer by sending/receiving data bytes according to the value of the CMD bit. If the Tx FIFO is empty, the master holds the SCL line low and stalls the bus until a new command is available in the Tx FIFO.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_op_mode_get()

ALT_STATUS_CODE alt_i2c_op_mode_get ( ALT_I2C_DEV_t i2c_dev,
ALT_I2C_MODE_t mode 
)

Gets the current operational mode of the I2C controller.

Parameters
i2c_devA pointer to the I2C controller device block instance.
mode[out] The current operational mode enabled for the I2C controller.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_op_mode_set()

ALT_STATUS_CODE alt_i2c_op_mode_set ( ALT_I2C_DEV_t i2c_dev,
const ALT_I2C_MODE_t  mode 
)

Sets the operational mode of the I2C controller.

Parameters
i2c_devA pointer to the I2C controller device block instance.
modeThe operational mode to enable for the I2C controller.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_read()

ALT_STATUS_CODE alt_i2c_read ( ALT_I2C_DEV_t i2c_dev,
uint8_t *  val 
)

This function reads a single data byte from the receive FIFO.

This function is used to perform low level access to the data bytes received by the I2C controller and buffered in the receive FIFO. It may be used by master-receivers or slave receivers.

This function does not check for valid data in the receive FIFO beforehand and may cause an underflow if improperly used. It is meant to be called from a context where preconditions have been previously asserted such as in the implementation of the alt_i2c_slave_receive() or alt_i2c_master_receive() function.

Parameters
i2c_devA pointer to the I2C controller device block instance.
val[out] The single data byte read from the receive FIFO.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_reset()

ALT_STATUS_CODE alt_i2c_reset ( ALT_I2C_DEV_t i2c_dev)

Reset the specified I2C controller instance for use.

Parameters
i2c_devA pointer to the I2C controller device block instance.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_slave_bulk_transmit()

ALT_STATUS_CODE alt_i2c_slave_bulk_transmit ( ALT_I2C_DEV_t i2c_dev,
const void *  data,
const size_t  size 
)

This function acts in the role of a slave-transmitter by transmitting data in bulk to the I2C bus in response to a series of read requests from a master.

In the standard I2C protocol, all transactions are single byte transactions and the slave responds to a remote master read request by writing one byte into the slave's TX FIFO. When a slave (slave-transmitter) is issued with a read request from the remote master (master-receiver), at a minimum there should be at least one entry placed into the slave-transmitter's TX FIFO. The I2C controller is capable of handling more data in the TX FIFO so that subsequent read requests can receive that data without raising an interrupt or software having to poll to request more data. This eliminates overhead latencies from being incurred by servicing the interrupt or polling for data requests each time had there been a restriction of having only one entry placed in the TX FIFO.

If the remote master acknowledges the data sent by the slave-transmitter and there is no data in the slave's TX FIFO, the I2C controller raises the read request interrupt and waits for data to be written into the TX FIFO before it can be sent to the remote master.

If the programmer knows in advance that the master is requesting a packet of n bytes, then when another master request for data is received, the TX FIFO could be written with n number bytes and the master receives it as a continuous stream of data. For example, the slave continues to send data to the master as long as the master is acknowledging the data sent and there is data available in the TX FIFO. There is no need to hold the SCL line low or to issue READ request again.

If the remote master is to receive n bytes from the slave but the programmer wrote a number of bytes larger than n to the TX FIFO, then when the slave finishes sending the requested n bytes, it clears the TX FIFO and ignores any excess bytes.

This API is suitable for being called during an interrupt context. It is the programmer's responsibility to ensure that there is enough space in the TX FIFO to accomodate the request made.

The I2C controller must be in slave mode before calling this function.

Parameters
i2c_devA pointer to the I2C controller device block instance.
dataA pointer to the data buffer to transmit.
sizeThe size of the data buffer in bytes to place in the TX FIFO.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_slave_config_get()

ALT_STATUS_CODE alt_i2c_slave_config_get ( ALT_I2C_DEV_t i2c_dev,
ALT_I2C_SLAVE_CONFIG_t cfg 
)

Gets the current configuration of the I2C controller when operating in slave mode.

Parameters
i2c_devA pointer to the I2C controller device block instance.
cfg[out] Pointer to a ALT_I2C_SLAVE_CONFIG_t structure for holding the returned I2C slave mode configuration parameters.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_slave_config_set()

ALT_STATUS_CODE alt_i2c_slave_config_set ( ALT_I2C_DEV_t i2c_dev,
const ALT_I2C_SLAVE_CONFIG_t cfg 
)

Sets the configuration of the I2C controller with operational parameters for operating in slave mode.

Parameters
i2c_devA pointer to the I2C controller device block instance.
cfgPointer to a ALT_I2C_SLAVE_CONFIG_t structure holding the desired I2C slave mode operational parameters.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_slave_receive()

ALT_STATUS_CODE alt_i2c_slave_receive ( ALT_I2C_DEV_t i2c_dev,
uint8_t *  data 
)

This function acts in the role of a slave-receiver by receiving a single data byte from the I2C bus in response to a write command from the master.

This API is suitable for being called during an interrupt context. It is the programmer's responsibility to ensure that there is data in the RX FIFO to accomodate the request made.

The I2C controller must be in slave mode before calling this function.

Parameters
i2c_devA pointer to the I2C controller device block instance.
data[out] A pointer to a buffer to contain the received data byte.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_slave_transmit()

ALT_STATUS_CODE alt_i2c_slave_transmit ( ALT_I2C_DEV_t i2c_dev,
const uint8_t  data 
)

This function acts in the role of a slave-transmitter by transmitting a single data byte to the I2C bus in response to a read request from the master.

This API is suitable for being called during an interrupt context. It is the programmer's responsibility to ensure that there is enough space in the TX FIFO to accomodate the request made.

The I2C controller must be in slave mode before calling this function.

Parameters
i2c_devA pointer to the I2C controller device block instance.
dataThe data byte to transmit.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_uninit()

ALT_STATUS_CODE alt_i2c_uninit ( ALT_I2C_DEV_t i2c_dev)

Uninitialize the I2C controller referenced by the i2c_dev handle.

This function attempts to gracefully shutdown the I2C controller by waiting for any inpcomplete transactions to finish and then putting the I2C controller into reset.

Parameters
i2c_devA pointer to the I2C controller device block instance.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code

◆ alt_i2c_write()

ALT_STATUS_CODE alt_i2c_write ( ALT_I2C_DEV_t i2c_dev,
const uint8_t  val 
)

This function writes a single data byte to the transmit FIFO.

This function is used to perform low level writes of data to the transmit FIFO for transmission by the I2C controller. It may be used by slave receivers.

This function does not check whether the transmit FIFO is full or not beforehand and may cause an overflow if improperly used. It is meant to be called from a context where preconditions have been previously asserted such as in the implementation of the alt_i2c_slave_transmit() function.

Parameters
i2c_devA pointer to the I2C controller device block instance.
valThe data byte to write to the transmission FIFO.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code