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