source: rtems/bsps/arm/altera-cyclone-v/include/bsp/alt_i2c.h @ 2afb22b

5
Last change on this file since 2afb22b was 2afb22b, checked in by Chris Johns <chrisj@…>, on 12/23/17 at 07:18:56

Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step. It
copied header files from arbitrary locations into the build tree. The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

  • The make preinstall step itself needs time and disk space.
  • Errors in header files show up in the build tree copy. This makes it hard for editors to open the right file to fix the error.
  • There is no clear relationship between source and build tree header files. This makes an audit of the build process difficult.
  • The visibility of all header files in the build tree makes it difficult to enforce API barriers. For example it is discouraged to use BSP-specifics in the cpukit.
  • An introduction of a new build system is difficult.
  • Include paths specified by the -B option are system headers. This may suppress warnings.
  • The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step. All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc. Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

  • cpukit/include
  • cpukit/score/cpu/@RTEMS_CPU@/include
  • cpukit/libnetworking

The new BSP include directories are:

  • bsps/include
  • bsps/@RTEMS_CPU@/include
  • bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed. The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

  • 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.