Software APIs
clkmgr.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_CLKMGR_H_
8
#define OPENTITAN_DT_CLKMGR_H_
9
10
#ifdef __cplusplus
11
extern
"C"
{
12
#endif
// __cplusplus
13
14
/**
15
* @file
16
* @brief Device Tables (DT) for IP clkmgr and top earlgrey.
17
*
18
* This file contains the type definitions and global functions of the clkmgr.
19
*/
20
21
#include "hw/top/dt/api.h"
22
#include <stdint.h>
23
24
25
#include "
sw/device/lib/base/bitfield.h
"
26
27
28
/**
29
* List of instances.
30
*/
31
typedef
enum
dt_clkmgr
{
32
kDtClkmgrFirst
= 0,
/**< First instance */
33
kDtClkmgr
= 0,
/**< clkmgr */
34
}
dt_clkmgr_t
;
35
36
enum
{
37
kDtClkmgrCount
= 1,
/**< Number of instances */
38
};
39
40
41
/**
42
* List of register blocks.
43
*
44
* Register blocks are guaranteed to start at 0 and to be consecutively numbered.
45
*/
46
typedef
enum
dt_clkmgr_reg_block
{
47
kDtClkmgrRegBlockCore = 0,
/**< */
48
}
dt_clkmgr_reg_block_t
;
49
50
enum
{
51
kDtClkmgrRegBlockCount
= 1,
/**< Number of register blocks */
52
};
53
54
55
/** Primary register block (associated with the "primary" set of registers that control the IP). */
56
static
const
dt_clkmgr_reg_block_t
kDtClkmgrRegBlockPrimary = kDtClkmgrRegBlockCore;
57
58
/**
59
* List of Alerts.
60
*
61
* Alerts are guaranteed to be numbered consecutively from 0.
62
*/
63
typedef
enum
dt_clkmgr_alert
{
64
kDtClkmgrAlertRecovFault
= 0,
/**< This recoverable alert is triggered when there are measurement errors. */
65
kDtClkmgrAlertFatalFault
= 1,
/**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
66
}
dt_clkmgr_alert_t
;
67
68
enum
{
69
kDtClkmgrAlertCount
= 2,
/**< Number of Alerts */
70
};
71
72
73
/**
74
* List of clock ports.
75
*
76
* Clock ports are guaranteed to be numbered consecutively from 0.
77
*/
78
typedef
enum
dt_clkmgr_clock
{
79
kDtClkmgrClockClk
= 0,
/**< Clock port clk_i */
80
kDtClkmgrClockMain
= 1,
/**< Clock port clk_main_i */
81
kDtClkmgrClockIo
= 2,
/**< Clock port clk_io_i */
82
kDtClkmgrClockUsb
= 3,
/**< Clock port clk_usb_i */
83
kDtClkmgrClockAon
= 4,
/**< Clock port clk_aon_i */
84
}
dt_clkmgr_clock_t
;
85
86
enum
{
87
kDtClkmgrClockCount
= 5,
/**< Number of clock ports */
88
};
89
90
91
/**
92
* List of reset ports.
93
*
94
* Reset ports are guaranteed to be numbered consecutively from 0.
95
*/
96
typedef
enum
dt_clkmgr_reset
{
97
kDtClkmgrResetRst
= 0,
/**< Reset port rst_ni */
98
kDtClkmgrResetRoot
= 1,
/**< Reset port rst_root_ni */
99
kDtClkmgrResetMain
= 2,
/**< Reset port rst_main_ni */
100
kDtClkmgrResetIo
= 3,
/**< Reset port rst_io_ni */
101
kDtClkmgrResetUsb
= 4,
/**< Reset port rst_usb_ni */
102
kDtClkmgrResetAon
= 5,
/**< Reset port rst_aon_ni */
103
kDtClkmgrResetIoDiv4
= 6,
/**< Reset port rst_io_div4_ni */
104
kDtClkmgrResetRootMain
= 7,
/**< Reset port rst_root_main_ni */
105
kDtClkmgrResetRootIo
= 8,
/**< Reset port rst_root_io_ni */
106
kDtClkmgrResetRootIoDiv4
= 9,
/**< Reset port rst_root_io_div4_ni */
107
kDtClkmgrResetRootUsb
= 10,
/**< Reset port rst_root_usb_ni */
108
}
dt_clkmgr_reset_t
;
109
110
enum
{
111
kDtClkmgrResetCount
= 11,
/**< Number of reset ports */
112
};
113
114
115
/**
116
* List of supported hardware features.
117
*/
118
#define OPENTITAN_CLKMGR_HAS_ENABLE_IO_DIV4 1
119
#define OPENTITAN_CLKMGR_HAS_ENABLE_IO_PERI 1
120
#define OPENTITAN_CLKMGR_HAS_ENABLE_USB 1
121
#define OPENTITAN_CLKMGR_HAS_ENABLE_IO_SPI_HOST1 1
122
#define OPENTITAN_CLKMGR_HAS_HINT_AES 1
123
#define OPENTITAN_CLKMGR_HAS_HINT_HMAC 1
124
#define OPENTITAN_CLKMGR_HAS_HINT_KMAC 1
125
#define OPENTITAN_CLKMGR_HAS_HINT_OTBN 1
126
#define OPENTITAN_CLKMGR_HAS_MEAS_CTRL_REGWEN 1
127
#define OPENTITAN_CLKMGR_HAS_MEAS_CTRL_IO 1
128
#define OPENTITAN_CLKMGR_HAS_MEAS_CTRL_IO_DIV4 1
129
#define OPENTITAN_CLKMGR_HAS_MEAS_CTRL_MAIN 1
130
#define OPENTITAN_CLKMGR_HAS_MEAS_CTRL_USB 1
131
#define OPENTITAN_CLKMGR_HAS_MEAS_CTRL_RECOV_ERR 1
132
#define OPENTITAN_CLKMGR_HAS_LC_EXTCLK_SPEED 1
133
#define OPENTITAN_CLKMGR_HAS_SW_EXTCLK_REGWEN 1
134
#define OPENTITAN_CLKMGR_HAS_SW_EXTCLK_HIGH_SPEED 1
135
#define OPENTITAN_CLKMGR_HAS_SW_EXTCLK_LOW_SPEED 1
136
#define OPENTITAN_CLKMGR_HAS_JITTER_REGWEN 1
137
#define OPENTITAN_CLKMGR_HAS_JITTER_ENABLE 1
138
#define OPENTITAN_CLKMGR_HAS_ALERT_HANDLER_CLOCK_STATUS 1
139
140
141
142
/**
143
* Get the clkmgr instance from an instance ID
144
*
145
* For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
146
*
147
* @param inst_id Instance ID.
148
* @return A clkmgr instance.
149
*
150
* **Note:** This function only makes sense if the instance ID has device type clkmgr,
151
* otherwise the returned value is unspecified.
152
*/
153
dt_clkmgr_t
dt_clkmgr_from_instance_id
(
dt_instance_id_t
inst_id);
154
155
/**
156
* Get the instance ID of an instance.
157
*
158
* @param dt Instance of clkmgr.
159
* @return The instance ID of that instance.
160
*/
161
dt_instance_id_t
dt_clkmgr_instance_id
(
dt_clkmgr_t
dt);
162
163
/**
164
* Get the register base address of an instance.
165
*
166
* @param dt Instance of clkmgr.
167
* @param reg_block The register block requested.
168
* @return The register base address of the requested block.
169
*/
170
uint32_t
dt_clkmgr_reg_block
(
171
dt_clkmgr_t
dt,
172
dt_clkmgr_reg_block_t
reg_block);
173
174
/**
175
* Get the primary register base address of an instance.
176
*
177
* This is just a convenience function, equivalent to
178
* `dt_clkmgr_reg_block(dt, kDtClkmgrRegBlockCore)`
179
*
180
* @param dt Instance of clkmgr.
181
* @return The register base address of the primary register block.
182
*/
183
static
inline
uint32_t dt_clkmgr_primary_reg_block(
184
dt_clkmgr_t
dt) {
185
return
dt_clkmgr_reg_block
(dt, kDtClkmgrRegBlockCore);
186
}
187
188
189
/**
190
* Get the alert ID of a clkmgr alert for a given instance.
191
*
192
* **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
193
* instances where the instance is not connected, the return value is unspecified.
194
*
195
* @param dt Instance of clkmgr.
196
* @param alert A clkmgr alert.
197
* @return The Alert Handler alert ID of the alert of this instance.
198
*/
199
dt_alert_id_t
dt_clkmgr_alert_to_alert_id
(
200
dt_clkmgr_t
dt,
201
dt_clkmgr_alert_t
alert);
202
203
/**
204
* Convert a global alert ID to a local clkmgr alert type.
205
*
206
* @param dt Instance of clkmgr.
207
* @param alert A global alert ID that belongs to this instance.
208
* @return The clkmgr alert, or `kDtClkmgrAlertCount`.
209
*
210
* **Note:** This function assumes that the global alert ID belongs to the
211
* instance of clkmgr passed in parameter. In other words, it must be the case
212
* that `dt_clkmgr_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
213
* this function will return `kDtClkmgrAlertCount`.
214
*/
215
dt_clkmgr_alert_t
dt_clkmgr_alert_from_alert_id
(
216
dt_clkmgr_t
dt,
217
dt_alert_id_t
alert);
218
219
220
221
/**
222
* Get the clock signal connected to a clock port of an instance.
223
*
224
* @param dt Instance of clkmgr.
225
* @param clk Clock port.
226
* @return Clock signal.
227
*/
228
dt_clock_t
dt_clkmgr_clock
(
229
dt_clkmgr_t
dt,
230
dt_clkmgr_clock_t
clk);
231
232
/**
233
* Get the reset signal connected to a reset port of an instance.
234
*
235
* @param dt Instance of clkmgr.
236
* @param rst Reset port.
237
* @return Reset signal.
238
*/
239
dt_reset_t
dt_clkmgr_reset
(
240
dt_clkmgr_t
dt,
241
dt_clkmgr_reset_t
rst);
242
243
244
245
/**
246
* Get the number of software gateable clocks.
247
*
248
* @param dt Instance of clkmgr.
249
* @return Number of gateable clocks.
250
*/
251
size_t
dt_clkmgr_gateable_clock_count
(
dt_clkmgr_t
dt);
252
253
/**
254
* Get the instance ID of a gateable clock.
255
*
256
* The clocks are ordered as they appear in the registers.
257
*
258
* @param dt Instance of clkmgr.
259
* @param idx Index of the gateable clock, between 0 and `dt_clkmgr_sw_clock_count(dt)-1`.
260
* @return Instance ID of the device whose clock is gateable.
261
*/
262
dt_instance_id_t
dt_clkmgr_gateable_clock
(
dt_clkmgr_t
dt,
size_t
idx);
263
264
/**
265
* Get the number of software hintable clocks.
266
*
267
* @param dt Instance of clkmgr.
268
* @return Number of hintable clocks.
269
*/
270
size_t
dt_clkmgr_hintable_clock_count
(
dt_clkmgr_t
dt);
271
272
/**
273
* Get the instance ID of a hintable clock.
274
*
275
* The clocks sources are ordered as they appear in the registers.
276
*
277
* @param dt Instance of clkmgr.
278
* @param idx Index of the hintable clock, between 0 and `dt_clkmgr_hint_clock_count(dt)-1`.
279
* @return Instance ID of the device whose clock is hintable.
280
*/
281
dt_instance_id_t
dt_clkmgr_hintable_clock
(
dt_clkmgr_t
dt,
size_t
idx);
282
283
/**
284
* Description of a measurable clock.
285
*
286
*/
287
typedef
struct
dt_clkmgr_measurable_clk
{
288
dt_clock_t
clock
;
/**< Clock */
289
uint32_t
meas_ctrl_en_off
;
/**< MEAS_CTRL_EN register offset */
290
bitfield_field32_t
meas_ctrl_en_en_field
;
/**< MEAS_CTRL_EN_EN bitfield */
291
uint32_t
meas_ctrl_shadowed_off
;
/**< CTRL_SHADOWED register offset */
292
bitfield_field32_t
meas_ctrl_shadowed_lo_field
;
/**< CTRL_SHADOWED_LO bitfield */
293
bitfield_field32_t
meas_ctrl_shadowed_hi_field
;
/**< CTRL_SHADOWED_HI bitfield */
294
}
dt_clkmgr_measurable_clk_t
;
295
296
297
/**
298
* Get the number of measurable clocks.
299
*
300
* @param dt Instance of clkmgr.
301
* @return Number of measurable clocks.
302
*/
303
size_t
dt_clkmgr_measurable_clock_count
(
dt_clkmgr_t
dt);
304
305
/**
306
* Get the description of a measurable clock.
307
*
308
* @param dt Instance of clkmgr.
309
* @param idx Index of the measurable clock, between 0 and
310
* `dt_clkmgr_measurable_clock_count(dt)-1`.
311
* @return Description of the measurable clock.
312
*/
313
dt_clkmgr_measurable_clk_t
dt_clkmgr_measurable_clock
(
dt_clkmgr_t
dt,
size_t
idx);
314
315
316
317
#ifdef __cplusplus
318
}
// extern "C"
319
#endif
// __cplusplus
320
321
#endif
// OPENTITAN_DT_CLKMGR_H_
(earlgrey)
hw
top
dt
clkmgr.h
Return to
OpenTitan Documentation