diff options
Diffstat (limited to 'c/src/lib/libbsp/arm/altera-cyclone-v/hwlib/include/alt_i2c.h')
| -rw-r--r-- | c/src/lib/libbsp/arm/altera-cyclone-v/hwlib/include/alt_i2c.h | 2024 |
1 files changed, 0 insertions, 2024 deletions
diff --git a/c/src/lib/libbsp/arm/altera-cyclone-v/hwlib/include/alt_i2c.h b/c/src/lib/libbsp/arm/altera-cyclone-v/hwlib/include/alt_i2c.h deleted file mode 100644 index 7af55cf4ac..0000000000 --- a/c/src/lib/libbsp/arm/altera-cyclone-v/hwlib/include/alt_i2c.h +++ /dev/null @@ -1,2024 +0,0 @@ -/****************************************************************************** -* -* 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: - * * <em>Cyclone V Device Handbook Volume 3: Hard Processor System Technical - * Reference Manual, Chapter 20. I2C Controller (cv_54020-1.2)</em> - * * <em>Synopsys DesignWare DW_apb_i2c Databook DW_apb_i2c, Version 1.15a</em> - * * <em>The I2C-Bus Specification Version 2.1</em> - * - * @{ - */ - -/******************************************************************************/ -/*! - * 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 <em>Chapter 20. I2C - * Controller</em> in the <em>Cyclone V Device Handbook Volume 3: Hard - * Processor System Technical Reference Manual</em> 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 <em>Slave-Transfer Operation for Bulk Transfers</em> 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_I2C<em>n</em>_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_I2C<em>n</em>_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_I2C<em>n</em>_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_I2C<em>n</em>_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_I2C<em>n</em>_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_I2C<em>n</em>_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__ */ |