Software APIs
dt_otbn.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_OTBN_H_
8#define OPENTITAN_DT_OTBN_H_
9
10#ifdef __cplusplus
11extern "C" {
12#endif // __cplusplus
13
14/**
15 * @file
16 * @brief Device Tables (DT) for IP otbn and top earlgrey.
17 *
18 * This file contains the type definitions and global functions of the otbn.
19 */
20
21#include "dt_api.h"
22#include <stdint.h>
23
24
25
26/**
27 * List of instances.
28 */
29typedef enum dt_otbn {
30 kDtOtbn = 0, /**< otbn */
31 kDtOtbnFirst = 0, /**< \internal First instance */
32 kDtOtbnCount = 1, /**< \internal Number of instances */
34
35/**
36 * List of register blocks.
37 *
38 * Register blocks are guaranteed to start at 0 and to be consecutively numbered.
39 */
40typedef enum dt_otbn_reg_block {
41 kDtOtbnRegBlockCore = 0, /**< */
42 kDtOtbnRegBlockCount = 1, /**< \internal Number of register blocks */
44
45/** Primary register block (associated with the "primary" set of registers that control the IP). */
46static const dt_otbn_reg_block_t kDtOtbnRegBlockPrimary = kDtOtbnRegBlockCore;
47
48/**
49 * List of IRQs.
50 *
51 * IRQs are guaranteed to be numbered consecutively from 0.
52 */
53typedef enum dt_otbn_irq {
54 kDtOtbnIrqDone = 0, /**< OTBN has completed the operation. */
55 kDtOtbnIrqCount = 1, /**< \internal Number of IRQs */
57
58/**
59 * List of Alerts.
60 *
61 * Alerts are guaranteed to be numbered consecutively from 0.
62 */
63typedef enum dt_otbn_alert {
64 kDtOtbnAlertFatal = 0, /**< A fatal error. Fatal alerts are non-recoverable and will be asserted until a hard reset. */
65 kDtOtbnAlertRecov = 1, /**< A recoverable error. Just sent once (as the processor stops). */
66 kDtOtbnAlertCount = 2, /**< \internal Number of Alerts */
68
69/**
70 * List of clock ports.
71 *
72 * Clock ports are guaranteed to be numbered consecutively from 0.
73 */
74typedef enum dt_otbn_clock {
75 kDtOtbnClockClk = 0, /**< Clock port clk_i */
76 kDtOtbnClockEdn = 1, /**< Clock port clk_edn_i */
77 kDtOtbnClockOtp = 2, /**< Clock port clk_otp_i */
78 kDtOtbnClockCount = 3, /**< \internal Number of clock ports */
80
81/**
82 * List of reset ports.
83 *
84 * Reset ports are guaranteed to be numbered consecutively from 0.
85 */
86typedef enum dt_otbn_reset {
87 kDtOtbnResetRst = 0, /**< Reset port rst_ni */
88 kDtOtbnResetEdn = 1, /**< Reset port rst_edn_ni */
89 kDtOtbnResetOtp = 2, /**< Reset port rst_otp_ni */
90 kDtOtbnResetCount = 3, /**< \internal Number of reset ports */
92
93/**
94 * List of supported hardware features.
95 */
96#define OPENTITAN_OTBN_HAS_MEM_SCRAMBLE 1
97
98
99
100/**
101 * Get the otbn instance from an instance ID
102 *
103 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
104 *
105 * @param inst_id Instance ID.
106 * @return A otbn instance.
107 *
108 * **Note:** This function only makes sense if the instance ID has device type otbn,
109 * otherwise the returned value is unspecified.
110 */
112
113/**
114 * Get the instance ID of an instance.
115 *
116 * @param dt Instance of otbn.
117 * @return The instance ID of that instance.
118 */
120
121/**
122 * Get the register base address of an instance.
123 *
124 * @param dt Instance of otbn.
125 * @param reg_block The register block requested.
126 * @return The register base address of the requested block.
127 */
128uint32_t dt_otbn_reg_block(
129 dt_otbn_t dt,
130 dt_otbn_reg_block_t reg_block);
131
132/**
133 * Get the primary register base address of an instance.
134 *
135 * This is just a convenience function, equivalent to
136 * `dt_otbn_reg_block(dt, kDtOtbnRegBlockCore)`
137 *
138 * @param dt Instance of otbn.
139 * @return The register base address of the primary register block.
140 */
141static inline uint32_t dt_otbn_primary_reg_block(
142 dt_otbn_t dt) {
143 return dt_otbn_reg_block(dt, kDtOtbnRegBlockCore);
144}
145
146/**
147 * Get the PLIC ID of a otbn IRQ for a given instance.
148 *
149 * If the instance is not connected to the PLIC, this function
150 * will return `kDtPlicIrqIdNone`.
151 *
152 * @param dt Instance of otbn.
153 * @param irq A otbn IRQ.
154 * @return The PLIC ID of the IRQ of this instance.
155 */
157 dt_otbn_t dt,
158 dt_otbn_irq_t irq);
159
160/**
161 * Convert a global IRQ ID to a local otbn IRQ type.
162 *
163 * @param dt Instance of otbn.
164 * @param irq A PLIC ID that belongs to this instance.
165 * @return The otbn IRQ, or `kDtOtbnIrqCount`.
166 *
167 * **Note:** This function assumes that the PLIC ID belongs to the instance
168 * of otbn passed in parameter. In other words, it must be the case that
169 * `dt_otbn_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
170 * will return `kDtOtbnIrqCount`.
171 */
173 dt_otbn_t dt,
174 dt_plic_irq_id_t irq);
175
176
177/**
178 * Get the alert ID of a otbn alert for a given instance.
179 *
180 * **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
181 * instances where the instance is not connected, the return value is unspecified.
182 *
183 * @param dt Instance of otbn.
184 * @param alert A otbn alert.
185 * @return The Alert Handler alert ID of the alert of this instance.
186 */
188 dt_otbn_t dt,
189 dt_otbn_alert_t alert);
190
191/**
192 * Convert a global alert ID to a local otbn alert type.
193 *
194 * @param dt Instance of otbn.
195 * @param alert A global alert ID that belongs to this instance.
196 * @return The otbn alert, or `kDtOtbnAlertCount`.
197 *
198 * **Note:** This function assumes that the global alert ID belongs to the
199 * instance of otbn passed in parameter. In other words, it must be the case
200 * that `dt_otbn_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
201 * this function will return `kDtOtbnAlertCount`.
202 */
204 dt_otbn_t dt,
205 dt_alert_id_t alert);
206
207
208
209/**
210 * Get the clock signal connected to a clock port of an instance.
211 *
212 * @param dt Instance of otbn.
213 * @param clk Clock port.
214 * @return Clock signal.
215 */
217 dt_otbn_t dt,
218 dt_otbn_clock_t clk);
219
220/**
221 * Get the reset signal connected to a reset port of an instance.
222 *
223 * @param dt Instance of otbn.
224 * @param rst Reset port.
225 * @return Reset signal.
226 */
228 dt_otbn_t dt,
229 dt_otbn_reset_t rst);
230
231
232
233#ifdef __cplusplus
234} // extern "C"
235#endif // __cplusplus
236
237#endif // OPENTITAN_DT_OTBN_H_