Software APIs
dt_kmac.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_KMAC_H_
8#define OPENTITAN_DT_KMAC_H_
9
10/**
11 * @file
12 * @brief Device Tables (DT) for IP kmac and top earlgrey.
13 *
14 * This file contains the type definitions and global functions of the kmac.
15 */
16
17#include "dt_api.h"
18#include <stdint.h>
19
20
21
22/**
23 * List of instances.
24 */
25typedef enum dt_kmac {
26 kDtKmac = 0, /**< kmac */
27 kDtKmacFirst = 0, /**< \internal First instance */
28 kDtKmacCount = 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_kmac_reg_block {
37 kDtKmacRegBlockCore = 0, /**< */
38 kDtKmacRegBlockCount = 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_kmac_reg_block_t kDtKmacRegBlockPrimary = kDtKmacRegBlockCore;
43
44/**
45 * List of IRQs.
46 *
47 * IRQs are guaranteed to be numbered consecutively from 0.
48 */
49typedef enum dt_kmac_irq {
50 kDtKmacIrqKmacDone = 0, /**< KMAC/SHA3 absorbing has been completed */
51 kDtKmacIrqFifoEmpty = 1, /**< The message FIFO is empty.
52This interrupt is raised only if the message FIFO is actually writable by software, i.e., if all of the following conditions are met:
53i) The KMAC block is not exercised by a hardware application interface.
54ii) The SHA3 block is in the Absorb state.
55iii) Software has not yet written the Process command to finish the absorption process.
56For the interrupt to be raised, the message FIFO must also have been full previously.
57Otherwise, the hardware empties the FIFO faster than software can fill it and there is no point in interrupting the software to inform it about the message FIFO being empty. */
58 kDtKmacIrqKmacErr = 2, /**< KMAC/SHA3 error occurred. ERR_CODE register shows the details */
59 kDtKmacIrqCount = 3, /**< \internal Number of IRQs */
61
62/**
63 * List of Alerts.
64 *
65 * Alerts are guaranteed to be numbered consecutively from 0.
66 */
67typedef enum dt_kmac_alert {
68 kDtKmacAlertRecovOperationErr = 0, /**< Alert for KMAC operation error. It occurs when the shadow registers have update errors. */
69 kDtKmacAlertFatalFaultErr = 1, /**< This fatal alert is triggered when a fatal error is detected inside the KMAC unit.
70Examples for such faults include:
71i) TL-UL bus integrity fault.
72ii) Storage errors in the shadow registers.
73iii) Errors in the message, round, or key counter.
74iv) Any internal FSM entering an invalid state.
75v) An error in the redundant lfsr.
76The KMAC unit cannot recover from such an error and needs to be reset. */
77 kDtKmacAlertCount = 2, /**< \internal Number of Alerts */
79
80/**
81 * List of clock ports.
82 *
83 * Clock ports are guaranteed to be numbered consecutively from 0.
84 */
85typedef enum dt_kmac_clock {
86 kDtKmacClockClk = 0, /**< Clock port clk_i */
87 kDtKmacClockEdn = 1, /**< Clock port clk_edn_i */
88 kDtKmacClockCount = 2, /**< \internal Number of clock ports */
90
91/**
92 * List of reset ports.
93 *
94 * Reset ports are guaranteed to be numbered consecutively from 0.
95 */
96typedef enum dt_kmac_reset {
97 kDtKmacResetRst = 0, /**< Reset port rst_ni */
98 kDtKmacResetEdn = 1, /**< Reset port rst_edn_ni */
99 kDtKmacResetCount = 2, /**< \internal Number of reset ports */
101
102/**
103 * List of supported hardware features.
104 */
105#define OPENTITAN_KMAC_HAS_MODE_SHA3 1
106#define OPENTITAN_KMAC_HAS_MODE_SHAKE 1
107#define OPENTITAN_KMAC_HAS_MODE_CSHAKE 1
108#define OPENTITAN_KMAC_HAS_MODE_KMAC 1
109#define OPENTITAN_KMAC_HAS_MODE_XOF 1
110#define OPENTITAN_KMAC_HAS_ENDIANNESS_MESSAGE 1
111#define OPENTITAN_KMAC_HAS_ENDIANNESS_DIGEST 1
112#define OPENTITAN_KMAC_HAS_KEY_SIDELOAD 1
113#define OPENTITAN_KMAC_HAS_ENTROPY_MODES 1
114
115
116
117/**
118 * Get the kmac instance from an instance ID
119 *
120 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
121 *
122 * @param inst_id Instance ID.
123 * @return A kmac instance.
124 *
125 * **Note:** This function only makes sense if the instance ID has device type kmac,
126 * otherwise the returned value is unspecified.
127 */
129
130/**
131 * Get the instance ID of an instance.
132 *
133 * @param dt Instance of kmac.
134 * @return The instance ID of that instance.
135 */
137
138/**
139 * Get the register base address of an instance.
140 *
141 * @param dt Instance of kmac.
142 * @param reg_block The register block requested.
143 * @return The register base address of the requested block.
144 */
145uint32_t dt_kmac_reg_block(
146 dt_kmac_t dt,
147 dt_kmac_reg_block_t reg_block);
148
149/**
150 * Get the primary register base address of an instance.
151 *
152 * This is just a convenience function, equivalent to
153 * `dt_kmac_reg_block(dt, kDtKmacRegBlockCore)`
154 *
155 * @param dt Instance of kmac.
156 * @return The register base address of the primary register block.
157 */
158static inline uint32_t dt_kmac_primary_reg_block(
159 dt_kmac_t dt) {
160 return dt_kmac_reg_block(dt, kDtKmacRegBlockCore);
161}
162
163/**
164 * Get the PLIC ID of a kmac IRQ for a given instance.
165 *
166 * If the instance is not connected to the PLIC, this function
167 * will return `kDtPlicIrqIdNone`.
168 *
169 * @param dt Instance of kmac.
170 * @param irq A kmac IRQ.
171 * @return The PLIC ID of the IRQ of this instance.
172 */
174 dt_kmac_t dt,
175 dt_kmac_irq_t irq);
176
177/**
178 * Convert a global IRQ ID to a local kmac IRQ type.
179 *
180 * @param dt Instance of kmac.
181 * @param irq A PLIC ID that belongs to this instance.
182 * @return The kmac IRQ, or `kDtKmacIrqCount`.
183 *
184 * **Note:** This function assumes that the PLIC ID belongs to the instance
185 * of kmac passed in parameter. In other words, it must be the case that
186 * `dt_kmac_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
187 * will return `kDtKmacIrqCount`.
188 */
190 dt_kmac_t dt,
191 dt_plic_irq_id_t irq);
192
193
194/**
195 * Get the alert ID of a kmac alert for a given instance.
196 *
197 * **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
198 * instances where the instance is not connected, the return value is unspecified.
199 *
200 * @param dt Instance of kmac.
201 * @param alert A kmac alert.
202 * @return The Alert Handler alert ID of the alert of this instance.
203 */
205 dt_kmac_t dt,
206 dt_kmac_alert_t alert);
207
208/**
209 * Convert a global alert ID to a local kmac alert type.
210 *
211 * @param dt Instance of kmac.
212 * @param alert A global alert ID that belongs to this instance.
213 * @return The kmac alert, or `kDtKmacAlertCount`.
214 *
215 * **Note:** This function assumes that the global alert ID belongs to the
216 * instance of kmac passed in parameter. In other words, it must be the case
217 * that `dt_kmac_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
218 * this function will return `kDtKmacAlertCount`.
219 */
221 dt_kmac_t dt,
222 dt_alert_id_t alert);
223
224
225
226/**
227 * Get the clock signal connected to a clock port of an instance.
228 *
229 * @param dt Instance of kmac.
230 * @param clk Clock port.
231 * @return Clock signal.
232 */
234 dt_kmac_t dt,
235 dt_kmac_clock_t clk);
236
237/**
238 * Get the reset signal connected to a reset port of an instance.
239 *
240 * @param dt Instance of kmac.
241 * @param rst Reset port.
242 * @return Reset signal.
243 */
245 dt_kmac_t dt,
246 dt_kmac_reset_t rst);
247
248
249
250#endif // OPENTITAN_DT_KMAC_H_