source: rtems/c/src/lib/libbsp/arm/altera-cyclone-v/hwlib/include/alt_i2c.h @ 3f9cd87d

4.115
Last change on this file since 3f9cd87d was 3f9cd87d, checked in by Christian Mauderer <Christian.Mauderer@…>, on 07/14/14 at 14:33:52

bsp/altera-cyclone-v: Add a simple I2C driver.

  • Property mode set to 100644
File size: 85.5 KB
Line 
1/******************************************************************************
2*
3* Copyright 2013 Altera Corporation. All Rights Reserved.
4*
5* Redistribution and use in source and binary forms, with or without
6* modification, are permitted provided that the following conditions are met:
7*
8* 1. Redistributions of source code must retain the above copyright notice,
9* this list of conditions and the following disclaimer.
10*
11* 2. Redistributions in binary form must reproduce the above copyright notice,
12* this list of conditions and the following disclaimer in the documentation
13* and/or other materials provided with the distribution.
14*
15* 3. The name of the author may not be used to endorse or promote products
16* derived from this software without specific prior written permission.
17*
18* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR
19* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
20* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO
21* EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
22* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
23* OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
26* IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
27* OF SUCH DAMAGE.
28*
29******************************************************************************/
30
31/*! \file
32 *  Altera - I2C Controller API
33 */
34
35#ifndef __ALT_I2C_H__
36#define __ALT_I2C_H__
37
38#include "hwlib.h"
39#include "alt_clock_manager.h"
40#include "socal/alt_i2c.h"
41#include "socal/alt_rstmgr.h"
42#include "socal/hps.h"
43#include "socal/socal.h"
44
45#ifdef __cplusplus
46extern "C"
47{
48#endif  /* __cplusplus */
49
50/******************************************************************************/
51/*! \addtogroup ALT_I2C I2C Controller API
52 *
53 * This module defines an API for configuring and managing the HPS I2C controllers.
54 *
55 * The I2C controller provides support for a communication link between integrated
56 * circuits on a board. It is a simple two-wire bus which consists of a serial
57 * data line (SDA) and a serial clock (SCL) for use in applications such as
58 * temperature sensors and voltage level translators to EEPROMs, A/D and D/A
59 * converters, CODECs, and many types of microprocessors.
60 *
61 * The Hard Processor System (HPS) provides four I2C controllers to enable system
62 * software to communicate serially with I2C buses. Each I2C controller can
63 * operate in master or slave mode, and support standard mode of up to 100
64 * kilobits per second (Kbps) or fast mode of up to 400 Kbps. These I2C
65 * controllers are instances of the Synopsys DesignWare APB I2C (DW_apb_i2c)
66 * controller.
67 *
68 * NOTE: Each I2C controller must be programmed to operate in either master or
69 *       slave mode only. Operating as a master and slave simultaneously is not
70 *       supported.
71 *
72 * Features of the I2C Controller:
73 *  * Support both 100 KBps and 400 KBps modes
74 *  * One of the following I2C operations: master or slave
75 *  * Support both 7-bit and 10-bit addressing modes
76 *  * Mixed read and write combined-format transactions
77 *  * Bulk transmit mode
78 *  * DMA handshaking interface
79 *
80 * For a complete details on the configuration and operation of I2C controller,
81 * consult the following references:
82 *  * <em>Cyclone V Device Handbook Volume 3: Hard Processor System Technical
83 *    Reference Manual, Chapter 20. I2C Controller (cv_54020-1.2)</em>
84 *  * <em>Synopsys DesignWare DW_apb_i2c Databook DW_apb_i2c, Version 1.15a</em>
85 *  * <em>The I2C-Bus Specification Version 2.1</em>
86 *
87 * @{
88 */
89
90/******************************************************************************/
91/*!
92 * This type definition enumerates the operational state of I2C by
93 * transfer operation.
94 */
95typedef enum ALT_I2C_TRANSFER_TYPE_e
96{
97    ALT_I2C_TRANSFER_NONE     = 0, /*!< No transfer operation */
98    ALT_I2C_TRANSFER_START    = 1, /*!< Start detect */
99    ALT_I2C_TRANSFER_COMPLETE = 2, /*!< All operations done */
100    ALT_I2C_TRANSFER_READ     = 3, /*!< Read operation is active */
101    ALT_I2C_TRANSFER_WRITE    = 4, /*!< Write operation is active */
102}
103ALT_I2C_TRANSFER_TYPE_t;
104
105
106/*
107 * A pointer or handle to the I2C controller device instance. The ALT_I2C_DEV_t is
108 * initialized by a call to alt_i2c_init() and subsequently used by the other I2C
109 * controller API functions as a reference to a specific device.
110 *
111 * \internal
112 * ALT_I2C_DEV_t may be a struct or reference to an opaque data
113 * structure. Whatever "internal" type is suited to the needs of the
114 * implementation.
115 * \endinternal
116 */
117typedef struct ALT_I2C_DEV_s
118{
119    void *                  location;    /*!< HPS address of I2C instance. */
120    alt_freq_t              clock_freq;  /*!< Input clock frequency. */
121    uint32_t                last_target; /*!< Last issued target address. */
122}
123ALT_I2C_DEV_t;
124
125/*!
126 * This type enumerates the HPS I2C controller instances.
127 */
128typedef enum ALT_I2C_CTLR_e
129{
130    ALT_I2C_I2C0        = (int)ALT_I2C0_OFST,  /*!< I2C0 instance. */
131    ALT_I2C_I2C1        = (int)ALT_I2C1_OFST,  /*!< I2C1 instance. */
132    ALT_I2C_I2C2        = (int)ALT_I2C2_OFST,  /*!< I2C2 instance. */
133    ALT_I2C_I2C3        = (int)ALT_I2C3_OFST,  /*!< I2C3 instance. */
134} ALT_I2C_CTLR_t;
135
136/*!
137 * This type enumerates the modes that the I2C controller may operate in.
138 *
139 * NOTE: Each I2C controller must be programmed to operate in either master or
140 *       slave mode only. Operating as a master and slave simultaneously is not
141 *       supported.
142 */
143typedef enum ALT_I2C_MODE_e
144{
145    ALT_I2C_MODE_SLAVE     = ALT_I2C_CON_MST_MOD_E_DIS,  /*!< Slave Mode  */
146    ALT_I2C_MODE_MASTER    = ALT_I2C_CON_MST_MOD_E_EN    /*!< Master Mode */
147} ALT_I2C_MODE_t;
148
149/*!
150 * This type enumerates the I2C controller operational speed modes.
151 *
152 * The I2C controller can operate in standard mode (with data rates 0 to 100 Kbps)
153 * or fast mode (with data rates less than or equal to 400 Kbps). Additionally,
154 * fast mode devices are downward compatible. For instance, fast mode devices can
155 * communicate with standard mode devices in 0 to 100 Kbps I2C bus
156 * system. However, standard mode devices are not upward compatible and should not
157 * be incorporated in a fast-mode I2C bus system as they cannot follow the higher
158 * transfer rate and therefore unpredictable states would occur.
159 *
160 * This setting is relevant only if one is operating the I2C in master mode.
161 */
162typedef enum ALT_I2C_SPEED_e
163{
164    ALT_I2C_SPEED_STANDARD   = ALT_I2C_CON_SPEED_E_STANDARD,
165                                    /*!< Standard mode (0 to 100 Kbps) */
166    ALT_I2C_SPEED_FAST       = ALT_I2C_CON_SPEED_E_FAST
167                                    /*!< Fast mode (<= 400 Kbps)       */
168} ALT_I2C_SPEED_t;
169
170/*!
171 * This type enumerates the two addressing modes formats supported by the I2C
172 * controller.
173 *
174 * The I2C controller does not support mixed address format - that is, a 7-bit
175 * address transaction followed by a 10-bit address transaction or vice versa -
176 * combined format transactions.
177 */
178typedef enum ALT_I2C_ADDR_MODE_e
179{
180    ALT_I2C_ADDR_MODE_7_BIT     = ALT_I2C_TAR_IC_10BITADDR_MST_E_START7,
181                                    /*!< 7-Bit Address Format  */
182    ALT_I2C_ADDR_MODE_10_BIT    = ALT_I2C_TAR_IC_10BITADDR_MST_E_START10
183                                    /*!< 10-Bit Address Format */
184} ALT_I2C_ADDR_MODE_t;
185
186/*!
187 * This type enumerates interrupt status conditions for the I2C controller.
188 */
189typedef enum ALT_I2C_STATUS_e
190{
191    ALT_I2C_STATUS_RX_UNDER     = 1UL << 0,
192                                /*!< Set if the processor attempts to read the
193                                 *   receive buffer when it is empty. If the I2C
194                                 *   controller is disabled, this status keeps
195                                 *   maintains its state until the master or slave
196                                 *   state machines go into idle, then this
197                                 *   interrupt is cleared.
198                                 */
199    ALT_I2C_STATUS_RX_OVER      = 1UL << 1,
200                                /*!< Set if the receive buffer is completely
201                                 *   filled to capacity and an additional byte is
202                                 *   received from an external I2C device. The I2C
203                                 *   controller acknowledges this, but any data
204                                 *   bytes received after the FIFO is full are
205                                 *   discarded. If the I2C controller is disabled,
206                                 *   this status maintains its statue until the
207                                 *   master or slave state machines go into idle,
208                                 *   then this interrupt is cleared.
209                                 */
210    ALT_I2C_STATUS_RX_FULL      = 1UL << 2,
211                                /*!< Set when the receive buffer reaches or goes
212                                 *   above the RX_TL threshold. It is
213                                 *   automatically cleared by hardware when buffer
214                                 *   level goes below the threshold. If the I2C
215                                 *   controller is disabled, the RX FIFO is
216                                 *   flushed and held in reset; therefore the RX
217                                 *   FIFO is not full. So this bit is cleared once
218                                 *   the I2C controller is disabled, regardless of
219                                 *   the activity that continues.
220                                 */
221    ALT_I2C_STATUS_TX_OVER     = 1UL << 3,
222                                /*!< Set during transmit if the transmit buffer is
223                                 *   filled to capacity and the processor attempts
224                                 *   to issue another I2C command. When the I2C
225                                 *   controller is disabled, this bit maintains
226                                 *   its state until the master or slave state
227                                 *   machines go into idle, then this interrupt is
228                                 *   cleared.
229                                 */
230    ALT_I2C_STATUS_TX_EMPTY     = 1UL << 4,
231                                /*!< This bit is set to 1 when the transmit buffer
232                                 *   is at or below the configured threshold
233                                 *   value. It is automatically cleared by
234                                 *   hardware when the buffer level goes above the
235                                 *   threshold. When the I2C controller is
236                                 *   disabled, the TX FIFO is flushed and held in
237                                 *   reset. The TX FIFO appears as if it has no
238                                 *   data in it, so this bit is set to 1, provided
239                                 *   there is activity in the master or slave
240                                 *   state machines. When there is no longer
241                                 *   activity, then this bit is set to 0.
242                                 *
243                                 */
244    ALT_I2C_STATUS_RD_REQ       = 1UL << 5,
245                                /*!< This bit is set to 1 when I2C is acting as a
246                                 *   slave and another I2C master is attempting to
247                                 *   read data from the I2C. The I2C holds the bus
248                                 *   in a wait state until this interrupt is
249                                 *   serviced, which means that the slave has been
250                                 *   addressed by a remote master that is asking
251                                 *   for data to be transferred. The processor
252                                 *   must respond to this interrupt and then write
253                                 *   the requested data. This bit is set to 0 just
254                                 *   after the processor by calling
255                                 *   alt_i2c_int_clear() with
256                                 *   ALT_I2C_STATUS_RD_REQ in the mask..
257                                 */
258    ALT_I2C_STATUS_TX_ABORT     = 1UL << 6,
259                                /*!< This bit indicates if I2C, as an I2C
260                                 *   transmitter, is unable to complete the
261                                 *   intended actions on the contents of the
262                                 *   transmit FIFO. This situation can occur both
263                                 *   as an I2C master or an I2C slave, and is
264                                 *   referred to as a 'transmit abort'. When this
265                                 *   bit is set to 1, the IC_TX_ABRT_SOURCE
266                                 *   register indicates the reason why the
267                                 *   transmit abort takes places.
268                                 *
269                                 *   NOTE: The I2C flushes/resets/empties the TX
270                                 *   FIFO whenever this bit is set. The TX FIFO
271                                 *   remains in this flushed state until the
272                                 *   register alt_i2c_int_clear() with
273                                 *   ALT_I2C_STATUS_TX_ABORT in the mask is
274                                 *   called. Once this happens, the TX FIFO is
275                                 *   then ready to accept more data bytes from the
276                                 *   APB interface.
277                                 */
278    ALT_I2C_STATUS_RX_DONE      = 1UL << 7,
279                                /*!< When the I2C is acting as a
280                                 *   slave-transmitter, this bit is set to 1 if
281                                 *   the master does not acknowledge a transmitted
282                                 *   byte. This occurs on the last byte of the
283                                 *   transmission, indicating that the
284                                 *   transmission is done.
285                                 */
286    ALT_I2C_STATUS_ACTIVITY     = 1UL << 8,
287                                /*!< This bit captures I2C activity and stays set
288                                 *   until it is cleared. There are four ways to
289                                 *   clear it:
290                                 *   * Disabling the I2C controller
291                                 *   * Calling alt_i2c_int_clear() with
292                                 *     ALT_I2C_STATUS_ACTIVITY in the mask.
293                                 *   * Calling alt_i2c_int_clear() with
294                                 *     ALT_I2C_STATUS_ALL in the mask.
295                                 *   * System reset
296                                 *
297                                 *   Once this bit is set, it stays set unless one
298                                 *   of the four methods is used to clear it. Even
299                                 *   if the I2C module is idle, this bit remains
300                                 *   set until cleared, indicating that there was
301                                 *   activity on the bus.
302                                 */
303    ALT_I2C_STATUS_STOP_DET     = 1UL << 9,
304                                /*!< Indicates whether a STOP condition has
305                                 *   occurred on the I2C interface regardless of
306                                 *   whether I2C is operating in slave or master
307                                 *   mode.
308                                 */
309    ALT_I2C_STATUS_START_DET    = 1UL << 10,
310                                /*!< Indicates whether a START or RESTART
311                                 *   condition has occurred on the I2C interface
312                                 *   regardless of whether I2C is operating in
313                                 *   slave or master mode.
314                                 */
315    ALT_I2C_STATUS_INT_CALL     = 1UL << 11,
316                                /*!< Set only when a General Call address is
317                                 *   received and it is acknowledged. It stays set
318                                 *   until it is cleared either by disabling I2C
319                                 *   or when alt_i2c_int_clear() with
320                                 *   ALT_I2C_STATUS_CALL in the mask is
321                                 *   called. I2C stores the received data in the
322                                 *   Rx buffer.
323                                 */
324    ALT_I2C_STATUS_INT_ALL      = 0xFFF,
325                                /*!< All Combined and Individual Interrupts. This
326                                 *   enumeration value can be used to clear,
327                                 *   disable, and enable the combined interrupt
328                                 *   and all individual interrupt status
329                                 *   conditions. As a side effect, when passed to
330                                 *   alt_i2c_int_clear(), clears the source causes
331                                 *   (\ref ALT_I2C_TX_ABORT_CAUSE_t) of the
332                                 *   ALT_I2C_STATUS_TX_ABORT condition.
333                                 */
334} ALT_I2C_STATUS_t;
335
336/*!
337 * This type enumerates the source causes of a ALT_I2C_STATUS_TX_ABORT condition.
338 *
339 * The active ALT_I2C_TX_ABORT_CAUSE_t source conditions are cleared when
340 * alt_i2c_int_clear() with is called ALT_I2C_STATUS_TX_ABORT in the mask or
341 * alt_i2c_int_clear() is called with ALT_I2C_STATUS_ALL in the mask.
342 *
343 * \internal
344 * Discuss special handling of abrt_sbyte_norstrt TX_ABRT source required in ???() function.
345 * \endinternal
346 */
347typedef enum ALT_I2C_TX_ABORT_CAUSE_e
348{
349    ALT_I2C_TX_ABORT_CAUSE_7B_ADDR_NOACK        = 1UL << 0,
350                                /*!< Master Abort 7 Bit Address - If set (1),
351                                 *   Master is in 7-bit addressing mode and the
352                                 *   address sent was not acknowledged by any
353                                 *   slave.
354                                 *   
355                                 *   Role of I2C: Master-Transmitter or
356                                 *   Master-Receiver
357                                 */
358    ALT_I2C_TX_ABORT_CAUSE_10ADDR1_NOACK        = 1UL << 1,
359                                /*!< Master Abort 10 Bit Address Byte 1 - If set
360                                 *   (1), Master is in 10-bit address mode and the
361                                 *   first 10-bit address byte was not
362                                 *   acknowledged by any slave.
363                                 *   
364                                 *   Role of I2C: Master-Transmitter or
365                                 *   Master-Receiver
366                                 */
367    ALT_I2C_TX_ABORT_CAUSE_10ADDR2_NOACK        = 1UL << 2,
368                                /*!< Master Abort 10 Bit Address Byte 2 - If set
369                                 *   (1), Master is in 10-bit address mode and the
370                                 *   second address byte of the 10-bit address was
371                                 *   not acknowledged by any slave
372                                 *   
373                                 *   Role of I2C: Master-Transmitter or
374                                 *   Master-Receiver
375                                 */
376    ALT_I2C_TX_ABORT_CAUSE_TXDATA_NOACK         = 1UL << 3,
377                                /*!< Master Abort TX NOACK Bit - If set (1),
378                                 *   Master has received an acknowledgement for
379                                 *   the address, but when it sent data byte(s)
380                                 *   following the address, it did not receive an
381                                 *   acknowledge from the remote slave(s). This is
382                                 *   a master-mode only bit.
383                                 *   
384                                 *   Role of I2C: Master-Transmitter.
385                                 */
386    ALT_I2C_TX_ABORT_CAUSE_GCALL_NOACK          = 1UL << 4,
387                                /*!< Master Abort GC Noack Bit - If set (1), I2C
388                                 *   controller in master mode sent a General Call
389                                 *   and no slave on the bus acknowledged the
390                                 *   General Call.
391                                 *   
392                                 *   Role of I2C: Master-Transmitter.
393                                 */
394    ALT_I2C_TX_ABORT_CAUSE_GCALL_RD             = 1UL << 5,
395                                /*!< Master Abort GC Read Bit - If set (1), I2C
396                                 *   controller in master mode sent a General Call
397                                 *   but the user programmed the byte following
398                                 *   the General Call to be a read from the bus
399                                 *   (IC_DATA_CMD[9] is set to 1).
400                                 *   
401                                 *   Role of I2C: Master-Transmitter.
402                                 */
403    ALT_I2C_TX_ABORT_CAUSE_HS_ACKDET            = 1UL << 6,
404                                /*!< Master HS MC Ack - If set (1), Master is in
405                                 *   High Speed mode and the High Speed Master
406                                 *   code was acknowledged (wrong behavior).
407                                 *   
408                                 *   Role of I2C: Master.
409                                 */
410    ALT_I2C_TX_ABORT_CAUSE_SBYTE_ACKDET         = 1UL << 7,
411                                /*!< Master Abort START Byte - If set (1), Master
412                                 *   has sent a START Byte and the START Byte was
413                                 *   acknowledged (wrong behavior).
414                                 *   
415                                 *   Role of I2C: Master.
416                                 */
417    ALT_I2C_TX_ABORT_CAUSE_HS_NORSTRT           = 1UL << 8,
418                                /*!< Master HS Restart Disabled - If set (1), the
419                                 *   restart is disabled (IC_RESTART_EN bit
420                                 *   (IC_CON[5]) = 0) and the user is trying to
421                                 *   use the master to transfer data in High Speed
422                                 *   mode.
423                                 *   
424                                 *   Role of I2C: Master-Transmitter or
425                                 *   Master-Receiver
426                                 */
427    ALT_I2C_TX_ABORT_CAUSE_SBYTE_NORSTRT        = 1UL << 9,
428                                /*!< Master Abort START No Restart - To clear, the
429                                 *   source of the ABRT_SBYTE_NORSTRT must be
430                                 *   fixed first; restart must be enabled
431                                 *   (IC_CON[5]=1), the SPECIAL bit must be
432                                 *   cleared (IC_TAR[11]), or the GC_OR_START bit
433                                 *   must be cleared (IC_TAR[10]). Once the source
434                                 *   of the ABRT_SBYTE_NORSTRT is fixed, then this
435                                 *   bit can be cleared in the same manner as
436                                 *   other bits in this register. If the source of
437                                 *   the ABRT_SBYTE_NORSTRT is not fixed before
438                                 *   attempting to clear this bit, bit 9 clears
439                                 *   for one cycle and then gets re-asserted.
440                                 *
441                                 *   If set (1), the restart is disabled
442                                 *   (IC_RESTART_EN bit (IC_CON[5]) = 0) and the
443                                 *   user is trying to send a START Byte.
444                                 *   
445                                 *   Role of I2C: Master.
446                                 */
447    ALT_I2C_TX_ABORT_CAUSE_10B_RD_NORSTRT       = 1UL << 10,
448                                /*!< Master Abort 10 Bit No Restart - If set (1),
449                                 *   the restart is disabled (IC_RESTART_EN bit
450                                 *   (IC_CON[5]) = 0) and the master sends a read
451                                 *   command in 10-bit addressing mode.
452                                 *   
453                                 *   Role of I2C: Master Receiver.
454                                 */
455    ALT_I2C_TX_ABORT_CAUSE_MST_DIS              = 1UL << 11,
456                                /*!< Master Operation with Master Disabled - If set
457                                 *   (1), user tries to initiate a Master
458                                 *   operation with the Master mode disabled.
459                                 *   
460                                 *   Role of I2C: Master or Slave-Receiver.
461                                 */
462    ALT_I2C_TX_ABORT_CAUSE_ARB_LOST             = 1UL << 12,
463                                /*!< Master Abort Arbitration Lost - If set (1),
464                                 *   master has lost arbitration, or if
465                                 *   IC_TX_ABRT_SOURCE[14] is also set, then the
466                                 *   slave transmitter has lost arbitration. Note:
467                                 *   I2C can be both master and slave at the same
468                                 *   time.
469                                 *   
470                                 *   Role of I2C: Master or Slave-Transmitter.
471                                 */
472    ALT_I2C_TX_ABORT_CAUSE_SLVFLUSH_TXFIFO      = 1UL << 13,
473                                /*!< Slave Abort Flush TXFIFO - If set (1), Slave
474                                 *   has received a read command and some data
475                                 *   exists in the TX FIFO so the slave issues a
476                                 *   TX_ABRT interrupt to flush old data in TX
477                                 *   FIFO.
478                                 *
479                                 *   Role of I2C: Slave-Transmitter.
480                                 */
481    ALT_I2C_TX_ABORT_CAUSE_SLV_ARBLOST          = 1UL << 14,
482                                /*!< Slave Abort Arbitration Lost - If set (1),
483                                 *   Slave lost the bus while transmitting data to
484                                 *   a remote master. IC_TX_ABRT_SOURCE[12] is set
485                                 *   at the same time.
486                                 * 
487                                 *   Note: Even though the slave never owns the
488                                 *   bus, something could go wrong on the
489                                 *   bus. This is a fail safe check. For instance,
490                                 *   during a data transmission at the low-to-high
491                                 *   transition of SCL, if what is on the data bus
492                                 *   is not what is supposed to be transmitted,
493                                 *   then DW_apb_i2c no longer own the bus.
494                                 *
495                                 *   Role of I2C: Slave-Transmitter.
496                                 */
497    ALT_I2C_TX_ABORT_CAUSE_SLVRD_INTX           = 1UL << 15
498                                /*!< Slave Abort Read TX - If set (1),
499                                 *   when the processor side responds to a
500                                 *   slave mode request for data to be transmitted
501                                 *   to a remote master and user writes a 1 in CMD
502                                 *   (bit 8) of IC_DATA_CMD register.
503                                 *
504                                 *   Role of I2C: Slave-Transmitter.
505                                 */
506} ALT_I2C_TX_ABORT_CAUSE_t;
507
508/*!
509 * This type defines a structure for configuration of the SCL high and low counts
510 * to ensure proper I/O timing with the device interface.
511 *     
512 * The SCL count values are only relevant if the I2C controller is enabled to as
513 * an I2C master. The SCL count values are ignored when the I2C controller is
514 * enabled as an I2C slave.
515 *
516 * See: Clock Frequency Configuration section of <em>Chapter 20. I2C
517 *      Controller</em> in the <em>Cyclone V Device Handbook Volume 3: Hard
518 *      Processor System Technical Reference Manual</em> for a complete discussion
519 *      of calculation of the proper SCL clock high and low times.
520 */
521typedef struct ALT_I2C_MASTER_CONFIG_s
522{
523    ALT_I2C_ADDR_MODE_t addr_mode;
524                                    /*!< The address mode (7 or 10 bit) when
525                                     *   acting as a master.
526                                     */
527    bool                restart_enable;
528                                    /*!< This setting determines whether RESTART
529                                     *   conditions may be sent when acting as a
530                                     *   master. When the \e restart_enable is
531                                     *   false, the I2C controller master is
532                                     *   incapable of performing the following
533                                     *   functions:
534                                     *   * Sending a START BYTE
535                                     *   * Performing any high-speed mode
536                                     *     operation
537                                     *   * Performing direction changes in
538                                     *     combined format mode
539                                     *   * Performing a read operation with a
540                                     *     10-bit address
541                                     */
542    ALT_I2C_SPEED_t     speed_mode;
543                                    /*!< The speed mode of the I2C operation.
544                                     */
545    uint16_t            ss_scl_hcnt;
546                                    /*!< The SCL clock high-period count for
547                                     *   standard speed.
548                                     */
549    uint16_t            ss_scl_lcnt;   
550                                    /*!< The SCL clock low-period count for
551                                     *   standard speed.
552                                     */
553    uint16_t            fs_scl_hcnt;   
554                                    /*!< The SCL clock high-period count for fast
555                                     *   speed.
556                                     */
557    uint16_t            fs_scl_lcnt;   
558                                    /*!< The SCL clock low-period count for fast
559                                     *   speed.
560                                     */
561    uint8_t             fs_spklen;
562                                    /*!< The duration, measured in ic_clk cycles,
563                                     *   of the longest spike that is filtered out
564                                     *   by the spike suppression logic when the
565                                     *   component is operating in SS or FS modes.
566                                     */
567} ALT_I2C_MASTER_CONFIG_t;
568
569/*!
570 * This type defines a structure for configuration of the I2C controller when it
571 * is operating in slave mode.
572 */
573typedef struct ALT_I2C_SLAVE_CONFIG_s
574{
575    ALT_I2C_ADDR_MODE_t addr_mode;      /*!< The address mode (7 or 10 bit) when
576                                         *   acting as a slave.
577                                         */
578    uint32_t            addr;           /*!< The slave address to which the I2C
579                                         *   controller responds when acting as a
580                                         *   slave.
581                                         */
582    bool                nack_enable;    /*!< Enable generation of a NACK. when the
583                                         *   I2C controller is a
584                                         *   slave-receiver. If \b true, it can
585                                         *   only generate a NACK after a data
586                                         *   byte is received; hence, the data
587                                         *   transfer is aborted and the data
588                                         *   received is not pushed onto the
589                                         *   receive buffer. When \b false, it
590                                         *   generates NACK/ACK, depending on
591                                         *   normal criteria.
592                                         *   * \b true = generate NACK after data
593                                         *               byte received
594                                         *   * \b false = generate NACK/ACK normally
595                                         */
596} ALT_I2C_SLAVE_CONFIG_t;
597
598/*!
599 * Initialize the specified I2C controller instance for use and return a device
600 * handle referencing it.
601 *
602 * \param       i2c
603 *              The HPS I2C controller instance to initialize.
604 *
605 * \param       i2c_dev
606 *              A pointer to the I2C controller device block instance.
607 *
608 * \retval      ALT_E_SUCCESS   Successful status.
609 * \retval      ALT_E_ERROR     Details about error status code
610 *
611 * \internal
612 * Initialization process:
613 * * Initialize internal driver state
614 * * Check clock setup (ALT_CLK_L4_SP)
615 * * Take I2C instance out of reset (System Manager)
616 * * Disable and clear all interrupts and status conditions
617 * * Setup and initialize any expected initial I2C controller state
618 * \endinternal
619 */
620ALT_STATUS_CODE alt_i2c_init(const ALT_I2C_CTLR_t i2c, ALT_I2C_DEV_t *i2c_dev);
621
622/*!
623 * Reset the specified I2C controller instance for use.
624 *
625 * \param       i2c_dev
626 *              A pointer to the I2C controller device block instance.
627 *
628 * \retval      ALT_E_SUCCESS   Successful status.
629 * \retval      ALT_E_ERROR     Details about error status code
630 *
631 * \internal
632 * Reset process:
633 *  * Disable controller
634 *  * Initialize internal driver state
635 *  * Check clock setup (ALT_CLK_L4_SP)
636 *  * Take I2C instance out of reset (System Manager)
637 *  * Disable and clear all interrupts and status conditions
638 *  * Setup and initialize any expected initial I2C controller state
639 *  * Enable controller
640 * \endinternal
641 */
642ALT_STATUS_CODE alt_i2c_reset(ALT_I2C_DEV_t * i2c_dev);
643
644/*!
645 * Uninitialize the I2C controller referenced by the \e i2c_dev handle.
646 *
647 * This function attempts to gracefully shutdown the I2C controller by waiting for
648 * any inpcomplete transactions to finish and then putting the I2C controller into
649 * reset.
650 *
651 * \param       i2c_dev
652 *              A pointer to the I2C controller device block instance.
653 *
654 * \retval      ALT_E_SUCCESS   Successful status.
655 * \retval      ALT_E_ERROR     Details about error status code
656 *
657 * \internal
658 * \endinternal
659 */
660ALT_STATUS_CODE alt_i2c_uninit(ALT_I2C_DEV_t *i2c_dev);
661
662/*!
663 * Disables the I2C controller.
664 *
665 * When the I2C controller is disabled, the following occurs:
666 * * The TX FIFO and RX FIFO get flushed.
667 * * The I2C interrupt status conditions remain active until the I2C controller
668 *   goes into IDLE state.
669 *
670 * If the controller is transmitting, it stops as well as deletes the contents of
671 * the transmit buffer after the current transfer is complete. If the module is
672 * receiving, the controller stops the current transfer at the end of the current
673 * byte and does not acknowledge the transfer.
674 *
675 * \param       i2c_dev
676 *              A pointer to the I2C controller device block instance.
677 *
678 * \retval      ALT_E_SUCCESS   Successful status.
679 * \retval      ALT_E_ERROR     Details about error status code
680 *
681 * \internal
682 * IC_ENABLE.ENABLE = 0
683 * Follow the procedure in section 3.8.3 Disabling DW_apb_i2c of the DW Databook.
684 * \endinternal
685 */
686ALT_STATUS_CODE alt_i2c_disable(ALT_I2C_DEV_t *i2c_dev);
687
688/*!
689 * Enables the I2C controller.
690 *
691 * \param       i2c_dev
692 *              A pointer to the I2C controller device block instance.
693 *
694 * \retval      ALT_E_SUCCESS   Successful status.
695 * \retval      ALT_E_ERROR     Details about error status code
696 *
697 * \internal
698 * IC_ENABLE.ENABLE = 1
699 * \endinternal
700 */
701ALT_STATUS_CODE alt_i2c_enable(ALT_I2C_DEV_t *i2c_dev);
702
703/*!
704 * Returns ALT_E_TRUE if the I2C controller is enabled.
705 *
706 * \param       i2c_dev
707 *              A pointer to the I2C controller device block instance.
708 *
709 * \retval      ALT_E_SUCCESS   Successful status.
710 * \retval      ALT_E_ERROR     Details about error status code
711 *
712 * \internal
713 * IC_ENABLE.ENABLE == 1
714 * \endinternal
715 */
716ALT_STATUS_CODE alt_i2c_is_enabled(ALT_I2C_DEV_t *i2c_dev);
717
718/*!
719 * Gets the current configuration of the I2C controller when operating in master
720 * mode.
721 *
722 * \param       i2c_dev
723 *              A pointer to the I2C controller device block instance.
724 *
725 * \param       cfg
726 *              [out] Pointer to a ALT_I2C_MASTER_CONFIG_t structure for holding
727 *              the returned I2C master mode configuration parameters.
728 *
729 * \retval      ALT_E_SUCCESS   Successful status.
730 * \retval      ALT_E_ERROR     Details about error status code
731 *
732 * \internal
733 * \endinternal
734 */
735ALT_STATUS_CODE alt_i2c_master_config_get(ALT_I2C_DEV_t *i2c_dev,
736                                          ALT_I2C_MASTER_CONFIG_t* cfg);
737
738/*!
739 * Sets the configuration of the I2C controller with operational parameters for
740 * operating in master mode.
741 *
742 * \param       i2c_dev
743 *              A pointer to the I2C controller device block instance.
744 *
745 * \param       cfg
746 *              Pointer to a ALT_I2C_MASTER_CONFIG_t structure holding the desired
747 *              I2C master mode operational parameters.
748 *
749 * \retval      ALT_E_SUCCESS   Successful status.
750 * \retval      ALT_E_ERROR     Details about error status code
751 *
752 * \internal
753 * \endinternal
754 */
755ALT_STATUS_CODE alt_i2c_master_config_set(ALT_I2C_DEV_t *i2c_dev,
756                                          const ALT_I2C_MASTER_CONFIG_t* cfg);
757
758/*!
759 * This is a utility function that returns the speed based on parameters of the
760 * I2C master configuration.
761 *
762 * \param       i2c_dev
763 *              A pointer to the I2C controller device block instance.
764 *
765 * \param       cfg
766 *              A pointer to the master confugurations.
767 *
768 * \param       speed_in_hz
769 *              [out] Speed (Hz) of the I2C bus currently configured at.
770 *
771 * \retval      ALT_E_SUCCESS   Successful status.
772 * \retval      ALT_E_ERROR     Details about error status code
773 */
774ALT_STATUS_CODE alt_i2c_master_config_speed_get(ALT_I2C_DEV_t *i2c_dev,
775                                                const ALT_I2C_MASTER_CONFIG_t* cfg,
776                                                uint32_t * speed_in_hz);
777
778/*!
779 * This is a utility function that computes parameters for the I2C master
780 * configuration that best matches the speed requested.
781 *
782 * \param       i2c_dev
783 *              A pointer to the I2C controller device block instance.
784 *
785 * \param       cfg
786 *              A pointer to the master confugurations.
787 *
788 * \param       speed_in_hz
789 *              Speed (Hz) of the I2C bus to configure.
790 *
791 * \retval      ALT_E_SUCCESS   Successful status.
792 * \retval      ALT_E_ERROR     Details about error status code
793 *
794 * \internal
795 * \endinternal
796 */
797ALT_STATUS_CODE alt_i2c_master_config_speed_set(ALT_I2C_DEV_t *i2c_dev,
798                                                ALT_I2C_MASTER_CONFIG_t * cfg,
799                                                uint32_t speed_in_hz);
800
801/*!
802 * Definition included for backwards compatibility.
803 */
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))
805
806/*!
807 * Definition included for backwards compatibility.
808 */
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))
810
811/*!
812 * Gets the current configuration of the I2C controller when operating in slave
813 * mode.
814 *
815 * \param       i2c_dev
816 *              A pointer to the I2C controller device block instance.
817 *
818 * \param       cfg
819 *              [out] Pointer to a ALT_I2C_SLAVE_CONFIG_t structure for holding
820 *              the returned I2C slave mode configuration parameters.
821 *
822 * \retval      ALT_E_SUCCESS   Successful status.
823 * \retval      ALT_E_ERROR     Details about error status code
824 *
825 * \internal
826 * \endinternal
827 */
828ALT_STATUS_CODE alt_i2c_slave_config_get(ALT_I2C_DEV_t *i2c_dev,
829                                         ALT_I2C_SLAVE_CONFIG_t* cfg);
830
831/*!
832 * Sets the configuration of the I2C controller with operational parameters for
833 * operating in slave mode.
834 *
835 * \param       i2c_dev
836 *              A pointer to the I2C controller device block instance.
837 *
838 * \param       cfg
839 *              Pointer to a ALT_I2C_SLAVE_CONFIG_t structure holding the desired
840 *              I2C slave mode operational parameters.
841 *
842 * \retval      ALT_E_SUCCESS   Successful status.
843 * \retval      ALT_E_ERROR     Details about error status code
844 *
845 * \internal
846 * \endinternal
847 */
848ALT_STATUS_CODE alt_i2c_slave_config_set(ALT_I2C_DEV_t *i2c_dev,
849                                         const ALT_I2C_SLAVE_CONFIG_t* cfg);
850
851/*! \addtogroup ALT_I2C_SDA_HOLD SDA Hold Time Configuration
852 *
853 * The I2C protocol specification requires 300ns of hold time on the SDA signal in
854 * standard and fast speed modes. Board delays on the SCL and SDA signals can mean
855 * that the hold-time requirement is met at the I2C master, but not at the I2C
856 * slave (or vice-versa). Because each system may encounter differing board signal
857 * delays, the I2C controller provides the capability to adjust of the SDA
858 * hold-time.
859 *
860 * The functions in this section provide software configuration of SDA hold time
861 * for the I2C controller.
862 *
863 * @{
864 */
865
866/*!
867 * Gets the currently configured value for the SDA hold time in I2C controller
868 * clock (\ref ALT_CLK_L4_SP) clock ticks.
869 *
870 * \param       i2c_dev
871 *              A pointer to the I2C controller device block instance.
872 *
873 * \param       hold_time
874 *              [out] The configured SDA hold time in \ref ALT_CLK_L4_SP clock
875 *              ticks.
876 *
877 * \retval      ALT_E_SUCCESS   Successful status.
878 * \retval      ALT_E_ERROR     Details about error status code
879 *
880 * \internal
881 * \endinternal
882 */
883ALT_STATUS_CODE alt_i2c_sda_hold_time_get(ALT_I2C_DEV_t *i2c_dev,
884                                          uint16_t *hold_time);
885
886/*!
887 * Sets the configured value for the SDA hold time in terms of I2C controller
888 * clock (\ref ALT_CLK_L4_SP) clock ticks.
889 *
890 * \param       i2c_dev
891 *              A pointer to the I2C controller device block instance.
892 *
893 * \param       hold_time
894 *              The SDA hold time in \ref ALT_CLK_L4_SP clock ticks.
895 *
896 * \retval      ALT_E_SUCCESS   Successful status.
897 * \retval      ALT_E_ERROR     Details about error status code
898 *
899 * \internal
900 * IC_SDA_HOLD is 16 bits wide. hold_time must be in range 0..65535.
901 * \endinternal
902 */
903ALT_STATUS_CODE alt_i2c_sda_hold_time_set(ALT_I2C_DEV_t *i2c_dev,
904                                          const uint16_t hold_time);
905
906/*! @} */
907
908/*!
909 * Gets the current operational mode of the I2C controller.
910 *
911 * \param       i2c_dev
912 *              A pointer to the I2C controller device block instance.
913 *
914 * \param       mode
915 *              [out] The current operational mode enabled for the I2C
916 *              controller.
917 *
918 * \retval      ALT_E_SUCCESS   Successful status.
919 * \retval      ALT_E_ERROR     Details about error status code
920 *
921 * \internal
922 * \endinternal
923 */
924ALT_STATUS_CODE alt_i2c_op_mode_get(ALT_I2C_DEV_t *i2c_dev,
925                                    ALT_I2C_MODE_t* mode);
926
927/*!
928 * Sets the operational mode of the I2C controller.
929 *
930 * \param       i2c_dev
931 *              A pointer to the I2C controller device block instance.
932 *
933 * \param       mode
934 *              The operational mode to enable for the I2C controller.
935 *
936 * \retval      ALT_E_SUCCESS   Successful status.
937 * \retval      ALT_E_ERROR     Details about error status code
938 *
939 * \internal
940 * \endinternal
941 */
942ALT_STATUS_CODE alt_i2c_op_mode_set(ALT_I2C_DEV_t *i2c_dev,
943                                    const ALT_I2C_MODE_t mode);
944 
945/*!
946 * Returns ALT_E_TRUE if the I2C controller is busy. The I2C controller is busy if
947 * either the Slave Finite State Machine (FSM) is not in the IDLE state or the
948 * Master Finite State Machine (FSM) is not in the IDLE state.
949 *
950 * \param       i2c_dev
951 *              A pointer to the I2C controller device block instance.
952 *
953 * \retval      ALT_E_SUCCESS   Successful status.
954 * \retval      ALT_E_ERROR     Details about error status code
955 *
956 * \internal
957 * IC_STATUS.ACTIVITY == 1
958 * NOTE: IC_STATUS[0] that is, the ACTIVITY bit is the OR of SLV_ACTIVITY and
959 * MST_ACTIVITY bits.
960 * \endinternal
961 */
962ALT_STATUS_CODE alt_i2c_is_busy(ALT_I2C_DEV_t *i2c_dev);
963
964/*!
965 * This function reads a single data byte from the receive FIFO.
966 *
967 * This function is used to perform low level access to the data bytes
968 * received by the I2C controller and buffered in the receive FIFO. It
969 * may be used by master-receivers or slave receivers.
970 *
971 * This function does not check for valid data in the receive FIFO
972 * beforehand and may cause an underflow if improperly used. It is
973 * meant to be called from a context where preconditions have been
974 * previously asserted such as in the implementation of the
975 * alt_i2c_slave_receive() or alt_i2c_master_receive() function.
976 *
977 * \param       i2c_dev
978 *              A pointer to the I2C controller device block instance.
979 *
980 * \param       val
981 *              [out] The single data byte read from the receive FIFO.
982 *
983 * \retval      ALT_E_SUCCESS   Successful status.
984 * \retval      ALT_E_ERROR     Details about error status code
985 *
986 * \internal
987 * \endinternal
988 */
989ALT_STATUS_CODE alt_i2c_read(ALT_I2C_DEV_t *i2c_dev, uint8_t *val);
990
991/*!
992 * This function writes a single data byte to the transmit FIFO.
993 *
994 * This function is used to perform low level writes of data to the
995 * transmit FIFO for transmission by the I2C controller. It may be
996 * used by slave receivers.
997 *
998 * This function does not check whether the transmit FIFO is full or
999 * not beforehand and may cause an overflow if improperly used. It is
1000 * meant to be called from a context where preconditions have been
1001 * previously asserted such as in the implementation of the
1002 * alt_i2c_slave_transmit() function.
1003 *
1004 * \param       i2c_dev
1005 *              A pointer to the I2C controller device block instance.
1006 *
1007 * \param       val
1008 *              The data byte to write to the transmission FIFO.
1009 *
1010 * \retval      ALT_E_SUCCESS   Successful status.
1011 * \retval      ALT_E_ERROR     Details about error status code
1012 *
1013 * \internal
1014 * \endinternal
1015 */
1016ALT_STATUS_CODE alt_i2c_write(ALT_I2C_DEV_t *i2c_dev, const uint8_t val);
1017
1018/*!
1019 * This function acts in the role of a slave-receiver by receiving a single data
1020 * byte from the I2C bus in response to a write command from the master.
1021 *
1022 * This API is suitable for being called during an interrupt context. It is the
1023 * programmer's responsibility to ensure that there is data in the RX FIFO to
1024 * accomodate the request made.
1025 *
1026 * The I2C controller must be in slave mode before calling this function.
1027 *
1028 * \param       i2c_dev
1029 *              A pointer to the I2C controller device block instance.
1030 *
1031 * \param       data
1032 *              [out] A pointer to a buffer to contain the received data byte.
1033 *
1034 * \retval      ALT_E_SUCCESS   Successful status.
1035 * \retval      ALT_E_ERROR     Details about error status code
1036 *
1037 * \internal
1038 * \endinternal
1039 */
1040ALT_STATUS_CODE alt_i2c_slave_receive(ALT_I2C_DEV_t *i2c_dev,
1041                                      uint8_t *data);
1042
1043/*!
1044 * This function acts in the role of a slave-transmitter by transmitting a single
1045 * data byte to the I2C bus in response to a read request from the master.
1046 *
1047 * This API is suitable for being called during an interrupt context. It is the
1048 * programmer's responsibility to ensure that there is enough space in the TX
1049 * FIFO to accomodate the request made.
1050 *
1051 * The I2C controller must be in slave mode before calling this function.
1052 *
1053 * \param       i2c_dev
1054 *              A pointer to the I2C controller device block instance.
1055 *
1056 * \param       data
1057 *              The data byte to transmit.
1058 *
1059 * \retval      ALT_E_SUCCESS   Successful status.
1060 * \retval      ALT_E_ERROR     Details about error status code
1061 *
1062 * \internal
1063 * \endinternal
1064 */
1065ALT_STATUS_CODE alt_i2c_slave_transmit(ALT_I2C_DEV_t *i2c_dev,
1066                                       const uint8_t data);
1067
1068/*!
1069 * This function acts in the role of a slave-transmitter by transmitting data in
1070 * bulk to the I2C bus in response to a series of read requests from a master.
1071 *
1072 * In the standard I2C protocol, all transactions are single byte transactions and
1073 * the slave responds to a remote master read request by writing one byte into the
1074 * slave's TX FIFO. When a slave (slave-transmitter) is issued with a read request
1075 * from the remote master (master-receiver), at a minimum there should be at least
1076 * one entry placed into the slave-transmitter's TX FIFO. The I2C controller is
1077 * capable of handling more data in the TX FIFO so that subsequent read requests
1078 * can receive that data without raising an interrupt or software having to poll
1079 * to request more data. This eliminates overhead latencies from being incurred by
1080 * servicing the interrupt or polling for data requests each time had there been a
1081 * restriction of having only one entry placed in the TX FIFO.
1082 *
1083 * If the remote master acknowledges the data sent by the slave-transmitter and
1084 * there is no data in the slave's TX FIFO, the I2C controller raises the read
1085 * request interrupt and waits for data to be written into the TX FIFO before it
1086 * can be sent to the remote master.
1087 *
1088 * If the programmer knows in advance that the master is requesting a packet of \e
1089 * n bytes, then when another master request for data is received, the TX FIFO
1090 * could be written with \e n number bytes and the master receives it as a
1091 * continuous stream of data. For example, the slave continues to send data to the
1092 * master as long as the master is acknowledging the data sent and there is data
1093 * available in the TX FIFO. There is no need to hold the SCL line low or to issue
1094 * READ request again.
1095 *
1096 * If the remote master is to receive \e n bytes from the slave but the programmer
1097 * wrote a number of bytes larger than \e n to the TX FIFO, then when the slave
1098 * finishes sending the requested \e n bytes, it clears the TX FIFO and ignores
1099 * any excess bytes.
1100 *
1101 * This API is suitable for being called during an interrupt context. It is the
1102 * programmer's responsibility to ensure that there is enough space in the TX
1103 * FIFO to accomodate the request made.
1104 *
1105 * The I2C controller must be in slave mode before calling this function.
1106 *
1107 * \param       i2c_dev
1108 *              A pointer to the I2C controller device block instance.
1109 *
1110 * \param       data
1111 *              A pointer to the data buffer to transmit.
1112 *
1113 * \param       size
1114 *              The size of the data buffer in bytes to place in the TX FIFO.
1115 *
1116 * \retval      ALT_E_SUCCESS   Successful status.
1117 * \retval      ALT_E_ERROR     Details about error status code
1118 *
1119 * \internal
1120 * See: Section <em>Slave-Transfer Operation for Bulk Transfers</em> of the DW
1121 * Databook for details of implementation and error conditions that may occur.
1122 * \endinternal
1123 */
1124ALT_STATUS_CODE alt_i2c_slave_bulk_transmit(ALT_I2C_DEV_t *i2c_dev,
1125                                            const void * data,
1126                                            const size_t size);
1127
1128/*!
1129 * This function returns the current target address.
1130 *
1131 * The I2C controller must be in master mode before calling this function.
1132 *
1133 * \param       i2c_dev
1134 *              A pointer to the I2C controller device block instance.
1135 *
1136 * \param       target_addr
1137 *              [out] The 7 or 10 bit slave target address.
1138 *
1139 * \retval      ALT_E_SUCCESS   Successful status.
1140 * \retval      ALT_E_ERROR     Details about error status code.
1141 */
1142ALT_STATUS_CODE alt_i2c_master_target_get(ALT_I2C_DEV_t * i2c_dev, uint32_t * target_addr);
1143
1144/*!
1145 * This function updates the target slave address for any upcoming I2C bus IO.
1146 *
1147 * This API is not suitlabe for being called in an interrupt context as it
1148 * will wait for the TX FIFO to flush before applying the changes. If the TX
1149 * FIFO is known to be empty and the controller idle, then it can be safely
1150 * called.
1151 *
1152 * The I2C controller must be in master mode before calling this function.
1153 *
1154 * \param       i2c_dev
1155 *              A pointer to the I2C controller device block instance.
1156 *
1157 * \param       target_addr
1158 *              The 7 or 10 bit slave target address.
1159 *
1160 * \retval      ALT_E_SUCCESS   Successful status.
1161 * \retval      ALT_E_ERROR     Details about error status code.
1162 */
1163ALT_STATUS_CODE alt_i2c_master_target_set(ALT_I2C_DEV_t * i2c_dev, uint32_t target_addr);
1164
1165/*!
1166 * This function acts in the role of a master-transmitter by issuing a write
1167 * command and transmitting data to the I2C bus.
1168 *
1169 * This API is not suitable for being called in an interrupt context as it may
1170 * wait for certain controller states before completing.
1171 *
1172 * The I2C controller must be in master mode before calling this function.
1173 *
1174 * \param       i2c_dev
1175 *              A pointer to the I2C controller device block instance.
1176 *
1177 * \param       data
1178 *              A pointer to a data buffer to transmit
1179 *
1180 * \param       size
1181 *              The size of the data buffer in bytes to place in the TX FIFO.
1182 *
1183 * \param       issue_restart
1184 *              This parameter controls whether a RESTART is issued before the
1185 *              byte is sent or received. If:
1186 *              * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
1187 *                is \b true, a RESTART is issued before the data is sent/received
1188 *                (according to the value of CMD), regardless of whether or not
1189 *                the transfer direction is changing from the previous command; if
1190 *                \e restart_enabled is \b false, a STOP followed by a START is
1191 *                issued instead.
1192 *              * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
1193 *                is \b true, a RESTART is issued only if the transfer direction
1194 *                is changing from the previous command; if \e restart_enabled is
1195 *                \b false, a STOP followed by a START is issued instead.
1196 *             
1197 * \param       issue_stop
1198 *              This parameter controls whether a STOP is issued after the byte is
1199 *              sent or received. If:
1200 *              * \b true - STOP is issued after this byte, regardless of whether or
1201 *                not the Tx FIFO is empty. If the Tx FIFO is not empty, the
1202 *                master immediately tries to start a new transfer by issuing a
1203 *                START and arbitrating for the bus.
1204 *              * \b false - STOP is not issued after this byte, regardless of
1205 *                whether or not the Tx FIFO is empty. If the Tx FIFO is not
1206 *                empty, the master continues the current transfer by
1207 *                sending/receiving data bytes according to the value of the CMD
1208 *                bit. If the Tx FIFO is empty, the master holds the SCL line low
1209 *                and stalls the bus until a new command is available in the Tx
1210 *                FIFO.
1211 *
1212 * \retval      ALT_E_SUCCESS   Successful status.
1213 * \retval      ALT_E_ERROR     Details about error status code
1214 *
1215 * \internal
1216 * \endinternal
1217 */
1218ALT_STATUS_CODE alt_i2c_master_transmit(ALT_I2C_DEV_t *i2c_dev,
1219                                        const void * data,
1220                                        const size_t size,
1221                                        const bool issue_restart,
1222                                        const bool issue_stop);
1223
1224/*!
1225 * This function acts in the role of a master-receiver by receiving one or more
1226 * data bytes transmitted from a slave in response to read requests issued from
1227 * this master.
1228 *
1229 * This function causes the master to issue the required number of read requests
1230 * to the slave and read the received data bytes from the Rx FIFO.
1231 *
1232 * The \e issue_restart and \e issue_stop parameters apply to the final read
1233 * request transaction in the \e num_data_entries sequence required to fulfill the
1234 * aggregate receive request.
1235 *
1236 * This API is not suitable for being called in an interrupt context as it may
1237 * wait for certain controller states before completing.
1238 *
1239 * The I2C controller must be in master mode before calling this function.
1240 *
1241 * \param       i2c_dev
1242 *              A pointer to the I2C controller device block instance.
1243 *
1244 * \param       data
1245 *              [out] The data buffer to receive the requested \e size bytes.
1246 *
1247 * \param       size
1248 *              The size of the data buffer to read from the RX FIFO.
1249 *
1250 * \param       issue_restart
1251 *              This parameter controls whether a RESTART is issued before the
1252 *              byte is sent or received. If:
1253 *              * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
1254 *                is \b true, a RESTART is issued before the data is sent/received
1255 *                (according to the value of CMD), regardless of whether or not
1256 *                the transfer direction is changing from the previous command; if
1257 *                \e restart_enabled is \b false, a STOP followed by a START is
1258 *                issued instead.
1259 *              * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
1260 *                is \b true, a RESTART is issued only if the transfer direction
1261 *                is changing from the previous command; if \e restart_enabled is
1262 *                \b false, a STOP followed by a START is issued instead.
1263 *             
1264 * \param       issue_stop
1265 *              This parameter controls whether a STOP is issued after the byte is
1266 *              sent or received. If:
1267 *              * \b true - STOP is issued after this byte, regardless of whether or
1268 *                not the Tx FIFO is empty. If the Tx FIFO is not empty, the
1269 *                master immediately tries to start a new transfer by issuing a
1270 *                START and arbitrating for the bus.
1271 *              * \b false - STOP is not issued after this byte, regardless of
1272 *                whether or not the Tx FIFO is empty. If the Tx FIFO is not
1273 *                empty, the master continues the current transfer by
1274 *                sending/receiving data bytes according to the value of the CMD
1275 *                bit. If the Tx FIFO is empty, the master holds the SCL line low
1276 *                and stalls the bus until a new command is available in the Tx
1277 *                FIFO.
1278 *
1279 * \retval      ALT_E_SUCCESS   Successful status.
1280 * \retval      ALT_E_ERROR     Details about error status code
1281 *
1282 * \internal
1283 * \endinternal
1284 */
1285ALT_STATUS_CODE alt_i2c_master_receive(ALT_I2C_DEV_t *i2c_dev,
1286                                       void * data,
1287                                       const size_t size,
1288                                       const bool issue_restart,
1289                                       const bool issue_stop);
1290
1291/*!
1292 * This function causes the I2C controller master to issue a READ request on the
1293 * bus. This function is typically used during master-receiver transfers.
1294 *
1295 * The I2C controller must be in master mode before calling this function.
1296 *
1297 * \param       i2c_dev
1298 *              A pointer to the I2C controller device block instance.
1299 *
1300 * \param       issue_restart
1301 *              This parameter controls whether a RESTART is issued before the
1302 *              byte is sent or received. If:
1303 *              * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
1304 *                is \b true, a RESTART is issued before the data is sent/received
1305 *                (according to the value of CMD), regardless of whether or not
1306 *                the transfer direction is changing from the previous command; if
1307 *                \e restart_enabled is \b false, a STOP followed by a START is
1308 *                issued instead.
1309 *              * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
1310 *                is \b true, a RESTART is issued only if the transfer direction
1311 *                is changing from the previous command; if \e restart_enabled is
1312 *                \b false, a STOP followed by a START is issued instead.
1313 *             
1314 * \param       issue_stop
1315 *              This parameter controls whether a STOP is issued after the byte is
1316 *              sent or received. If:
1317 *              * \b true - STOP is issued after this byte, regardless of whether or
1318 *                not the Tx FIFO is empty. If the Tx FIFO is not empty, the
1319 *                master immediately tries to start a new transfer by issuing a
1320 *                START and arbitrating for the bus.
1321 *              * \b false - STOP is not issued after this byte, regardless of
1322 *                whether or not the Tx FIFO is empty. If the Tx FIFO is not
1323 *                empty, the master continues the current transfer by
1324 *                sending/receiving data bytes according to the value of the CMD
1325 *                bit. If the Tx FIFO is empty, the master holds the SCL line low
1326 *                and stalls the bus until a new command is available in the Tx
1327 *                FIFO.
1328 *
1329 * \retval      ALT_E_SUCCESS   Successful status.
1330 * \retval      ALT_E_ERROR     Details about error status code
1331 *
1332 * \internal
1333 * Write IC_DATA_CMD.CMD = 1 (read request). IC_DATA_CMD.DAT is
1334 * written with "don't care" values as these bits are ignored by the
1335 * I2C controller .
1336 * \endinternal
1337 */
1338ALT_STATUS_CODE alt_i2c_issue_read(ALT_I2C_DEV_t *i2c_dev,
1339                                   const bool issue_restart,
1340                                   const bool issue_stop);
1341
1342/*!
1343 * This function causes the I2C controller master to issue a send byte on the
1344 * bus. This function is typically used during master-transmitter/slave-transmitter
1345 * transfers.
1346 *
1347 * The I2C controller must be in master mode before calling this function.
1348 *
1349 * \param       i2c_dev
1350 *              A pointer to the I2C controller device block instance.
1351 *
1352 * \param       value
1353 *              The data item to be transmitted.
1354 *
1355 * \param       issue_restart
1356 *              This parameter controls whether a RESTART is issued before the
1357 *              byte is sent or received. If:
1358 *              * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
1359 *                is \b true, a RESTART is issued before the data is sent/received
1360 *                (according to the value of CMD), regardless of whether or not
1361 *                the transfer direction is changing from the previous command; if
1362 *                \e restart_enabled is \b false, a STOP followed by a START is
1363 *                issued instead.
1364 *              * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
1365 *                is \b true, a RESTART is issued only if the transfer direction
1366 *                is changing from the previous command; if \e restart_enabled is
1367 *                \b false, a STOP followed by a START is issued instead.
1368 *             
1369 * \param       issue_stop
1370 *              This parameter controls whether a STOP is issued after the byte is
1371 *              sent or received. If:
1372 *              * \b true - STOP is issued after this byte, regardless of whether or
1373 *                not the Tx FIFO is empty. If the Tx FIFO is not empty, the
1374 *                master immediately tries to start a new transfer by issuing a
1375 *                START and arbitrating for the bus.
1376 *              * \b false - STOP is not issued after this byte, regardless of
1377 *                whether or not the Tx FIFO is empty. If the Tx FIFO is not
1378 *                empty, the master continues the current transfer by
1379 *                sending/receiving data bytes according to the value of the CMD
1380 *                bit. If the Tx FIFO is empty, the master holds the SCL line low
1381 *                and stalls the bus until a new command is available in the Tx
1382 *                FIFO.
1383 *
1384 * \retval      ALT_E_SUCCESS   Successful status.
1385 * \retval      ALT_E_ERROR     Details about error status code
1386 *
1387 * \internal
1388 * Write IC_DATA_CMD.CMD = 0 (write request).
1389 * \endinternal
1390 */
1391ALT_STATUS_CODE alt_i2c_issue_write(ALT_I2C_DEV_t *i2c_dev,
1392                                    const uint8_t value,
1393                                    const bool issue_restart,
1394                                    const bool issue_stop);
1395
1396/******************************************************************************/
1397/*! \addtogroup ALT_I2C_GEN_CALL General Call
1398 *
1399 * The functions in this group support General Call addresses.
1400 *
1401 * The general call address is for addressing every device connected to the I2C
1402 * bus at the same time. However, if a device does not need any of the data
1403 * supplied within the general call structure, it can ignore this address by not
1404 * issuing an acknowledgment. If a device does require data from a general call
1405 * address, it acknowledges this address and behaves as a slave-receiver. The
1406 * master does not actually know how many devices acknowledged if one or more
1407 * devices respond. The second and following bytes are acknowledged by every
1408 * slave-receiver capable of handling this data. A slave who cannot process one of
1409 * these bytes must ignore it by not-acknowledging. If one or more slaves
1410 * acknowledge, the not-acknowledge will not be seen by the master.
1411 *
1412 * The functions in this group do not provide any general call functional command
1413 * interpretation or implementation (e.g. software reset).
1414 *
1415 * @{
1416 */
1417
1418/*!
1419 * This function acts in the role of a master-transmitter by issuing a general
1420 * call command to all devices connected to the I2C bus.
1421 *
1422 * The \e issue_restart and \e issue_stop parameters apply to the final write
1423 * transaction in the \e num_data_entries byte transmission sequence.
1424 *
1425 * The I2C controller must be in master mode before calling this function.
1426 *
1427 * The target slave address will be modified by this function. Call
1428 * alt_i2c_master_target_set() to reset the slave target address for
1429 * subsequent IO.
1430 *
1431 * \param       i2c_dev
1432 *              A pointer to the I2C controller device block instance.
1433 *
1434 * \param       data
1435 *              An array of data byte(s) to transmit.
1436 *
1437 * \param       num_data_entries
1438 *              The number of entries (bytes) in \e data to place in the TX FIFO.
1439 *
1440 * \param       issue_restart
1441 *              This parameter controls whether a RESTART is issued before the
1442 *              byte is sent or received. If:
1443 *              * \b true - if \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
1444 *                is \b true, a RESTART is issued before the data is sent/received
1445 *                (according to the value of CMD), regardless of whether or not
1446 *                the transfer direction is changing from the previous command; if
1447 *                \e restart_enabled is \b false, a STOP followed by a START is
1448 *                issued instead.
1449 *              * \b false - If \e restart_enabled in \ref ALT_I2C_MASTER_CONFIG_t
1450 *                is \b true, a RESTART is issued only if the transfer direction
1451 *                is changing from the previous command; if \e restart_enabled is
1452 *                \b false, a STOP followed by a START is issued instead.
1453 *             
1454 * \param       issue_stop
1455 *              This parameter controls whether a STOP is issued after the byte is
1456 *              sent or received. If:
1457 *              * \b true - STOP is issued after this byte, regardless of whether or
1458 *                not the Tx FIFO is empty. If the Tx FIFO is not empty, the
1459 *                master immediately tries to start a new transfer by issuing a
1460 *                START and arbitrating for the bus.
1461 *              * \b false - STOP is not issued after this byte, regardless of
1462 *                whether or not the Tx FIFO is empty. If the Tx FIFO is not
1463 *                empty, the master continues the current transfer by
1464 *                sending/receiving data bytes according to the value of the CMD
1465 *                bit. If the Tx FIFO is empty, the master holds the SCL line low
1466 *                and stalls the bus until a new command is available in the Tx
1467 *                FIFO.
1468 *
1469 * \retval      ALT_E_SUCCESS   Successful status.
1470 * \retval      ALT_E_ERROR     Details about error status code
1471 *
1472 * \internal
1473 * \endinternal
1474 */
1475ALT_STATUS_CODE alt_i2c_master_general_call(ALT_I2C_DEV_t *i2c_dev,
1476                                            const void * data,
1477                                            const size_t size,
1478                                            const bool issue_restart,
1479                                            const bool issue_stop);
1480
1481/*!
1482 * Disables the I2C controller from responding to a General Call address. The
1483 * controller will respond with a NACK and no General Call status conditions or
1484 * interrupts are generated.
1485 *
1486 * \param       i2c_dev
1487 *              A pointer to the I2C controller device block instance.
1488 *
1489 * \retval      ALT_E_SUCCESS   Successful status.
1490 * \retval      ALT_E_ERROR     Details about error status code
1491 *
1492 * \internal
1493 * IC_ACK_GENERAL_CALL.ACK_GEN_CALL = 0
1494 * \endinternal
1495 */
1496ALT_STATUS_CODE alt_i2c_general_call_ack_disable(ALT_I2C_DEV_t *i2c_dev);
1497
1498/*!
1499 * Enables the I2C controller to respond with an ACK when it receives a General
1500 * Call address.
1501 *
1502 * \param       i2c_dev
1503 *              A pointer to the I2C controller device block instance.
1504 *
1505 * \retval      ALT_E_SUCCESS   Successful status.
1506 * \retval      ALT_E_ERROR     Details about error status code
1507 *
1508 * \internal
1509 * IC_ACK_GENERAL_CALL.ACK_GEN_CALL = 1
1510 * \endinternal
1511 */
1512ALT_STATUS_CODE alt_i2c_general_call_ack_enable(ALT_I2C_DEV_t *i2c_dev);
1513
1514/*!
1515 * Returns ALT_E_TRUE if the I2C controller is enabled to respond to General Call
1516 * addresses.
1517 *
1518 * \param       i2c_dev
1519 *              A pointer to the I2C controller device block instance.
1520 *
1521 * \retval      ALT_E_SUCCESS   Successful status.
1522 * \retval      ALT_E_ERROR     Details about error status code
1523 *
1524 * \internal
1525 * IC_ACK_GENERAL_CALL.ACK_GEN_CALL == 1
1526 * \endinternal
1527 */
1528ALT_STATUS_CODE alt_i2c_general_call_ack_is_enabled(ALT_I2C_DEV_t *i2c_dev);
1529
1530/*! @} */
1531
1532/******************************************************************************/
1533/*! \addtogroup ALT_I2C_INT Interrupt and Status Conditions
1534 *
1535 * The functions in this group provide management for the I2C controller status
1536 * conditions and interrupts.
1537 *
1538 * Each I2C controller has a single combined interrupt output (\b
1539 * ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ). The following events can generate an
1540 * interrupt:
1541 * * General Call Address Received
1542 * * Start or Restart Condition Occurred
1543 * * Stop Condition Occurred
1544 * * I2C Controller Activity
1545 * * Receive Done
1546 * * Transmit Abort
1547 * * Read Request
1548 * * Transmit Buffer Empty
1549 * * Transmit Overflow
1550 * * Receive Buffer Full
1551 * * Receive Overflow
1552 * * Receive Underflow
1553 *
1554 * These interrupt status conditions may be monitored either by polling their
1555 * status or by configuring interrupt handlers using the HWLIB Interrupt
1556 * Controller API.
1557 *
1558 * Functions to get the current status, enable or disable (i.e. mass or unmask),
1559 * and clear interrupt status conditions for the I2C controller are defined in
1560 * this section.
1561 *
1562 * @{
1563 */
1564
1565/*!
1566 * Returns the current I2C controller interrupt status conditions.
1567 *
1568 * This function returns the current value of the I2C controller interrupt status
1569 * register value which reflects the current I2C controller status conditions that
1570 * are not disabled (i.e. masked).
1571 *
1572 * \param       i2c_dev
1573 *              A pointer to the I2C controller device block instance.
1574 *
1575 * \param       status
1576 *              [out] A pointer to a bit mask of the active \ref ALT_I2C_STATUS_t
1577 *              interrupt and status conditions.
1578 *
1579 * \retval      ALT_E_SUCCESS   Successful status.
1580 * \retval      ALT_E_ERROR     Details about error status code
1581 *
1582 * \internal
1583 * IC_INTR_STAT
1584 * \endinternal
1585 */
1586ALT_STATUS_CODE alt_i2c_int_status_get(ALT_I2C_DEV_t *i2c_dev,
1587                                       uint32_t *status);
1588
1589/*!
1590 * Returns the I2C controller raw interrupt status conditions irrespective of
1591 * the interrupt status condition enablement state.
1592 *
1593 * This function returns the current value of the I2C controller raw interrupt
1594 * status register value which reflects the current I2C controller status
1595 * conditions regardless of whether they are disabled (i.e. masked) or not.
1596 *
1597 * \param       i2c_dev
1598 *              A pointer to the I2C controller device block instance.
1599 *
1600 * \param       status
1601 *              [out] A pointer to a bit mask of the active \ref ALT_I2C_STATUS_t
1602 *              interrupt and status conditions.
1603 *
1604 * \retval      ALT_E_SUCCESS   Successful status.
1605 * \retval      ALT_E_ERROR     Details about error status code
1606 *
1607 * \internal
1608 * IC_INTR_STAT
1609 * \endinternal
1610 */
1611ALT_STATUS_CODE alt_i2c_int_raw_status_get(ALT_I2C_DEV_t *i2c_dev,
1612                                           uint32_t *status);
1613
1614/*!
1615 * Clears the specified I2C controller interrupt status conditions identified
1616 * in the mask.
1617 *
1618 * This function clears one or more of the status conditions as contributors to
1619 * the \b ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state.
1620 *
1621 * \param       i2c_dev
1622 *              A pointer to the I2C controller device block instance.
1623 *
1624 * \param       mask
1625 *              Specifies the QSPI interrupt status conditions to clear. \e mask
1626 *              is a mask of logically OR'ed \ref ALT_I2C_STATUS_t values that
1627 *              designate the status conditions to clear.
1628 *
1629 * \retval      ALT_E_SUCCESS   Successful status.
1630 * \retval      ALT_E_ERROR     Details about error status code
1631 *
1632 * \internal
1633 * \endinternal
1634 */
1635ALT_STATUS_CODE alt_i2c_int_clear(ALT_I2C_DEV_t *i2c_dev, const uint32_t mask);
1636
1637/*!
1638 * Disable the specified I2C controller interrupt status conditions identified in
1639 * the mask.
1640 *
1641 * This function disables one or more of the status conditions as contributors to
1642 * the \b ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state.
1643 *
1644 * NOTE: A cleared bit for any status condition in the mask value does not have
1645 *       the effect of enabling it as a contributor to the \b
1646 *       ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state. The function
1647 *       alt_i2c_int_enable() is used to enable status source conditions.
1648 *
1649 * \param       i2c_dev
1650 *              A pointer to the I2C controller device block instance.
1651 *
1652 * \param       mask
1653 *              Specifies the status conditions to disable as interrupt source
1654 *              contributors. \e mask is a mask of logically OR'ed \ref
1655 *              ALT_I2C_STATUS_t values that designate the status conditions to
1656 *              disable.
1657 *
1658 * \retval      ALT_E_SUCCESS   Successful status.
1659 * \retval      ALT_E_ERROR     Details about error status code
1660 *
1661 * \internal
1662 * \endinternal
1663 */
1664ALT_STATUS_CODE alt_i2c_int_disable(ALT_I2C_DEV_t *i2c_dev, const uint32_t mask);
1665
1666/*!
1667 * Enable the specified I2C controller interrupt status conditions identified in
1668 * the mask.
1669 *
1670 * This function enables one or more of the status conditions as contributors to
1671 * the \b ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state.
1672 *
1673 * NOTE: A cleared bit for any status condition in the mask value does not have
1674 *       the effect of disabling it as a contributor to the \b
1675 *       ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state. The function
1676 *       alt_i2c_int_disable() is used to disable status source conditions.
1677 *
1678 * \param       i2c_dev
1679 *              A pointer to the I2C controller device block instance.
1680 *
1681 * \param       mask
1682 *              Specifies the status conditions to enable as interrupt source
1683 *              contributors. \e mask is a mask of logically OR'ed \ref
1684 *              ALT_I2C_STATUS_t values that designate the status conditions to
1685 *              enable.
1686 *
1687 * \retval      ALT_E_SUCCESS   Successful status.
1688 * \retval      ALT_E_ERROR     Details about error status code
1689 *
1690 * \internal
1691 * \endinternal
1692 */
1693ALT_STATUS_CODE alt_i2c_int_enable(ALT_I2C_DEV_t *i2c_dev, const uint32_t mask);
1694
1695/*!
1696 * Gets the cause of I2C transmission abort. A I2C transmission abort indicates
1697 * that the I2C transmitter is unable to complete the intended actions on the
1698 * contents of the transmit FIFO. This situation can occur both as an I2C master
1699 * or an I2C slave, and is referred to as a "transmit abort".
1700 *
1701 * The returned value of this function is the value of the IC_TX_ABRT_SOURCE
1702 * register which indicates the cause why the transmit abort occurred.
1703 *
1704 * \param       i2c_dev
1705 *              A pointer to the I2C controller device block instance.
1706 *
1707 * \param       cause
1708 *              [out] A pointer to a bit mask of the \ref ALT_I2C_TX_ABORT_CAUSE_t
1709 *              causes of the transmission abort.
1710 *
1711 * \retval      ALT_E_SUCCESS   Successful status.
1712 * \retval      ALT_E_ERROR     Details about error status code
1713 *
1714 * \internal
1715 * IC_TX_ABRT_SOURCE
1716 * \endinternal
1717 */
1718ALT_STATUS_CODE alt_i2c_tx_abort_cause_get(ALT_I2C_DEV_t *i2c_dev,
1719                                           ALT_I2C_TX_ABORT_CAUSE_t *cause);
1720
1721/*! @} */
1722
1723/******************************************************************************/
1724/*! \addtogroup ALT_I2C_RX_FIFO RX FIFO Management
1725 *
1726 * The receive FIFO has a configurable threshold value that controls the level of
1727 * entries (or above) that sets the RX_FULL status condition and triggers an
1728 * interrupt. The valid range is 0 - (ALT_I2C_RX_FIFO_NUM_ENTRIES-1), with the
1729 * additional restriction that I2C controller does not allow this value to be set
1730 * to a value larger than the depth of the buffer. If an attempt is made to do
1731 * that, the actual value set will be the maximum depth of the buffer. A value of
1732 * 0 sets the threshold for 1 entry, and a value of (ALT_I2C_RX_FIFO_NUM_ENTRIES-1)
1733 * sets the threshold for ALT_I2C_RX_FIFO_NUM_ENTRIES entries.
1734 *
1735 * @{
1736 */
1737
1738/*!
1739 * The number of entries (depth) of the I2C controller receive FIFO.
1740 */
1741#define ALT_I2C_RX_FIFO_NUM_ENTRIES     64
1742
1743/*!
1744 * Returns ALT_E_TRUE when the receive FIFO is empty.
1745 *
1746 * \param       i2c_dev
1747 *              A pointer to the I2C controller device block instance.
1748 *
1749 * \retval      ALT_E_SUCCESS   Successful status.
1750 * \retval      ALT_E_ERROR     Details about error status code
1751 *
1752 * \internal
1753 * IC_STATUS.RFNE == 0
1754 * \endinternal
1755 */
1756ALT_STATUS_CODE alt_i2c_rx_fifo_is_empty(ALT_I2C_DEV_t *i2c_dev);
1757
1758/*!
1759 * Returns ALT_E_TRUE when the receive FIFO is completely full.
1760 *
1761 * \param       i2c_dev
1762 *              A pointer to the I2C controller device block instance.
1763 *
1764 * \retval      ALT_E_SUCCESS   Successful status.
1765 * \retval      ALT_E_ERROR     Details about error status code
1766 *
1767 * \internal
1768 * IC_STATUS.RFF == 1
1769 * \endinternal
1770 */
1771ALT_STATUS_CODE alt_i2c_rx_fifo_is_full(ALT_I2C_DEV_t *i2c_dev);
1772
1773/*!
1774 * Returns the number of valid entries in the receive FIFO.
1775 *
1776 * \param       i2c_dev
1777 *              A pointer to the I2C controller device block instance.
1778 *
1779 * \param       num_entries
1780 *              [out] The number of entries in the receive FIFO.
1781 *
1782 * \retval      ALT_E_SUCCESS   Successful status.
1783 * \retval      ALT_E_ERROR     Details about error status code
1784 *
1785 * \internal
1786 * IC_RXFLR.RXFLR
1787 * \endinternal
1788 */
1789ALT_STATUS_CODE alt_i2c_rx_fifo_level_get(ALT_I2C_DEV_t *i2c_dev,
1790                                          uint32_t *num_entries);
1791
1792/*!
1793 * Gets the current receive FIFO threshold level value.
1794 *
1795 * \param       i2c_dev
1796 *              A pointer to the I2C controller device block instance.
1797 *
1798 * \param       threshold
1799 *              [out] The current threshold value.
1800 *
1801 * \retval      ALT_E_SUCCESS   Successful status.
1802 * \retval      ALT_E_ERROR     Details about error status code
1803 *
1804 * \internal
1805 * IC_RX_TL.RX_TL
1806 * \endinternal
1807 */
1808ALT_STATUS_CODE alt_i2c_rx_fifo_threshold_get(ALT_I2C_DEV_t *i2c_dev,
1809                                              uint8_t *threshold);
1810
1811/*!
1812 * Sets the current receive FIFO threshold level value.
1813 *
1814 * \param       i2c_dev
1815 *              A pointer to the I2C controller device block instance.
1816 *
1817 * \param       threshold
1818 *              The threshold value.
1819 *
1820 * \retval      ALT_E_SUCCESS   Successful status.
1821 * \retval      ALT_E_ERROR     Details about error status code
1822 *
1823 * \internal
1824 * IC_RX_TL.RX_TL = threshold
1825 * \endinternal
1826 */
1827ALT_STATUS_CODE alt_i2c_rx_fifo_threshold_set(ALT_I2C_DEV_t *i2c_dev,
1828                                              const uint8_t threshold);
1829
1830/*! @} */
1831
1832/******************************************************************************/
1833/*! \addtogroup ALT_I2C_TX_FIFO TX FIFO Management
1834 *
1835 * The transmit FIFO has a configurable threshold value that controls the level of
1836 * entries (or below) that sets the TX_EMPTY status condition and triggers an
1837 * interrupt. The valid range is 0 - (ALT_I2C_TX_FIFO_NUM_ENTRIES-1), with the
1838 * additional restriction that I2C controller does not allow this value to be set
1839 * to a value larger than the depth of the buffer. If an attempt is made to do
1840 * that, the actual value set will be the maximum depth of the buffer. A value of
1841 * 0 sets the threshold for 0 entries, and a value of (ALT_I2C_TX_FIFO_NUM_ENTRIES-1)
1842 * sets the threshold for (ALT_I2C_TX_FIFO_NUM_ENTRIES-1) entries.
1843 *
1844 * @{
1845 */
1846
1847/*!
1848 * The number of entries (depth) of the I2C controller transmit FIFO.
1849 */
1850#define ALT_I2C_TX_FIFO_NUM_ENTRIES     64
1851
1852/*!
1853 * Returns ALT_E_TRUE when the transmit FIFO is empty.
1854 *
1855 * \param       i2c_dev
1856 *              A pointer to the I2C controller device block instance.
1857 *
1858 * \retval      ALT_E_SUCCESS   Successful status.
1859 * \retval      ALT_E_ERROR     Details about error status code
1860 *
1861 * \internal
1862 * IC_STATUS.TFE == 1
1863 * \endinternal
1864 */
1865ALT_STATUS_CODE alt_i2c_tx_fifo_is_empty(ALT_I2C_DEV_t *i2c_dev);
1866
1867/*!
1868 * Returns ALT_E_TRUE when the transmit FIFO is completely full.
1869 *
1870 * \param       i2c_dev
1871 *              A pointer to the I2C controller device block instance.
1872 *
1873 * \retval      ALT_E_SUCCESS   Successful status.
1874 * \retval      ALT_E_ERROR     Details about error status code
1875 *
1876 * \internal
1877 * IC_STATUS.TFNF == 0
1878 * \endinternal
1879 */
1880ALT_STATUS_CODE alt_i2c_tx_fifo_is_full(ALT_I2C_DEV_t *i2c_dev);
1881
1882/*!
1883 * Returns the number of valid entries in the transmit FIFO.
1884 *
1885 * \param       i2c_dev
1886 *              A pointer to the I2C controller device block instance.
1887 *
1888 * \param       num_entries
1889 *              [out] The number of entries in the transmit FIFO.
1890 *
1891 * \retval      ALT_E_SUCCESS   Successful status.
1892 * \retval      ALT_E_ERROR     Details about error status code
1893 *
1894 * \internal
1895 * IC_TXFLR.TXFLR
1896 * \endinternal
1897 */
1898ALT_STATUS_CODE alt_i2c_tx_fifo_level_get(ALT_I2C_DEV_t *i2c_dev,
1899                                          uint32_t *num_entries);
1900
1901/*!
1902 * Gets the current transmit FIFO threshold level value.
1903 *
1904 * \param       i2c_dev
1905 *              A pointer to the I2C controller device block instance.
1906 *
1907 * \param       threshold
1908 *              [out] The current threshold value.
1909 *
1910 * \retval      ALT_E_SUCCESS   Successful status.
1911 * \retval      ALT_E_ERROR     Details about error status code
1912 *
1913 * \internal
1914 * IC_TX_TL.TX_TL
1915 * \endinternal
1916 */
1917ALT_STATUS_CODE alt_i2c_tx_fifo_threshold_get(ALT_I2C_DEV_t *i2c_dev,
1918                                              uint8_t *threshold);
1919
1920/*!
1921 * Sets the current transmit FIFO threshold level value.
1922 *
1923 * \param       i2c_dev
1924 *              A pointer to the I2C controller device block instance.
1925 *
1926 * \param       threshold
1927 *              The threshold value.
1928 *
1929 * \retval      ALT_E_SUCCESS   Successful status.
1930 * \retval      ALT_E_ERROR     Details about error status code
1931 *
1932 * \internal
1933 * IC_TX_TL.TX_TL = threshold
1934 * \endinternal
1935 */
1936ALT_STATUS_CODE alt_i2c_tx_fifo_threshold_set(ALT_I2C_DEV_t *i2c_dev,
1937                                              const uint8_t threshold);
1938
1939/*! @} */
1940
1941/******************************************************************************/
1942/*! \addtogroup ALT_I2C_DMA DMA Interface
1943 *
1944 * The DMA interface has a configurable threshold value that controls the
1945 * level of entries that triggers the burst handshaking request used for DMA
1946 * integration.
1947 *
1948 * For the TX threshold, if the number of entries in the TX FIFO is at or
1949 * below the set threshold, a DMA handshaking request will be made. The valid
1950 * range for the TX threshold is 0 - (ALT_I2C_TX_FIFO_NUM_ENTRIES - 1).
1951 *
1952 * For the RX threshold, if the number of entries in the RX FIFO is above the
1953 * set threshold, a DMA handshaking request will be made. The valid range for
1954 * the RX treshold is 0 - (ALT_I2C_TX_FIFO_NUM_ENTRIES - 1).
1955 *
1956 * Having a higher threshold can improve the AXI bus utilization at the
1957 * expense of the likelyhoold of overflow / underflow conditions.
1958 * @{
1959 */
1960
1961/*!
1962 * Gets the current RX DMA threshold level value.
1963 *
1964 * \param       i2c_dev
1965 *              A pointer to the I2C controller device block instance.
1966 *
1967 * \param       threshold
1968 *              [out] The threshold value.
1969 *
1970 * \retval      ALT_E_SUCCESS   Successful status.
1971 * \retval      ALT_E_ERROR     Details about error status code
1972 */
1973ALT_STATUS_CODE alt_i2c_rx_dma_threshold_get(ALT_I2C_DEV_t * i2c_dev, uint8_t * threshold);
1974
1975/*!
1976 * Sets the current RX DMA threshold level value.
1977 *
1978 * \param       i2c_dev
1979 *              A pointer to the I2C controller device block instance.
1980 *
1981 * \param       threshold
1982 *              The threshold value.
1983 *
1984 * \retval      ALT_E_SUCCESS   Successful status.
1985 * \retval      ALT_E_ERROR     Details about error status code
1986 */
1987ALT_STATUS_CODE alt_i2c_rx_dma_threshold_set(ALT_I2C_DEV_t * i2c_dev, uint8_t threshold);
1988
1989/*!
1990 * Gets the current TX DMA threshold level value.
1991 *
1992 * \param       i2c_dev
1993 *              A pointer to the I2C controller device block instance.
1994 *
1995 * \param       threshold
1996 *              [out] The threshold value.
1997 *
1998 * \retval      ALT_E_SUCCESS   Successful status.
1999 * \retval      ALT_E_ERROR     Details about error status code
2000 */
2001ALT_STATUS_CODE alt_i2c_tx_dma_threshold_get(ALT_I2C_DEV_t * i2c_dev, uint8_t * threshold);
2002
2003/*!
2004 * Sets the current TX DMA threshold level value.
2005 *
2006 * \param       i2c_dev
2007 *              A pointer to the I2C controller device block instance.
2008 *
2009 * \param       threshold
2010 *              The threshold value.
2011 *
2012 * \retval      ALT_E_SUCCESS   Successful status.
2013 * \retval      ALT_E_ERROR     Details about error status code
2014 */
2015ALT_STATUS_CODE alt_i2c_tx_dma_threshold_set(ALT_I2C_DEV_t * i2c_dev, uint8_t threshold);
2016
2017/*! @} */
2018
2019/*! @} */
2020
2021#ifdef __cplusplus
2022}
2023#endif  /* __cplusplus */
2024#endif  /* __ALT_I2C_H__ */
Note: See TracBrowser for help on using the repository browser.