LXR |
|
|
|
|||
File indexing completed on 2025-05-11 08:22:44
0001 /** 0002 * @file 0003 * 0004 * @ingroup RTEMSBSPsARMCycVContrib 0005 */ 0006 0007 /****************************************************************************** 0008 * 0009 * Copyright 2013 Altera Corporation. All Rights Reserved. 0010 * 0011 * Redistribution and use in source and binary forms, with or without 0012 * modification, are permitted provided that the following conditions are met: 0013 * 0014 * 1. Redistributions of source code must retain the above copyright notice, 0015 * this list of conditions and the following disclaimer. 0016 * 0017 * 2. Redistributions in binary form must reproduce the above copyright notice, 0018 * this list of conditions and the following disclaimer in the documentation 0019 * and/or other materials provided with the distribution. 0020 * 0021 * 3. The name of the author may not be used to endorse or promote products 0022 * derived from this software without specific prior written permission. 0023 * 0024 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR 0025 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 0026 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO 0027 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 0028 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 0029 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 0030 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 0031 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 0032 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 0033 * OF SUCH DAMAGE. 0034 * 0035 ******************************************************************************/ 0036 0037 /*! \file 0038 * Altera - I2C Controller API 0039 */ 0040 0041 #ifndef __ALT_I2C_H__ 0042 #define __ALT_I2C_H__ 0043 0044 #include "hwlib.h" 0045 #include "alt_clock_manager.h" 0046 #include "socal/alt_i2c.h" 0047 #include "socal/alt_rstmgr.h" 0048 #include "socal/hps.h" 0049 #include "socal/socal.h" 0050 0051 #ifdef __cplusplus 0052 extern "C" 0053 { 0054 #endif /* __cplusplus */ 0055 0056 /******************************************************************************/ 0057 /*! \addtogroup ALT_I2C I2C Controller API 0058 * 0059 * This module defines an API for configuring and managing the HPS I2C controllers. 0060 * 0061 * The I2C controller provides support for a communication link between integrated 0062 * circuits on a board. It is a simple two-wire bus which consists of a serial 0063 * data line (SDA) and a serial clock (SCL) for use in applications such as 0064 * temperature sensors and voltage level translators to EEPROMs, A/D and D/A 0065 * converters, CODECs, and many types of microprocessors. 0066 * 0067 * The Hard Processor System (HPS) provides four I2C controllers to enable system 0068 * software to communicate serially with I2C buses. Each I2C controller can 0069 * operate in master or slave mode, and support standard mode of up to 100 0070 * kilobits per second (Kbps) or fast mode of up to 400 Kbps. These I2C 0071 * controllers are instances of the Synopsys DesignWare APB I2C (DW_apb_i2c) 0072 * controller. 0073 * 0074 * NOTE: Each I2C controller must be programmed to operate in either master or 0075 * slave mode only. Operating as a master and slave simultaneously is not 0076 * supported. 0077 * 0078 * Features of the I2C Controller: 0079 * * Support both 100 KBps and 400 KBps modes 0080 * * One of the following I2C operations: master or slave 0081 * * Support both 7-bit and 10-bit addressing modes 0082 * * Mixed read and write combined-format transactions 0083 * * Bulk transmit mode 0084 * * DMA handshaking interface 0085 * 0086 * For a complete details on the configuration and operation of I2C controller, 0087 * consult the following references: 0088 * * <em>Cyclone V Device Handbook Volume 3: Hard Processor System Technical 0089 * Reference Manual, Chapter 20. I2C Controller (cv_54020-1.2)</em> 0090 * * <em>Synopsys DesignWare DW_apb_i2c Databook DW_apb_i2c, Version 1.15a</em> 0091 * * <em>The I2C-Bus Specification Version 2.1</em> 0092 * 0093 * @{ 0094 */ 0095 0096 /******************************************************************************/ 0097 /*! 0098 * This type definition enumerates the operational state of I2C by 0099 * transfer operation. 0100 */ 0101 typedef enum ALT_I2C_TRANSFER_TYPE_e 0102 { 0103 ALT_I2C_TRANSFER_NONE = 0, /*!< No transfer operation */ 0104 ALT_I2C_TRANSFER_START = 1, /*!< Start detect */ 0105 ALT_I2C_TRANSFER_COMPLETE = 2, /*!< All operations done */ 0106 ALT_I2C_TRANSFER_READ = 3, /*!< Read operation is active */ 0107 ALT_I2C_TRANSFER_WRITE = 4, /*!< Write operation is active */ 0108 } 0109 ALT_I2C_TRANSFER_TYPE_t; 0110 0111 0112 /* 0113 * A pointer or handle to the I2C controller device instance. The ALT_I2C_DEV_t is 0114 * initialized by a call to alt_i2c_init() and subsequently used by the other I2C 0115 * controller API functions as a reference to a specific device. 0116 * 0117 * \internal 0118 * ALT_I2C_DEV_t may be a struct or reference to an opaque data 0119 * structure. Whatever "internal" type is suited to the needs of the 0120 * implementation. 0121 * \endinternal 0122 */ 0123 typedef struct ALT_I2C_DEV_s 0124 { 0125 void * location; /*!< HPS address of I2C instance. */ 0126 alt_freq_t clock_freq; /*!< Input clock frequency. */ 0127 uint32_t last_target; /*!< Last issued target address. */ 0128 } 0129 ALT_I2C_DEV_t; 0130 0131 /*! 0132 * This type enumerates the HPS I2C controller instances. 0133 */ 0134 typedef enum ALT_I2C_CTLR_e 0135 { 0136 ALT_I2C_I2C0 = (int)ALT_I2C0_OFST, /*!< I2C0 instance. */ 0137 ALT_I2C_I2C1 = (int)ALT_I2C1_OFST, /*!< I2C1 instance. */ 0138 ALT_I2C_I2C2 = (int)ALT_I2C2_OFST, /*!< I2C2 instance. */ 0139 ALT_I2C_I2C3 = (int)ALT_I2C3_OFST, /*!< I2C3 instance. */ 0140 } ALT_I2C_CTLR_t; 0141 0142 /*! 0143 * This type enumerates the modes that the I2C controller may operate in. 0144 * 0145 * NOTE: Each I2C controller must be programmed to operate in either master or 0146 * slave mode only. Operating as a master and slave simultaneously is not 0147 * supported. 0148 */ 0149 typedef enum ALT_I2C_MODE_e 0150 { 0151 ALT_I2C_MODE_SLAVE = ALT_I2C_CON_MST_MOD_E_DIS, /*!< Slave Mode */ 0152 ALT_I2C_MODE_MASTER = ALT_I2C_CON_MST_MOD_E_EN /*!< Master Mode */ 0153 } ALT_I2C_MODE_t; 0154 0155 /*! 0156 * This type enumerates the I2C controller operational speed modes. 0157 * 0158 * The I2C controller can operate in standard mode (with data rates 0 to 100 Kbps) 0159 * or fast mode (with data rates less than or equal to 400 Kbps). Additionally, 0160 * fast mode devices are downward compatible. For instance, fast mode devices can 0161 * communicate with standard mode devices in 0 to 100 Kbps I2C bus 0162 * system. However, standard mode devices are not upward compatible and should not 0163 * be incorporated in a fast-mode I2C bus system as they cannot follow the higher 0164 * transfer rate and therefore unpredictable states would occur. 0165 * 0166 * This setting is relevant only if one is operating the I2C in master mode. 0167 */ 0168 typedef enum ALT_I2C_SPEED_e 0169 { 0170 ALT_I2C_SPEED_STANDARD = ALT_I2C_CON_SPEED_E_STANDARD, 0171 /*!< Standard mode (0 to 100 Kbps) */ 0172 ALT_I2C_SPEED_FAST = ALT_I2C_CON_SPEED_E_FAST 0173 /*!< Fast mode (<= 400 Kbps) */ 0174 } ALT_I2C_SPEED_t; 0175 0176 /*! 0177 * This type enumerates the two addressing modes formats supported by the I2C 0178 * controller. 0179 * 0180 * The I2C controller does not support mixed address format - that is, a 7-bit 0181 * address transaction followed by a 10-bit address transaction or vice versa - 0182 * combined format transactions. 0183 */ 0184 typedef enum ALT_I2C_ADDR_MODE_e 0185 { 0186 ALT_I2C_ADDR_MODE_7_BIT = ALT_I2C_TAR_IC_10BITADDR_MST_E_START7, 0187 /*!< 7-Bit Address Format */ 0188 ALT_I2C_ADDR_MODE_10_BIT = ALT_I2C_TAR_IC_10BITADDR_MST_E_START10 0189 /*!< 10-Bit Address Format */ 0190 } ALT_I2C_ADDR_MODE_t; 0191 0192 /*! 0193 * This type enumerates interrupt status conditions for the I2C controller. 0194 */ 0195 typedef enum ALT_I2C_STATUS_e 0196 { 0197 ALT_I2C_STATUS_RX_UNDER = 1UL << 0, 0198 /*!< Set if the processor attempts to read the 0199 * receive buffer when it is empty. If the I2C 0200 * controller is disabled, this status keeps 0201 * maintains its state until the master or slave 0202 * state machines go into idle, then this 0203 * interrupt is cleared. 0204 */ 0205 ALT_I2C_STATUS_RX_OVER = 1UL << 1, 0206 /*!< Set if the receive buffer is completely 0207 * filled to capacity and an additional byte is 0208 * received from an external I2C device. The I2C 0209 * controller acknowledges this, but any data 0210 * bytes received after the FIFO is full are 0211 * discarded. If the I2C controller is disabled, 0212 * this status maintains its statue until the 0213 * master or slave state machines go into idle, 0214 * then this interrupt is cleared. 0215 */ 0216 ALT_I2C_STATUS_RX_FULL = 1UL << 2, 0217 /*!< Set when the receive buffer reaches or goes 0218 * above the RX_TL threshold. It is 0219 * automatically cleared by hardware when buffer 0220 * level goes below the threshold. If the I2C 0221 * controller is disabled, the RX FIFO is 0222 * flushed and held in reset; therefore the RX 0223 * FIFO is not full. So this bit is cleared once 0224 * the I2C controller is disabled, regardless of 0225 * the activity that continues. 0226 */ 0227 ALT_I2C_STATUS_TX_OVER = 1UL << 3, 0228 /*!< Set during transmit if the transmit buffer is 0229 * filled to capacity and the processor attempts 0230 * to issue another I2C command. When the I2C 0231 * controller is disabled, this bit maintains 0232 * its state until the master or slave state 0233 * machines go into idle, then this interrupt is 0234 * cleared. 0235 */ 0236 ALT_I2C_STATUS_TX_EMPTY = 1UL << 4, 0237 /*!< This bit is set to 1 when the transmit buffer 0238 * is at or below the configured threshold 0239 * value. It is automatically cleared by 0240 * hardware when the buffer level goes above the 0241 * threshold. When the I2C controller is 0242 * disabled, the TX FIFO is flushed and held in 0243 * reset. The TX FIFO appears as if it has no 0244 * data in it, so this bit is set to 1, provided 0245 * there is activity in the master or slave 0246 * state machines. When there is no longer 0247 * activity, then this bit is set to 0. 0248 * 0249 */ 0250 ALT_I2C_STATUS_RD_REQ = 1UL << 5, 0251 /*!< This bit is set to 1 when I2C is acting as a 0252 * slave and another I2C master is attempting to 0253 * read data from the I2C. The I2C holds the bus 0254 * in a wait state until this interrupt is 0255 * serviced, which means that the slave has been 0256 * addressed by a remote master that is asking 0257 * for data to be transferred. The processor 0258 * must respond to this interrupt and then write 0259 * the requested data. This bit is set to 0 just 0260 * after the processor by calling 0261 * alt_i2c_int_clear() with 0262 * ALT_I2C_STATUS_RD_REQ in the mask.. 0263 */ 0264 ALT_I2C_STATUS_TX_ABORT = 1UL << 6, 0265 /*!< This bit indicates if I2C, as an I2C 0266 * transmitter, is unable to complete the 0267 * intended actions on the contents of the 0268 * transmit FIFO. This situation can occur both 0269 * as an I2C master or an I2C slave, and is 0270 * referred to as a 'transmit abort'. When this 0271 * bit is set to 1, the IC_TX_ABRT_SOURCE 0272 * register indicates the reason why the 0273 * transmit abort takes places. 0274 * 0275 * NOTE: The I2C flushes/resets/empties the TX 0276 * FIFO whenever this bit is set. The TX FIFO 0277 * remains in this flushed state until the 0278 * register alt_i2c_int_clear() with 0279 * ALT_I2C_STATUS_TX_ABORT in the mask is 0280 * called. Once this happens, the TX FIFO is 0281 * then ready to accept more data bytes from the 0282 * APB interface. 0283 */ 0284 ALT_I2C_STATUS_RX_DONE = 1UL << 7, 0285 /*!< When the I2C is acting as a 0286 * slave-transmitter, this bit is set to 1 if 0287 * the master does not acknowledge a transmitted 0288 * byte. This occurs on the last byte of the 0289 * transmission, indicating that the 0290 * transmission is done. 0291 */ 0292 ALT_I2C_STATUS_ACTIVITY = 1UL << 8, 0293 /*!< This bit captures I2C activity and stays set 0294 * until it is cleared. There are four ways to 0295 * clear it: 0296 * * Disabling the I2C controller 0297 * * Calling alt_i2c_int_clear() with 0298 * ALT_I2C_STATUS_ACTIVITY in the mask. 0299 * * Calling alt_i2c_int_clear() with 0300 * ALT_I2C_STATUS_ALL in the mask. 0301 * * System reset 0302 * 0303 * Once this bit is set, it stays set unless one 0304 * of the four methods is used to clear it. Even 0305 * if the I2C module is idle, this bit remains 0306 * set until cleared, indicating that there was 0307 * activity on the bus. 0308 */ 0309 ALT_I2C_STATUS_STOP_DET = 1UL << 9, 0310 /*!< Indicates whether a STOP condition has 0311 * occurred on the I2C interface regardless of 0312 * whether I2C is operating in slave or master 0313 * mode. 0314 */ 0315 ALT_I2C_STATUS_START_DET = 1UL << 10, 0316 /*!< Indicates whether a START or RESTART 0317 * condition has occurred on the I2C interface 0318 * regardless of whether I2C is operating in 0319 * slave or master mode. 0320 */ 0321 ALT_I2C_STATUS_INT_CALL = 1UL << 11, 0322 /*!< Set only when a General Call address is 0323 * received and it is acknowledged. It stays set 0324 * until it is cleared either by disabling I2C 0325 * or when alt_i2c_int_clear() with 0326 * ALT_I2C_STATUS_CALL in the mask is 0327 * called. I2C stores the received data in the 0328 * Rx buffer. 0329 */ 0330 ALT_I2C_STATUS_INT_ALL = 0xFFF, 0331 /*!< All Combined and Individual Interrupts. This 0332 * enumeration value can be used to clear, 0333 * disable, and enable the combined interrupt 0334 * and all individual interrupt status 0335 * conditions. As a side effect, when passed to 0336 * alt_i2c_int_clear(), clears the source causes 0337 * (\ref ALT_I2C_TX_ABORT_CAUSE_t) of the 0338 * ALT_I2C_STATUS_TX_ABORT condition. 0339 */ 0340 } ALT_I2C_STATUS_t; 0341 0342 /*! 0343 * This type enumerates the source causes of a ALT_I2C_STATUS_TX_ABORT condition. 0344 * 0345 * The active ALT_I2C_TX_ABORT_CAUSE_t source conditions are cleared when 0346 * alt_i2c_int_clear() with is called ALT_I2C_STATUS_TX_ABORT in the mask or 0347 * alt_i2c_int_clear() is called with ALT_I2C_STATUS_ALL in the mask. 0348 * 0349 * \internal 0350 * Discuss special handling of abrt_sbyte_norstrt TX_ABRT source required in ???() function. 0351 * \endinternal 0352 */ 0353 typedef enum ALT_I2C_TX_ABORT_CAUSE_e 0354 { 0355 ALT_I2C_TX_ABORT_CAUSE_7B_ADDR_NOACK = 1UL << 0, 0356 /*!< Master Abort 7 Bit Address - If set (1), 0357 * Master is in 7-bit addressing mode and the 0358 * address sent was not acknowledged by any 0359 * slave. 0360 * 0361 * Role of I2C: Master-Transmitter or 0362 * Master-Receiver 0363 */ 0364 ALT_I2C_TX_ABORT_CAUSE_10ADDR1_NOACK = 1UL << 1, 0365 /*!< Master Abort 10 Bit Address Byte 1 - If set 0366 * (1), Master is in 10-bit address mode and the 0367 * first 10-bit address byte was not 0368 * acknowledged by any slave. 0369 * 0370 * Role of I2C: Master-Transmitter or 0371 * Master-Receiver 0372 */ 0373 ALT_I2C_TX_ABORT_CAUSE_10ADDR2_NOACK = 1UL << 2, 0374 /*!< Master Abort 10 Bit Address Byte 2 - If set 0375 * (1), Master is in 10-bit address mode and the 0376 * second address byte of the 10-bit address was 0377 * not acknowledged by any slave 0378 * 0379 * Role of I2C: Master-Transmitter or 0380 * Master-Receiver 0381 */ 0382 ALT_I2C_TX_ABORT_CAUSE_TXDATA_NOACK = 1UL << 3, 0383 /*!< Master Abort TX NOACK Bit - If set (1), 0384 * Master has received an acknowledgement for 0385 * the address, but when it sent data byte(s) 0386 * following the address, it did not receive an 0387 * acknowledge from the remote slave(s). This is 0388 * a master-mode only bit. 0389 * 0390 * Role of I2C: Master-Transmitter. 0391 */ 0392 ALT_I2C_TX_ABORT_CAUSE_GCALL_NOACK = 1UL << 4, 0393 /*!< Master Abort GC Noack Bit - If set (1), I2C 0394 * controller in master mode sent a General Call 0395 * and no slave on the bus acknowledged the 0396 * General Call. 0397 * 0398 * Role of I2C: Master-Transmitter. 0399 */ 0400 ALT_I2C_TX_ABORT_CAUSE_GCALL_RD = 1UL << 5, 0401 /*!< Master Abort GC Read Bit - If set (1), I2C 0402 * controller in master mode sent a General Call 0403 * but the user programmed the byte following 0404 * the General Call to be a read from the bus 0405 * (IC_DATA_CMD[9] is set to 1). 0406 * 0407 * Role of I2C: Master-Transmitter. 0408 */ 0409 ALT_I2C_TX_ABORT_CAUSE_HS_ACKDET = 1UL << 6, 0410 /*!< Master HS MC Ack - If set (1), Master is in 0411 * High Speed mode and the High Speed Master 0412 * code was acknowledged (wrong behavior). 0413 * 0414 * Role of I2C: Master. 0415 */ 0416 ALT_I2C_TX_ABORT_CAUSE_SBYTE_ACKDET = 1UL << 7, 0417 /*!< Master Abort START Byte - If set (1), Master 0418 * has sent a START Byte and the START Byte was 0419 * acknowledged (wrong behavior). 0420 * 0421 * Role of I2C: Master. 0422 */ 0423 ALT_I2C_TX_ABORT_CAUSE_HS_NORSTRT = 1UL << 8, 0424 /*!< Master HS Restart Disabled - If set (1), the 0425 * restart is disabled (IC_RESTART_EN bit 0426 * (IC_CON[5]) = 0) and the user is trying to 0427 * use the master to transfer data in High Speed 0428 * mode. 0429 * 0430 * Role of I2C: Master-Transmitter or 0431 * Master-Receiver 0432 */ 0433 ALT_I2C_TX_ABORT_CAUSE_SBYTE_NORSTRT = 1UL << 9, 0434 /*!< Master Abort START No Restart - To clear, the 0435 * source of the ABRT_SBYTE_NORSTRT must be 0436 * fixed first; restart must be enabled 0437 * (IC_CON[5]=1), the SPECIAL bit must be 0438 * cleared (IC_TAR[11]), or the GC_OR_START bit 0439 * must be cleared (IC_TAR[10]). Once the source 0440 * of the ABRT_SBYTE_NORSTRT is fixed, then this 0441 * bit can be cleared in the same manner as 0442 * other bits in this register. If the source of 0443 * the ABRT_SBYTE_NORSTRT is not fixed before 0444 * attempting to clear this bit, bit 9 clears 0445 * for one cycle and then gets re-asserted. 0446 * 0447 * If set (1), the restart is disabled 0448 * (IC_RESTART_EN bit (IC_CON[5]) = 0) and the 0449 * user is trying to send a START Byte. 0450 * 0451 * Role of I2C: Master. 0452 */ 0453 ALT_I2C_TX_ABORT_CAUSE_10B_RD_NORSTRT = 1UL << 10, 0454 /*!< Master Abort 10 Bit No Restart - If set (1), 0455 * the restart is disabled (IC_RESTART_EN bit 0456 * (IC_CON[5]) = 0) and the master sends a read 0457 * command in 10-bit addressing mode. 0458 * 0459 * Role of I2C: Master Receiver. 0460 */ 0461 ALT_I2C_TX_ABORT_CAUSE_MST_DIS = 1UL << 11, 0462 /*!< Master Operation with Master Disabled - If set 0463 * (1), user tries to initiate a Master 0464 * operation with the Master mode disabled. 0465 * 0466 * Role of I2C: Master or Slave-Receiver. 0467 */ 0468 ALT_I2C_TX_ABORT_CAUSE_ARB_LOST = 1UL << 12, 0469 /*!< Master Abort Arbitration Lost - If set (1), 0470 * master has lost arbitration, or if 0471 * IC_TX_ABRT_SOURCE[14] is also set, then the 0472 * slave transmitter has lost arbitration. Note: 0473 * I2C can be both master and slave at the same 0474 * time. 0475 * 0476 * Role of I2C: Master or Slave-Transmitter. 0477 */ 0478 ALT_I2C_TX_ABORT_CAUSE_SLVFLUSH_TXFIFO = 1UL << 13, 0479 /*!< Slave Abort Flush TXFIFO - If set (1), Slave 0480 * has received a read command and some data 0481 * exists in the TX FIFO so the slave issues a 0482 * TX_ABRT interrupt to flush old data in TX 0483 * FIFO. 0484 * 0485 * Role of I2C: Slave-Transmitter. 0486 */ 0487 ALT_I2C_TX_ABORT_CAUSE_SLV_ARBLOST = 1UL << 14, 0488 /*!< Slave Abort Arbitration Lost - If set (1), 0489 * Slave lost the bus while transmitting data to 0490 * a remote master. IC_TX_ABRT_SOURCE[12] is set 0491 * at the same time. 0492 * 0493 * Note: Even though the slave never owns the 0494 * bus, something could go wrong on the 0495 * bus. This is a fail safe check. For instance, 0496 * during a data transmission at the low-to-high 0497 * transition of SCL, if what is on the data bus 0498 * is not what is supposed to be transmitted, 0499 * then DW_apb_i2c no longer own the bus. 0500 * 0501 * Role of I2C: Slave-Transmitter. 0502 */ 0503 ALT_I2C_TX_ABORT_CAUSE_SLVRD_INTX = 1UL << 15 0504 /*!< Slave Abort Read TX - If set (1), 0505 * when the processor side responds to a 0506 * slave mode request for data to be transmitted 0507 * to a remote master and user writes a 1 in CMD 0508 * (bit 8) of IC_DATA_CMD register. 0509 * 0510 * Role of I2C: Slave-Transmitter. 0511 */ 0512 } ALT_I2C_TX_ABORT_CAUSE_t; 0513 0514 /*! 0515 * This type defines a structure for configuration of the SCL high and low counts 0516 * to ensure proper I/O timing with the device interface. 0517 * 0518 * The SCL count values are only relevant if the I2C controller is enabled to as 0519 * an I2C master. The SCL count values are ignored when the I2C controller is 0520 * enabled as an I2C slave. 0521 * 0522 * See: Clock Frequency Configuration section of <em>Chapter 20. I2C 0523 * Controller</em> in the <em>Cyclone V Device Handbook Volume 3: Hard 0524 * Processor System Technical Reference Manual</em> for a complete discussion 0525 * of calculation of the proper SCL clock high and low times. 0526 */ 0527 typedef struct ALT_I2C_MASTER_CONFIG_s 0528 { 0529 ALT_I2C_ADDR_MODE_t addr_mode; 0530 /*!< The address mode (7 or 10 bit) when 0531 * acting as a master. 0532 */ 0533 bool restart_enable; 0534 /*!< This setting determines whether RESTART 0535 * conditions may be sent when acting as a 0536 * master. When the \e restart_enable is 0537 * false, the I2C controller master is 0538 * incapable of performing the following 0539 * functions: 0540 * * Sending a START BYTE 0541 * * Performing any high-speed mode 0542 * operation 0543 * * Performing direction changes in 0544 * combined format mode 0545 * * Performing a read operation with a 0546 * 10-bit address 0547 */ 0548 ALT_I2C_SPEED_t speed_mode; 0549 /*!< The speed mode of the I2C operation. 0550 */ 0551 uint16_t ss_scl_hcnt; 0552 /*!< The SCL clock high-period count for 0553 * standard speed. 0554 */ 0555 uint16_t ss_scl_lcnt; 0556 /*!< The SCL clock low-period count for 0557 * standard speed. 0558 */ 0559 uint16_t fs_scl_hcnt; 0560 /*!< The SCL clock high-period count for fast 0561 * speed. 0562 */ 0563 uint16_t fs_scl_lcnt; 0564 /*!< The SCL clock low-period count for fast 0565 * speed. 0566 */ 0567 uint8_t fs_spklen; 0568 /*!< The duration, measured in ic_clk cycles, 0569 * of the longest spike that is filtered out 0570 * by the spike suppression logic when the 0571 * component is operating in SS or FS modes. 0572 */ 0573 } ALT_I2C_MASTER_CONFIG_t; 0574 0575 /*! 0576 * This type defines a structure for configuration of the I2C controller when it 0577 * is operating in slave mode. 0578 */ 0579 typedef struct ALT_I2C_SLAVE_CONFIG_s 0580 { 0581 ALT_I2C_ADDR_MODE_t addr_mode; /*!< The address mode (7 or 10 bit) when 0582 * acting as a slave. 0583 */ 0584 uint32_t addr; /*!< The slave address to which the I2C 0585 * controller responds when acting as a 0586 * slave. 0587 */ 0588 bool nack_enable; /*!< Enable generation of a NACK. when the 0589 * I2C controller is a 0590 * slave-receiver. If \b true, it can 0591 * only generate a NACK after a data 0592 * byte is received; hence, the data 0593 * transfer is aborted and the data 0594 * received is not pushed onto the 0595 * receive buffer. When \b false, it 0596 * generates NACK/ACK, depending on 0597 * normal criteria. 0598 * * \b true = generate NACK after data 0599 * byte received 0600 * * \b false = generate NACK/ACK normally 0601 */ 0602 } ALT_I2C_SLAVE_CONFIG_t; 0603 0604 /*! 0605 * Initialize the specified I2C controller instance for use and return a device 0606 * handle referencing it. 0607 * 0608 * \param i2c 0609 * The HPS I2C controller instance to initialize. 0610 * 0611 * \param i2c_dev 0612 * A pointer to the I2C controller device block instance. 0613 * 0614 * \retval ALT_E_SUCCESS Successful status. 0615 * \retval ALT_E_ERROR Details about error status code 0616 * 0617 * \internal 0618 * Initialization process: 0619 * * Initialize internal driver state 0620 * * Check clock setup (ALT_CLK_L4_SP) 0621 * * Take I2C instance out of reset (System Manager) 0622 * * Disable and clear all interrupts and status conditions 0623 * * Setup and initialize any expected initial I2C controller state 0624 * \endinternal 0625 */ 0626 ALT_STATUS_CODE alt_i2c_init(const ALT_I2C_CTLR_t i2c, ALT_I2C_DEV_t *i2c_dev); 0627 0628 /*! 0629 * Reset the specified I2C controller instance for use. 0630 * 0631 * \param i2c_dev 0632 * A pointer to the I2C controller device block instance. 0633 * 0634 * \retval ALT_E_SUCCESS Successful status. 0635 * \retval ALT_E_ERROR Details about error status code 0636 * 0637 * \internal 0638 * Reset process: 0639 * * Disable controller 0640 * * Initialize internal driver state 0641 * * Check clock setup (ALT_CLK_L4_SP) 0642 * * Take I2C instance out of reset (System Manager) 0643 * * Disable and clear all interrupts and status conditions 0644 * * Setup and initialize any expected initial I2C controller state 0645 * * Enable controller 0646 * \endinternal 0647 */ 0648 ALT_STATUS_CODE alt_i2c_reset(ALT_I2C_DEV_t * i2c_dev); 0649 0650 /*! 0651 * Uninitialize the I2C controller referenced by the \e i2c_dev handle. 0652 * 0653 * This function attempts to gracefully shutdown the I2C controller by waiting for 0654 * any inpcomplete transactions to finish and then putting the I2C controller into 0655 * reset. 0656 * 0657 * \param i2c_dev 0658 * A pointer to the I2C controller device block instance. 0659 * 0660 * \retval ALT_E_SUCCESS Successful status. 0661 * \retval ALT_E_ERROR Details about error status code 0662 * 0663 * \internal 0664 * \endinternal 0665 */ 0666 ALT_STATUS_CODE alt_i2c_uninit(ALT_I2C_DEV_t *i2c_dev); 0667 0668 /*! 0669 * Disables the I2C controller. 0670 * 0671 * When the I2C controller is disabled, the following occurs: 0672 * * The TX FIFO and RX FIFO get flushed. 0673 * * The I2C interrupt status conditions remain active until the I2C controller 0674 * goes into IDLE state. 0675 * 0676 * If the controller is transmitting, it stops as well as deletes the contents of 0677 * the transmit buffer after the current transfer is complete. If the module is 0678 * receiving, the controller stops the current transfer at the end of the current 0679 * byte and does not acknowledge the transfer. 0680 * 0681 * \param i2c_dev 0682 * A pointer to the I2C controller device block instance. 0683 * 0684 * \retval ALT_E_SUCCESS Successful status. 0685 * \retval ALT_E_ERROR Details about error status code 0686 * 0687 * \internal 0688 * IC_ENABLE.ENABLE = 0 0689 * Follow the procedure in section 3.8.3 Disabling DW_apb_i2c of the DW Databook. 0690 * \endinternal 0691 */ 0692 ALT_STATUS_CODE alt_i2c_disable(ALT_I2C_DEV_t *i2c_dev); 0693 0694 /*! 0695 * Enables the I2C controller. 0696 * 0697 * \param i2c_dev 0698 * A pointer to the I2C controller device block instance. 0699 * 0700 * \retval ALT_E_SUCCESS Successful status. 0701 * \retval ALT_E_ERROR Details about error status code 0702 * 0703 * \internal 0704 * IC_ENABLE.ENABLE = 1 0705 * \endinternal 0706 */ 0707 ALT_STATUS_CODE alt_i2c_enable(ALT_I2C_DEV_t *i2c_dev); 0708 0709 /*! 0710 * Returns ALT_E_TRUE if the I2C controller is enabled. 0711 * 0712 * \param i2c_dev 0713 * A pointer to the I2C controller device block instance. 0714 * 0715 * \retval ALT_E_SUCCESS Successful status. 0716 * \retval ALT_E_ERROR Details about error status code 0717 * 0718 * \internal 0719 * IC_ENABLE.ENABLE == 1 0720 * \endinternal 0721 */ 0722 ALT_STATUS_CODE alt_i2c_is_enabled(ALT_I2C_DEV_t *i2c_dev); 0723 0724 /*! 0725 * Gets the current configuration of the I2C controller when operating in master 0726 * mode. 0727 * 0728 * \param i2c_dev 0729 * A pointer to the I2C controller device block instance. 0730 * 0731 * \param cfg 0732 * [out] Pointer to a ALT_I2C_MASTER_CONFIG_t structure for holding 0733 * the returned I2C master mode configuration parameters. 0734 * 0735 * \retval ALT_E_SUCCESS Successful status. 0736 * \retval ALT_E_ERROR Details about error status code 0737 * 0738 * \internal 0739 * \endinternal 0740 */ 0741 ALT_STATUS_CODE alt_i2c_master_config_get(ALT_I2C_DEV_t *i2c_dev, 0742 ALT_I2C_MASTER_CONFIG_t* cfg); 0743 0744 /*! 0745 * Sets the configuration of the I2C controller with operational parameters for 0746 * operating in master mode. 0747 * 0748 * \param i2c_dev 0749 * A pointer to the I2C controller device block instance. 0750 * 0751 * \param cfg 0752 * Pointer to a ALT_I2C_MASTER_CONFIG_t structure holding the desired 0753 * I2C master mode operational parameters. 0754 * 0755 * \retval ALT_E_SUCCESS Successful status. 0756 * \retval ALT_E_ERROR Details about error status code 0757 * 0758 * \internal 0759 * \endinternal 0760 */ 0761 ALT_STATUS_CODE alt_i2c_master_config_set(ALT_I2C_DEV_t *i2c_dev, 0762 const ALT_I2C_MASTER_CONFIG_t* cfg); 0763 0764 /*! 0765 * This is a utility function that returns the speed based on parameters of the 0766 * I2C master configuration. 0767 * 0768 * \param i2c_dev 0769 * A pointer to the I2C controller device block instance. 0770 * 0771 * \param cfg 0772 * A pointer to the master confugurations. 0773 * 0774 * \param speed_in_hz 0775 * [out] Speed (Hz) of the I2C bus currently configured at. 0776 * 0777 * \retval ALT_E_SUCCESS Successful status. 0778 * \retval ALT_E_ERROR Details about error status code 0779 */ 0780 ALT_STATUS_CODE alt_i2c_master_config_speed_get(ALT_I2C_DEV_t *i2c_dev, 0781 const ALT_I2C_MASTER_CONFIG_t* cfg, 0782 uint32_t * speed_in_hz); 0783 0784 /*! 0785 * This is a utility function that computes parameters for the I2C master 0786 * configuration that best matches the speed requested. 0787 * 0788 * \param i2c_dev 0789 * A pointer to the I2C controller device block instance. 0790 * 0791 * \param cfg 0792 * A pointer to the master confugurations. 0793 * 0794 * \param speed_in_hz 0795 * Speed (Hz) of the I2C bus to configure. 0796 * 0797 * \retval ALT_E_SUCCESS Successful status. 0798 * \retval ALT_E_ERROR Details about error status code 0799 * 0800 * \internal 0801 * \endinternal 0802 */ 0803 ALT_STATUS_CODE alt_i2c_master_config_speed_set(ALT_I2C_DEV_t *i2c_dev, 0804 ALT_I2C_MASTER_CONFIG_t * cfg, 0805 uint32_t speed_in_hz); 0806 0807 /*! 0808 * Definition included for backwards compatibility. 0809 */ 0810 #define alt_i2c_cfg_to_speed(i2c_dev, speed_in_hz, cfg) alt_i2c_master_config_speed_get((i2c_dev), (cfg), (speed_in_hz)) 0811 0812 /*! 0813 * Definition included for backwards compatibility. 0814 */ 0815 #define alt_i2c_speed_to_cfg(i2c_dev, speed_in_hz, cfg) alt_i2c_master_config_speed_set((i2c_dev), (cfg), (speed_in_hz)) 0816 0817 /*! 0818 * Gets the current configuration of the I2C controller when operating in slave 0819 * mode. 0820 * 0821 * \param i2c_dev 0822 * A pointer to the I2C controller device block instance. 0823 * 0824 * \param cfg 0825 * [out] Pointer to a ALT_I2C_SLAVE_CONFIG_t structure for holding 0826 * the returned I2C slave mode configuration parameters. 0827 * 0828 * \retval ALT_E_SUCCESS Successful status. 0829 * \retval ALT_E_ERROR Details about error status code 0830 * 0831 * \internal 0832 * \endinternal 0833 */ 0834 ALT_STATUS_CODE alt_i2c_slave_config_get(ALT_I2C_DEV_t *i2c_dev, 0835 ALT_I2C_SLAVE_CONFIG_t* cfg); 0836 0837 /*! 0838 * Sets the configuration of the I2C controller with operational parameters for 0839 * operating in slave mode. 0840 * 0841 * \param i2c_dev 0842 * A pointer to the I2C controller device block instance. 0843 * 0844 * \param cfg 0845 * Pointer to a ALT_I2C_SLAVE_CONFIG_t structure holding the desired 0846 * I2C slave mode operational parameters. 0847 * 0848 * \retval ALT_E_SUCCESS Successful status. 0849 * \retval ALT_E_ERROR Details about error status code 0850 * 0851 * \internal 0852 * \endinternal 0853 */ 0854 ALT_STATUS_CODE alt_i2c_slave_config_set(ALT_I2C_DEV_t *i2c_dev, 0855 const ALT_I2C_SLAVE_CONFIG_t* cfg); 0856 0857 /*! \addtogroup ALT_I2C_SDA_HOLD SDA Hold Time Configuration 0858 * 0859 * The I2C protocol specification requires 300ns of hold time on the SDA signal in 0860 * standard and fast speed modes. Board delays on the SCL and SDA signals can mean 0861 * that the hold-time requirement is met at the I2C master, but not at the I2C 0862 * slave (or vice-versa). Because each system may encounter differing board signal 0863 * delays, the I2C controller provides the capability to adjust of the SDA 0864 * hold-time. 0865 * 0866 * The functions in this section provide software configuration of SDA hold time 0867 * for the I2C controller. 0868 * 0869 * @{ 0870 */ 0871 0872 /*! 0873 * Gets the currently configured value for the SDA hold time in I2C controller 0874 * clock (\ref ALT_CLK_L4_SP) clock ticks. 0875 * 0876 * \param i2c_dev 0877 * A pointer to the I2C controller device block instance. 0878 * 0879 * \param hold_time 0880 * [out] The configured SDA hold time in \ref ALT_CLK_L4_SP clock 0881 * ticks. 0882 * 0883 * \retval ALT_E_SUCCESS Successful status. 0884 * \retval ALT_E_ERROR Details about error status code 0885 * 0886 * \internal 0887 * \endinternal 0888 */ 0889 ALT_STATUS_CODE alt_i2c_sda_hold_time_get(ALT_I2C_DEV_t *i2c_dev, 0890 uint16_t *hold_time); 0891 0892 /*! 0893 * Sets the configured value for the SDA hold time in terms of I2C controller 0894 * clock (\ref ALT_CLK_L4_SP) clock ticks. 0895 * 0896 * \param i2c_dev 0897 * A pointer to the I2C controller device block instance. 0898 * 0899 * \param hold_time 0900 * The SDA hold time in \ref ALT_CLK_L4_SP clock ticks. 0901 * 0902 * \retval ALT_E_SUCCESS Successful status. 0903 * \retval ALT_E_ERROR Details about error status code 0904 * 0905 * \internal 0906 * IC_SDA_HOLD is 16 bits wide. hold_time must be in range 0..65535. 0907 * \endinternal 0908 */ 0909 ALT_STATUS_CODE alt_i2c_sda_hold_time_set(ALT_I2C_DEV_t *i2c_dev, 0910 const uint16_t hold_time); 0911 0912 /*! @} */ 0913 0914 /*! 0915 * Gets the current operational mode of the I2C controller. 0916 * 0917 * \param i2c_dev 0918 * A pointer to the I2C controller device block instance. 0919 * 0920 * \param mode 0921 * [out] The current operational mode enabled for the I2C 0922 * controller. 0923 * 0924 * \retval ALT_E_SUCCESS Successful status. 0925 * \retval ALT_E_ERROR Details about error status code 0926 * 0927 * \internal 0928 * \endinternal 0929 */ 0930 ALT_STATUS_CODE alt_i2c_op_mode_get(ALT_I2C_DEV_t *i2c_dev, 0931 ALT_I2C_MODE_t* mode); 0932 0933 /*! 0934 * Sets the operational mode of the I2C controller. 0935 * 0936 * \param i2c_dev 0937 * A pointer to the I2C controller device block instance. 0938 * 0939 * \param mode 0940 * The operational mode to enable for the I2C controller. 0941 * 0942 * \retval ALT_E_SUCCESS Successful status. 0943 * \retval ALT_E_ERROR Details about error status code 0944 * 0945 * \internal 0946 * \endinternal 0947 */ 0948 ALT_STATUS_CODE alt_i2c_op_mode_set(ALT_I2C_DEV_t *i2c_dev, 0949 const ALT_I2C_MODE_t mode); 0950 0951 /*! 0952 * Returns ALT_E_TRUE if the I2C controller is busy. The I2C controller is busy if 0953 * either the Slave Finite State Machine (FSM) is not in the IDLE state or the 0954 * Master Finite State Machine (FSM) is not in the IDLE state. 0955 * 0956 * \param i2c_dev 0957 * A pointer to the I2C controller device block instance. 0958 * 0959 * \retval ALT_E_SUCCESS Successful status. 0960 * \retval ALT_E_ERROR Details about error status code 0961 * 0962 * \internal 0963 * IC_STATUS.ACTIVITY == 1 0964 * NOTE: IC_STATUS[0] that is, the ACTIVITY bit is the OR of SLV_ACTIVITY and 0965 * MST_ACTIVITY bits. 0966 * \endinternal 0967 */ 0968 ALT_STATUS_CODE alt_i2c_is_busy(ALT_I2C_DEV_t *i2c_dev); 0969 0970 /*! 0971 * This function reads a single data byte from the receive FIFO. 0972 * 0973 * This function is used to perform low level access to the data bytes 0974 * received by the I2C controller and buffered in the receive FIFO. It 0975 * may be used by master-receivers or slave receivers. 0976 * 0977 * This function does not check for valid data in the receive FIFO 0978 * beforehand and may cause an underflow if improperly used. It is 0979 * meant to be called from a context where preconditions have been 0980 * previously asserted such as in the implementation of the 0981 * alt_i2c_slave_receive() or alt_i2c_master_receive() function. 0982 * 0983 * \param i2c_dev 0984 * A pointer to the I2C controller device block instance. 0985 * 0986 * \param val 0987 * [out] The single data byte read from the receive FIFO. 0988 * 0989 * \retval ALT_E_SUCCESS Successful status. 0990 * \retval ALT_E_ERROR Details about error status code 0991 * 0992 * \internal 0993 * \endinternal 0994 */ 0995 ALT_STATUS_CODE alt_i2c_read(ALT_I2C_DEV_t *i2c_dev, uint8_t *val); 0996 0997 /*! 0998 * This function writes a single data byte to the transmit FIFO. 0999 * 1000 * This function is used to perform low level writes of data to the 1001 * transmit FIFO for transmission by the I2C controller. It may be 1002 * used by slave receivers. 1003 * 1004 * This function does not check whether the transmit FIFO is full or 1005 * not beforehand and may cause an overflow if improperly used. It is 1006 * meant to be called from a context where preconditions have been 1007 * previously asserted such as in the implementation of the 1008 * alt_i2c_slave_transmit() function. 1009 * 1010 * \param i2c_dev 1011 * A pointer to the I2C controller device block instance. 1012 * 1013 * \param val 1014 * The data byte to write to the transmission FIFO. 1015 * 1016 * \retval ALT_E_SUCCESS Successful status. 1017 * \retval ALT_E_ERROR Details about error status code 1018 * 1019 * \internal 1020 * \endinternal 1021 */ 1022 ALT_STATUS_CODE alt_i2c_write(ALT_I2C_DEV_t *i2c_dev, const uint8_t val); 1023 1024 /*! 1025 * This function acts in the role of a slave-receiver by receiving a single data 1026 * byte from the I2C bus in response to a write command from the master. 1027 * 1028 * This API is suitable for being called during an interrupt context. It is the 1029 * programmer's responsibility to ensure that there is data in the RX FIFO to 1030 * accomodate the request made. 1031 * 1032 * The I2C controller must be in slave mode before calling this function. 1033 * 1034 * \param i2c_dev 1035 * A pointer to the I2C controller device block instance. 1036 * 1037 * \param data 1038 * [out] A pointer to a buffer to contain the received data byte. 1039 * 1040 * \retval ALT_E_SUCCESS Successful status. 1041 * \retval ALT_E_ERROR Details about error status code 1042 * 1043 * \internal 1044 * \endinternal 1045 */ 1046 ALT_STATUS_CODE alt_i2c_slave_receive(ALT_I2C_DEV_t *i2c_dev, 1047 uint8_t *data); 1048 1049 /*! 1050 * This function acts in the role of a slave-transmitter by transmitting a single 1051 * data byte to the I2C bus in response to a read request from the master. 1052 * 1053 * This API is suitable for being called during an interrupt context. It is the 1054 * programmer's responsibility to ensure that there is enough space in the TX 1055 * FIFO to accomodate the request made. 1056 * 1057 * The I2C controller must be in slave mode before calling this function. 1058 * 1059 * \param i2c_dev 1060 * A pointer to the I2C controller device block instance. 1061 * 1062 * \param data 1063 * The data byte to transmit. 1064 * 1065 * \retval ALT_E_SUCCESS Successful status. 1066 * \retval ALT_E_ERROR Details about error status code 1067 * 1068 * \internal 1069 * \endinternal 1070 */ 1071 ALT_STATUS_CODE alt_i2c_slave_transmit(ALT_I2C_DEV_t *i2c_dev, 1072 const uint8_t data); 1073 1074 /*! 1075 * This function acts in the role of a slave-transmitter by transmitting data in 1076 * bulk to the I2C bus in response to a series of read requests from a master. 1077 * 1078 * In the standard I2C protocol, all transactions are single byte transactions and 1079 * the slave responds to a remote master read request by writing one byte into the 1080 * slave's TX FIFO. When a slave (slave-transmitter) is issued with a read request 1081 * from the remote master (master-receiver), at a minimum there should be at least 1082 * one entry placed into the slave-transmitter's TX FIFO. The I2C controller is 1083 * capable of handling more data in the TX FIFO so that subsequent read requests 1084 * can receive that data without raising an interrupt or software having to poll 1085 * to request more data. This eliminates overhead latencies from being incurred by 1086 * servicing the interrupt or polling for data requests each time had there been a 1087 * restriction of having only one entry placed in the TX FIFO. 1088 * 1089 * If the remote master acknowledges the data sent by the slave-transmitter and 1090 * there is no data in the slave's TX FIFO, the I2C controller raises the read 1091 * request interrupt and waits for data to be written into the TX FIFO before it 1092 * can be sent to the remote master. 1093 * 1094 * If the programmer knows in advance that the master is requesting a packet of \e 1095 * n bytes, then when another master request for data is received, the TX FIFO 1096 * could be written with \e n number bytes and the master receives it as a 1097 * continuous stream of data. For example, the slave continues to send data to the 1098 * master as long as the master is acknowledging the data sent and there is data 1099 * available in the TX FIFO. There is no need to hold the SCL line low or to issue 1100 * READ request again. 1101 * 1102 * If the remote master is to receive \e n bytes from the slave but the programmer 1103 * wrote a number of bytes larger than \e n to the TX FIFO, then when the slave 1104 * finishes sending the requested \e n bytes, it clears the TX FIFO and ignores 1105 * any excess bytes. 1106 * 1107 * This API is suitable for being called during an interrupt context. It is the 1108 * programmer's responsibility to ensure that there is enough space in the TX 1109 * FIFO to accomodate the request made. 1110 * 1111 * The I2C controller must be in slave mode before calling this function. 1112 * 1113 * \param i2c_dev 1114 * A pointer to the I2C controller device block instance. 1115 * 1116 * \param data 1117 * A pointer to the data buffer to transmit. 1118 * 1119 * \param size 1120 * The size of the data buffer in bytes to place in the TX FIFO. 1121 * 1122 * \retval ALT_E_SUCCESS Successful status. 1123 * \retval ALT_E_ERROR Details about error status code 1124 * 1125 * \internal 1126 * See: Section <em>Slave-Transfer Operation for Bulk Transfers</em> of the DW 1127 * Databook for details of implementation and error conditions that may occur. 1128 * \endinternal 1129 */ 1130 ALT_STATUS_CODE alt_i2c_slave_bulk_transmit(ALT_I2C_DEV_t *i2c_dev, 1131 const void * data, 1132 const size_t size); 1133 1134 /*! 1135 * This function returns the current target address. 1136 * 1137 * The I2C controller must be in master mode before calling this function. 1138 * 1139 * \param i2c_dev 1140 * A pointer to the I2C controller device block instance. 1141 * 1142 * \param target_addr 1143 * [out] The 7 or 10 bit slave target address. 1144 * 1145 * \retval ALT_E_SUCCESS Successful status. 1146 * \retval ALT_E_ERROR Details about error status code. 1147 */ 1148 ALT_STATUS_CODE alt_i2c_master_target_get(ALT_I2C_DEV_t * i2c_dev, uint32_t * target_addr); 1149 1150 /*! 1151 * This function updates the target slave address for any upcoming I2C bus IO. 1152 * 1153 * This API is not suitlabe for being called in an interrupt context as it 1154 * will wait for the TX FIFO to flush before applying the changes. If the TX 1155 * FIFO is known to be empty and the controller idle, then it can be safely 1156 * called. 1157 * 1158 * The I2C controller must be in master mode before calling this function. 1159 * 1160 * \param i2c_dev 1161 * A pointer to the I2C controller device block instance. 1162 * 1163 * \param target_addr 1164 * The 7 or 10 bit slave target address. 1165 * 1166 * \retval ALT_E_SUCCESS Successful status. 1167 * \retval ALT_E_ERROR Details about error status code. 1168 */ 1169 ALT_STATUS_CODE alt_i2c_master_target_set(ALT_I2C_DEV_t * i2c_dev, uint32_t target_addr); 1170 1171 /*! 1172 * This function acts in the role of a master-transmitter by issuing a write 1173 * command and transmitting data to the I2C bus. 1174 * 1175 * This API is not suitable for being called in an interrupt context as it may 1176 * wait for certain controller states before completing. 1177 * 1178 * The I2C controller must be in master mode before calling this function. 1179 * 1180 * \param i2c_dev 1181 * A pointer to the I2C controller device block instance. 1182 * 1183 * \param data 1184 * A pointer to a data buffer to transmit 1185 * 1186 * \param size 1187 * The size of the data buffer in bytes to place in the TX FIFO. 1188 * 1189 * \param issue_restart 1190 * This parameter controls whether a RESTART is issued before the 1191 * byte is sent or received. If: 1192 * * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t 1193 * is \b true, a RESTART is issued before the data is sent/received 1194 * (according to the value of CMD), regardless of whether or not 1195 * the transfer direction is changing from the previous command; if 1196 * \e restart_enabled is \b false, a STOP followed by a START is 1197 * issued instead. 1198 * * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t 1199 * is \b true, a RESTART is issued only if the transfer direction 1200 * is changing from the previous command; if \e restart_enabled is 1201 * \b false, a STOP followed by a START is issued instead. 1202 * 1203 * \param issue_stop 1204 * This parameter controls whether a STOP is issued after the byte is 1205 * sent or received. If: 1206 * * \b true - STOP is issued after this byte, regardless of whether or 1207 * not the Tx FIFO is empty. If the Tx FIFO is not empty, the 1208 * master immediately tries to start a new transfer by issuing a 1209 * START and arbitrating for the bus. 1210 * * \b false - STOP is not issued after this byte, regardless of 1211 * whether or not the Tx FIFO is empty. If the Tx FIFO is not 1212 * empty, the master continues the current transfer by 1213 * sending/receiving data bytes according to the value of the CMD 1214 * bit. If the Tx FIFO is empty, the master holds the SCL line low 1215 * and stalls the bus until a new command is available in the Tx 1216 * FIFO. 1217 * 1218 * \retval ALT_E_SUCCESS Successful status. 1219 * \retval ALT_E_ERROR Details about error status code 1220 * 1221 * \internal 1222 * \endinternal 1223 */ 1224 ALT_STATUS_CODE alt_i2c_master_transmit(ALT_I2C_DEV_t *i2c_dev, 1225 const void * data, 1226 const size_t size, 1227 const bool issue_restart, 1228 const bool issue_stop); 1229 1230 /*! 1231 * This function acts in the role of a master-receiver by receiving one or more 1232 * data bytes transmitted from a slave in response to read requests issued from 1233 * this master. 1234 * 1235 * This function causes the master to issue the required number of read requests 1236 * to the slave and read the received data bytes from the Rx FIFO. 1237 * 1238 * The \e issue_restart and \e issue_stop parameters apply to the final read 1239 * request transaction in the \e num_data_entries sequence required to fulfill the 1240 * aggregate receive request. 1241 * 1242 * This API is not suitable for being called in an interrupt context as it may 1243 * wait for certain controller states before completing. 1244 * 1245 * The I2C controller must be in master mode before calling this function. 1246 * 1247 * \param i2c_dev 1248 * A pointer to the I2C controller device block instance. 1249 * 1250 * \param data 1251 * [out] The data buffer to receive the requested \e size bytes. 1252 * 1253 * \param size 1254 * The size of the data buffer to read from the RX FIFO. 1255 * 1256 * \param issue_restart 1257 * This parameter controls whether a RESTART is issued before the 1258 * byte is sent or received. If: 1259 * * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t 1260 * is \b true, a RESTART is issued before the data is sent/received 1261 * (according to the value of CMD), regardless of whether or not 1262 * the transfer direction is changing from the previous command; if 1263 * \e restart_enabled is \b false, a STOP followed by a START is 1264 * issued instead. 1265 * * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t 1266 * is \b true, a RESTART is issued only if the transfer direction 1267 * is changing from the previous command; if \e restart_enabled is 1268 * \b false, a STOP followed by a START is issued instead. 1269 * 1270 * \param issue_stop 1271 * This parameter controls whether a STOP is issued after the byte is 1272 * sent or received. If: 1273 * * \b true - STOP is issued after this byte, regardless of whether or 1274 * not the Tx FIFO is empty. If the Tx FIFO is not empty, the 1275 * master immediately tries to start a new transfer by issuing a 1276 * START and arbitrating for the bus. 1277 * * \b false - STOP is not issued after this byte, regardless of 1278 * whether or not the Tx FIFO is empty. If the Tx FIFO is not 1279 * empty, the master continues the current transfer by 1280 * sending/receiving data bytes according to the value of the CMD 1281 * bit. If the Tx FIFO is empty, the master holds the SCL line low 1282 * and stalls the bus until a new command is available in the Tx 1283 * FIFO. 1284 * 1285 * \retval ALT_E_SUCCESS Successful status. 1286 * \retval ALT_E_ERROR Details about error status code 1287 * 1288 * \internal 1289 * \endinternal 1290 */ 1291 ALT_STATUS_CODE alt_i2c_master_receive(ALT_I2C_DEV_t *i2c_dev, 1292 void * data, 1293 const size_t size, 1294 const bool issue_restart, 1295 const bool issue_stop); 1296 1297 /*! 1298 * This function causes the I2C controller master to issue a READ request on the 1299 * bus. This function is typically used during master-receiver transfers. 1300 * 1301 * The I2C controller must be in master mode before calling this function. 1302 * 1303 * \param i2c_dev 1304 * A pointer to the I2C controller device block instance. 1305 * 1306 * \param issue_restart 1307 * This parameter controls whether a RESTART is issued before the 1308 * byte is sent or received. If: 1309 * * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t 1310 * is \b true, a RESTART is issued before the data is sent/received 1311 * (according to the value of CMD), regardless of whether or not 1312 * the transfer direction is changing from the previous command; if 1313 * \e restart_enabled is \b false, a STOP followed by a START is 1314 * issued instead. 1315 * * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t 1316 * is \b true, a RESTART is issued only if the transfer direction 1317 * is changing from the previous command; if \e restart_enabled is 1318 * \b false, a STOP followed by a START is issued instead. 1319 * 1320 * \param issue_stop 1321 * This parameter controls whether a STOP is issued after the byte is 1322 * sent or received. If: 1323 * * \b true - STOP is issued after this byte, regardless of whether or 1324 * not the Tx FIFO is empty. If the Tx FIFO is not empty, the 1325 * master immediately tries to start a new transfer by issuing a 1326 * START and arbitrating for the bus. 1327 * * \b false - STOP is not issued after this byte, regardless of 1328 * whether or not the Tx FIFO is empty. If the Tx FIFO is not 1329 * empty, the master continues the current transfer by 1330 * sending/receiving data bytes according to the value of the CMD 1331 * bit. If the Tx FIFO is empty, the master holds the SCL line low 1332 * and stalls the bus until a new command is available in the Tx 1333 * FIFO. 1334 * 1335 * \retval ALT_E_SUCCESS Successful status. 1336 * \retval ALT_E_ERROR Details about error status code 1337 * 1338 * \internal 1339 * Write IC_DATA_CMD.CMD = 1 (read request). IC_DATA_CMD.DAT is 1340 * written with "don't care" values as these bits are ignored by the 1341 * I2C controller . 1342 * \endinternal 1343 */ 1344 ALT_STATUS_CODE alt_i2c_issue_read(ALT_I2C_DEV_t *i2c_dev, 1345 const bool issue_restart, 1346 const bool issue_stop); 1347 1348 /*! 1349 * This function causes the I2C controller master to issue a send byte on the 1350 * bus. This function is typically used during master-transmitter/slave-transmitter 1351 * transfers. 1352 * 1353 * The I2C controller must be in master mode before calling this function. 1354 * 1355 * \param i2c_dev 1356 * A pointer to the I2C controller device block instance. 1357 * 1358 * \param value 1359 * The data item to be transmitted. 1360 * 1361 * \param issue_restart 1362 * This parameter controls whether a RESTART is issued before the 1363 * byte is sent or received. If: 1364 * * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t 1365 * is \b true, a RESTART is issued before the data is sent/received 1366 * (according to the value of CMD), regardless of whether or not 1367 * the transfer direction is changing from the previous command; if 1368 * \e restart_enabled is \b false, a STOP followed by a START is 1369 * issued instead. 1370 * * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t 1371 * is \b true, a RESTART is issued only if the transfer direction 1372 * is changing from the previous command; if \e restart_enabled is 1373 * \b false, a STOP followed by a START is issued instead. 1374 * 1375 * \param issue_stop 1376 * This parameter controls whether a STOP is issued after the byte is 1377 * sent or received. If: 1378 * * \b true - STOP is issued after this byte, regardless of whether or 1379 * not the Tx FIFO is empty. If the Tx FIFO is not empty, the 1380 * master immediately tries to start a new transfer by issuing a 1381 * START and arbitrating for the bus. 1382 * * \b false - STOP is not issued after this byte, regardless of 1383 * whether or not the Tx FIFO is empty. If the Tx FIFO is not 1384 * empty, the master continues the current transfer by 1385 * sending/receiving data bytes according to the value of the CMD 1386 * bit. If the Tx FIFO is empty, the master holds the SCL line low 1387 * and stalls the bus until a new command is available in the Tx 1388 * FIFO. 1389 * 1390 * \retval ALT_E_SUCCESS Successful status. 1391 * \retval ALT_E_ERROR Details about error status code 1392 * 1393 * \internal 1394 * Write IC_DATA_CMD.CMD = 0 (write request). 1395 * \endinternal 1396 */ 1397 ALT_STATUS_CODE alt_i2c_issue_write(ALT_I2C_DEV_t *i2c_dev, 1398 const uint8_t value, 1399 const bool issue_restart, 1400 const bool issue_stop); 1401 1402 /******************************************************************************/ 1403 /*! \addtogroup ALT_I2C_GEN_CALL General Call 1404 * 1405 * The functions in this group support General Call addresses. 1406 * 1407 * The general call address is for addressing every device connected to the I2C 1408 * bus at the same time. However, if a device does not need any of the data 1409 * supplied within the general call structure, it can ignore this address by not 1410 * issuing an acknowledgment. If a device does require data from a general call 1411 * address, it acknowledges this address and behaves as a slave-receiver. The 1412 * master does not actually know how many devices acknowledged if one or more 1413 * devices respond. The second and following bytes are acknowledged by every 1414 * slave-receiver capable of handling this data. A slave who cannot process one of 1415 * these bytes must ignore it by not-acknowledging. If one or more slaves 1416 * acknowledge, the not-acknowledge will not be seen by the master. 1417 * 1418 * The functions in this group do not provide any general call functional command 1419 * interpretation or implementation (e.g. software reset). 1420 * 1421 * @{ 1422 */ 1423 1424 /*! 1425 * This function acts in the role of a master-transmitter by issuing a general 1426 * call command to all devices connected to the I2C bus. 1427 * 1428 * The \e issue_restart and \e issue_stop parameters apply to the final write 1429 * transaction in the \e num_data_entries byte transmission sequence. 1430 * 1431 * The I2C controller must be in master mode before calling this function. 1432 * 1433 * The target slave address will be modified by this function. Call 1434 * alt_i2c_master_target_set() to reset the slave target address for 1435 * subsequent IO. 1436 * 1437 * \param i2c_dev 1438 * A pointer to the I2C controller device block instance. 1439 * 1440 * \param data 1441 * An array of data byte(s) to transmit. 1442 * 1443 * \param num_data_entries 1444 * The number of entries (bytes) in \e data to place in the TX FIFO. 1445 * 1446 * \param issue_restart 1447 * This parameter controls whether a RESTART is issued before the 1448 * byte is sent or received. If: 1449 * * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t 1450 * is \b true, a RESTART is issued before the data is sent/received 1451 * (according to the value of CMD), regardless of whether or not 1452 * the transfer direction is changing from the previous command; if 1453 * \e restart_enabled is \b false, a STOP followed by a START is 1454 * issued instead. 1455 * * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t 1456 * is \b true, a RESTART is issued only if the transfer direction 1457 * is changing from the previous command; if \e restart_enabled is 1458 * \b false, a STOP followed by a START is issued instead. 1459 * 1460 * \param issue_stop 1461 * This parameter controls whether a STOP is issued after the byte is 1462 * sent or received. If: 1463 * * \b true - STOP is issued after this byte, regardless of whether or 1464 * not the Tx FIFO is empty. If the Tx FIFO is not empty, the 1465 * master immediately tries to start a new transfer by issuing a 1466 * START and arbitrating for the bus. 1467 * * \b false - STOP is not issued after this byte, regardless of 1468 * whether or not the Tx FIFO is empty. If the Tx FIFO is not 1469 * empty, the master continues the current transfer by 1470 * sending/receiving data bytes according to the value of the CMD 1471 * bit. If the Tx FIFO is empty, the master holds the SCL line low 1472 * and stalls the bus until a new command is available in the Tx 1473 * FIFO. 1474 * 1475 * \retval ALT_E_SUCCESS Successful status. 1476 * \retval ALT_E_ERROR Details about error status code 1477 * 1478 * \internal 1479 * \endinternal 1480 */ 1481 ALT_STATUS_CODE alt_i2c_master_general_call(ALT_I2C_DEV_t *i2c_dev, 1482 const void * data, 1483 const size_t size, 1484 const bool issue_restart, 1485 const bool issue_stop); 1486 1487 /*! 1488 * Disables the I2C controller from responding to a General Call address. The 1489 * controller will respond with a NACK and no General Call status conditions or 1490 * interrupts are generated. 1491 * 1492 * \param i2c_dev 1493 * A pointer to the I2C controller device block instance. 1494 * 1495 * \retval ALT_E_SUCCESS Successful status. 1496 * \retval ALT_E_ERROR Details about error status code 1497 * 1498 * \internal 1499 * IC_ACK_GENERAL_CALL.ACK_GEN_CALL = 0 1500 * \endinternal 1501 */ 1502 ALT_STATUS_CODE alt_i2c_general_call_ack_disable(ALT_I2C_DEV_t *i2c_dev); 1503 1504 /*! 1505 * Enables the I2C controller to respond with an ACK when it receives a General 1506 * Call address. 1507 * 1508 * \param i2c_dev 1509 * A pointer to the I2C controller device block instance. 1510 * 1511 * \retval ALT_E_SUCCESS Successful status. 1512 * \retval ALT_E_ERROR Details about error status code 1513 * 1514 * \internal 1515 * IC_ACK_GENERAL_CALL.ACK_GEN_CALL = 1 1516 * \endinternal 1517 */ 1518 ALT_STATUS_CODE alt_i2c_general_call_ack_enable(ALT_I2C_DEV_t *i2c_dev); 1519 1520 /*! 1521 * Returns ALT_E_TRUE if the I2C controller is enabled to respond to General Call 1522 * addresses. 1523 * 1524 * \param i2c_dev 1525 * A pointer to the I2C controller device block instance. 1526 * 1527 * \retval ALT_E_SUCCESS Successful status. 1528 * \retval ALT_E_ERROR Details about error status code 1529 * 1530 * \internal 1531 * IC_ACK_GENERAL_CALL.ACK_GEN_CALL == 1 1532 * \endinternal 1533 */ 1534 ALT_STATUS_CODE alt_i2c_general_call_ack_is_enabled(ALT_I2C_DEV_t *i2c_dev); 1535 1536 /*! @} */ 1537 1538 /******************************************************************************/ 1539 /*! \addtogroup ALT_I2C_INT Interrupt and Status Conditions 1540 * 1541 * The functions in this group provide management for the I2C controller status 1542 * conditions and interrupts. 1543 * 1544 * Each I2C controller has a single combined interrupt output (\b 1545 * ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ). The following events can generate an 1546 * interrupt: 1547 * * General Call Address Received 1548 * * Start or Restart Condition Occurred 1549 * * Stop Condition Occurred 1550 * * I2C Controller Activity 1551 * * Receive Done 1552 * * Transmit Abort 1553 * * Read Request 1554 * * Transmit Buffer Empty 1555 * * Transmit Overflow 1556 * * Receive Buffer Full 1557 * * Receive Overflow 1558 * * Receive Underflow 1559 * 1560 * These interrupt status conditions may be monitored either by polling their 1561 * status or by configuring interrupt handlers using the HWLIB Interrupt 1562 * Controller API. 1563 * 1564 * Functions to get the current status, enable or disable (i.e. mass or unmask), 1565 * and clear interrupt status conditions for the I2C controller are defined in 1566 * this section. 1567 * 1568 * @{ 1569 */ 1570 1571 /*! 1572 * Returns the current I2C controller interrupt status conditions. 1573 * 1574 * This function returns the current value of the I2C controller interrupt status 1575 * register value which reflects the current I2C controller status conditions that 1576 * are not disabled (i.e. masked). 1577 * 1578 * \param i2c_dev 1579 * A pointer to the I2C controller device block instance. 1580 * 1581 * \param status 1582 * [out] A pointer to a bit mask of the active \ref ALT_I2C_STATUS_t 1583 * interrupt and status conditions. 1584 * 1585 * \retval ALT_E_SUCCESS Successful status. 1586 * \retval ALT_E_ERROR Details about error status code 1587 * 1588 * \internal 1589 * IC_INTR_STAT 1590 * \endinternal 1591 */ 1592 ALT_STATUS_CODE alt_i2c_int_status_get(ALT_I2C_DEV_t *i2c_dev, 1593 uint32_t *status); 1594 1595 /*! 1596 * Returns the I2C controller raw interrupt status conditions irrespective of 1597 * the interrupt status condition enablement state. 1598 * 1599 * This function returns the current value of the I2C controller raw interrupt 1600 * status register value which reflects the current I2C controller status 1601 * conditions regardless of whether they are disabled (i.e. masked) or not. 1602 * 1603 * \param i2c_dev 1604 * A pointer to the I2C controller device block instance. 1605 * 1606 * \param status 1607 * [out] A pointer to a bit mask of the active \ref ALT_I2C_STATUS_t 1608 * interrupt and status conditions. 1609 * 1610 * \retval ALT_E_SUCCESS Successful status. 1611 * \retval ALT_E_ERROR Details about error status code 1612 * 1613 * \internal 1614 * IC_INTR_STAT 1615 * \endinternal 1616 */ 1617 ALT_STATUS_CODE alt_i2c_int_raw_status_get(ALT_I2C_DEV_t *i2c_dev, 1618 uint32_t *status); 1619 1620 /*! 1621 * Clears the specified I2C controller interrupt status conditions identified 1622 * in the mask. 1623 * 1624 * This function clears one or more of the status conditions as contributors to 1625 * the \b ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state. 1626 * 1627 * \param i2c_dev 1628 * A pointer to the I2C controller device block instance. 1629 * 1630 * \param mask 1631 * Specifies the QSPI interrupt status conditions to clear. \e mask 1632 * is a mask of logically OR'ed \ref ALT_I2C_STATUS_t values that 1633 * designate the status conditions to clear. 1634 * 1635 * \retval ALT_E_SUCCESS Successful status. 1636 * \retval ALT_E_ERROR Details about error status code 1637 * 1638 * \internal 1639 * \endinternal 1640 */ 1641 ALT_STATUS_CODE alt_i2c_int_clear(ALT_I2C_DEV_t *i2c_dev, const uint32_t mask); 1642 1643 /*! 1644 * Disable the specified I2C controller interrupt status conditions identified in 1645 * the mask. 1646 * 1647 * This function disables one or more of the status conditions as contributors to 1648 * the \b ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state. 1649 * 1650 * NOTE: A cleared bit for any status condition in the mask value does not have 1651 * the effect of enabling it as a contributor to the \b 1652 * ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state. The function 1653 * alt_i2c_int_enable() is used to enable status source conditions. 1654 * 1655 * \param i2c_dev 1656 * A pointer to the I2C controller device block instance. 1657 * 1658 * \param mask 1659 * Specifies the status conditions to disable as interrupt source 1660 * contributors. \e mask is a mask of logically OR'ed \ref 1661 * ALT_I2C_STATUS_t values that designate the status conditions to 1662 * disable. 1663 * 1664 * \retval ALT_E_SUCCESS Successful status. 1665 * \retval ALT_E_ERROR Details about error status code 1666 * 1667 * \internal 1668 * \endinternal 1669 */ 1670 ALT_STATUS_CODE alt_i2c_int_disable(ALT_I2C_DEV_t *i2c_dev, const uint32_t mask); 1671 1672 /*! 1673 * Enable the specified I2C controller interrupt status conditions identified in 1674 * the mask. 1675 * 1676 * This function enables one or more of the status conditions as contributors to 1677 * the \b ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state. 1678 * 1679 * NOTE: A cleared bit for any status condition in the mask value does not have 1680 * the effect of disabling it as a contributor to the \b 1681 * ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state. The function 1682 * alt_i2c_int_disable() is used to disable status source conditions. 1683 * 1684 * \param i2c_dev 1685 * A pointer to the I2C controller device block instance. 1686 * 1687 * \param mask 1688 * Specifies the status conditions to enable as interrupt source 1689 * contributors. \e mask is a mask of logically OR'ed \ref 1690 * ALT_I2C_STATUS_t values that designate the status conditions to 1691 * enable. 1692 * 1693 * \retval ALT_E_SUCCESS Successful status. 1694 * \retval ALT_E_ERROR Details about error status code 1695 * 1696 * \internal 1697 * \endinternal 1698 */ 1699 ALT_STATUS_CODE alt_i2c_int_enable(ALT_I2C_DEV_t *i2c_dev, const uint32_t mask); 1700 1701 /*! 1702 * Gets the cause of I2C transmission abort. A I2C transmission abort indicates 1703 * that the I2C transmitter is unable to complete the intended actions on the 1704 * contents of the transmit FIFO. This situation can occur both as an I2C master 1705 * or an I2C slave, and is referred to as a "transmit abort". 1706 * 1707 * The returned value of this function is the value of the IC_TX_ABRT_SOURCE 1708 * register which indicates the cause why the transmit abort occurred. 1709 * 1710 * \param i2c_dev 1711 * A pointer to the I2C controller device block instance. 1712 * 1713 * \param cause 1714 * [out] A pointer to a bit mask of the \ref ALT_I2C_TX_ABORT_CAUSE_t 1715 * causes of the transmission abort. 1716 * 1717 * \retval ALT_E_SUCCESS Successful status. 1718 * \retval ALT_E_ERROR Details about error status code 1719 * 1720 * \internal 1721 * IC_TX_ABRT_SOURCE 1722 * \endinternal 1723 */ 1724 ALT_STATUS_CODE alt_i2c_tx_abort_cause_get(ALT_I2C_DEV_t *i2c_dev, 1725 ALT_I2C_TX_ABORT_CAUSE_t *cause); 1726 1727 /*! @} */ 1728 1729 /******************************************************************************/ 1730 /*! \addtogroup ALT_I2C_RX_FIFO RX FIFO Management 1731 * 1732 * The receive FIFO has a configurable threshold value that controls the level of 1733 * entries (or above) that sets the RX_FULL status condition and triggers an 1734 * interrupt. The valid range is 0 - (ALT_I2C_RX_FIFO_NUM_ENTRIES-1), with the 1735 * additional restriction that I2C controller does not allow this value to be set 1736 * to a value larger than the depth of the buffer. If an attempt is made to do 1737 * that, the actual value set will be the maximum depth of the buffer. A value of 1738 * 0 sets the threshold for 1 entry, and a value of (ALT_I2C_RX_FIFO_NUM_ENTRIES-1) 1739 * sets the threshold for ALT_I2C_RX_FIFO_NUM_ENTRIES entries. 1740 * 1741 * @{ 1742 */ 1743 1744 /*! 1745 * The number of entries (depth) of the I2C controller receive FIFO. 1746 */ 1747 #define ALT_I2C_RX_FIFO_NUM_ENTRIES 64 1748 1749 /*! 1750 * Returns ALT_E_TRUE when the receive FIFO is empty. 1751 * 1752 * \param i2c_dev 1753 * A pointer to the I2C controller device block instance. 1754 * 1755 * \retval ALT_E_SUCCESS Successful status. 1756 * \retval ALT_E_ERROR Details about error status code 1757 * 1758 * \internal 1759 * IC_STATUS.RFNE == 0 1760 * \endinternal 1761 */ 1762 ALT_STATUS_CODE alt_i2c_rx_fifo_is_empty(ALT_I2C_DEV_t *i2c_dev); 1763 1764 /*! 1765 * Returns ALT_E_TRUE when the receive FIFO is completely full. 1766 * 1767 * \param i2c_dev 1768 * A pointer to the I2C controller device block instance. 1769 * 1770 * \retval ALT_E_SUCCESS Successful status. 1771 * \retval ALT_E_ERROR Details about error status code 1772 * 1773 * \internal 1774 * IC_STATUS.RFF == 1 1775 * \endinternal 1776 */ 1777 ALT_STATUS_CODE alt_i2c_rx_fifo_is_full(ALT_I2C_DEV_t *i2c_dev); 1778 1779 /*! 1780 * Returns the number of valid entries in the receive FIFO. 1781 * 1782 * \param i2c_dev 1783 * A pointer to the I2C controller device block instance. 1784 * 1785 * \param num_entries 1786 * [out] The number of entries in the receive FIFO. 1787 * 1788 * \retval ALT_E_SUCCESS Successful status. 1789 * \retval ALT_E_ERROR Details about error status code 1790 * 1791 * \internal 1792 * IC_RXFLR.RXFLR 1793 * \endinternal 1794 */ 1795 ALT_STATUS_CODE alt_i2c_rx_fifo_level_get(ALT_I2C_DEV_t *i2c_dev, 1796 uint32_t *num_entries); 1797 1798 /*! 1799 * Gets the current receive FIFO threshold level value. 1800 * 1801 * \param i2c_dev 1802 * A pointer to the I2C controller device block instance. 1803 * 1804 * \param threshold 1805 * [out] The current threshold value. 1806 * 1807 * \retval ALT_E_SUCCESS Successful status. 1808 * \retval ALT_E_ERROR Details about error status code 1809 * 1810 * \internal 1811 * IC_RX_TL.RX_TL 1812 * \endinternal 1813 */ 1814 ALT_STATUS_CODE alt_i2c_rx_fifo_threshold_get(ALT_I2C_DEV_t *i2c_dev, 1815 uint8_t *threshold); 1816 1817 /*! 1818 * Sets the current receive FIFO threshold level value. 1819 * 1820 * \param i2c_dev 1821 * A pointer to the I2C controller device block instance. 1822 * 1823 * \param threshold 1824 * The threshold value. 1825 * 1826 * \retval ALT_E_SUCCESS Successful status. 1827 * \retval ALT_E_ERROR Details about error status code 1828 * 1829 * \internal 1830 * IC_RX_TL.RX_TL = threshold 1831 * \endinternal 1832 */ 1833 ALT_STATUS_CODE alt_i2c_rx_fifo_threshold_set(ALT_I2C_DEV_t *i2c_dev, 1834 const uint8_t threshold); 1835 1836 /*! @} */ 1837 1838 /******************************************************************************/ 1839 /*! \addtogroup ALT_I2C_TX_FIFO TX FIFO Management 1840 * 1841 * The transmit FIFO has a configurable threshold value that controls the level of 1842 * entries (or below) that sets the TX_EMPTY status condition and triggers an 1843 * interrupt. The valid range is 0 - (ALT_I2C_TX_FIFO_NUM_ENTRIES-1), with the 1844 * additional restriction that I2C controller does not allow this value to be set 1845 * to a value larger than the depth of the buffer. If an attempt is made to do 1846 * that, the actual value set will be the maximum depth of the buffer. A value of 1847 * 0 sets the threshold for 0 entries, and a value of (ALT_I2C_TX_FIFO_NUM_ENTRIES-1) 1848 * sets the threshold for (ALT_I2C_TX_FIFO_NUM_ENTRIES-1) entries. 1849 * 1850 * @{ 1851 */ 1852 1853 /*! 1854 * The number of entries (depth) of the I2C controller transmit FIFO. 1855 */ 1856 #define ALT_I2C_TX_FIFO_NUM_ENTRIES 64 1857 1858 /*! 1859 * Returns ALT_E_TRUE when the transmit FIFO is empty. 1860 * 1861 * \param i2c_dev 1862 * A pointer to the I2C controller device block instance. 1863 * 1864 * \retval ALT_E_SUCCESS Successful status. 1865 * \retval ALT_E_ERROR Details about error status code 1866 * 1867 * \internal 1868 * IC_STATUS.TFE == 1 1869 * \endinternal 1870 */ 1871 ALT_STATUS_CODE alt_i2c_tx_fifo_is_empty(ALT_I2C_DEV_t *i2c_dev); 1872 1873 /*! 1874 * Returns ALT_E_TRUE when the transmit FIFO is completely full. 1875 * 1876 * \param i2c_dev 1877 * A pointer to the I2C controller device block instance. 1878 * 1879 * \retval ALT_E_SUCCESS Successful status. 1880 * \retval ALT_E_ERROR Details about error status code 1881 * 1882 * \internal 1883 * IC_STATUS.TFNF == 0 1884 * \endinternal 1885 */ 1886 ALT_STATUS_CODE alt_i2c_tx_fifo_is_full(ALT_I2C_DEV_t *i2c_dev); 1887 1888 /*! 1889 * Returns the number of valid entries in the transmit FIFO. 1890 * 1891 * \param i2c_dev 1892 * A pointer to the I2C controller device block instance. 1893 * 1894 * \param num_entries 1895 * [out] The number of entries in the transmit FIFO. 1896 * 1897 * \retval ALT_E_SUCCESS Successful status. 1898 * \retval ALT_E_ERROR Details about error status code 1899 * 1900 * \internal 1901 * IC_TXFLR.TXFLR 1902 * \endinternal 1903 */ 1904 ALT_STATUS_CODE alt_i2c_tx_fifo_level_get(ALT_I2C_DEV_t *i2c_dev, 1905 uint32_t *num_entries); 1906 1907 /*! 1908 * Gets the current transmit FIFO threshold level value. 1909 * 1910 * \param i2c_dev 1911 * A pointer to the I2C controller device block instance. 1912 * 1913 * \param threshold 1914 * [out] The current threshold value. 1915 * 1916 * \retval ALT_E_SUCCESS Successful status. 1917 * \retval ALT_E_ERROR Details about error status code 1918 * 1919 * \internal 1920 * IC_TX_TL.TX_TL 1921 * \endinternal 1922 */ 1923 ALT_STATUS_CODE alt_i2c_tx_fifo_threshold_get(ALT_I2C_DEV_t *i2c_dev, 1924 uint8_t *threshold); 1925 1926 /*! 1927 * Sets the current transmit FIFO threshold level value. 1928 * 1929 * \param i2c_dev 1930 * A pointer to the I2C controller device block instance. 1931 * 1932 * \param threshold 1933 * The threshold value. 1934 * 1935 * \retval ALT_E_SUCCESS Successful status. 1936 * \retval ALT_E_ERROR Details about error status code 1937 * 1938 * \internal 1939 * IC_TX_TL.TX_TL = threshold 1940 * \endinternal 1941 */ 1942 ALT_STATUS_CODE alt_i2c_tx_fifo_threshold_set(ALT_I2C_DEV_t *i2c_dev, 1943 const uint8_t threshold); 1944 1945 /*! @} */ 1946 1947 /******************************************************************************/ 1948 /*! \addtogroup ALT_I2C_DMA DMA Interface 1949 * 1950 * The DMA interface has a configurable threshold value that controls the 1951 * level of entries that triggers the burst handshaking request used for DMA 1952 * integration. 1953 * 1954 * For the TX threshold, if the number of entries in the TX FIFO is at or 1955 * below the set threshold, a DMA handshaking request will be made. The valid 1956 * range for the TX threshold is 0 - (ALT_I2C_TX_FIFO_NUM_ENTRIES - 1). 1957 * 1958 * For the RX threshold, if the number of entries in the RX FIFO is above the 1959 * set threshold, a DMA handshaking request will be made. The valid range for 1960 * the RX treshold is 0 - (ALT_I2C_TX_FIFO_NUM_ENTRIES - 1). 1961 * 1962 * Having a higher threshold can improve the AXI bus utilization at the 1963 * expense of the likelyhoold of overflow / underflow conditions. 1964 * @{ 1965 */ 1966 1967 /*! 1968 * Gets the current RX DMA threshold level value. 1969 * 1970 * \param i2c_dev 1971 * A pointer to the I2C controller device block instance. 1972 * 1973 * \param threshold 1974 * [out] The threshold value. 1975 * 1976 * \retval ALT_E_SUCCESS Successful status. 1977 * \retval ALT_E_ERROR Details about error status code 1978 */ 1979 ALT_STATUS_CODE alt_i2c_rx_dma_threshold_get(ALT_I2C_DEV_t * i2c_dev, uint8_t * threshold); 1980 1981 /*! 1982 * Sets the current RX DMA threshold level value. 1983 * 1984 * \param i2c_dev 1985 * A pointer to the I2C controller device block instance. 1986 * 1987 * \param threshold 1988 * The threshold value. 1989 * 1990 * \retval ALT_E_SUCCESS Successful status. 1991 * \retval ALT_E_ERROR Details about error status code 1992 */ 1993 ALT_STATUS_CODE alt_i2c_rx_dma_threshold_set(ALT_I2C_DEV_t * i2c_dev, uint8_t threshold); 1994 1995 /*! 1996 * Gets the current TX DMA threshold level value. 1997 * 1998 * \param i2c_dev 1999 * A pointer to the I2C controller device block instance. 2000 * 2001 * \param threshold 2002 * [out] The threshold value. 2003 * 2004 * \retval ALT_E_SUCCESS Successful status. 2005 * \retval ALT_E_ERROR Details about error status code 2006 */ 2007 ALT_STATUS_CODE alt_i2c_tx_dma_threshold_get(ALT_I2C_DEV_t * i2c_dev, uint8_t * threshold); 2008 2009 /*! 2010 * Sets the current TX DMA threshold level value. 2011 * 2012 * \param i2c_dev 2013 * A pointer to the I2C controller device block instance. 2014 * 2015 * \param threshold 2016 * The threshold value. 2017 * 2018 * \retval ALT_E_SUCCESS Successful status. 2019 * \retval ALT_E_ERROR Details about error status code 2020 */ 2021 ALT_STATUS_CODE alt_i2c_tx_dma_threshold_set(ALT_I2C_DEV_t * i2c_dev, uint8_t threshold); 2022 2023 /*! @} */ 2024 2025 /*! @} */ 2026 2027 #ifdef __cplusplus 2028 } 2029 #endif /* __cplusplus */ 2030 #endif /* __ALT_I2C_H__ */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|