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 |
---|
46 | extern "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 | */ |
---|
95 | typedef 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 | } |
---|
103 | ALT_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 | */ |
---|
117 | typedef 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 | } |
---|
123 | ALT_I2C_DEV_t; |
---|
124 | |
---|
125 | /*! |
---|
126 | * This type enumerates the HPS I2C controller instances. |
---|
127 | */ |
---|
128 | typedef 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 | */ |
---|
143 | typedef 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 | */ |
---|
162 | typedef 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 | */ |
---|
178 | typedef 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 | */ |
---|
189 | typedef 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 | */ |
---|
347 | typedef 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 | */ |
---|
521 | typedef 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 | */ |
---|
573 | typedef 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 | */ |
---|
620 | ALT_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 | */ |
---|
642 | ALT_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 | */ |
---|
660 | ALT_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 | */ |
---|
686 | ALT_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 | */ |
---|
701 | ALT_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 | */ |
---|
716 | ALT_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 | */ |
---|
735 | ALT_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 | */ |
---|
755 | ALT_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 | */ |
---|
774 | ALT_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 | */ |
---|
797 | ALT_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 | */ |
---|
828 | ALT_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 | */ |
---|
848 | ALT_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 | */ |
---|
883 | ALT_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 | */ |
---|
903 | ALT_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 | */ |
---|
924 | ALT_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 | */ |
---|
942 | ALT_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 | */ |
---|
962 | ALT_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 | */ |
---|
989 | ALT_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 | */ |
---|
1016 | ALT_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 | */ |
---|
1040 | ALT_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 | */ |
---|
1065 | ALT_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 | */ |
---|
1124 | ALT_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 | */ |
---|
1142 | ALT_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 | */ |
---|
1163 | ALT_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 | */ |
---|
1218 | ALT_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 | */ |
---|
1285 | ALT_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 | */ |
---|
1338 | ALT_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 | */ |
---|
1391 | ALT_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 | */ |
---|
1475 | ALT_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 | */ |
---|
1496 | ALT_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 | */ |
---|
1512 | ALT_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 | */ |
---|
1528 | ALT_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 | */ |
---|
1586 | ALT_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 | */ |
---|
1611 | ALT_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 | */ |
---|
1635 | ALT_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 | */ |
---|
1664 | ALT_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 | */ |
---|
1693 | ALT_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 | */ |
---|
1718 | ALT_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 | */ |
---|
1756 | ALT_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 | */ |
---|
1771 | ALT_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 | */ |
---|
1789 | ALT_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 | */ |
---|
1808 | ALT_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 | */ |
---|
1827 | ALT_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 | */ |
---|
1865 | ALT_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 | */ |
---|
1880 | ALT_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 | */ |
---|
1898 | ALT_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 | */ |
---|
1917 | ALT_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 | */ |
---|
1936 | ALT_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 | */ |
---|
1973 | ALT_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 | */ |
---|
1987 | ALT_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 | */ |
---|
2001 | ALT_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 | */ |
---|
2015 | ALT_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__ */ |
---|