Software APIs
dt_mbx.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_MBX_H_
8#define OPENTITAN_DT_MBX_H_
9
10#ifdef __cplusplus
11extern "C" {
12#endif // __cplusplus
13
14/**
15 * @file
16 * @brief Device Tables (DT) for IP mbx and top darjeeling.
17 *
18 * This file contains the type definitions and global functions of the mbx.
19 */
20
21#include "hw/top/dt/dt_api.h"
22#include <stdint.h>
23
24
25
26/**
27 * List of instances.
28 */
29typedef enum dt_mbx {
30 kDtMbx0 = 0, /**< mbx0 */
31 kDtMbx1 = 1, /**< mbx1 */
32 kDtMbx2 = 2, /**< mbx2 */
33 kDtMbx3 = 3, /**< mbx3 */
34 kDtMbx4 = 4, /**< mbx4 */
35 kDtMbx5 = 5, /**< mbx5 */
36 kDtMbx6 = 6, /**< mbx6 */
37 kDtMbxJtag = 7, /**< mbx_jtag */
38 kDtMbxPcie0 = 8, /**< mbx_pcie0 */
39 kDtMbxPcie1 = 9, /**< mbx_pcie1 */
40 kDtMbxFirst = 0, /**< \internal First instance */
41 kDtMbxCount = 10, /**< \internal Number of instances */
43
44/**
45 * List of register blocks.
46 *
47 * Register blocks are guaranteed to start at 0 and to be consecutively numbered.
48 */
49typedef enum dt_mbx_reg_block {
50 kDtMbxRegBlockCore = 0, /**< */
51 kDtMbxRegBlockSoc = 1, /**< */
52 kDtMbxRegBlockCount = 2, /**< \internal Number of register blocks */
54
55/**
56 * List of memories.
57 *
58 * Memories are guaranteed to start at 0 and to be consecutively numbered.
59 */
60typedef enum dt_mbx_memory {
61 kDtMbxMemoryCount = 0, /**< \internal Number of memories */
63
64/** Primary register block (associated with the "primary" set of registers that control the IP). */
65static const dt_mbx_reg_block_t kDtMbxRegBlockPrimary = kDtMbxRegBlockCore;
66
67/**
68 * List of IRQs.
69 *
70 * IRQs are guaranteed to be numbered consecutively from 0.
71 */
72typedef enum dt_mbx_irq {
73 kDtMbxIrqMbxReady = 0, /**< A new object was received in the inbound mailbox. */
74 kDtMbxIrqMbxAbort = 1, /**< An abort request was received from the requester. */
75 kDtMbxIrqMbxError = 2, /**< The mailbox instance generated an error. */
76 kDtMbxIrqCount = 3, /**< \internal Number of IRQs */
78
79/**
80 * List of Alerts.
81 *
82 * Alerts are guaranteed to be numbered consecutively from 0.
83 */
84typedef enum dt_mbx_alert {
85 kDtMbxAlertFatalFault = 0, /**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
86 kDtMbxAlertRecovFault = 1, /**< This recoverable alert is triggered when memory with invalid ECC (e.g., uninitialized memory) or at an invalid address is accessed. */
87 kDtMbxAlertCount = 2, /**< \internal Number of Alerts */
89
90/**
91 * List of clock ports.
92 *
93 * Clock ports are guaranteed to be numbered consecutively from 0.
94 */
95typedef enum dt_mbx_clock {
96 kDtMbxClockClk = 0, /**< Clock port clk_i */
97 kDtMbxClockCount = 1, /**< \internal Number of clock ports */
99
100/**
101 * List of reset ports.
102 *
103 * Reset ports are guaranteed to be numbered consecutively from 0.
104 */
105typedef enum dt_mbx_reset {
106 kDtMbxResetRst = 0, /**< Reset port rst_ni */
107 kDtMbxResetCount = 1, /**< \internal Number of reset ports */
109
110
111/**
112 * Get the mbx instance from an instance ID
113 *
114 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
115 *
116 * @param inst_id Instance ID.
117 * @return A mbx instance.
118 *
119 * **Note:** This function only makes sense if the instance ID has device type mbx,
120 * otherwise the returned value is unspecified.
121 */
123
124/**
125 * Get the instance ID of an instance.
126 *
127 * @param dt Instance of mbx.
128 * @return The instance ID of that instance.
129 */
131
132/**
133 * Get the register base address of an instance.
134 *
135 * @param dt Instance of mbx.
136 * @param reg_block The register block requested.
137 * @return The register base address of the requested block.
138 */
139uint32_t dt_mbx_reg_block(
140 dt_mbx_t dt,
141 dt_mbx_reg_block_t reg_block);
142
143/**
144 * Get the primary register base address of an instance.
145 *
146 * This is just a convenience function, equivalent to
147 * `dt_mbx_reg_block(dt, kDtMbxRegBlockCore)`
148 *
149 * @param dt Instance of mbx.
150 * @return The register base address of the primary register block.
151 */
152static inline uint32_t dt_mbx_primary_reg_block(
153 dt_mbx_t dt) {
154 return dt_mbx_reg_block(dt, kDtMbxRegBlockCore);
155}
156
157/**
158 * Get the base address of a memory.
159 *
160 * @param dt Instance of mbx.
161 * @param mem The memory requested.
162 * @return The base address of the requested memory.
163 */
164uint32_t dt_mbx_memory_base(
165 dt_mbx_t dt,
166 dt_mbx_memory_t mem);
167
168/**
169 * Get the size of a memory.
170 *
171 * @param dt Instance of mbx.
172 * @param mem The memory requested.
173 * @return The size of the requested memory.
174 */
175uint32_t dt_mbx_memory_size(
176 dt_mbx_t dt,
177 dt_mbx_memory_t mem);
178
179/**
180 * Get the PLIC ID of a mbx 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 mbx.
186 * @param irq A mbx IRQ.
187 * @return The PLIC ID of the IRQ of this instance.
188 */
190 dt_mbx_t dt,
191 dt_mbx_irq_t irq);
192
193/**
194 * Convert a global IRQ ID to a local mbx IRQ type.
195 *
196 * @param dt Instance of mbx.
197 * @param irq A PLIC ID that belongs to this instance.
198 * @return The mbx IRQ, or `kDtMbxIrqCount`.
199 *
200 * **Note:** This function assumes that the PLIC ID belongs to the instance
201 * of mbx passed in parameter. In other words, it must be the case that
202 * `dt_mbx_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
203 * will return `kDtMbxIrqCount`.
204 */
206 dt_mbx_t dt,
207 dt_plic_irq_id_t irq);
208
209
210/**
211 * Get the alert ID of a mbx 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 mbx.
217 * @param alert A mbx alert.
218 * @return The Alert Handler alert ID of the alert of this instance.
219 */
221 dt_mbx_t dt,
222 dt_mbx_alert_t alert);
223
224/**
225 * Convert a global alert ID to a local mbx alert type.
226 *
227 * @param dt Instance of mbx.
228 * @param alert A global alert ID that belongs to this instance.
229 * @return The mbx alert, or `kDtMbxAlertCount`.
230 *
231 * **Note:** This function assumes that the global alert ID belongs to the
232 * instance of mbx passed in parameter. In other words, it must be the case
233 * that `dt_mbx_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
234 * this function will return `kDtMbxAlertCount`.
235 */
237 dt_mbx_t dt,
238 dt_alert_id_t alert);
239
240
241
242/**
243 * Get the clock signal connected to a clock port of an instance.
244 *
245 * @param dt Instance of mbx.
246 * @param clk Clock port.
247 * @return Clock signal.
248 */
250 dt_mbx_t dt,
251 dt_mbx_clock_t clk);
252
253/**
254 * Get the reset signal connected to a reset port of an instance.
255 *
256 * @param dt Instance of mbx.
257 * @param rst Reset port.
258 * @return Reset signal.
259 */
261 dt_mbx_t dt,
262 dt_mbx_reset_t rst);
263
264
265
266#ifdef __cplusplus
267} // extern "C"
268#endif // __cplusplus
269
270#endif // OPENTITAN_DT_MBX_H_