Software APIs
dt_i2c.h
Go to the documentation of this file.
1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4//
5// Device table API auto-generated by `dtgen`
6
7#ifndef OPENTITAN_DT_I2C_H_
8#define OPENTITAN_DT_I2C_H_
9
10#ifdef __cplusplus
11extern "C" {
12#endif // __cplusplus
13
14/**
15 * @file
16 * @brief Device Tables (DT) for IP i2c and top earlgrey.
17 *
18 * This file contains the type definitions and global functions of the i2c.
19 */
20
21#include "dt_api.h"
22#include <stdint.h>
23
24
25
26/**
27 * List of instances.
28 */
29typedef enum dt_i2c {
30 kDtI2c0 = 0, /**< i2c0 */
31 kDtI2c1 = 1, /**< i2c1 */
32 kDtI2c2 = 2, /**< i2c2 */
33 kDtI2cFirst = 0, /**< \internal First instance */
34 kDtI2cCount = 3, /**< \internal Number of instances */
36
37/**
38 * List of register blocks.
39 *
40 * Register blocks are guaranteed to start at 0 and to be consecutively numbered.
41 */
42typedef enum dt_i2c_reg_block {
43 kDtI2cRegBlockCore = 0, /**< */
44 kDtI2cRegBlockCount = 1, /**< \internal Number of register blocks */
46
47/** Primary register block (associated with the "primary" set of registers that control the IP). */
48static const dt_i2c_reg_block_t kDtI2cRegBlockPrimary = kDtI2cRegBlockCore;
49
50/**
51 * List of IRQs.
52 *
53 * IRQs are guaranteed to be numbered consecutively from 0.
54 */
55typedef enum dt_i2c_irq {
56 kDtI2cIrqFmtThreshold = 0, /**< host mode interrupt: asserted whilst the FMT FIFO level is below the low threshold. This is a level status interrupt. */
57 kDtI2cIrqRxThreshold = 1, /**< host mode interrupt: asserted whilst the RX FIFO level is above the high threshold. This is a level status interrupt. */
58 kDtI2cIrqAcqThreshold = 2, /**< target mode interrupt: asserted whilst the ACQ FIFO level is above the high threshold. This is a level status interrupt. */
59 kDtI2cIrqRxOverflow = 3, /**< host mode interrupt: raised if the RX FIFO has overflowed. */
60 kDtI2cIrqControllerHalt = 4, /**< host mode interrupt: raised if the controller FSM is halted, such as on an unexpected NACK or lost arbitration.
61Check !!CONTROLLER_EVENTS for the reason.
62The interrupt will be released when the bits in !!CONTROLLER_EVENTS are cleared. */
63 kDtI2cIrqSclInterference = 5, /**< host mode interrupt: raised if the SCL line drops early (not supported without clock synchronization). */
64 kDtI2cIrqSdaInterference = 6, /**< host mode interrupt: raised if the SDA line goes low when host is trying to assert high */
65 kDtI2cIrqStretchTimeout = 7, /**< host mode interrupt: raised if target stretches the clock beyond the allowed timeout period */
66 kDtI2cIrqSdaUnstable = 8, /**< host mode interrupt: raised if the target does not assert a constant value of SDA during transmission. */
67 kDtI2cIrqCmdComplete = 9, /**< host and target mode interrupt.
68In host mode, raised if the host issues a repeated START or terminates the transaction by issuing STOP.
69In target mode, raised if the external host issues a STOP or repeated START. */
70 kDtI2cIrqTxStretch = 10, /**< target mode interrupt: raised if the target is stretching clocks for a read command. This is a level status interrupt. */
71 kDtI2cIrqTxThreshold = 11, /**< target mode interrupt: asserted whilst the TX FIFO level is below the low threshold. This is a level status interrupt. */
72 kDtI2cIrqAcqStretch = 12, /**< target mode interrupt: raised if the target is stretching clocks due to full ACQ FIFO or zero count in !!TARGET_ACK_CTRL.NBYTES (if enabled). This is a level status interrupt. */
73 kDtI2cIrqUnexpStop = 13, /**< target mode interrupt: raised if STOP is received without a preceding NACK during an external host read. */
74 kDtI2cIrqHostTimeout = 14, /**< target mode interrupt: raised if the host stops sending the clock during an ongoing transaction. */
75 kDtI2cIrqCount = 15, /**< \internal Number of IRQs */
77
78/**
79 * List of Alerts.
80 *
81 * Alerts are guaranteed to be numbered consecutively from 0.
82 */
83typedef enum dt_i2c_alert {
84 kDtI2cAlertFatalFault = 0, /**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
85 kDtI2cAlertCount = 1, /**< \internal Number of Alerts */
87
88/**
89 * List of clock ports.
90 *
91 * Clock ports are guaranteed to be numbered consecutively from 0.
92 */
93typedef enum dt_i2c_clock {
94 kDtI2cClockClk = 0, /**< Clock port clk_i */
95 kDtI2cClockCount = 1, /**< \internal Number of clock ports */
97
98/**
99 * List of reset ports.
100 *
101 * Reset ports are guaranteed to be numbered consecutively from 0.
102 */
103typedef enum dt_i2c_reset {
104 kDtI2cResetRst = 0, /**< Reset port rst_ni */
105 kDtI2cResetCount = 1, /**< \internal Number of reset ports */
107
108/**
109 * List of peripheral I/O.
110 *
111 * Peripheral I/O are guaranteed to be numbered consecutively from 0.
112 */
113typedef enum dt_i2c_periph_io {
114 kDtI2cPeriphIoSda = 0, /**< */
115 kDtI2cPeriphIoScl = 1, /**< */
116 kDtI2cPeriphIoCount = 2, /**< \internal Number of peripheral I/O */
118
119/**
120 * List of supported hardware features.
121 */
122#define OPENTITAN_I2C_HAS_MODE_HOST 1
123#define OPENTITAN_I2C_HAS_MODE_TARGET 1
124#define OPENTITAN_I2C_HAS_MODE_ACKCONTROL 1
125#define OPENTITAN_I2C_HAS_SPEED_STANDARD 1
126#define OPENTITAN_I2C_HAS_SPEED_FAST 1
127#define OPENTITAN_I2C_HAS_SPEED_FASTPLUS 1
128#define OPENTITAN_I2C_HAS_OVERRIDE 1
129#define OPENTITAN_I2C_HAS_OPERATION_READ 1
130#define OPENTITAN_I2C_HAS_OPERATION_WRITE 1
131#define OPENTITAN_I2C_HAS_PROTOCOL_CLOCKSTRETCHING 1
132#define OPENTITAN_I2C_HAS_PROTOCOL_NACK 1
133#define OPENTITAN_I2C_HAS_PROTOCOL_REPEATEDSTART 1
134
135
136
137/**
138 * Get the i2c instance from an instance ID
139 *
140 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
141 *
142 * @param inst_id Instance ID.
143 * @return A i2c instance.
144 *
145 * **Note:** This function only makes sense if the instance ID has device type i2c,
146 * otherwise the returned value is unspecified.
147 */
149
150/**
151 * Get the instance ID of an instance.
152 *
153 * @param dt Instance of i2c.
154 * @return The instance ID of that instance.
155 */
157
158/**
159 * Get the register base address of an instance.
160 *
161 * @param dt Instance of i2c.
162 * @param reg_block The register block requested.
163 * @return The register base address of the requested block.
164 */
165uint32_t dt_i2c_reg_block(
166 dt_i2c_t dt,
167 dt_i2c_reg_block_t reg_block);
168
169/**
170 * Get the primary register base address of an instance.
171 *
172 * This is just a convenience function, equivalent to
173 * `dt_i2c_reg_block(dt, kDtI2cRegBlockCore)`
174 *
175 * @param dt Instance of i2c.
176 * @return The register base address of the primary register block.
177 */
178static inline uint32_t dt_i2c_primary_reg_block(
179 dt_i2c_t dt) {
180 return dt_i2c_reg_block(dt, kDtI2cRegBlockCore);
181}
182
183/**
184 * Get the PLIC ID of a i2c IRQ for a given instance.
185 *
186 * If the instance is not connected to the PLIC, this function
187 * will return `kDtPlicIrqIdNone`.
188 *
189 * @param dt Instance of i2c.
190 * @param irq A i2c IRQ.
191 * @return The PLIC ID of the IRQ of this instance.
192 */
194 dt_i2c_t dt,
195 dt_i2c_irq_t irq);
196
197/**
198 * Convert a global IRQ ID to a local i2c IRQ type.
199 *
200 * @param dt Instance of i2c.
201 * @param irq A PLIC ID that belongs to this instance.
202 * @return The i2c IRQ, or `kDtI2cIrqCount`.
203 *
204 * **Note:** This function assumes that the PLIC ID belongs to the instance
205 * of i2c passed in parameter. In other words, it must be the case that
206 * `dt_i2c_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
207 * will return `kDtI2cIrqCount`.
208 */
210 dt_i2c_t dt,
211 dt_plic_irq_id_t irq);
212
213
214/**
215 * Get the alert ID of a i2c alert for a given instance.
216 *
217 * **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
218 * instances where the instance is not connected, the return value is unspecified.
219 *
220 * @param dt Instance of i2c.
221 * @param alert A i2c alert.
222 * @return The Alert Handler alert ID of the alert of this instance.
223 */
225 dt_i2c_t dt,
226 dt_i2c_alert_t alert);
227
228/**
229 * Convert a global alert ID to a local i2c alert type.
230 *
231 * @param dt Instance of i2c.
232 * @param alert A global alert ID that belongs to this instance.
233 * @return The i2c alert, or `kDtI2cAlertCount`.
234 *
235 * **Note:** This function assumes that the global alert ID belongs to the
236 * instance of i2c passed in parameter. In other words, it must be the case
237 * that `dt_i2c_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
238 * this function will return `kDtI2cAlertCount`.
239 */
241 dt_i2c_t dt,
242 dt_alert_id_t alert);
243
244
245/**
246 * Get the peripheral I/O description of an instance.
247 *
248 * @param dt Instance of i2c.
249 * @param sig Requested peripheral I/O.
250 * @return Description of the requested peripheral I/O for this instance.
251 */
253 dt_i2c_t dt,
255
256/**
257 * Get the clock signal connected to a clock port of an instance.
258 *
259 * @param dt Instance of i2c.
260 * @param clk Clock port.
261 * @return Clock signal.
262 */
264 dt_i2c_t dt,
265 dt_i2c_clock_t clk);
266
267/**
268 * Get the reset signal connected to a reset port of an instance.
269 *
270 * @param dt Instance of i2c.
271 * @param rst Reset port.
272 * @return Reset signal.
273 */
275 dt_i2c_t dt,
276 dt_i2c_reset_t rst);
277
278
279
280#ifdef __cplusplus
281} // extern "C"
282#endif // __cplusplus
283
284#endif // OPENTITAN_DT_I2C_H_