Software APIs
dt_aes.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_AES_H_
8#define OPENTITAN_DT_AES_H_
9
10/**
11 * @file
12 * @brief Device Tables (DT) for IP aes and top earlgrey.
13 *
14 * This file contains the type definitions and global functions of the aes.
15 */
16
17#include "dt_api.h"
18#include <stdint.h>
19
20
21
22/**
23 * List of instances.
24 */
25typedef enum dt_aes {
26 kDtAes = 0, /**< aes */
27 kDtAesFirst = 0, /**< \internal First instance */
28 kDtAesCount = 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_aes_reg_block {
37 kDtAesRegBlockCore = 0, /**< */
38 kDtAesRegBlockCount = 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_aes_reg_block_t kDtAesRegBlockPrimary = kDtAesRegBlockCore;
43
44/**
45 * List of Alerts.
46 *
47 * Alerts are guaranteed to be numbered consecutively from 0.
48 */
49typedef enum dt_aes_alert {
50 kDtAesAlertRecovCtrlUpdateErr = 0, /**< This recoverable alert is triggered upon detecting an update error in the shadowed Control Register.
51The content of the Control Register is not modified (See Control Register).
52The AES unit can be recovered from such a condition by restarting the AES operation, i.e., by re-writing the Control Register.
53This should be monitored by the system. */
54 kDtAesAlertFatalFault = 1, /**< This fatal alert is triggered upon detecting a fatal fault inside the AES unit.
55Examples for such faults include
56i) storage errors in the shadowed Control Register,
57ii) any internal FSM entering an invalid state,
58iii) any sparsely encoded signal taking on an invalid value,
59iv) errors in the internal round counter,
60v) escalations triggered by the life cycle controller, and
61vi) fatal integrity failures on the TL-UL bus.
62The AES unit cannot recover from such an error and needs to be reset. */
63 kDtAesAlertCount = 2, /**< \internal Number of Alerts */
65
66/**
67 * List of clock ports.
68 *
69 * Clock ports are guaranteed to be numbered consecutively from 0.
70 */
71typedef enum dt_aes_clock {
72 kDtAesClockClk = 0, /**< Clock port clk_i */
73 kDtAesClockEdn = 1, /**< Clock port clk_edn_i */
74 kDtAesClockCount = 2, /**< \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_aes_reset {
83 kDtAesResetRst = 0, /**< Reset port rst_ni */
84 kDtAesResetEdn = 1, /**< Reset port rst_edn_ni */
85 kDtAesResetCount = 2, /**< \internal Number of reset ports */
87
88/**
89 * List of supported hardware features.
90 */
91#define OPENTITAN_AES_HAS_KEY_LEN_128 1
92#define OPENTITAN_AES_HAS_KEY_LEN_192 1
93#define OPENTITAN_AES_HAS_KEY_LEN_256 1
94#define OPENTITAN_AES_HAS_MODE_ECB 1
95#define OPENTITAN_AES_HAS_MODE_CBC 1
96#define OPENTITAN_AES_HAS_MODE_CFB_128 1
97#define OPENTITAN_AES_HAS_MODE_OFB 1
98#define OPENTITAN_AES_HAS_MODE_CTR 1
99#define OPENTITAN_AES_HAS_KEY_SIDELOAD 1
100#define OPENTITAN_AES_HAS_CLEAR_DATA_OUT 1
101#define OPENTITAN_AES_HAS_CLEAR_KEY_IV_DATA_IN 1
102#define OPENTITAN_AES_HAS_PRNG_RESEED_RATE 1
103#define OPENTITAN_AES_HAS_PRNG_KEY_TOUCH_FORCES_RESEED 1
104#define OPENTITAN_AES_HAS_PRNG_FORCE_MASKS 1
105#define OPENTITAN_AES_HAS_MANUAL_OPERATION 1
106
107
108
109/**
110 * Get the aes instance from an instance ID
111 *
112 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
113 *
114 * @param inst_id Instance ID.
115 * @return A aes instance.
116 *
117 * **Note:** This function only makes sense if the instance ID has device type aes,
118 * otherwise the returned value is unspecified.
119 */
121
122/**
123 * Get the instance ID of an instance.
124 *
125 * @param dt Instance of aes.
126 * @return The instance ID of that instance.
127 */
129
130/**
131 * Get the register base address of an instance.
132 *
133 * @param dt Instance of aes.
134 * @param reg_block The register block requested.
135 * @return The register base address of the requested block.
136 */
137uint32_t dt_aes_reg_block(
138 dt_aes_t dt,
139 dt_aes_reg_block_t reg_block);
140
141/**
142 * Get the primary register base address of an instance.
143 *
144 * This is just a convenience function, equivalent to
145 * `dt_aes_reg_block(dt, kDtAesRegBlockCore)`
146 *
147 * @param dt Instance of aes.
148 * @return The register base address of the primary register block.
149 */
150static inline uint32_t dt_aes_primary_reg_block(
151 dt_aes_t dt) {
152 return dt_aes_reg_block(dt, kDtAesRegBlockCore);
153}
154
155
156/**
157 * Get the alert ID of a aes alert for a given instance.
158 *
159 * **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
160 * instances where the instance is not connected, the return value is unspecified.
161 *
162 * @param dt Instance of aes.
163 * @param alert A aes alert.
164 * @return The Alert Handler alert ID of the alert of this instance.
165 */
167 dt_aes_t dt,
168 dt_aes_alert_t alert);
169
170/**
171 * Convert a global alert ID to a local aes alert type.
172 *
173 * @param dt Instance of aes.
174 * @param alert A global alert ID that belongs to this instance.
175 * @return The aes alert, or `kDtAesAlertCount`.
176 *
177 * **Note:** This function assumes that the global alert ID belongs to the
178 * instance of aes passed in parameter. In other words, it must be the case
179 * that `dt_aes_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
180 * this function will return `kDtAesAlertCount`.
181 */
183 dt_aes_t dt,
184 dt_alert_id_t alert);
185
186
187
188/**
189 * Get the clock signal connected to a clock port of an instance.
190 *
191 * @param dt Instance of aes.
192 * @param clk Clock port.
193 * @return Clock signal.
194 */
196 dt_aes_t dt,
197 dt_aes_clock_t clk);
198
199/**
200 * Get the reset signal connected to a reset port of an instance.
201 *
202 * @param dt Instance of aes.
203 * @param rst Reset port.
204 * @return Reset signal.
205 */
207 dt_aes_t dt,
208 dt_aes_reset_t rst);
209
210
211
212#endif // OPENTITAN_DT_AES_H_