Software APIs
dt_hmac.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_HMAC_H_
8#define OPENTITAN_DT_HMAC_H_
9
10/**
11 * @file
12 * @brief Device Tables (DT) for IP hmac and top darjeeling.
13 *
14 * This file contains the type definitions and global functions of the hmac.
15 */
16
17#include "dt_api.h"
18#include <stdint.h>
19
20
21
22/**
23 * List of instances.
24 */
25typedef enum dt_hmac {
26 kDtHmac = 0, /**< hmac */
27 kDtHmacFirst = 0, /**< \internal First instance */
28 kDtHmacCount = 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_hmac_reg_block {
37 kDtHmacRegBlockCore = 0, /**< */
38 kDtHmacRegBlockCount = 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_hmac_reg_block_t kDtHmacRegBlockPrimary = kDtHmacRegBlockCore;
43
44/**
45 * List of IRQs.
46 *
47 * IRQs are guaranteed to be numbered consecutively from 0.
48 */
49typedef enum dt_hmac_irq {
50 kDtHmacIrqHmacDone = 0, /**< HMAC/SHA-2 has completed. */
51 kDtHmacIrqFifoEmpty = 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 HMAC block is not running in HMAC mode and performing the second round of computing the final hash of the outer key as well as the result of the first round using the inner key.
54ii) Software has not yet written the Process or Stop command to finish the hashing operation.
55For the interrupt to be raised, the message FIFO must also have been full previously.
56Otherwise, 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. */
57 kDtHmacIrqHmacErr = 2, /**< HMAC error has occurred. ERR_CODE register shows which error occurred. */
58 kDtHmacIrqCount = 3, /**< \internal Number of IRQs */
60
61/**
62 * List of Alerts.
63 *
64 * Alerts are guaranteed to be numbered consecutively from 0.
65 */
66typedef enum dt_hmac_alert {
67 kDtHmacAlertFatalFault = 0, /**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
68 kDtHmacAlertCount = 1, /**< \internal Number of Alerts */
70
71/**
72 * List of clock ports.
73 *
74 * Clock ports are guaranteed to be numbered consecutively from 0.
75 */
76typedef enum dt_hmac_clock {
77 kDtHmacClockClk = 0, /**< Clock port clk_i */
78 kDtHmacClockCount = 1, /**< \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_hmac_reset {
87 kDtHmacResetRst = 0, /**< Reset port rst_ni */
88 kDtHmacResetCount = 1, /**< \internal Number of reset ports */
90
91/**
92 * List of supported hardware features.
93 */
94#define OPENTITAN_HMAC_HAS_MODE_SHA2 1
95#define OPENTITAN_HMAC_HAS_MODE_HMAC 1
96#define OPENTITAN_HMAC_HAS_DIGEST_SIZE_SHA2_256 1
97#define OPENTITAN_HMAC_HAS_DIGEST_SIZE_SHA2_384 1
98#define OPENTITAN_HMAC_HAS_DIGEST_SIZE_SHA2_512 1
99#define OPENTITAN_HMAC_HAS_KEY_LENGTH_KEY_128 1
100#define OPENTITAN_HMAC_HAS_KEY_LENGTH_KEY_256 1
101#define OPENTITAN_HMAC_HAS_KEY_LENGTH_KEY_384 1
102#define OPENTITAN_HMAC_HAS_KEY_LENGTH_KEY_512 1
103#define OPENTITAN_HMAC_HAS_KEY_LENGTH_KEY_1024 1
104#define OPENTITAN_HMAC_HAS_ENDIANNESS_MESSAGE 1
105#define OPENTITAN_HMAC_HAS_ENDIANNESS_DIGEST 1
106#define OPENTITAN_HMAC_HAS_SECURE_WIPE 1
107
108
109
110/**
111 * Get the hmac instance from an instance ID
112 *
113 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
114 *
115 * @param inst_id Instance ID.
116 * @return A hmac instance.
117 *
118 * **Note:** This function only makes sense if the instance ID has device type hmac,
119 * otherwise the returned value is unspecified.
120 */
122
123/**
124 * Get the instance ID of an instance.
125 *
126 * @param dt Instance of hmac.
127 * @return The instance ID of that instance.
128 */
130
131/**
132 * Get the register base address of an instance.
133 *
134 * @param dt Instance of hmac.
135 * @param reg_block The register block requested.
136 * @return The register base address of the requested block.
137 */
138uint32_t dt_hmac_reg_block(
139 dt_hmac_t dt,
140 dt_hmac_reg_block_t reg_block);
141
142/**
143 * Get the primary register base address of an instance.
144 *
145 * This is just a convenience function, equivalent to
146 * `dt_hmac_reg_block(dt, kDtHmacRegBlockCore)`
147 *
148 * @param dt Instance of hmac.
149 * @return The register base address of the primary register block.
150 */
151static inline uint32_t dt_hmac_primary_reg_block(
152 dt_hmac_t dt) {
153 return dt_hmac_reg_block(dt, kDtHmacRegBlockCore);
154}
155
156/**
157 * Get the PLIC ID of a hmac IRQ for a given instance.
158 *
159 * If the instance is not connected to the PLIC, this function
160 * will return `kDtPlicIrqIdNone`.
161 *
162 * @param dt Instance of hmac.
163 * @param irq A hmac IRQ.
164 * @return The PLIC ID of the IRQ of this instance.
165 */
167 dt_hmac_t dt,
168 dt_hmac_irq_t irq);
169
170/**
171 * Convert a global IRQ ID to a local hmac IRQ type.
172 *
173 * @param dt Instance of hmac.
174 * @param irq A PLIC ID that belongs to this instance.
175 * @return The hmac IRQ, or `kDtHmacIrqCount`.
176 *
177 * **Note:** This function assumes that the PLIC ID belongs to the instance
178 * of hmac passed in parameter. In other words, it must be the case that
179 * `dt_hmac_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
180 * will return `kDtHmacIrqCount`.
181 */
183 dt_hmac_t dt,
184 dt_plic_irq_id_t irq);
185
186
187/**
188 * Get the alert ID of a hmac alert for a given instance.
189 *
190 * **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
191 * instances where the instance is not connected, the return value is unspecified.
192 *
193 * @param dt Instance of hmac.
194 * @param alert A hmac alert.
195 * @return The Alert Handler alert ID of the alert of this instance.
196 */
198 dt_hmac_t dt,
199 dt_hmac_alert_t alert);
200
201/**
202 * Convert a global alert ID to a local hmac alert type.
203 *
204 * @param dt Instance of hmac.
205 * @param alert A global alert ID that belongs to this instance.
206 * @return The hmac alert, or `kDtHmacAlertCount`.
207 *
208 * **Note:** This function assumes that the global alert ID belongs to the
209 * instance of hmac passed in parameter. In other words, it must be the case
210 * that `dt_hmac_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
211 * this function will return `kDtHmacAlertCount`.
212 */
214 dt_hmac_t dt,
215 dt_alert_id_t alert);
216
217
218
219/**
220 * Get the clock signal connected to a clock port of an instance.
221 *
222 * @param dt Instance of hmac.
223 * @param clk Clock port.
224 * @return Clock signal.
225 */
227 dt_hmac_t dt,
228 dt_hmac_clock_t clk);
229
230/**
231 * Get the reset signal connected to a reset port of an instance.
232 *
233 * @param dt Instance of hmac.
234 * @param rst Reset port.
235 * @return Reset signal.
236 */
238 dt_hmac_t dt,
239 dt_hmac_reset_t rst);
240
241
242
243#endif // OPENTITAN_DT_HMAC_H_