/******************************************************************************
*
* Copyright 2013 Altera Corporation. All Rights Reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* 3. The name of the author may not be used to endorse or promote products
* derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO
* EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
* OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
* IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
* OF SUCH DAMAGE.
*
******************************************************************************/
/*! \file
* Altera - I2C Controller API
*/
#ifndef __ALT_I2C_H__
#define __ALT_I2C_H__
#include "hwlib.h"
#include "alt_clock_manager.h"
#include "socal/alt_i2c.h"
#include "socal/alt_rstmgr.h"
#include "socal/hps.h"
#include "socal/socal.h"
#ifdef __cplusplus
extern "C"
{
#endif /* __cplusplus */
/******************************************************************************/
/*! \addtogroup ALT_I2C I2C Controller API
*
* 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:
* * Support both 100 KBps and 400 KBps modes
* * One of the following I2C operations: master or slave
* * Support both 7-bit and 10-bit addressing modes
* * Mixed read and write combined-format transactions
* * Bulk transmit mode
* * DMA handshaking interface
*
* For a complete details on the configuration and operation of I2C controller,
* consult the following references:
* * Cyclone V Device Handbook Volume 3: Hard Processor System Technical
* Reference Manual, Chapter 20. I2C Controller (cv_54020-1.2)
* * Synopsys DesignWare DW_apb_i2c Databook DW_apb_i2c, Version 1.15a
* * The I2C-Bus Specification Version 2.1
*
* @{
*/
/******************************************************************************/
/*!
* This type definition enumerates the operational state of I2C by
* transfer operation.
*/
typedef enum ALT_I2C_TRANSFER_TYPE_e
{
ALT_I2C_TRANSFER_NONE = 0, /*!< No transfer operation */
ALT_I2C_TRANSFER_START = 1, /*!< Start detect */
ALT_I2C_TRANSFER_COMPLETE = 2, /*!< All operations done */
ALT_I2C_TRANSFER_READ = 3, /*!< Read operation is active */
ALT_I2C_TRANSFER_WRITE = 4, /*!< Write operation is active */
}
ALT_I2C_TRANSFER_TYPE_t;
/*
* A pointer or handle to the I2C controller device instance. The ALT_I2C_DEV_t is
* initialized by a call to alt_i2c_init() and subsequently used by the other I2C
* controller API functions as a reference to a specific device.
*
* \internal
* ALT_I2C_DEV_t may be a struct or reference to an opaque data
* structure. Whatever "internal" type is suited to the needs of the
* implementation.
* \endinternal
*/
typedef struct ALT_I2C_DEV_s
{
void * location; /*!< HPS address of I2C instance. */
alt_freq_t clock_freq; /*!< Input clock frequency. */
uint32_t last_target; /*!< Last issued target address. */
}
ALT_I2C_DEV_t;
/*!
* This type enumerates the HPS I2C controller instances.
*/
typedef enum ALT_I2C_CTLR_e
{
ALT_I2C_I2C0 = (int)ALT_I2C0_OFST, /*!< I2C0 instance. */
ALT_I2C_I2C1 = (int)ALT_I2C1_OFST, /*!< I2C1 instance. */
ALT_I2C_I2C2 = (int)ALT_I2C2_OFST, /*!< I2C2 instance. */
ALT_I2C_I2C3 = (int)ALT_I2C3_OFST, /*!< I2C3 instance. */
} ALT_I2C_CTLR_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.
*/
typedef enum ALT_I2C_MODE_e
{
ALT_I2C_MODE_SLAVE = ALT_I2C_CON_MST_MOD_E_DIS, /*!< Slave Mode */
ALT_I2C_MODE_MASTER = ALT_I2C_CON_MST_MOD_E_EN /*!< Master Mode */
} ALT_I2C_MODE_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.
*/
typedef enum ALT_I2C_SPEED_e
{
ALT_I2C_SPEED_STANDARD = ALT_I2C_CON_SPEED_E_STANDARD,
/*!< Standard mode (0 to 100 Kbps) */
ALT_I2C_SPEED_FAST = ALT_I2C_CON_SPEED_E_FAST
/*!< Fast mode (<= 400 Kbps) */
} ALT_I2C_SPEED_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.
*/
typedef enum ALT_I2C_ADDR_MODE_e
{
ALT_I2C_ADDR_MODE_7_BIT = ALT_I2C_TAR_IC_10BITADDR_MST_E_START7,
/*!< 7-Bit Address Format */
ALT_I2C_ADDR_MODE_10_BIT = ALT_I2C_TAR_IC_10BITADDR_MST_E_START10
/*!< 10-Bit Address Format */
} ALT_I2C_ADDR_MODE_t;
/*!
* This type enumerates interrupt status conditions for the I2C controller.
*/
typedef enum ALT_I2C_STATUS_e
{
ALT_I2C_STATUS_RX_UNDER = 1UL << 0,
/*!< 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 = 1UL << 1,
/*!< 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 = 1UL << 2,
/*!< 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 = 1UL << 3,
/*!< 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 = 1UL << 4,
/*!< 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 = 1UL << 5,
/*!< 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 = 1UL << 6,
/*!< 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 = 1UL << 7,
/*!< 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 = 1UL << 8,
/*!< This bit captures I2C activity and stays set
* until it is cleared. There are four ways to
* clear it:
* * Disabling the I2C controller
* * Calling alt_i2c_int_clear() with
* ALT_I2C_STATUS_ACTIVITY in the mask.
* * Calling alt_i2c_int_clear() with
* ALT_I2C_STATUS_ALL in the mask.
* * System reset
*
* 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 = 1UL << 9,
/*!< 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 = 1UL << 10,
/*!< 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 = 1UL << 11,
/*!< 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 = 0xFFF,
/*!< 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
* (\ref ALT_I2C_TX_ABORT_CAUSE_t) of the
* ALT_I2C_STATUS_TX_ABORT condition.
*/
} ALT_I2C_STATUS_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.
*
* \internal
* Discuss special handling of abrt_sbyte_norstrt TX_ABRT source required in ???() function.
* \endinternal
*/
typedef enum ALT_I2C_TX_ABORT_CAUSE_e
{
ALT_I2C_TX_ABORT_CAUSE_7B_ADDR_NOACK = 1UL << 0,
/*!< 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 = 1UL << 1,
/*!< 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 = 1UL << 2,
/*!< 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 = 1UL << 3,
/*!< 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 = 1UL << 4,
/*!< 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 = 1UL << 5,
/*!< 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 = 1UL << 6,
/*!< 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 = 1UL << 7,
/*!< 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 = 1UL << 8,
/*!< 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 = 1UL << 9,
/*!< 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 = 1UL << 10,
/*!< 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 = 1UL << 11,
/*!< 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 = 1UL << 12,
/*!< 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 = 1UL << 13,
/*!< 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 = 1UL << 14,
/*!< 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 = 1UL << 15
/*!< 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.
*/
} ALT_I2C_TX_ABORT_CAUSE_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.
*/
typedef struct ALT_I2C_MASTER_CONFIG_s
{
ALT_I2C_ADDR_MODE_t addr_mode;
/*!< The address mode (7 or 10 bit) when
* acting as a master.
*/
bool restart_enable;
/*!< This setting determines whether RESTART
* conditions may be sent when acting as a
* master. When the \e restart_enable is
* false, the I2C controller master is
* incapable of performing the following
* functions:
* * Sending a START BYTE
* * Performing any high-speed mode
* operation
* * Performing direction changes in
* combined format mode
* * Performing a read operation with a
* 10-bit address
*/
ALT_I2C_SPEED_t speed_mode;
/*!< The speed mode of the I2C operation.
*/
uint16_t ss_scl_hcnt;
/*!< The SCL clock high-period count for
* standard speed.
*/
uint16_t ss_scl_lcnt;
/*!< The SCL clock low-period count for
* standard speed.
*/
uint16_t fs_scl_hcnt;
/*!< The SCL clock high-period count for fast
* speed.
*/
uint16_t fs_scl_lcnt;
/*!< The SCL clock low-period count for fast
* speed.
*/
uint8_t fs_spklen;
/*!< The duration, measured in ic_clk cycles,
* of the longest spike that is filtered out
* by the spike suppression logic when the
* component is operating in SS or FS modes.
*/
} ALT_I2C_MASTER_CONFIG_t;
/*!
* This type defines a structure for configuration of the I2C controller when it
* is operating in slave mode.
*/
typedef struct ALT_I2C_SLAVE_CONFIG_s
{
ALT_I2C_ADDR_MODE_t addr_mode; /*!< The address mode (7 or 10 bit) when
* acting as a slave.
*/
uint32_t addr; /*!< The slave address to which the I2C
* controller responds when acting as a
* slave.
*/
bool nack_enable; /*!< Enable generation of a NACK. when the
* I2C controller is a
* slave-receiver. If \b true, it can
* only generate a NACK after a data
* byte is received; hence, the data
* transfer is aborted and the data
* received is not pushed onto the
* receive buffer. When \b false, it
* generates NACK/ACK, depending on
* normal criteria.
* * \b true = generate NACK after data
* byte received
* * \b false = generate NACK/ACK normally
*/
} ALT_I2C_SLAVE_CONFIG_t;
/*!
* Initialize the specified I2C controller instance for use and return a device
* handle referencing it.
*
* \param i2c
* The HPS I2C controller instance to initialize.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* Initialization process:
* * Initialize internal driver state
* * Check clock setup (ALT_CLK_L4_SP)
* * Take I2C instance out of reset (System Manager)
* * Disable and clear all interrupts and status conditions
* * Setup and initialize any expected initial I2C controller state
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_init(const ALT_I2C_CTLR_t i2c, ALT_I2C_DEV_t *i2c_dev);
/*!
* Reset the specified I2C controller instance for use.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* Reset process:
* * Disable controller
* * Initialize internal driver state
* * Check clock setup (ALT_CLK_L4_SP)
* * Take I2C instance out of reset (System Manager)
* * Disable and clear all interrupts and status conditions
* * Setup and initialize any expected initial I2C controller state
* * Enable controller
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_reset(ALT_I2C_DEV_t * i2c_dev);
/*!
* Uninitialize the I2C controller referenced by the \e 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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_uninit(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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_ENABLE.ENABLE = 0
* Follow the procedure in section 3.8.3 Disabling DW_apb_i2c of the DW Databook.
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_disable(ALT_I2C_DEV_t *i2c_dev);
/*!
* Enables the I2C controller.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_ENABLE.ENABLE = 1
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_enable(ALT_I2C_DEV_t *i2c_dev);
/*!
* Returns ALT_E_TRUE if the I2C controller is enabled.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_ENABLE.ENABLE == 1
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_is_enabled(ALT_I2C_DEV_t *i2c_dev);
/*!
* Gets the current configuration of the I2C controller when operating in master
* mode.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param cfg
* [out] Pointer to a ALT_I2C_MASTER_CONFIG_t structure for holding
* the returned I2C master mode configuration parameters.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_master_config_get(ALT_I2C_DEV_t *i2c_dev,
ALT_I2C_MASTER_CONFIG_t* cfg);
/*!
* Sets the configuration of the I2C controller with operational parameters for
* operating in master mode.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param cfg
* Pointer to a ALT_I2C_MASTER_CONFIG_t structure holding the desired
* I2C master mode operational parameters.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_master_config_set(ALT_I2C_DEV_t *i2c_dev,
const ALT_I2C_MASTER_CONFIG_t* cfg);
/*!
* This is a utility function that returns the speed based on parameters of the
* I2C master configuration.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param cfg
* A pointer to the master confugurations.
*
* \param speed_in_hz
* [out] Speed (Hz) of the I2C bus currently configured at.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*/
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 computes parameters for the I2C master
* configuration that best matches the speed requested.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param cfg
* A pointer to the master confugurations.
*
* \param speed_in_hz
* Speed (Hz) of the I2C bus to configure.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
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);
/*!
* Definition included for backwards compatibility.
*/
#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.
*/
#define alt_i2c_speed_to_cfg(i2c_dev, speed_in_hz, cfg) alt_i2c_master_config_speed_set((i2c_dev), (cfg), (speed_in_hz))
/*!
* Gets the current configuration of the I2C controller when operating in slave
* mode.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param cfg
* [out] Pointer to a ALT_I2C_SLAVE_CONFIG_t structure for holding
* the returned I2C slave mode configuration parameters.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_slave_config_get(ALT_I2C_DEV_t *i2c_dev,
ALT_I2C_SLAVE_CONFIG_t* cfg);
/*!
* Sets the configuration of the I2C controller with operational parameters for
* operating in slave mode.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param cfg
* Pointer to a ALT_I2C_SLAVE_CONFIG_t structure holding the desired
* I2C slave mode operational parameters.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_slave_config_set(ALT_I2C_DEV_t *i2c_dev,
const ALT_I2C_SLAVE_CONFIG_t* cfg);
/*! \addtogroup ALT_I2C_SDA_HOLD SDA Hold Time Configuration
*
* The I2C protocol specification requires 300ns of hold time on the SDA signal in
* standard and fast speed modes. Board delays on the SCL and SDA signals can mean
* that the hold-time requirement is met at the I2C master, but not at the I2C
* slave (or vice-versa). Because each system may encounter differing board signal
* delays, the I2C controller provides the capability to adjust of the SDA
* hold-time.
*
* The functions in this section provide software configuration of SDA hold time
* for the I2C controller.
*
* @{
*/
/*!
* Gets the currently configured value for the SDA hold time in I2C controller
* clock (\ref ALT_CLK_L4_SP) clock ticks.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param hold_time
* [out] The configured SDA hold time in \ref ALT_CLK_L4_SP clock
* ticks.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_sda_hold_time_get(ALT_I2C_DEV_t *i2c_dev,
uint16_t *hold_time);
/*!
* Sets the configured value for the SDA hold time in terms of I2C controller
* clock (\ref ALT_CLK_L4_SP) clock ticks.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param hold_time
* The SDA hold time in \ref ALT_CLK_L4_SP clock ticks.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_SDA_HOLD is 16 bits wide. hold_time must be in range 0..65535.
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_sda_hold_time_set(ALT_I2C_DEV_t *i2c_dev,
const uint16_t hold_time);
/*! @} */
/*!
* Gets the current operational mode of the I2C controller.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param mode
* [out] The current operational mode enabled for the I2C
* controller.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_op_mode_get(ALT_I2C_DEV_t *i2c_dev,
ALT_I2C_MODE_t* mode);
/*!
* Sets the operational mode of the I2C controller.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param mode
* The operational mode to enable for the I2C controller.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_op_mode_set(ALT_I2C_DEV_t *i2c_dev,
const ALT_I2C_MODE_t mode);
/*!
* 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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_STATUS.ACTIVITY == 1
* NOTE: IC_STATUS[0] that is, the ACTIVITY bit is the OR of SLV_ACTIVITY and
* MST_ACTIVITY bits.
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_is_busy(ALT_I2C_DEV_t *i2c_dev);
/*!
* 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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param val
* [out] The single data byte read from the receive FIFO.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_read(ALT_I2C_DEV_t *i2c_dev, 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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param val
* The data byte to write to the transmission FIFO.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_write(ALT_I2C_DEV_t *i2c_dev, const uint8_t val);
/*!
* 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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param data
* [out] A pointer to a buffer to contain the received data byte.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
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-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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param data
* The data byte to transmit.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
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 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 \e
* n bytes, then when another master request for data is received, the TX FIFO
* could be written with \e 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 \e n bytes from the slave but the programmer
* wrote a number of bytes larger than \e n to the TX FIFO, then when the slave
* finishes sending the requested \e 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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param data
* A pointer to the data buffer to transmit.
*
* \param size
* The size of the data buffer in bytes to place in the TX FIFO.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* See: Section Slave-Transfer Operation for Bulk Transfers of the DW
* Databook for details of implementation and error conditions that may occur.
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_slave_bulk_transmit(ALT_I2C_DEV_t *i2c_dev,
const void * data,
const size_t size);
/*!
* This function returns the current target address.
*
* The I2C controller must be in master mode before calling this function.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param target_addr
* [out] The 7 or 10 bit slave target address.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code.
*/
ALT_STATUS_CODE alt_i2c_master_target_get(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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param target_addr
* The 7 or 10 bit slave target address.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code.
*/
ALT_STATUS_CODE alt_i2c_master_target_set(ALT_I2C_DEV_t * i2c_dev, uint32_t target_addr);
/*!
* 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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param data
* A pointer to a data buffer to transmit
*
* \param size
* The size of the data buffer in bytes to place in the TX FIFO.
*
* \param issue_restart
* This parameter controls whether a RESTART is issued before the
* byte is sent or received. If:
* * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
* is \b 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
* \e restart_enabled is \b false, a STOP followed by a START is
* issued instead.
* * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
* is \b true, a RESTART is issued only if the transfer direction
* is changing from the previous command; if \e restart_enabled is
* \b false, a STOP followed by a START is issued instead.
*
* \param issue_stop
* This parameter controls whether a STOP is issued after the byte is
* sent or received. If:
* * \b 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.
* * \b 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.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
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-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 \e issue_restart and \e issue_stop parameters apply to the final read
* request transaction in the \e 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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param data
* [out] The data buffer to receive the requested \e size bytes.
*
* \param size
* The size of the data buffer to read from the RX FIFO.
*
* \param issue_restart
* This parameter controls whether a RESTART is issued before the
* byte is sent or received. If:
* * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
* is \b 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
* \e restart_enabled is \b false, a STOP followed by a START is
* issued instead.
* * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
* is \b true, a RESTART is issued only if the transfer direction
* is changing from the previous command; if \e restart_enabled is
* \b false, a STOP followed by a START is issued instead.
*
* \param issue_stop
* This parameter controls whether a STOP is issued after the byte is
* sent or received. If:
* * \b 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.
* * \b 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.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
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 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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param issue_restart
* This parameter controls whether a RESTART is issued before the
* byte is sent or received. If:
* * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
* is \b 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
* \e restart_enabled is \b false, a STOP followed by a START is
* issued instead.
* * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
* is \b true, a RESTART is issued only if the transfer direction
* is changing from the previous command; if \e restart_enabled is
* \b false, a STOP followed by a START is issued instead.
*
* \param issue_stop
* This parameter controls whether a STOP is issued after the byte is
* sent or received. If:
* * \b 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.
* * \b 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.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* Write IC_DATA_CMD.CMD = 1 (read request). IC_DATA_CMD.DAT is
* written with "don't care" values as these bits are ignored by the
* I2C controller .
* \endinternal
*/
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 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.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param value
* The data item to be transmitted.
*
* \param issue_restart
* This parameter controls whether a RESTART is issued before the
* byte is sent or received. If:
* * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
* is \b 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
* \e restart_enabled is \b false, a STOP followed by a START is
* issued instead.
* * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
* is \b true, a RESTART is issued only if the transfer direction
* is changing from the previous command; if \e restart_enabled is
* \b false, a STOP followed by a START is issued instead.
*
* \param issue_stop
* This parameter controls whether a STOP is issued after the byte is
* sent or received. If:
* * \b 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.
* * \b 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.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* Write IC_DATA_CMD.CMD = 0 (write request).
* \endinternal
*/
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);
/******************************************************************************/
/*! \addtogroup ALT_I2C_GEN_CALL General Call
*
* The functions in this group support General Call addresses.
*
* The general call address is for addressing every device connected to the I2C
* bus at the same time. However, if a device does not need any of the data
* supplied within the general call structure, it can ignore this address by not
* issuing an acknowledgment. If a device does require data from a general call
* address, it acknowledges this address and behaves as a slave-receiver. The
* master does not actually know how many devices acknowledged if one or more
* devices respond. The second and following bytes are acknowledged by every
* slave-receiver capable of handling this data. A slave who cannot process one of
* these bytes must ignore it by not-acknowledging. If one or more slaves
* acknowledge, the not-acknowledge will not be seen by the master.
*
* The functions in this group do not provide any general call functional command
* interpretation or implementation (e.g. software reset).
*
* @{
*/
/*!
* This function acts in the role of a master-transmitter by issuing a general
* call command to all devices connected to the I2C bus.
*
* The \e issue_restart and \e issue_stop parameters apply to the final write
* transaction in the \e num_data_entries byte transmission sequence.
*
* The I2C controller must be in master mode before calling this function.
*
* The target slave address will be modified by this function. Call
* alt_i2c_master_target_set() to reset the slave target address for
* subsequent IO.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param data
* An array of data byte(s) to transmit.
*
* \param num_data_entries
* The number of entries (bytes) in \e data to place in the TX FIFO.
*
* \param issue_restart
* This parameter controls whether a RESTART is issued before the
* byte is sent or received. If:
* * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
* is \b 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
* \e restart_enabled is \b false, a STOP followed by a START is
* issued instead.
* * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
* is \b true, a RESTART is issued only if the transfer direction
* is changing from the previous command; if \e restart_enabled is
* \b false, a STOP followed by a START is issued instead.
*
* \param issue_stop
* This parameter controls whether a STOP is issued after the byte is
* sent or received. If:
* * \b 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.
* * \b 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.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_master_general_call(ALT_I2C_DEV_t *i2c_dev,
const void * data,
const size_t size,
const bool issue_restart,
const bool issue_stop);
/*!
* Disables the I2C controller from responding to a General Call address. The
* controller will respond with a NACK and no General Call status conditions or
* interrupts are generated.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_ACK_GENERAL_CALL.ACK_GEN_CALL = 0
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_general_call_ack_disable(ALT_I2C_DEV_t *i2c_dev);
/*!
* Enables the I2C controller to respond with an ACK when it receives a General
* Call address.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_ACK_GENERAL_CALL.ACK_GEN_CALL = 1
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_general_call_ack_enable(ALT_I2C_DEV_t *i2c_dev);
/*!
* Returns ALT_E_TRUE if the I2C controller is enabled to respond to General Call
* addresses.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_ACK_GENERAL_CALL.ACK_GEN_CALL == 1
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_general_call_ack_is_enabled(ALT_I2C_DEV_t *i2c_dev);
/*! @} */
/******************************************************************************/
/*! \addtogroup ALT_I2C_INT Interrupt and Status Conditions
*
* The functions in this group provide management for the I2C controller status
* conditions and interrupts.
*
* Each I2C controller has a single combined interrupt output (\b
* ALT_INT_INTERRUPT_I2Cn_IRQ). The following events can generate an
* interrupt:
* * General Call Address Received
* * Start or Restart Condition Occurred
* * Stop Condition Occurred
* * I2C Controller Activity
* * Receive Done
* * Transmit Abort
* * Read Request
* * Transmit Buffer Empty
* * Transmit Overflow
* * Receive Buffer Full
* * Receive Overflow
* * Receive Underflow
*
* These interrupt status conditions may be monitored either by polling their
* status or by configuring interrupt handlers using the HWLIB Interrupt
* Controller API.
*
* Functions to get the current status, enable or disable (i.e. mass or unmask),
* and clear interrupt status conditions for the I2C controller are defined in
* this section.
*
* @{
*/
/*!
* Returns the current I2C controller interrupt status conditions.
*
* This function returns the current value of the I2C controller interrupt status
* register value which reflects the current I2C controller status conditions that
* are not disabled (i.e. masked).
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param status
* [out] A pointer to a bit mask of the active \ref ALT_I2C_STATUS_t
* interrupt and status conditions.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_INTR_STAT
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_int_status_get(ALT_I2C_DEV_t *i2c_dev,
uint32_t *status);
/*!
* Returns the I2C controller raw interrupt status conditions irrespective of
* the interrupt status condition enablement state.
*
* This function returns the current value of the I2C controller raw interrupt
* status register value which reflects the current I2C controller status
* conditions regardless of whether they are disabled (i.e. masked) or not.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param status
* [out] A pointer to a bit mask of the active \ref ALT_I2C_STATUS_t
* interrupt and status conditions.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_INTR_STAT
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_int_raw_status_get(ALT_I2C_DEV_t *i2c_dev,
uint32_t *status);
/*!
* Clears the specified I2C controller interrupt status conditions identified
* in the mask.
*
* This function clears one or more of the status conditions as contributors to
* the \b ALT_INT_INTERRUPT_I2Cn_IRQ interrupt signal state.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param mask
* Specifies the QSPI interrupt status conditions to clear. \e mask
* is a mask of logically OR'ed \ref ALT_I2C_STATUS_t values that
* designate the status conditions to clear.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_int_clear(ALT_I2C_DEV_t *i2c_dev, const uint32_t mask);
/*!
* Disable the specified I2C controller interrupt status conditions identified in
* the mask.
*
* This function disables one or more of the status conditions as contributors to
* the \b ALT_INT_INTERRUPT_I2Cn_IRQ interrupt signal state.
*
* NOTE: A cleared bit for any status condition in the mask value does not have
* the effect of enabling it as a contributor to the \b
* ALT_INT_INTERRUPT_I2Cn_IRQ interrupt signal state. The function
* alt_i2c_int_enable() is used to enable status source conditions.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param mask
* Specifies the status conditions to disable as interrupt source
* contributors. \e mask is a mask of logically OR'ed \ref
* ALT_I2C_STATUS_t values that designate the status conditions to
* disable.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_int_disable(ALT_I2C_DEV_t *i2c_dev, const uint32_t mask);
/*!
* Enable the specified I2C controller interrupt status conditions identified in
* the mask.
*
* This function enables one or more of the status conditions as contributors to
* the \b ALT_INT_INTERRUPT_I2Cn_IRQ interrupt signal state.
*
* NOTE: A cleared bit for any status condition in the mask value does not have
* the effect of disabling it as a contributor to the \b
* ALT_INT_INTERRUPT_I2Cn_IRQ interrupt signal state. The function
* alt_i2c_int_disable() is used to disable status source conditions.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param mask
* Specifies the status conditions to enable as interrupt source
* contributors. \e mask is a mask of logically OR'ed \ref
* ALT_I2C_STATUS_t values that designate the status conditions to
* enable.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_int_enable(ALT_I2C_DEV_t *i2c_dev, const uint32_t mask);
/*!
* Gets the cause of I2C transmission abort. A I2C transmission abort indicates
* that the 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".
*
* The returned value of this function is the value of the IC_TX_ABRT_SOURCE
* register which indicates the cause why the transmit abort occurred.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param cause
* [out] A pointer to a bit mask of the \ref ALT_I2C_TX_ABORT_CAUSE_t
* causes of the transmission abort.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_TX_ABRT_SOURCE
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_tx_abort_cause_get(ALT_I2C_DEV_t *i2c_dev,
ALT_I2C_TX_ABORT_CAUSE_t *cause);
/*! @} */
/******************************************************************************/
/*! \addtogroup ALT_I2C_RX_FIFO RX FIFO Management
*
* The receive FIFO has a configurable threshold value that controls the level of
* entries (or above) that sets the RX_FULL status condition and triggers an
* interrupt. The valid range is 0 - (ALT_I2C_RX_FIFO_NUM_ENTRIES-1), with the
* additional restriction that I2C controller does not allow this value to be set
* to a value larger than the depth of the buffer. If an attempt is made to do
* that, the actual value set will be the maximum depth of the buffer. A value of
* 0 sets the threshold for 1 entry, and a value of (ALT_I2C_RX_FIFO_NUM_ENTRIES-1)
* sets the threshold for ALT_I2C_RX_FIFO_NUM_ENTRIES entries.
*
* @{
*/
/*!
* The number of entries (depth) of the I2C controller receive FIFO.
*/
#define ALT_I2C_RX_FIFO_NUM_ENTRIES 64
/*!
* Returns ALT_E_TRUE when the receive FIFO is empty.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_STATUS.RFNE == 0
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_rx_fifo_is_empty(ALT_I2C_DEV_t *i2c_dev);
/*!
* Returns ALT_E_TRUE when the receive FIFO is completely full.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_STATUS.RFF == 1
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_rx_fifo_is_full(ALT_I2C_DEV_t *i2c_dev);
/*!
* Returns the number of valid entries in the receive FIFO.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param num_entries
* [out] The number of entries in the receive FIFO.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_RXFLR.RXFLR
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_rx_fifo_level_get(ALT_I2C_DEV_t *i2c_dev,
uint32_t *num_entries);
/*!
* Gets the current receive FIFO threshold level value.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param threshold
* [out] The current threshold value.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_RX_TL.RX_TL
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_rx_fifo_threshold_get(ALT_I2C_DEV_t *i2c_dev,
uint8_t *threshold);
/*!
* Sets the current receive FIFO threshold level value.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param threshold
* The threshold value.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_RX_TL.RX_TL = threshold
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_rx_fifo_threshold_set(ALT_I2C_DEV_t *i2c_dev,
const uint8_t threshold);
/*! @} */
/******************************************************************************/
/*! \addtogroup ALT_I2C_TX_FIFO TX FIFO Management
*
* The transmit FIFO has a configurable threshold value that controls the level of
* entries (or below) that sets the TX_EMPTY status condition and triggers an
* interrupt. The valid range is 0 - (ALT_I2C_TX_FIFO_NUM_ENTRIES-1), with the
* additional restriction that I2C controller does not allow this value to be set
* to a value larger than the depth of the buffer. If an attempt is made to do
* that, the actual value set will be the maximum depth of the buffer. A value of
* 0 sets the threshold for 0 entries, and a value of (ALT_I2C_TX_FIFO_NUM_ENTRIES-1)
* sets the threshold for (ALT_I2C_TX_FIFO_NUM_ENTRIES-1) entries.
*
* @{
*/
/*!
* The number of entries (depth) of the I2C controller transmit FIFO.
*/
#define ALT_I2C_TX_FIFO_NUM_ENTRIES 64
/*!
* Returns ALT_E_TRUE when the transmit FIFO is empty.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_STATUS.TFE == 1
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_tx_fifo_is_empty(ALT_I2C_DEV_t *i2c_dev);
/*!
* Returns ALT_E_TRUE when the transmit FIFO is completely full.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_STATUS.TFNF == 0
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_tx_fifo_is_full(ALT_I2C_DEV_t *i2c_dev);
/*!
* Returns the number of valid entries in the transmit FIFO.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param num_entries
* [out] The number of entries in the transmit FIFO.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_TXFLR.TXFLR
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_tx_fifo_level_get(ALT_I2C_DEV_t *i2c_dev,
uint32_t *num_entries);
/*!
* Gets the current transmit FIFO threshold level value.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param threshold
* [out] The current threshold value.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_TX_TL.TX_TL
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_tx_fifo_threshold_get(ALT_I2C_DEV_t *i2c_dev,
uint8_t *threshold);
/*!
* Sets the current transmit FIFO threshold level value.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param threshold
* The threshold value.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*
* \internal
* IC_TX_TL.TX_TL = threshold
* \endinternal
*/
ALT_STATUS_CODE alt_i2c_tx_fifo_threshold_set(ALT_I2C_DEV_t *i2c_dev,
const uint8_t threshold);
/*! @} */
/******************************************************************************/
/*! \addtogroup ALT_I2C_DMA DMA Interface
*
* The DMA interface has a configurable threshold value that controls the
* level of entries that triggers the burst handshaking request used for DMA
* integration.
*
* For the TX threshold, if the number of entries in the TX FIFO is at or
* below the set threshold, a DMA handshaking request will be made. The valid
* range for the TX threshold is 0 - (ALT_I2C_TX_FIFO_NUM_ENTRIES - 1).
*
* For the RX threshold, if the number of entries in the RX FIFO is above the
* set threshold, a DMA handshaking request will be made. The valid range for
* the RX treshold is 0 - (ALT_I2C_TX_FIFO_NUM_ENTRIES - 1).
*
* Having a higher threshold can improve the AXI bus utilization at the
* expense of the likelyhoold of overflow / underflow conditions.
* @{
*/
/*!
* Gets the current RX DMA threshold level value.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param threshold
* [out] The threshold value.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*/
ALT_STATUS_CODE alt_i2c_rx_dma_threshold_get(ALT_I2C_DEV_t * i2c_dev, uint8_t * threshold);
/*!
* Sets the current RX DMA threshold level value.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param threshold
* The threshold value.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*/
ALT_STATUS_CODE alt_i2c_rx_dma_threshold_set(ALT_I2C_DEV_t * i2c_dev, uint8_t threshold);
/*!
* Gets the current TX DMA threshold level value.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param threshold
* [out] The threshold value.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*/
ALT_STATUS_CODE alt_i2c_tx_dma_threshold_get(ALT_I2C_DEV_t * i2c_dev, uint8_t * threshold);
/*!
* Sets the current TX DMA threshold level value.
*
* \param i2c_dev
* A pointer to the I2C controller device block instance.
*
* \param threshold
* The threshold value.
*
* \retval ALT_E_SUCCESS Successful status.
* \retval ALT_E_ERROR Details about error status code
*/
ALT_STATUS_CODE alt_i2c_tx_dma_threshold_set(ALT_I2C_DEV_t * i2c_dev, uint8_t threshold);
/*! @} */
/*! @} */
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* __ALT_I2C_H__ */