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
*/
25
typedef
enum
dt_aes
{
26
kDtAes
= 0,
/**< aes */
27
kDtAesFirst = 0,
/**< \internal First instance */
28
kDtAesCount = 1,
/**< \internal Number of instances */
29
}
dt_aes_t
;
30
31
/**
32
* List of register blocks.
33
*
34
* Register blocks are guaranteed to start at 0 and to be consecutively numbered.
35
*/
36
typedef
enum
dt_aes_reg_block
{
37
kDtAesRegBlockCore = 0,
/**< */
38
kDtAesRegBlockCount = 1,
/**< \internal Number of register blocks */
39
}
dt_aes_reg_block_t
;
40
41
/** Primary register block (associated with the "primary" set of registers that control the IP). */
42
static
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
*/
49
typedef
enum
dt_aes_alert
{
50
kDtAesAlertRecovCtrlUpdateErr
= 0,
/**< This recoverable alert is triggered upon detecting an update error in the shadowed Control Register.
51
The content of the Control Register is not modified (See Control Register).
52
The AES unit can be recovered from such a condition by restarting the AES operation, i.e., by re-writing the Control Register.
53
This should be monitored by the system. */
54
kDtAesAlertFatalFault
= 1,
/**< This fatal alert is triggered upon detecting a fatal fault inside the AES unit.
55
Examples for such faults include
56
i) storage errors in the shadowed Control Register,
57
ii) any internal FSM entering an invalid state,
58
iii) any sparsely encoded signal taking on an invalid value,
59
iv) errors in the internal round counter,
60
v) escalations triggered by the life cycle controller, and
61
vi) fatal integrity failures on the TL-UL bus.
62
The AES unit cannot recover from such an error and needs to be reset. */
63
kDtAesAlertCount = 2,
/**< \internal Number of Alerts */
64
}
dt_aes_alert_t
;
65
66
/**
67
* List of clock ports.
68
*
69
* Clock ports are guaranteed to be numbered consecutively from 0.
70
*/
71
typedef
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 */
75
}
dt_aes_clock_t
;
76
77
/**
78
* List of reset ports.
79
*
80
* Reset ports are guaranteed to be numbered consecutively from 0.
81
*/
82
typedef
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 */
86
}
dt_aes_reset_t
;
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
*/
120
dt_aes_t
dt_aes_from_instance_id
(
dt_instance_id_t
inst_id);
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
*/
128
dt_instance_id_t
dt_aes_instance_id
(
dt_aes_t
dt);
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
*/
137
uint32_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
*/
150
static
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
*/
166
dt_alert_id_t
dt_aes_alert_to_alert_id
(
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
*/
182
dt_aes_alert_t
dt_aes_alert_from_alert_id
(
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
*/
195
dt_clock_t
dt_aes_clock
(
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
*/
206
dt_reset_t
dt_aes_reset
(
207
dt_aes_t
dt,
208
dt_aes_reset_t
rst);
209
210
211
212
#endif
// OPENTITAN_DT_AES_H_
(earlgrey)
hw
top
dt
dt_aes.h
Return to
OpenTitan Documentation