1 /******************************************************************************
\r
3 * Copyright 2013 Altera Corporation. All Rights Reserved.
\r
5 * Redistribution and use in source and binary forms, with or without
\r
6 * modification, are permitted provided that the following conditions are met:
\r
8 * 1. Redistributions of source code must retain the above copyright notice,
\r
9 * this list of conditions and the following disclaimer.
\r
11 * 2. Redistributions in binary form must reproduce the above copyright notice,
\r
12 * this list of conditions and the following disclaimer in the documentation
\r
13 * and/or other materials provided with the distribution.
\r
15 * 3. The name of the author may not be used to endorse or promote products
\r
16 * derived from this software without specific prior written permission.
\r
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR
\r
19 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
\r
20 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO
\r
21 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
\r
22 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
\r
23 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
\r
24 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
\r
25 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
\r
26 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
\r
29 ******************************************************************************/
\r
32 * Altera - I2C Controller API
\r
35 #ifndef __ALT_I2C_H__
\r
36 #define __ALT_I2C_H__
\r
39 #include "alt_clock_manager.h"
\r
40 #include "socal/alt_i2c.h"
\r
41 #include "socal/alt_rstmgr.h"
\r
42 #include "socal/hps.h"
\r
43 #include "socal/socal.h"
\r
48 #endif /* __cplusplus */
\r
50 /******************************************************************************/
\r
51 /*! \addtogroup ALT_I2C I2C Controller API
\r
53 * This module defines an API for configuring and managing the HPS I2C controllers.
\r
55 * The I2C controller provides support for a communication link between integrated
\r
56 * circuits on a board. It is a simple two-wire bus which consists of a serial
\r
57 * data line (SDA) and a serial clock (SCL) for use in applications such as
\r
58 * temperature sensors and voltage level translators to EEPROMs, A/D and D/A
\r
59 * converters, CODECs, and many types of microprocessors.
\r
61 * The Hard Processor System (HPS) provides four I2C controllers to enable system
\r
62 * software to communicate serially with I2C buses. Each I2C controller can
\r
63 * operate in master or slave mode, and support standard mode of up to 100
\r
64 * kilobits per second (Kbps) or fast mode of up to 400 Kbps. These I2C
\r
65 * controllers are instances of the Synopsys DesignWare APB I2C (DW_apb_i2c)
\r
68 * NOTE: Each I2C controller must be programmed to operate in either master or
\r
69 * slave mode only. Operating as a master and slave simultaneously is not
\r
72 * Features of the I2C Controller:
\r
73 * * Support both 100 KBps and 400 KBps modes
\r
74 * * One of the following I2C operations: master or slave
\r
75 * * Support both 7-bit and 10-bit addressing modes
\r
76 * * Mixed read and write combined-format transactions
\r
77 * * Bulk transmit mode
\r
78 * * DMA handshaking interface
\r
80 * For a complete details on the configuration and operation of I2C controller,
\r
81 * consult the following references:
\r
82 * * <em>Cyclone V Device Handbook Volume 3: Hard Processor System Technical
\r
83 * Reference Manual, Chapter 20. I2C Controller (cv_54020-1.2)</em>
\r
84 * * <em>Synopsys DesignWare DW_apb_i2c Databook DW_apb_i2c, Version 1.15a</em>
\r
85 * * <em>The I2C-Bus Specification Version 2.1</em>
\r
90 /******************************************************************************/
\r
92 * This type definition enumerates the operational state of I2C by
\r
93 * transfer operation.
\r
95 typedef enum ALT_I2C_TRANSFER_TYPE_e
\r
97 ALT_I2C_TRANSFER_NONE = 0, /*!< No transfer operation */
\r
98 ALT_I2C_TRANSFER_START = 1, /*!< Start detect */
\r
99 ALT_I2C_TRANSFER_COMPLETE = 2, /*!< All operations done */
\r
100 ALT_I2C_TRANSFER_READ = 3, /*!< Read operation is active */
\r
101 ALT_I2C_TRANSFER_WRITE = 4, /*!< Write operation is active */
\r
103 ALT_I2C_TRANSFER_TYPE_t;
\r
107 * A pointer or handle to the I2C controller device instance. The ALT_I2C_DEV_t is
\r
108 * initialized by a call to alt_i2c_init() and subsequently used by the other I2C
\r
109 * controller API functions as a reference to a specific device.
\r
112 * ALT_I2C_DEV_t may be a struct or reference to an opaque data
\r
113 * structure. Whatever "internal" type is suited to the needs of the
\r
117 typedef struct ALT_I2C_DEV_s
\r
119 void * location; /*!< HPS address of I2C instance. */
\r
120 alt_freq_t clock_freq; /*!< Input clock frequency. */
\r
121 uint32_t last_target; /*!< Last issued target address. */
\r
126 * This type enumerates the HPS I2C controller instances.
\r
128 typedef enum ALT_I2C_CTLR_e
\r
130 ALT_I2C_I2C0 = (int)ALT_I2C0_OFST, /*!< I2C0 instance. */
\r
131 ALT_I2C_I2C1 = (int)ALT_I2C1_OFST, /*!< I2C1 instance. */
\r
132 ALT_I2C_I2C2 = (int)ALT_I2C2_OFST, /*!< I2C2 instance. */
\r
133 ALT_I2C_I2C3 = (int)ALT_I2C3_OFST, /*!< I2C3 instance. */
\r
137 * This type enumerates the modes that the I2C controller may operate in.
\r
139 * NOTE: Each I2C controller must be programmed to operate in either master or
\r
140 * slave mode only. Operating as a master and slave simultaneously is not
\r
143 typedef enum ALT_I2C_MODE_e
\r
145 ALT_I2C_MODE_SLAVE = ALT_I2C_CON_MST_MOD_E_DIS, /*!< Slave Mode */
\r
146 ALT_I2C_MODE_MASTER = ALT_I2C_CON_MST_MOD_E_EN /*!< Master Mode */
\r
150 * This type enumerates the I2C controller operational speed modes.
\r
152 * The I2C controller can operate in standard mode (with data rates 0 to 100 Kbps)
\r
153 * or fast mode (with data rates less than or equal to 400 Kbps). Additionally,
\r
154 * fast mode devices are downward compatible. For instance, fast mode devices can
\r
155 * communicate with standard mode devices in 0 to 100 Kbps I2C bus
\r
156 * system. However, standard mode devices are not upward compatible and should not
\r
157 * be incorporated in a fast-mode I2C bus system as they cannot follow the higher
\r
158 * transfer rate and therefore unpredictable states would occur.
\r
160 * This setting is relevant only if one is operating the I2C in master mode.
\r
162 typedef enum ALT_I2C_SPEED_e
\r
164 ALT_I2C_SPEED_STANDARD = ALT_I2C_CON_SPEED_E_STANDARD,
\r
165 /*!< Standard mode (0 to 100 Kbps) */
\r
166 ALT_I2C_SPEED_FAST = ALT_I2C_CON_SPEED_E_FAST
\r
167 /*!< Fast mode (<= 400 Kbps) */
\r
171 * This type enumerates the two addressing modes formats supported by the I2C
\r
174 * The I2C controller does not support mixed address format - that is, a 7-bit
\r
175 * address transaction followed by a 10-bit address transaction or vice versa -
\r
176 * combined format transactions.
\r
178 typedef enum ALT_I2C_ADDR_MODE_e
\r
180 ALT_I2C_ADDR_MODE_7_BIT = ALT_I2C_TAR_IC_10BITADDR_MST_E_START7,
\r
181 /*!< 7-Bit Address Format */
\r
182 ALT_I2C_ADDR_MODE_10_BIT = ALT_I2C_TAR_IC_10BITADDR_MST_E_START10
\r
183 /*!< 10-Bit Address Format */
\r
184 } ALT_I2C_ADDR_MODE_t;
\r
187 * This type enumerates interrupt status conditions for the I2C controller.
\r
189 typedef enum ALT_I2C_STATUS_e
\r
191 ALT_I2C_STATUS_RX_UNDER = 1UL << 0,
\r
192 /*!< Set if the processor attempts to read the
\r
193 * receive buffer when it is empty. If the I2C
\r
194 * controller is disabled, this status keeps
\r
195 * maintains its state until the master or slave
\r
196 * state machines go into idle, then this
\r
197 * interrupt is cleared.
\r
199 ALT_I2C_STATUS_RX_OVER = 1UL << 1,
\r
200 /*!< Set if the receive buffer is completely
\r
201 * filled to capacity and an additional byte is
\r
202 * received from an external I2C device. The I2C
\r
203 * controller acknowledges this, but any data
\r
204 * bytes received after the FIFO is full are
\r
205 * discarded. If the I2C controller is disabled,
\r
206 * this status maintains its statue until the
\r
207 * master or slave state machines go into idle,
\r
208 * then this interrupt is cleared.
\r
210 ALT_I2C_STATUS_RX_FULL = 1UL << 2,
\r
211 /*!< Set when the receive buffer reaches or goes
\r
212 * above the RX_TL threshold. It is
\r
213 * automatically cleared by hardware when buffer
\r
214 * level goes below the threshold. If the I2C
\r
215 * controller is disabled, the RX FIFO is
\r
216 * flushed and held in reset; therefore the RX
\r
217 * FIFO is not full. So this bit is cleared once
\r
218 * the I2C controller is disabled, regardless of
\r
219 * the activity that continues.
\r
221 ALT_I2C_STATUS_TX_OVER = 1UL << 3,
\r
222 /*!< Set during transmit if the transmit buffer is
\r
223 * filled to capacity and the processor attempts
\r
224 * to issue another I2C command. When the I2C
\r
225 * controller is disabled, this bit maintains
\r
226 * its state until the master or slave state
\r
227 * machines go into idle, then this interrupt is
\r
230 ALT_I2C_STATUS_TX_EMPTY = 1UL << 4,
\r
231 /*!< This bit is set to 1 when the transmit buffer
\r
232 * is at or below the configured threshold
\r
233 * value. It is automatically cleared by
\r
234 * hardware when the buffer level goes above the
\r
235 * threshold. When the I2C controller is
\r
236 * disabled, the TX FIFO is flushed and held in
\r
237 * reset. The TX FIFO appears as if it has no
\r
238 * data in it, so this bit is set to 1, provided
\r
239 * there is activity in the master or slave
\r
240 * state machines. When there is no longer
\r
241 * activity, then this bit is set to 0.
\r
244 ALT_I2C_STATUS_RD_REQ = 1UL << 5,
\r
245 /*!< This bit is set to 1 when I2C is acting as a
\r
246 * slave and another I2C master is attempting to
\r
247 * read data from the I2C. The I2C holds the bus
\r
248 * in a wait state until this interrupt is
\r
249 * serviced, which means that the slave has been
\r
250 * addressed by a remote master that is asking
\r
251 * for data to be transferred. The processor
\r
252 * must respond to this interrupt and then write
\r
253 * the requested data. This bit is set to 0 just
\r
254 * after the processor by calling
\r
255 * alt_i2c_int_clear() with
\r
256 * ALT_I2C_STATUS_RD_REQ in the mask..
\r
258 ALT_I2C_STATUS_TX_ABORT = 1UL << 6,
\r
259 /*!< This bit indicates if I2C, as an I2C
\r
260 * transmitter, is unable to complete the
\r
261 * intended actions on the contents of the
\r
262 * transmit FIFO. This situation can occur both
\r
263 * as an I2C master or an I2C slave, and is
\r
264 * referred to as a 'transmit abort'. When this
\r
265 * bit is set to 1, the IC_TX_ABRT_SOURCE
\r
266 * register indicates the reason why the
\r
267 * transmit abort takes places.
\r
269 * NOTE: The I2C flushes/resets/empties the TX
\r
270 * FIFO whenever this bit is set. The TX FIFO
\r
271 * remains in this flushed state until the
\r
272 * register alt_i2c_int_clear() with
\r
273 * ALT_I2C_STATUS_TX_ABORT in the mask is
\r
274 * called. Once this happens, the TX FIFO is
\r
275 * then ready to accept more data bytes from the
\r
278 ALT_I2C_STATUS_RX_DONE = 1UL << 7,
\r
279 /*!< When the I2C is acting as a
\r
280 * slave-transmitter, this bit is set to 1 if
\r
281 * the master does not acknowledge a transmitted
\r
282 * byte. This occurs on the last byte of the
\r
283 * transmission, indicating that the
\r
284 * transmission is done.
\r
286 ALT_I2C_STATUS_ACTIVITY = 1UL << 8,
\r
287 /*!< This bit captures I2C activity and stays set
\r
288 * until it is cleared. There are four ways to
\r
290 * * Disabling the I2C controller
\r
291 * * Calling alt_i2c_int_clear() with
\r
292 * ALT_I2C_STATUS_ACTIVITY in the mask.
\r
293 * * Calling alt_i2c_int_clear() with
\r
294 * ALT_I2C_STATUS_ALL in the mask.
\r
297 * Once this bit is set, it stays set unless one
\r
298 * of the four methods is used to clear it. Even
\r
299 * if the I2C module is idle, this bit remains
\r
300 * set until cleared, indicating that there was
\r
301 * activity on the bus.
\r
303 ALT_I2C_STATUS_STOP_DET = 1UL << 9,
\r
304 /*!< Indicates whether a STOP condition has
\r
305 * occurred on the I2C interface regardless of
\r
306 * whether I2C is operating in slave or master
\r
309 ALT_I2C_STATUS_START_DET = 1UL << 10,
\r
310 /*!< Indicates whether a START or RESTART
\r
311 * condition has occurred on the I2C interface
\r
312 * regardless of whether I2C is operating in
\r
313 * slave or master mode.
\r
315 ALT_I2C_STATUS_INT_CALL = 1UL << 11,
\r
316 /*!< Set only when a General Call address is
\r
317 * received and it is acknowledged. It stays set
\r
318 * until it is cleared either by disabling I2C
\r
319 * or when alt_i2c_int_clear() with
\r
320 * ALT_I2C_STATUS_CALL in the mask is
\r
321 * called. I2C stores the received data in the
\r
324 ALT_I2C_STATUS_INT_ALL = 0xFFF,
\r
325 /*!< All Combined and Individual Interrupts. This
\r
326 * enumeration value can be used to clear,
\r
327 * disable, and enable the combined interrupt
\r
328 * and all individual interrupt status
\r
329 * conditions. As a side effect, when passed to
\r
330 * alt_i2c_int_clear(), clears the source causes
\r
331 * (\ref ALT_I2C_TX_ABORT_CAUSE_t) of the
\r
332 * ALT_I2C_STATUS_TX_ABORT condition.
\r
334 } ALT_I2C_STATUS_t;
\r
337 * This type enumerates the source causes of a ALT_I2C_STATUS_TX_ABORT condition.
\r
339 * The active ALT_I2C_TX_ABORT_CAUSE_t source conditions are cleared when
\r
340 * alt_i2c_int_clear() with is called ALT_I2C_STATUS_TX_ABORT in the mask or
\r
341 * alt_i2c_int_clear() is called with ALT_I2C_STATUS_ALL in the mask.
\r
344 * Discuss special handling of abrt_sbyte_norstrt TX_ABRT source required in ???() function.
\r
347 typedef enum ALT_I2C_TX_ABORT_CAUSE_e
\r
349 ALT_I2C_TX_ABORT_CAUSE_7B_ADDR_NOACK = 1UL << 0,
\r
350 /*!< Master Abort 7 Bit Address - If set (1),
\r
351 * Master is in 7-bit addressing mode and the
\r
352 * address sent was not acknowledged by any
\r
355 * Role of I2C: Master-Transmitter or
\r
358 ALT_I2C_TX_ABORT_CAUSE_10ADDR1_NOACK = 1UL << 1,
\r
359 /*!< Master Abort 10 Bit Address Byte 1 - If set
\r
360 * (1), Master is in 10-bit address mode and the
\r
361 * first 10-bit address byte was not
\r
362 * acknowledged by any slave.
\r
364 * Role of I2C: Master-Transmitter or
\r
367 ALT_I2C_TX_ABORT_CAUSE_10ADDR2_NOACK = 1UL << 2,
\r
368 /*!< Master Abort 10 Bit Address Byte 2 - If set
\r
369 * (1), Master is in 10-bit address mode and the
\r
370 * second address byte of the 10-bit address was
\r
371 * not acknowledged by any slave
\r
373 * Role of I2C: Master-Transmitter or
\r
376 ALT_I2C_TX_ABORT_CAUSE_TXDATA_NOACK = 1UL << 3,
\r
377 /*!< Master Abort TX NOACK Bit - If set (1),
\r
378 * Master has received an acknowledgement for
\r
379 * the address, but when it sent data byte(s)
\r
380 * following the address, it did not receive an
\r
381 * acknowledge from the remote slave(s). This is
\r
382 * a master-mode only bit.
\r
384 * Role of I2C: Master-Transmitter.
\r
386 ALT_I2C_TX_ABORT_CAUSE_GCALL_NOACK = 1UL << 4,
\r
387 /*!< Master Abort GC Noack Bit - If set (1), I2C
\r
388 * controller in master mode sent a General Call
\r
389 * and no slave on the bus acknowledged the
\r
392 * Role of I2C: Master-Transmitter.
\r
394 ALT_I2C_TX_ABORT_CAUSE_GCALL_RD = 1UL << 5,
\r
395 /*!< Master Abort GC Read Bit - If set (1), I2C
\r
396 * controller in master mode sent a General Call
\r
397 * but the user programmed the byte following
\r
398 * the General Call to be a read from the bus
\r
399 * (IC_DATA_CMD[9] is set to 1).
\r
401 * Role of I2C: Master-Transmitter.
\r
403 ALT_I2C_TX_ABORT_CAUSE_HS_ACKDET = 1UL << 6,
\r
404 /*!< Master HS MC Ack - If set (1), Master is in
\r
405 * High Speed mode and the High Speed Master
\r
406 * code was acknowledged (wrong behavior).
\r
408 * Role of I2C: Master.
\r
410 ALT_I2C_TX_ABORT_CAUSE_SBYTE_ACKDET = 1UL << 7,
\r
411 /*!< Master Abort START Byte - If set (1), Master
\r
412 * has sent a START Byte and the START Byte was
\r
413 * acknowledged (wrong behavior).
\r
415 * Role of I2C: Master.
\r
417 ALT_I2C_TX_ABORT_CAUSE_HS_NORSTRT = 1UL << 8,
\r
418 /*!< Master HS Restart Disabled - If set (1), the
\r
419 * restart is disabled (IC_RESTART_EN bit
\r
420 * (IC_CON[5]) = 0) and the user is trying to
\r
421 * use the master to transfer data in High Speed
\r
424 * Role of I2C: Master-Transmitter or
\r
427 ALT_I2C_TX_ABORT_CAUSE_SBYTE_NORSTRT = 1UL << 9,
\r
428 /*!< Master Abort START No Restart - To clear, the
\r
429 * source of the ABRT_SBYTE_NORSTRT must be
\r
430 * fixed first; restart must be enabled
\r
431 * (IC_CON[5]=1), the SPECIAL bit must be
\r
432 * cleared (IC_TAR[11]), or the GC_OR_START bit
\r
433 * must be cleared (IC_TAR[10]). Once the source
\r
434 * of the ABRT_SBYTE_NORSTRT is fixed, then this
\r
435 * bit can be cleared in the same manner as
\r
436 * other bits in this register. If the source of
\r
437 * the ABRT_SBYTE_NORSTRT is not fixed before
\r
438 * attempting to clear this bit, bit 9 clears
\r
439 * for one cycle and then gets re-asserted.
\r
441 * If set (1), the restart is disabled
\r
442 * (IC_RESTART_EN bit (IC_CON[5]) = 0) and the
\r
443 * user is trying to send a START Byte.
\r
445 * Role of I2C: Master.
\r
447 ALT_I2C_TX_ABORT_CAUSE_10B_RD_NORSTRT = 1UL << 10,
\r
448 /*!< Master Abort 10 Bit No Restart - If set (1),
\r
449 * the restart is disabled (IC_RESTART_EN bit
\r
450 * (IC_CON[5]) = 0) and the master sends a read
\r
451 * command in 10-bit addressing mode.
\r
453 * Role of I2C: Master Receiver.
\r
455 ALT_I2C_TX_ABORT_CAUSE_MST_DIS = 1UL << 11,
\r
456 /*!< Master Operation with Master Disabled - If set
\r
457 * (1), user tries to initiate a Master
\r
458 * operation with the Master mode disabled.
\r
460 * Role of I2C: Master or Slave-Receiver.
\r
462 ALT_I2C_TX_ABORT_CAUSE_ARB_LOST = 1UL << 12,
\r
463 /*!< Master Abort Arbitration Lost - If set (1),
\r
464 * master has lost arbitration, or if
\r
465 * IC_TX_ABRT_SOURCE[14] is also set, then the
\r
466 * slave transmitter has lost arbitration. Note:
\r
467 * I2C can be both master and slave at the same
\r
470 * Role of I2C: Master or Slave-Transmitter.
\r
472 ALT_I2C_TX_ABORT_CAUSE_SLVFLUSH_TXFIFO = 1UL << 13,
\r
473 /*!< Slave Abort Flush TXFIFO - If set (1), Slave
\r
474 * has received a read command and some data
\r
475 * exists in the TX FIFO so the slave issues a
\r
476 * TX_ABRT interrupt to flush old data in TX
\r
479 * Role of I2C: Slave-Transmitter.
\r
481 ALT_I2C_TX_ABORT_CAUSE_SLV_ARBLOST = 1UL << 14,
\r
482 /*!< Slave Abort Arbitration Lost - If set (1),
\r
483 * Slave lost the bus while transmitting data to
\r
484 * a remote master. IC_TX_ABRT_SOURCE[12] is set
\r
485 * at the same time.
\r
487 * Note: Even though the slave never owns the
\r
488 * bus, something could go wrong on the
\r
489 * bus. This is a fail safe check. For instance,
\r
490 * during a data transmission at the low-to-high
\r
491 * transition of SCL, if what is on the data bus
\r
492 * is not what is supposed to be transmitted,
\r
493 * then DW_apb_i2c no longer own the bus.
\r
495 * Role of I2C: Slave-Transmitter.
\r
497 ALT_I2C_TX_ABORT_CAUSE_SLVRD_INTX = 1UL << 15
\r
498 /*!< Slave Abort Read TX - If set (1),
\r
499 * when the processor side responds to a
\r
500 * slave mode request for data to be transmitted
\r
501 * to a remote master and user writes a 1 in CMD
\r
502 * (bit 8) of IC_DATA_CMD register.
\r
504 * Role of I2C: Slave-Transmitter.
\r
506 } ALT_I2C_TX_ABORT_CAUSE_t;
\r
509 * This type defines a structure for configuration of the SCL high and low counts
\r
510 * to ensure proper I/O timing with the device interface.
\r
512 * The SCL count values are only relevant if the I2C controller is enabled to as
\r
513 * an I2C master. The SCL count values are ignored when the I2C controller is
\r
514 * enabled as an I2C slave.
\r
516 * See: Clock Frequency Configuration section of <em>Chapter 20. I2C
\r
517 * Controller</em> in the <em>Cyclone V Device Handbook Volume 3: Hard
\r
518 * Processor System Technical Reference Manual</em> for a complete discussion
\r
519 * of calculation of the proper SCL clock high and low times.
\r
521 typedef struct ALT_I2C_MASTER_CONFIG_s
\r
523 ALT_I2C_ADDR_MODE_t addr_mode;
\r
524 /*!< The address mode (7 or 10 bit) when
\r
525 * acting as a master.
\r
527 bool restart_enable;
\r
528 /*!< This setting determines whether RESTART
\r
529 * conditions may be sent when acting as a
\r
530 * master. When the \e restart_enable is
\r
531 * false, the I2C controller master is
\r
532 * incapable of performing the following
\r
534 * * Sending a START BYTE
\r
535 * * Performing any high-speed mode
\r
537 * * Performing direction changes in
\r
538 * combined format mode
\r
539 * * Performing a read operation with a
\r
542 ALT_I2C_SPEED_t speed_mode;
\r
543 /*!< The speed mode of the I2C operation.
\r
545 uint16_t ss_scl_hcnt;
\r
546 /*!< The SCL clock high-period count for
\r
549 uint16_t ss_scl_lcnt;
\r
550 /*!< The SCL clock low-period count for
\r
553 uint16_t fs_scl_hcnt;
\r
554 /*!< The SCL clock high-period count for fast
\r
557 uint16_t fs_scl_lcnt;
\r
558 /*!< The SCL clock low-period count for fast
\r
562 /*!< The duration, measured in ic_clk cycles,
\r
563 * of the longest spike that is filtered out
\r
564 * by the spike suppression logic when the
\r
565 * component is operating in SS or FS modes.
\r
567 } ALT_I2C_MASTER_CONFIG_t;
\r
570 * This type defines a structure for configuration of the I2C controller when it
\r
571 * is operating in slave mode.
\r
573 typedef struct ALT_I2C_SLAVE_CONFIG_s
\r
575 ALT_I2C_ADDR_MODE_t addr_mode; /*!< The address mode (7 or 10 bit) when
\r
576 * acting as a slave.
\r
578 uint32_t addr; /*!< The slave address to which the I2C
\r
579 * controller responds when acting as a
\r
582 bool nack_enable; /*!< Enable generation of a NACK. when the
\r
583 * I2C controller is a
\r
584 * slave-receiver. If \b true, it can
\r
585 * only generate a NACK after a data
\r
586 * byte is received; hence, the data
\r
587 * transfer is aborted and the data
\r
588 * received is not pushed onto the
\r
589 * receive buffer. When \b false, it
\r
590 * generates NACK/ACK, depending on
\r
592 * * \b true = generate NACK after data
\r
594 * * \b false = generate NACK/ACK normally
\r
596 } ALT_I2C_SLAVE_CONFIG_t;
\r
599 * Initialize the specified I2C controller instance for use and return a device
\r
600 * handle referencing it.
\r
603 * The HPS I2C controller instance to initialize.
\r
606 * A pointer to the I2C controller device block instance.
\r
608 * \retval ALT_E_SUCCESS Successful status.
\r
609 * \retval ALT_E_ERROR Details about error status code
\r
612 * Initialization process:
\r
613 * * Initialize internal driver state
\r
614 * * Check clock setup (ALT_CLK_L4_SP)
\r
615 * * Take I2C instance out of reset (System Manager)
\r
616 * * Disable and clear all interrupts and status conditions
\r
617 * * Setup and initialize any expected initial I2C controller state
\r
620 ALT_STATUS_CODE alt_i2c_init(const ALT_I2C_CTLR_t i2c, ALT_I2C_DEV_t *i2c_dev);
\r
623 * Reset the specified I2C controller instance for use.
\r
626 * A pointer to the I2C controller device block instance.
\r
628 * \retval ALT_E_SUCCESS Successful status.
\r
629 * \retval ALT_E_ERROR Details about error status code
\r
633 * * Disable controller
\r
634 * * Initialize internal driver state
\r
635 * * Check clock setup (ALT_CLK_L4_SP)
\r
636 * * Take I2C instance out of reset (System Manager)
\r
637 * * Disable and clear all interrupts and status conditions
\r
638 * * Setup and initialize any expected initial I2C controller state
\r
639 * * Enable controller
\r
642 ALT_STATUS_CODE alt_i2c_reset(ALT_I2C_DEV_t * i2c_dev);
\r
645 * Uninitialize the I2C controller referenced by the \e i2c_dev handle.
\r
647 * This function attempts to gracefully shutdown the I2C controller by waiting for
\r
648 * any inpcomplete transactions to finish and then putting the I2C controller into
\r
652 * A pointer to the I2C controller device block instance.
\r
654 * \retval ALT_E_SUCCESS Successful status.
\r
655 * \retval ALT_E_ERROR Details about error status code
\r
660 ALT_STATUS_CODE alt_i2c_uninit(ALT_I2C_DEV_t *i2c_dev);
\r
663 * Disables the I2C controller.
\r
665 * When the I2C controller is disabled, the following occurs:
\r
666 * * The TX FIFO and RX FIFO get flushed.
\r
667 * * The I2C interrupt status conditions remain active until the I2C controller
\r
668 * goes into IDLE state.
\r
670 * If the controller is transmitting, it stops as well as deletes the contents of
\r
671 * the transmit buffer after the current transfer is complete. If the module is
\r
672 * receiving, the controller stops the current transfer at the end of the current
\r
673 * byte and does not acknowledge the transfer.
\r
676 * A pointer to the I2C controller device block instance.
\r
678 * \retval ALT_E_SUCCESS Successful status.
\r
679 * \retval ALT_E_ERROR Details about error status code
\r
682 * IC_ENABLE.ENABLE = 0
\r
683 * Follow the procedure in section 3.8.3 Disabling DW_apb_i2c of the DW Databook.
\r
686 ALT_STATUS_CODE alt_i2c_disable(ALT_I2C_DEV_t *i2c_dev);
\r
689 * Enables the I2C controller.
\r
692 * A pointer to the I2C controller device block instance.
\r
694 * \retval ALT_E_SUCCESS Successful status.
\r
695 * \retval ALT_E_ERROR Details about error status code
\r
698 * IC_ENABLE.ENABLE = 1
\r
701 ALT_STATUS_CODE alt_i2c_enable(ALT_I2C_DEV_t *i2c_dev);
\r
704 * Returns ALT_E_TRUE if the I2C controller is enabled.
\r
707 * A pointer to the I2C controller device block instance.
\r
709 * \retval ALT_E_SUCCESS Successful status.
\r
710 * \retval ALT_E_ERROR Details about error status code
\r
713 * IC_ENABLE.ENABLE == 1
\r
716 ALT_STATUS_CODE alt_i2c_is_enabled(ALT_I2C_DEV_t *i2c_dev);
\r
719 * Gets the current configuration of the I2C controller when operating in master
\r
723 * A pointer to the I2C controller device block instance.
\r
726 * [out] Pointer to a ALT_I2C_MASTER_CONFIG_t structure for holding
\r
727 * the returned I2C master mode configuration parameters.
\r
729 * \retval ALT_E_SUCCESS Successful status.
\r
730 * \retval ALT_E_ERROR Details about error status code
\r
735 ALT_STATUS_CODE alt_i2c_master_config_get(ALT_I2C_DEV_t *i2c_dev,
\r
736 ALT_I2C_MASTER_CONFIG_t* cfg);
\r
739 * Sets the configuration of the I2C controller with operational parameters for
\r
740 * operating in master mode.
\r
743 * A pointer to the I2C controller device block instance.
\r
746 * Pointer to a ALT_I2C_MASTER_CONFIG_t structure holding the desired
\r
747 * I2C master mode operational parameters.
\r
749 * \retval ALT_E_SUCCESS Successful status.
\r
750 * \retval ALT_E_ERROR Details about error status code
\r
755 ALT_STATUS_CODE alt_i2c_master_config_set(ALT_I2C_DEV_t *i2c_dev,
\r
756 const ALT_I2C_MASTER_CONFIG_t* cfg);
\r
759 * This is a utility function that returns the speed based on parameters of the
\r
760 * I2C master configuration.
\r
763 * A pointer to the I2C controller device block instance.
\r
766 * A pointer to the master confugurations.
\r
768 * \param speed_in_hz
\r
769 * [out] Speed (Hz) of the I2C bus currently configured at.
\r
771 * \retval ALT_E_SUCCESS Successful status.
\r
772 * \retval ALT_E_ERROR Details about error status code
\r
774 ALT_STATUS_CODE alt_i2c_master_config_speed_get(ALT_I2C_DEV_t *i2c_dev,
\r
775 const ALT_I2C_MASTER_CONFIG_t* cfg,
\r
776 uint32_t * speed_in_hz);
\r
779 * This is a utility function that computes parameters for the I2C master
\r
780 * configuration that best matches the speed requested.
\r
783 * A pointer to the I2C controller device block instance.
\r
786 * A pointer to the master confugurations.
\r
788 * \param speed_in_hz
\r
789 * Speed (Hz) of the I2C bus to configure.
\r
791 * \retval ALT_E_SUCCESS Successful status.
\r
792 * \retval ALT_E_ERROR Details about error status code
\r
797 ALT_STATUS_CODE alt_i2c_master_config_speed_set(ALT_I2C_DEV_t *i2c_dev,
\r
798 ALT_I2C_MASTER_CONFIG_t * cfg,
\r
799 uint32_t speed_in_hz);
\r
802 * Definition included for backwards compatibility.
\r
804 #define alt_i2c_cfg_to_speed(i2c_dev, speed_in_hz, cfg) alt_i2c_master_config_speed_get((i2c_dev), (cfg), (speed_in_hz))
\r
807 * Definition included for backwards compatibility.
\r
809 #define alt_i2c_speed_to_cfg(i2c_dev, speed_in_hz, cfg) alt_i2c_master_config_speed_set((i2c_dev), (cfg), (speed_in_hz))
\r
812 * Gets the current configuration of the I2C controller when operating in slave
\r
816 * A pointer to the I2C controller device block instance.
\r
819 * [out] Pointer to a ALT_I2C_SLAVE_CONFIG_t structure for holding
\r
820 * the returned I2C slave mode configuration parameters.
\r
822 * \retval ALT_E_SUCCESS Successful status.
\r
823 * \retval ALT_E_ERROR Details about error status code
\r
828 ALT_STATUS_CODE alt_i2c_slave_config_get(ALT_I2C_DEV_t *i2c_dev,
\r
829 ALT_I2C_SLAVE_CONFIG_t* cfg);
\r
832 * Sets the configuration of the I2C controller with operational parameters for
\r
833 * operating in slave mode.
\r
836 * A pointer to the I2C controller device block instance.
\r
839 * Pointer to a ALT_I2C_SLAVE_CONFIG_t structure holding the desired
\r
840 * I2C slave mode operational parameters.
\r
842 * \retval ALT_E_SUCCESS Successful status.
\r
843 * \retval ALT_E_ERROR Details about error status code
\r
848 ALT_STATUS_CODE alt_i2c_slave_config_set(ALT_I2C_DEV_t *i2c_dev,
\r
849 const ALT_I2C_SLAVE_CONFIG_t* cfg);
\r
851 /*! \addtogroup ALT_I2C_SDA_HOLD SDA Hold Time Configuration
\r
853 * The I2C protocol specification requires 300ns of hold time on the SDA signal in
\r
854 * standard and fast speed modes. Board delays on the SCL and SDA signals can mean
\r
855 * that the hold-time requirement is met at the I2C master, but not at the I2C
\r
856 * slave (or vice-versa). Because each system may encounter differing board signal
\r
857 * delays, the I2C controller provides the capability to adjust of the SDA
\r
860 * The functions in this section provide software configuration of SDA hold time
\r
861 * for the I2C controller.
\r
867 * Gets the currently configured value for the SDA hold time in I2C controller
\r
868 * clock (\ref ALT_CLK_L4_SP) clock ticks.
\r
871 * A pointer to the I2C controller device block instance.
\r
874 * [out] The configured SDA hold time in \ref ALT_CLK_L4_SP clock
\r
877 * \retval ALT_E_SUCCESS Successful status.
\r
878 * \retval ALT_E_ERROR Details about error status code
\r
883 ALT_STATUS_CODE alt_i2c_sda_hold_time_get(ALT_I2C_DEV_t *i2c_dev,
\r
884 uint16_t *hold_time);
\r
887 * Sets the configured value for the SDA hold time in terms of I2C controller
\r
888 * clock (\ref ALT_CLK_L4_SP) clock ticks.
\r
891 * A pointer to the I2C controller device block instance.
\r
894 * The SDA hold time in \ref ALT_CLK_L4_SP clock ticks.
\r
896 * \retval ALT_E_SUCCESS Successful status.
\r
897 * \retval ALT_E_ERROR Details about error status code
\r
900 * IC_SDA_HOLD is 16 bits wide. hold_time must be in range 0..65535.
\r
903 ALT_STATUS_CODE alt_i2c_sda_hold_time_set(ALT_I2C_DEV_t *i2c_dev,
\r
904 const uint16_t hold_time);
\r
909 * Gets the current operational mode of the I2C controller.
\r
912 * A pointer to the I2C controller device block instance.
\r
915 * [out] The current operational mode enabled for the I2C
\r
918 * \retval ALT_E_SUCCESS Successful status.
\r
919 * \retval ALT_E_ERROR Details about error status code
\r
924 ALT_STATUS_CODE alt_i2c_op_mode_get(ALT_I2C_DEV_t *i2c_dev,
\r
925 ALT_I2C_MODE_t* mode);
\r
928 * Sets the operational mode of the I2C controller.
\r
931 * A pointer to the I2C controller device block instance.
\r
934 * The operational mode to enable for the I2C controller.
\r
936 * \retval ALT_E_SUCCESS Successful status.
\r
937 * \retval ALT_E_ERROR Details about error status code
\r
942 ALT_STATUS_CODE alt_i2c_op_mode_set(ALT_I2C_DEV_t *i2c_dev,
\r
943 const ALT_I2C_MODE_t mode);
\r
946 * Returns ALT_E_TRUE if the I2C controller is busy. The I2C controller is busy if
\r
947 * either the Slave Finite State Machine (FSM) is not in the IDLE state or the
\r
948 * Master Finite State Machine (FSM) is not in the IDLE state.
\r
951 * A pointer to the I2C controller device block instance.
\r
953 * \retval ALT_E_SUCCESS Successful status.
\r
954 * \retval ALT_E_ERROR Details about error status code
\r
957 * IC_STATUS.ACTIVITY == 1
\r
958 * NOTE: IC_STATUS[0] that is, the ACTIVITY bit is the OR of SLV_ACTIVITY and
\r
959 * MST_ACTIVITY bits.
\r
962 ALT_STATUS_CODE alt_i2c_is_busy(ALT_I2C_DEV_t *i2c_dev);
\r
965 * This function reads a single data byte from the receive FIFO.
\r
967 * This function is used to perform low level access to the data bytes
\r
968 * received by the I2C controller and buffered in the receive FIFO. It
\r
969 * may be used by master-receivers or slave receivers.
\r
971 * This function does not check for valid data in the receive FIFO
\r
972 * beforehand and may cause an underflow if improperly used. It is
\r
973 * meant to be called from a context where preconditions have been
\r
974 * previously asserted such as in the implementation of the
\r
975 * alt_i2c_slave_receive() or alt_i2c_master_receive() function.
\r
978 * A pointer to the I2C controller device block instance.
\r
981 * [out] The single data byte read from the receive FIFO.
\r
983 * \retval ALT_E_SUCCESS Successful status.
\r
984 * \retval ALT_E_ERROR Details about error status code
\r
989 ALT_STATUS_CODE alt_i2c_read(ALT_I2C_DEV_t *i2c_dev, uint8_t *val);
\r
992 * This function writes a single data byte to the transmit FIFO.
\r
994 * This function is used to perform low level writes of data to the
\r
995 * transmit FIFO for transmission by the I2C controller. It may be
\r
996 * used by slave receivers.
\r
998 * This function does not check whether the transmit FIFO is full or
\r
999 * not beforehand and may cause an overflow if improperly used. It is
\r
1000 * meant to be called from a context where preconditions have been
\r
1001 * previously asserted such as in the implementation of the
\r
1002 * alt_i2c_slave_transmit() function.
\r
1005 * A pointer to the I2C controller device block instance.
\r
1008 * The data byte to write to the transmission FIFO.
\r
1010 * \retval ALT_E_SUCCESS Successful status.
\r
1011 * \retval ALT_E_ERROR Details about error status code
\r
1016 ALT_STATUS_CODE alt_i2c_write(ALT_I2C_DEV_t *i2c_dev, const uint8_t val);
\r
1019 * This function acts in the role of a slave-receiver by receiving a single data
\r
1020 * byte from the I2C bus in response to a write command from the master.
\r
1022 * This API is suitable for being called during an interrupt context. It is the
\r
1023 * programmer's responsibility to ensure that there is data in the RX FIFO to
\r
1024 * accomodate the request made.
\r
1026 * The I2C controller must be in slave mode before calling this function.
\r
1029 * A pointer to the I2C controller device block instance.
\r
1032 * [out] A pointer to a buffer to contain the received data byte.
\r
1034 * \retval ALT_E_SUCCESS Successful status.
\r
1035 * \retval ALT_E_ERROR Details about error status code
\r
1040 ALT_STATUS_CODE alt_i2c_slave_receive(ALT_I2C_DEV_t *i2c_dev,
\r
1044 * This function acts in the role of a slave-transmitter by transmitting a single
\r
1045 * data byte to the I2C bus in response to a read request from the master.
\r
1047 * This API is suitable for being called during an interrupt context. It is the
\r
1048 * programmer's responsibility to ensure that there is enough space in the TX
\r
1049 * FIFO to accomodate the request made.
\r
1051 * The I2C controller must be in slave mode before calling this function.
\r
1054 * A pointer to the I2C controller device block instance.
\r
1057 * The data byte to transmit.
\r
1059 * \retval ALT_E_SUCCESS Successful status.
\r
1060 * \retval ALT_E_ERROR Details about error status code
\r
1065 ALT_STATUS_CODE alt_i2c_slave_transmit(ALT_I2C_DEV_t *i2c_dev,
\r
1066 const uint8_t data);
\r
1069 * This function acts in the role of a slave-transmitter by transmitting data in
\r
1070 * bulk to the I2C bus in response to a series of read requests from a master.
\r
1072 * In the standard I2C protocol, all transactions are single byte transactions and
\r
1073 * the slave responds to a remote master read request by writing one byte into the
\r
1074 * slave's TX FIFO. When a slave (slave-transmitter) is issued with a read request
\r
1075 * from the remote master (master-receiver), at a minimum there should be at least
\r
1076 * one entry placed into the slave-transmitter's TX FIFO. The I2C controller is
\r
1077 * capable of handling more data in the TX FIFO so that subsequent read requests
\r
1078 * can receive that data without raising an interrupt or software having to poll
\r
1079 * to request more data. This eliminates overhead latencies from being incurred by
\r
1080 * servicing the interrupt or polling for data requests each time had there been a
\r
1081 * restriction of having only one entry placed in the TX FIFO.
\r
1083 * If the remote master acknowledges the data sent by the slave-transmitter and
\r
1084 * there is no data in the slave's TX FIFO, the I2C controller raises the read
\r
1085 * request interrupt and waits for data to be written into the TX FIFO before it
\r
1086 * can be sent to the remote master.
\r
1088 * If the programmer knows in advance that the master is requesting a packet of \e
\r
1089 * n bytes, then when another master request for data is received, the TX FIFO
\r
1090 * could be written with \e n number bytes and the master receives it as a
\r
1091 * continuous stream of data. For example, the slave continues to send data to the
\r
1092 * master as long as the master is acknowledging the data sent and there is data
\r
1093 * available in the TX FIFO. There is no need to hold the SCL line low or to issue
\r
1094 * READ request again.
\r
1096 * If the remote master is to receive \e n bytes from the slave but the programmer
\r
1097 * wrote a number of bytes larger than \e n to the TX FIFO, then when the slave
\r
1098 * finishes sending the requested \e n bytes, it clears the TX FIFO and ignores
\r
1099 * any excess bytes.
\r
1101 * This API is suitable for being called during an interrupt context. It is the
\r
1102 * programmer's responsibility to ensure that there is enough space in the TX
\r
1103 * FIFO to accomodate the request made.
\r
1105 * The I2C controller must be in slave mode before calling this function.
\r
1108 * A pointer to the I2C controller device block instance.
\r
1111 * A pointer to the data buffer to transmit.
\r
1114 * The size of the data buffer in bytes to place in the TX FIFO.
\r
1116 * \retval ALT_E_SUCCESS Successful status.
\r
1117 * \retval ALT_E_ERROR Details about error status code
\r
1120 * See: Section <em>Slave-Transfer Operation for Bulk Transfers</em> of the DW
\r
1121 * Databook for details of implementation and error conditions that may occur.
\r
1124 ALT_STATUS_CODE alt_i2c_slave_bulk_transmit(ALT_I2C_DEV_t *i2c_dev,
\r
1125 const void * data,
\r
1126 const size_t size);
\r
1129 * This function returns the current target address.
\r
1131 * The I2C controller must be in master mode before calling this function.
\r
1134 * A pointer to the I2C controller device block instance.
\r
1136 * \param target_addr
\r
1137 * [out] The 7 or 10 bit slave target address.
\r
1139 * \retval ALT_E_SUCCESS Successful status.
\r
1140 * \retval ALT_E_ERROR Details about error status code.
\r
1142 ALT_STATUS_CODE alt_i2c_master_target_get(ALT_I2C_DEV_t * i2c_dev, uint32_t * target_addr);
\r
1145 * This function updates the target slave address for any upcoming I2C bus IO.
\r
1147 * This API is not suitlabe for being called in an interrupt context as it
\r
1148 * will wait for the TX FIFO to flush before applying the changes. If the TX
\r
1149 * FIFO is known to be empty and the controller idle, then it can be safely
\r
1152 * The I2C controller must be in master mode before calling this function.
\r
1155 * A pointer to the I2C controller device block instance.
\r
1157 * \param target_addr
\r
1158 * The 7 or 10 bit slave target address.
\r
1160 * \retval ALT_E_SUCCESS Successful status.
\r
1161 * \retval ALT_E_ERROR Details about error status code.
\r
1163 ALT_STATUS_CODE alt_i2c_master_target_set(ALT_I2C_DEV_t * i2c_dev, uint32_t target_addr);
\r
1166 * This function acts in the role of a master-transmitter by issuing a write
\r
1167 * command and transmitting data to the I2C bus.
\r
1169 * This API is not suitable for being called in an interrupt context as it may
\r
1170 * wait for certain controller states before completing.
\r
1172 * The I2C controller must be in master mode before calling this function.
\r
1175 * A pointer to the I2C controller device block instance.
\r
1178 * A pointer to a data buffer to transmit
\r
1181 * The size of the data buffer in bytes to place in the TX FIFO.
\r
1183 * \param issue_restart
\r
1184 * This parameter controls whether a RESTART is issued before the
\r
1185 * byte is sent or received. If:
\r
1186 * * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
\r
1187 * is \b true, a RESTART is issued before the data is sent/received
\r
1188 * (according to the value of CMD), regardless of whether or not
\r
1189 * the transfer direction is changing from the previous command; if
\r
1190 * \e restart_enabled is \b false, a STOP followed by a START is
\r
1192 * * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
\r
1193 * is \b true, a RESTART is issued only if the transfer direction
\r
1194 * is changing from the previous command; if \e restart_enabled is
\r
1195 * \b false, a STOP followed by a START is issued instead.
\r
1197 * \param issue_stop
\r
1198 * This parameter controls whether a STOP is issued after the byte is
\r
1199 * sent or received. If:
\r
1200 * * \b true - STOP is issued after this byte, regardless of whether or
\r
1201 * not the Tx FIFO is empty. If the Tx FIFO is not empty, the
\r
1202 * master immediately tries to start a new transfer by issuing a
\r
1203 * START and arbitrating for the bus.
\r
1204 * * \b false - STOP is not issued after this byte, regardless of
\r
1205 * whether or not the Tx FIFO is empty. If the Tx FIFO is not
\r
1206 * empty, the master continues the current transfer by
\r
1207 * sending/receiving data bytes according to the value of the CMD
\r
1208 * bit. If the Tx FIFO is empty, the master holds the SCL line low
\r
1209 * and stalls the bus until a new command is available in the Tx
\r
1212 * \retval ALT_E_SUCCESS Successful status.
\r
1213 * \retval ALT_E_ERROR Details about error status code
\r
1218 ALT_STATUS_CODE alt_i2c_master_transmit(ALT_I2C_DEV_t *i2c_dev,
\r
1219 const void * data,
\r
1220 const size_t size,
\r
1221 const bool issue_restart,
\r
1222 const bool issue_stop);
\r
1225 * This function acts in the role of a master-receiver by receiving one or more
\r
1226 * data bytes transmitted from a slave in response to read requests issued from
\r
1229 * This function causes the master to issue the required number of read requests
\r
1230 * to the slave and read the received data bytes from the Rx FIFO.
\r
1232 * The \e issue_restart and \e issue_stop parameters apply to the final read
\r
1233 * request transaction in the \e num_data_entries sequence required to fulfill the
\r
1234 * aggregate receive request.
\r
1236 * This API is not suitable for being called in an interrupt context as it may
\r
1237 * wait for certain controller states before completing.
\r
1239 * The I2C controller must be in master mode before calling this function.
\r
1242 * A pointer to the I2C controller device block instance.
\r
1245 * [out] The data buffer to receive the requested \e size bytes.
\r
1248 * The size of the data buffer to read from the RX FIFO.
\r
1250 * \param issue_restart
\r
1251 * This parameter controls whether a RESTART is issued before the
\r
1252 * byte is sent or received. If:
\r
1253 * * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
\r
1254 * is \b true, a RESTART is issued before the data is sent/received
\r
1255 * (according to the value of CMD), regardless of whether or not
\r
1256 * the transfer direction is changing from the previous command; if
\r
1257 * \e restart_enabled is \b false, a STOP followed by a START is
\r
1259 * * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
\r
1260 * is \b true, a RESTART is issued only if the transfer direction
\r
1261 * is changing from the previous command; if \e restart_enabled is
\r
1262 * \b false, a STOP followed by a START is issued instead.
\r
1264 * \param issue_stop
\r
1265 * This parameter controls whether a STOP is issued after the byte is
\r
1266 * sent or received. If:
\r
1267 * * \b true - STOP is issued after this byte, regardless of whether or
\r
1268 * not the Tx FIFO is empty. If the Tx FIFO is not empty, the
\r
1269 * master immediately tries to start a new transfer by issuing a
\r
1270 * START and arbitrating for the bus.
\r
1271 * * \b false - STOP is not issued after this byte, regardless of
\r
1272 * whether or not the Tx FIFO is empty. If the Tx FIFO is not
\r
1273 * empty, the master continues the current transfer by
\r
1274 * sending/receiving data bytes according to the value of the CMD
\r
1275 * bit. If the Tx FIFO is empty, the master holds the SCL line low
\r
1276 * and stalls the bus until a new command is available in the Tx
\r
1279 * \retval ALT_E_SUCCESS Successful status.
\r
1280 * \retval ALT_E_ERROR Details about error status code
\r
1285 ALT_STATUS_CODE alt_i2c_master_receive(ALT_I2C_DEV_t *i2c_dev,
\r
1287 const size_t size,
\r
1288 const bool issue_restart,
\r
1289 const bool issue_stop);
\r
1292 * This function causes the I2C controller master to issue a READ request on the
\r
1293 * bus. This function is typically used during master-receiver transfers.
\r
1295 * The I2C controller must be in master mode before calling this function.
\r
1298 * A pointer to the I2C controller device block instance.
\r
1300 * \param issue_restart
\r
1301 * This parameter controls whether a RESTART is issued before the
\r
1302 * byte is sent or received. If:
\r
1303 * * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
\r
1304 * is \b true, a RESTART is issued before the data is sent/received
\r
1305 * (according to the value of CMD), regardless of whether or not
\r
1306 * the transfer direction is changing from the previous command; if
\r
1307 * \e restart_enabled is \b false, a STOP followed by a START is
\r
1309 * * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
\r
1310 * is \b true, a RESTART is issued only if the transfer direction
\r
1311 * is changing from the previous command; if \e restart_enabled is
\r
1312 * \b false, a STOP followed by a START is issued instead.
\r
1314 * \param issue_stop
\r
1315 * This parameter controls whether a STOP is issued after the byte is
\r
1316 * sent or received. If:
\r
1317 * * \b true - STOP is issued after this byte, regardless of whether or
\r
1318 * not the Tx FIFO is empty. If the Tx FIFO is not empty, the
\r
1319 * master immediately tries to start a new transfer by issuing a
\r
1320 * START and arbitrating for the bus.
\r
1321 * * \b false - STOP is not issued after this byte, regardless of
\r
1322 * whether or not the Tx FIFO is empty. If the Tx FIFO is not
\r
1323 * empty, the master continues the current transfer by
\r
1324 * sending/receiving data bytes according to the value of the CMD
\r
1325 * bit. If the Tx FIFO is empty, the master holds the SCL line low
\r
1326 * and stalls the bus until a new command is available in the Tx
\r
1329 * \retval ALT_E_SUCCESS Successful status.
\r
1330 * \retval ALT_E_ERROR Details about error status code
\r
1333 * Write IC_DATA_CMD.CMD = 1 (read request). IC_DATA_CMD.DAT is
\r
1334 * written with "don't care" values as these bits are ignored by the
\r
1335 * I2C controller .
\r
1338 ALT_STATUS_CODE alt_i2c_issue_read(ALT_I2C_DEV_t *i2c_dev,
\r
1339 const bool issue_restart,
\r
1340 const bool issue_stop);
\r
1343 * This function causes the I2C controller master to issue a send byte on the
\r
1344 * bus. This function is typically used during master-transmitter/slave-transmitter
\r
1347 * The I2C controller must be in master mode before calling this function.
\r
1350 * A pointer to the I2C controller device block instance.
\r
1353 * The data item to be transmitted.
\r
1355 * \param issue_restart
\r
1356 * This parameter controls whether a RESTART is issued before the
\r
1357 * byte is sent or received. If:
\r
1358 * * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
\r
1359 * is \b true, a RESTART is issued before the data is sent/received
\r
1360 * (according to the value of CMD), regardless of whether or not
\r
1361 * the transfer direction is changing from the previous command; if
\r
1362 * \e restart_enabled is \b false, a STOP followed by a START is
\r
1364 * * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
\r
1365 * is \b true, a RESTART is issued only if the transfer direction
\r
1366 * is changing from the previous command; if \e restart_enabled is
\r
1367 * \b false, a STOP followed by a START is issued instead.
\r
1369 * \param issue_stop
\r
1370 * This parameter controls whether a STOP is issued after the byte is
\r
1371 * sent or received. If:
\r
1372 * * \b true - STOP is issued after this byte, regardless of whether or
\r
1373 * not the Tx FIFO is empty. If the Tx FIFO is not empty, the
\r
1374 * master immediately tries to start a new transfer by issuing a
\r
1375 * START and arbitrating for the bus.
\r
1376 * * \b false - STOP is not issued after this byte, regardless of
\r
1377 * whether or not the Tx FIFO is empty. If the Tx FIFO is not
\r
1378 * empty, the master continues the current transfer by
\r
1379 * sending/receiving data bytes according to the value of the CMD
\r
1380 * bit. If the Tx FIFO is empty, the master holds the SCL line low
\r
1381 * and stalls the bus until a new command is available in the Tx
\r
1384 * \retval ALT_E_SUCCESS Successful status.
\r
1385 * \retval ALT_E_ERROR Details about error status code
\r
1388 * Write IC_DATA_CMD.CMD = 0 (write request).
\r
1391 ALT_STATUS_CODE alt_i2c_issue_write(ALT_I2C_DEV_t *i2c_dev,
\r
1392 const uint8_t value,
\r
1393 const bool issue_restart,
\r
1394 const bool issue_stop);
\r
1396 /******************************************************************************/
\r
1397 /*! \addtogroup ALT_I2C_GEN_CALL General Call
\r
1399 * The functions in this group support General Call addresses.
\r
1401 * The general call address is for addressing every device connected to the I2C
\r
1402 * bus at the same time. However, if a device does not need any of the data
\r
1403 * supplied within the general call structure, it can ignore this address by not
\r
1404 * issuing an acknowledgment. If a device does require data from a general call
\r
1405 * address, it acknowledges this address and behaves as a slave-receiver. The
\r
1406 * master does not actually know how many devices acknowledged if one or more
\r
1407 * devices respond. The second and following bytes are acknowledged by every
\r
1408 * slave-receiver capable of handling this data. A slave who cannot process one of
\r
1409 * these bytes must ignore it by not-acknowledging. If one or more slaves
\r
1410 * acknowledge, the not-acknowledge will not be seen by the master.
\r
1412 * The functions in this group do not provide any general call functional command
\r
1413 * interpretation or implementation (e.g. software reset).
\r
1419 * This function acts in the role of a master-transmitter by issuing a general
\r
1420 * call command to all devices connected to the I2C bus.
\r
1422 * The \e issue_restart and \e issue_stop parameters apply to the final write
\r
1423 * transaction in the \e num_data_entries byte transmission sequence.
\r
1425 * The I2C controller must be in master mode before calling this function.
\r
1427 * The target slave address will be modified by this function. Call
\r
1428 * alt_i2c_master_target_set() to reset the slave target address for
\r
1432 * A pointer to the I2C controller device block instance.
\r
1435 * An array of data byte(s) to transmit.
\r
1437 * \param num_data_entries
\r
1438 * The number of entries (bytes) in \e data to place in the TX FIFO.
\r
1440 * \param issue_restart
\r
1441 * This parameter controls whether a RESTART is issued before the
\r
1442 * byte is sent or received. If:
\r
1443 * * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
\r
1444 * is \b true, a RESTART is issued before the data is sent/received
\r
1445 * (according to the value of CMD), regardless of whether or not
\r
1446 * the transfer direction is changing from the previous command; if
\r
1447 * \e restart_enabled is \b false, a STOP followed by a START is
\r
1449 * * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
\r
1450 * is \b true, a RESTART is issued only if the transfer direction
\r
1451 * is changing from the previous command; if \e restart_enabled is
\r
1452 * \b false, a STOP followed by a START is issued instead.
\r
1454 * \param issue_stop
\r
1455 * This parameter controls whether a STOP is issued after the byte is
\r
1456 * sent or received. If:
\r
1457 * * \b true - STOP is issued after this byte, regardless of whether or
\r
1458 * not the Tx FIFO is empty. If the Tx FIFO is not empty, the
\r
1459 * master immediately tries to start a new transfer by issuing a
\r
1460 * START and arbitrating for the bus.
\r
1461 * * \b false - STOP is not issued after this byte, regardless of
\r
1462 * whether or not the Tx FIFO is empty. If the Tx FIFO is not
\r
1463 * empty, the master continues the current transfer by
\r
1464 * sending/receiving data bytes according to the value of the CMD
\r
1465 * bit. If the Tx FIFO is empty, the master holds the SCL line low
\r
1466 * and stalls the bus until a new command is available in the Tx
\r
1469 * \retval ALT_E_SUCCESS Successful status.
\r
1470 * \retval ALT_E_ERROR Details about error status code
\r
1475 ALT_STATUS_CODE alt_i2c_master_general_call(ALT_I2C_DEV_t *i2c_dev,
\r
1476 const void * data,
\r
1477 const size_t size,
\r
1478 const bool issue_restart,
\r
1479 const bool issue_stop);
\r
1482 * Disables the I2C controller from responding to a General Call address. The
\r
1483 * controller will respond with a NACK and no General Call status conditions or
\r
1484 * interrupts are generated.
\r
1487 * A pointer to the I2C controller device block instance.
\r
1489 * \retval ALT_E_SUCCESS Successful status.
\r
1490 * \retval ALT_E_ERROR Details about error status code
\r
1493 * IC_ACK_GENERAL_CALL.ACK_GEN_CALL = 0
\r
1496 ALT_STATUS_CODE alt_i2c_general_call_ack_disable(ALT_I2C_DEV_t *i2c_dev);
\r
1499 * Enables the I2C controller to respond with an ACK when it receives a General
\r
1503 * A pointer to the I2C controller device block instance.
\r
1505 * \retval ALT_E_SUCCESS Successful status.
\r
1506 * \retval ALT_E_ERROR Details about error status code
\r
1509 * IC_ACK_GENERAL_CALL.ACK_GEN_CALL = 1
\r
1512 ALT_STATUS_CODE alt_i2c_general_call_ack_enable(ALT_I2C_DEV_t *i2c_dev);
\r
1515 * Returns ALT_E_TRUE if the I2C controller is enabled to respond to General Call
\r
1519 * A pointer to the I2C controller device block instance.
\r
1521 * \retval ALT_E_SUCCESS Successful status.
\r
1522 * \retval ALT_E_ERROR Details about error status code
\r
1525 * IC_ACK_GENERAL_CALL.ACK_GEN_CALL == 1
\r
1528 ALT_STATUS_CODE alt_i2c_general_call_ack_is_enabled(ALT_I2C_DEV_t *i2c_dev);
\r
1532 /******************************************************************************/
\r
1533 /*! \addtogroup ALT_I2C_INT Interrupt and Status Conditions
\r
1535 * The functions in this group provide management for the I2C controller status
\r
1536 * conditions and interrupts.
\r
1538 * Each I2C controller has a single combined interrupt output (\b
\r
1539 * ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ). The following events can generate an
\r
1541 * * General Call Address Received
\r
1542 * * Start or Restart Condition Occurred
\r
1543 * * Stop Condition Occurred
\r
1544 * * I2C Controller Activity
\r
1546 * * Transmit Abort
\r
1548 * * Transmit Buffer Empty
\r
1549 * * Transmit Overflow
\r
1550 * * Receive Buffer Full
\r
1551 * * Receive Overflow
\r
1552 * * Receive Underflow
\r
1554 * These interrupt status conditions may be monitored either by polling their
\r
1555 * status or by configuring interrupt handlers using the HWLIB Interrupt
\r
1558 * Functions to get the current status, enable or disable (i.e. mass or unmask),
\r
1559 * and clear interrupt status conditions for the I2C controller are defined in
\r
1566 * Returns the current I2C controller interrupt status conditions.
\r
1568 * This function returns the current value of the I2C controller interrupt status
\r
1569 * register value which reflects the current I2C controller status conditions that
\r
1570 * are not disabled (i.e. masked).
\r
1573 * A pointer to the I2C controller device block instance.
\r
1576 * [out] A pointer to a bit mask of the active \ref ALT_I2C_STATUS_t
\r
1577 * interrupt and status conditions.
\r
1579 * \retval ALT_E_SUCCESS Successful status.
\r
1580 * \retval ALT_E_ERROR Details about error status code
\r
1586 ALT_STATUS_CODE alt_i2c_int_status_get(ALT_I2C_DEV_t *i2c_dev,
\r
1587 uint32_t *status);
\r
1590 * Returns the I2C controller raw interrupt status conditions irrespective of
\r
1591 * the interrupt status condition enablement state.
\r
1593 * This function returns the current value of the I2C controller raw interrupt
\r
1594 * status register value which reflects the current I2C controller status
\r
1595 * conditions regardless of whether they are disabled (i.e. masked) or not.
\r
1598 * A pointer to the I2C controller device block instance.
\r
1601 * [out] A pointer to a bit mask of the active \ref ALT_I2C_STATUS_t
\r
1602 * interrupt and status conditions.
\r
1604 * \retval ALT_E_SUCCESS Successful status.
\r
1605 * \retval ALT_E_ERROR Details about error status code
\r
1611 ALT_STATUS_CODE alt_i2c_int_raw_status_get(ALT_I2C_DEV_t *i2c_dev,
\r
1612 uint32_t *status);
\r
1615 * Clears the specified I2C controller interrupt status conditions identified
\r
1618 * This function clears one or more of the status conditions as contributors to
\r
1619 * the \b ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state.
\r
1622 * A pointer to the I2C controller device block instance.
\r
1625 * Specifies the QSPI interrupt status conditions to clear. \e mask
\r
1626 * is a mask of logically OR'ed \ref ALT_I2C_STATUS_t values that
\r
1627 * designate the status conditions to clear.
\r
1629 * \retval ALT_E_SUCCESS Successful status.
\r
1630 * \retval ALT_E_ERROR Details about error status code
\r
1635 ALT_STATUS_CODE alt_i2c_int_clear(ALT_I2C_DEV_t *i2c_dev, const uint32_t mask);
\r
1638 * Disable the specified I2C controller interrupt status conditions identified in
\r
1641 * This function disables one or more of the status conditions as contributors to
\r
1642 * the \b ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state.
\r
1644 * NOTE: A cleared bit for any status condition in the mask value does not have
\r
1645 * the effect of enabling it as a contributor to the \b
\r
1646 * ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state. The function
\r
1647 * alt_i2c_int_enable() is used to enable status source conditions.
\r
1650 * A pointer to the I2C controller device block instance.
\r
1653 * Specifies the status conditions to disable as interrupt source
\r
1654 * contributors. \e mask is a mask of logically OR'ed \ref
\r
1655 * ALT_I2C_STATUS_t values that designate the status conditions to
\r
1658 * \retval ALT_E_SUCCESS Successful status.
\r
1659 * \retval ALT_E_ERROR Details about error status code
\r
1664 ALT_STATUS_CODE alt_i2c_int_disable(ALT_I2C_DEV_t *i2c_dev, const uint32_t mask);
\r
1667 * Enable the specified I2C controller interrupt status conditions identified in
\r
1670 * This function enables one or more of the status conditions as contributors to
\r
1671 * the \b ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state.
\r
1673 * NOTE: A cleared bit for any status condition in the mask value does not have
\r
1674 * the effect of disabling it as a contributor to the \b
\r
1675 * ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state. The function
\r
1676 * alt_i2c_int_disable() is used to disable status source conditions.
\r
1679 * A pointer to the I2C controller device block instance.
\r
1682 * Specifies the status conditions to enable as interrupt source
\r
1683 * contributors. \e mask is a mask of logically OR'ed \ref
\r
1684 * ALT_I2C_STATUS_t values that designate the status conditions to
\r
1687 * \retval ALT_E_SUCCESS Successful status.
\r
1688 * \retval ALT_E_ERROR Details about error status code
\r
1693 ALT_STATUS_CODE alt_i2c_int_enable(ALT_I2C_DEV_t *i2c_dev, const uint32_t mask);
\r
1696 * Gets the cause of I2C transmission abort. A I2C transmission abort indicates
\r
1697 * that the I2C transmitter is unable to complete the intended actions on the
\r
1698 * contents of the transmit FIFO. This situation can occur both as an I2C master
\r
1699 * or an I2C slave, and is referred to as a "transmit abort".
\r
1701 * The returned value of this function is the value of the IC_TX_ABRT_SOURCE
\r
1702 * register which indicates the cause why the transmit abort occurred.
\r
1705 * A pointer to the I2C controller device block instance.
\r
1708 * [out] A pointer to a bit mask of the \ref ALT_I2C_TX_ABORT_CAUSE_t
\r
1709 * causes of the transmission abort.
\r
1711 * \retval ALT_E_SUCCESS Successful status.
\r
1712 * \retval ALT_E_ERROR Details about error status code
\r
1715 * IC_TX_ABRT_SOURCE
\r
1718 ALT_STATUS_CODE alt_i2c_tx_abort_cause_get(ALT_I2C_DEV_t *i2c_dev,
\r
1719 ALT_I2C_TX_ABORT_CAUSE_t *cause);
\r
1723 /******************************************************************************/
\r
1724 /*! \addtogroup ALT_I2C_RX_FIFO RX FIFO Management
\r
1726 * The receive FIFO has a configurable threshold value that controls the level of
\r
1727 * entries (or above) that sets the RX_FULL status condition and triggers an
\r
1728 * interrupt. The valid range is 0 - (ALT_I2C_RX_FIFO_NUM_ENTRIES-1), with the
\r
1729 * additional restriction that I2C controller does not allow this value to be set
\r
1730 * to a value larger than the depth of the buffer. If an attempt is made to do
\r
1731 * that, the actual value set will be the maximum depth of the buffer. A value of
\r
1732 * 0 sets the threshold for 1 entry, and a value of (ALT_I2C_RX_FIFO_NUM_ENTRIES-1)
\r
1733 * sets the threshold for ALT_I2C_RX_FIFO_NUM_ENTRIES entries.
\r
1739 * The number of entries (depth) of the I2C controller receive FIFO.
\r
1741 #define ALT_I2C_RX_FIFO_NUM_ENTRIES 64
\r
1744 * Returns ALT_E_TRUE when the receive FIFO is empty.
\r
1747 * A pointer to the I2C controller device block instance.
\r
1749 * \retval ALT_E_SUCCESS Successful status.
\r
1750 * \retval ALT_E_ERROR Details about error status code
\r
1753 * IC_STATUS.RFNE == 0
\r
1756 ALT_STATUS_CODE alt_i2c_rx_fifo_is_empty(ALT_I2C_DEV_t *i2c_dev);
\r
1759 * Returns ALT_E_TRUE when the receive FIFO is completely full.
\r
1762 * A pointer to the I2C controller device block instance.
\r
1764 * \retval ALT_E_SUCCESS Successful status.
\r
1765 * \retval ALT_E_ERROR Details about error status code
\r
1768 * IC_STATUS.RFF == 1
\r
1771 ALT_STATUS_CODE alt_i2c_rx_fifo_is_full(ALT_I2C_DEV_t *i2c_dev);
\r
1774 * Returns the number of valid entries in the receive FIFO.
\r
1777 * A pointer to the I2C controller device block instance.
\r
1779 * \param num_entries
\r
1780 * [out] The number of entries in the receive FIFO.
\r
1782 * \retval ALT_E_SUCCESS Successful status.
\r
1783 * \retval ALT_E_ERROR Details about error status code
\r
1789 ALT_STATUS_CODE alt_i2c_rx_fifo_level_get(ALT_I2C_DEV_t *i2c_dev,
\r
1790 uint32_t *num_entries);
\r
1793 * Gets the current receive FIFO threshold level value.
\r
1796 * A pointer to the I2C controller device block instance.
\r
1798 * \param threshold
\r
1799 * [out] The current threshold value.
\r
1801 * \retval ALT_E_SUCCESS Successful status.
\r
1802 * \retval ALT_E_ERROR Details about error status code
\r
1808 ALT_STATUS_CODE alt_i2c_rx_fifo_threshold_get(ALT_I2C_DEV_t *i2c_dev,
\r
1809 uint8_t *threshold);
\r
1812 * Sets the current receive FIFO threshold level value.
\r
1815 * A pointer to the I2C controller device block instance.
\r
1817 * \param threshold
\r
1818 * The threshold value.
\r
1820 * \retval ALT_E_SUCCESS Successful status.
\r
1821 * \retval ALT_E_ERROR Details about error status code
\r
1824 * IC_RX_TL.RX_TL = threshold
\r
1827 ALT_STATUS_CODE alt_i2c_rx_fifo_threshold_set(ALT_I2C_DEV_t *i2c_dev,
\r
1828 const uint8_t threshold);
\r
1832 /******************************************************************************/
\r
1833 /*! \addtogroup ALT_I2C_TX_FIFO TX FIFO Management
\r
1835 * The transmit FIFO has a configurable threshold value that controls the level of
\r
1836 * entries (or below) that sets the TX_EMPTY status condition and triggers an
\r
1837 * interrupt. The valid range is 0 - (ALT_I2C_TX_FIFO_NUM_ENTRIES-1), with the
\r
1838 * additional restriction that I2C controller does not allow this value to be set
\r
1839 * to a value larger than the depth of the buffer. If an attempt is made to do
\r
1840 * that, the actual value set will be the maximum depth of the buffer. A value of
\r
1841 * 0 sets the threshold for 0 entries, and a value of (ALT_I2C_TX_FIFO_NUM_ENTRIES-1)
\r
1842 * sets the threshold for (ALT_I2C_TX_FIFO_NUM_ENTRIES-1) entries.
\r
1848 * The number of entries (depth) of the I2C controller transmit FIFO.
\r
1850 #define ALT_I2C_TX_FIFO_NUM_ENTRIES 64
\r
1853 * Returns ALT_E_TRUE when the transmit FIFO is empty.
\r
1856 * A pointer to the I2C controller device block instance.
\r
1858 * \retval ALT_E_SUCCESS Successful status.
\r
1859 * \retval ALT_E_ERROR Details about error status code
\r
1862 * IC_STATUS.TFE == 1
\r
1865 ALT_STATUS_CODE alt_i2c_tx_fifo_is_empty(ALT_I2C_DEV_t *i2c_dev);
\r
1868 * Returns ALT_E_TRUE when the transmit FIFO is completely full.
\r
1871 * A pointer to the I2C controller device block instance.
\r
1873 * \retval ALT_E_SUCCESS Successful status.
\r
1874 * \retval ALT_E_ERROR Details about error status code
\r
1877 * IC_STATUS.TFNF == 0
\r
1880 ALT_STATUS_CODE alt_i2c_tx_fifo_is_full(ALT_I2C_DEV_t *i2c_dev);
\r
1883 * Returns the number of valid entries in the transmit FIFO.
\r
1886 * A pointer to the I2C controller device block instance.
\r
1888 * \param num_entries
\r
1889 * [out] The number of entries in the transmit FIFO.
\r
1891 * \retval ALT_E_SUCCESS Successful status.
\r
1892 * \retval ALT_E_ERROR Details about error status code
\r
1898 ALT_STATUS_CODE alt_i2c_tx_fifo_level_get(ALT_I2C_DEV_t *i2c_dev,
\r
1899 uint32_t *num_entries);
\r
1902 * Gets the current transmit FIFO threshold level value.
\r
1905 * A pointer to the I2C controller device block instance.
\r
1907 * \param threshold
\r
1908 * [out] The current threshold value.
\r
1910 * \retval ALT_E_SUCCESS Successful status.
\r
1911 * \retval ALT_E_ERROR Details about error status code
\r
1917 ALT_STATUS_CODE alt_i2c_tx_fifo_threshold_get(ALT_I2C_DEV_t *i2c_dev,
\r
1918 uint8_t *threshold);
\r
1921 * Sets the current transmit FIFO threshold level value.
\r
1924 * A pointer to the I2C controller device block instance.
\r
1926 * \param threshold
\r
1927 * The threshold value.
\r
1929 * \retval ALT_E_SUCCESS Successful status.
\r
1930 * \retval ALT_E_ERROR Details about error status code
\r
1933 * IC_TX_TL.TX_TL = threshold
\r
1936 ALT_STATUS_CODE alt_i2c_tx_fifo_threshold_set(ALT_I2C_DEV_t *i2c_dev,
\r
1937 const uint8_t threshold);
\r
1941 /******************************************************************************/
\r
1942 /*! \addtogroup ALT_I2C_DMA DMA Interface
\r
1944 * The DMA interface has a configurable threshold value that controls the
\r
1945 * level of entries that triggers the burst handshaking request used for DMA
\r
1948 * For the TX threshold, if the number of entries in the TX FIFO is at or
\r
1949 * below the set threshold, a DMA handshaking request will be made. The valid
\r
1950 * range for the TX threshold is 0 - (ALT_I2C_TX_FIFO_NUM_ENTRIES - 1).
\r
1952 * For the RX threshold, if the number of entries in the RX FIFO is above the
\r
1953 * set threshold, a DMA handshaking request will be made. The valid range for
\r
1954 * the RX treshold is 0 - (ALT_I2C_TX_FIFO_NUM_ENTRIES - 1).
\r
1956 * Having a higher threshold can improve the AXI bus utilization at the
\r
1957 * expense of the likelyhoold of overflow / underflow conditions.
\r
1962 * Gets the current RX DMA threshold level value.
\r
1965 * A pointer to the I2C controller device block instance.
\r
1967 * \param threshold
\r
1968 * [out] The threshold value.
\r
1970 * \retval ALT_E_SUCCESS Successful status.
\r
1971 * \retval ALT_E_ERROR Details about error status code
\r
1973 ALT_STATUS_CODE alt_i2c_rx_dma_threshold_get(ALT_I2C_DEV_t * i2c_dev, uint8_t * threshold);
\r
1976 * Sets the current RX DMA threshold level value.
\r
1979 * A pointer to the I2C controller device block instance.
\r
1981 * \param threshold
\r
1982 * The threshold value.
\r
1984 * \retval ALT_E_SUCCESS Successful status.
\r
1985 * \retval ALT_E_ERROR Details about error status code
\r
1987 ALT_STATUS_CODE alt_i2c_rx_dma_threshold_set(ALT_I2C_DEV_t * i2c_dev, uint8_t threshold);
\r
1990 * Gets the current TX DMA threshold level value.
\r
1993 * A pointer to the I2C controller device block instance.
\r
1995 * \param threshold
\r
1996 * [out] The threshold value.
\r
1998 * \retval ALT_E_SUCCESS Successful status.
\r
1999 * \retval ALT_E_ERROR Details about error status code
\r
2001 ALT_STATUS_CODE alt_i2c_tx_dma_threshold_get(ALT_I2C_DEV_t * i2c_dev, uint8_t * threshold);
\r
2004 * Sets the current TX DMA threshold level value.
\r
2007 * A pointer to the I2C controller device block instance.
\r
2009 * \param threshold
\r
2010 * The threshold value.
\r
2012 * \retval ALT_E_SUCCESS Successful status.
\r
2013 * \retval ALT_E_ERROR Details about error status code
\r
2015 ALT_STATUS_CODE alt_i2c_tx_dma_threshold_set(ALT_I2C_DEV_t * i2c_dev, uint8_t threshold);
\r
2021 #ifdef __cplusplus
\r
2023 #endif /* __cplusplus */
\r
2024 #endif /* __ALT_I2C_H__ */
\r
projects / freertos / blob