| /****************************************************************************** | |
| * | |
| * 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__ */ |