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