Software APIs
dt_pwrmgr.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_PWRMGR_H_
8
#define OPENTITAN_DT_PWRMGR_H_
9
10
/**
11
* @file
12
* @brief Device Tables (DT) for IP pwrmgr and top earlgrey.
13
*
14
* This file contains the type definitions and global functions of the pwrmgr.
15
*/
16
17
#include "
dt_api.h
"
18
#include <stdint.h>
19
20
21
22
23
24
/**
25
* List of instances.
26
*/
27
typedef
enum
dt_pwrmgr
{
28
kDtPwrmgrAon
= 0,
/**< pwrmgr_aon */
29
kDtPwrmgrFirst = 0,
/**< \internal First instance */
30
kDtPwrmgrCount = 1,
/**< \internal Number of instances */
31
}
dt_pwrmgr_t
;
32
33
/**
34
* List of register blocks.
35
*
36
* Register blocks are guaranteed to start at 0 and to be consecutively numbered.
37
*/
38
typedef
enum
dt_pwrmgr_reg_block
{
39
kDtPwrmgrRegBlockCore = 0,
/**< */
40
kDtPwrmgrRegBlockCount = 1,
/**< \internal Number of register blocks */
41
}
dt_pwrmgr_reg_block_t
;
42
43
/** Primary register block (associated with the "primary" set of registers that control the IP). */
44
static
const
dt_pwrmgr_reg_block_t
kDtPwrmgrRegBlockPrimary = kDtPwrmgrRegBlockCore;
45
46
/**
47
* List of IRQs.
48
*
49
* IRQs are guaranteed to be numbered consecutively from 0.
50
*/
51
typedef
enum
dt_pwrmgr_irq
{
52
kDtPwrmgrIrqWakeup
= 0,
/**< Wake from low power state. See wake info for more details */
53
kDtPwrmgrIrqCount = 1,
/**< \internal Number of IRQs */
54
}
dt_pwrmgr_irq_t
;
55
56
/**
57
* List of Alerts.
58
*
59
* Alerts are guaranteed to be numbered consecutively from 0.
60
*/
61
typedef
enum
dt_pwrmgr_alert
{
62
kDtPwrmgrAlertFatalFault
= 0,
/**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
63
kDtPwrmgrAlertCount = 1,
/**< \internal Number of Alerts */
64
}
dt_pwrmgr_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_pwrmgr_clock
{
72
kDtPwrmgrClockClk
= 0,
/**< Clock port clk_i */
73
kDtPwrmgrClockSlow
= 1,
/**< Clock port clk_slow_i */
74
kDtPwrmgrClockLc
= 2,
/**< Clock port clk_lc_i */
75
kDtPwrmgrClockEsc
= 3,
/**< Clock port clk_esc_i */
76
kDtPwrmgrClockCount = 4,
/**< \internal Number of clock ports */
77
}
dt_pwrmgr_clock_t
;
78
79
/**
80
* List of reset ports.
81
*
82
* Reset ports are guaranteed to be numbered consecutively from 0.
83
*/
84
typedef
enum
dt_pwrmgr_reset
{
85
kDtPwrmgrResetRst
= 0,
/**< Reset port rst_ni */
86
kDtPwrmgrResetMain
= 1,
/**< Reset port rst_main_ni */
87
kDtPwrmgrResetSlow
= 2,
/**< Reset port rst_slow_ni */
88
kDtPwrmgrResetLc
= 3,
/**< Reset port rst_lc_ni */
89
kDtPwrmgrResetEsc
= 4,
/**< Reset port rst_esc_ni */
90
kDtPwrmgrResetCount = 5,
/**< \internal Number of reset ports */
91
}
dt_pwrmgr_reset_t
;
92
93
/**
94
* List of supported hardware features.
95
*/
96
#define OPENTITAN_PWRMGR_HAS_STARTUP_LIFE_CYCLE_INITIALIZATION 1
97
#define OPENTITAN_PWRMGR_HAS_CLOCK_CONTROL_IO_IN_LOW_POWER 1
98
#define OPENTITAN_PWRMGR_HAS_CLOCK_CONTROL_MAIN_IN_LOW_POWER 1
99
#define OPENTITAN_PWRMGR_HAS_CLOCK_CONTROL_USB_IN_LOW_POWER 1
100
#define OPENTITAN_PWRMGR_HAS_CLOCK_CONTROL_USB_WHEN_ACTIVE 1
101
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_ENTRY 1
102
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_DISABLE_POWER 1
103
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_SYSRST_CTRL_AON_WKUP_REQ_WAKEUP_ENABLE 1
104
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_SYSRST_CTRL_AON_WKUP_REQ_WAKEUP_REQUEST 1
105
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_ADC_CTRL_AON_WKUP_REQ_WAKEUP_ENABLE 1
106
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_ADC_CTRL_AON_WKUP_REQ_WAKEUP_REQUEST 1
107
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_PINMUX_AON_PIN_WKUP_REQ_WAKEUP_ENABLE 1
108
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_PINMUX_AON_PIN_WKUP_REQ_WAKEUP_REQUEST 1
109
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_PINMUX_AON_USB_WKUP_REQ_WAKEUP_ENABLE 1
110
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_PINMUX_AON_USB_WKUP_REQ_WAKEUP_REQUEST 1
111
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_AON_TIMER_AON_WKUP_REQ_WAKEUP_ENABLE 1
112
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_AON_TIMER_AON_WKUP_REQ_WAKEUP_REQUEST 1
113
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_SENSOR_CTRL_AON_WKUP_REQ_WAKEUP_ENABLE 1
114
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_SENSOR_CTRL_AON_WKUP_REQ_WAKEUP_REQUEST 1
115
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_WAKE_INFO 1
116
#define OPENTITAN_PWRMGR_HAS_RESET_CHECK_ROM_INTEGRITY 1
117
#define OPENTITAN_PWRMGR_HAS_RESET_SYSRST_CTRL_AON_RST_REQ_ENABLE 1
118
#define OPENTITAN_PWRMGR_HAS_RESET_SYSRST_CTRL_AON_RST_REQ_REQUEST 1
119
#define OPENTITAN_PWRMGR_HAS_RESET_AON_TIMER_AON_AON_TIMER_RST_REQ_ENABLE 1
120
#define OPENTITAN_PWRMGR_HAS_RESET_AON_TIMER_AON_AON_TIMER_RST_REQ_REQUEST 1
121
#define OPENTITAN_PWRMGR_HAS_RESET_ESCALATION_REQUEST 1
122
#define OPENTITAN_PWRMGR_HAS_RESET_ESCALATION_TIMEOUT 1
123
#define OPENTITAN_PWRMGR_HAS_RESET_SW_RST_REQUEST 1
124
#define OPENTITAN_PWRMGR_HAS_RESET_MAIN_POWER_GLITCH_RESET 1
125
#define OPENTITAN_PWRMGR_HAS_RESET_NDM_RESET_REQUEST 1
126
#define OPENTITAN_PWRMGR_HAS_RESET_POR_REQUEST 1
127
128
129
130
/**
131
* Get the pwrmgr instance from an instance ID
132
*
133
* For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
134
*
135
* @param inst_id Instance ID.
136
* @return A pwrmgr instance.
137
*
138
* **Note:** This function only makes sense if the instance ID has device type pwrmgr,
139
* otherwise the returned value is unspecified.
140
*/
141
dt_pwrmgr_t
dt_pwrmgr_from_instance_id
(
dt_instance_id_t
inst_id);
142
143
/**
144
* Get the instance ID of an instance.
145
*
146
* @param dt Instance of pwrmgr.
147
* @return The instance ID of that instance.
148
*/
149
dt_instance_id_t
dt_pwrmgr_instance_id
(
dt_pwrmgr_t
dt);
150
151
/**
152
* Get the register base address of an instance.
153
*
154
* @param dt Instance of pwrmgr.
155
* @param reg_block The register block requested.
156
* @return The register base address of the requested block.
157
*/
158
uint32_t
dt_pwrmgr_reg_block
(
159
dt_pwrmgr_t
dt,
160
dt_pwrmgr_reg_block_t
reg_block);
161
162
/**
163
* Get the primary register base address of an instance.
164
*
165
* This is just a convenience function, equivalent to
166
* `dt_pwrmgr_reg_block(dt, kDtPwrmgrRegBlockCore)`
167
*
168
* @param dt Instance of pwrmgr.
169
* @return The register base address of the primary register block.
170
*/
171
static
inline
uint32_t dt_pwrmgr_primary_reg_block(
172
dt_pwrmgr_t
dt) {
173
return
dt_pwrmgr_reg_block
(dt, kDtPwrmgrRegBlockCore);
174
}
175
176
/**
177
* Get the PLIC ID of a pwrmgr IRQ for a given instance.
178
*
179
* If the instance is not connected to the PLIC, this function
180
* will return `kDtPlicIrqIdNone`.
181
*
182
* @param dt Instance of pwrmgr.
183
* @param irq A pwrmgr IRQ.
184
* @return The PLIC ID of the IRQ of this instance.
185
*/
186
dt_plic_irq_id_t
dt_pwrmgr_irq_to_plic_id
(
187
dt_pwrmgr_t
dt,
188
dt_pwrmgr_irq_t
irq);
189
190
/**
191
* Convert a global IRQ ID to a local pwrmgr IRQ type.
192
*
193
* @param dt Instance of pwrmgr.
194
* @param irq A PLIC ID that belongs to this instance.
195
* @return The pwrmgr IRQ, or `kDtPwrmgrIrqCount`.
196
*
197
* **Note:** This function assumes that the PLIC ID belongs to the instance
198
* of pwrmgr passed in parameter. In other words, it must be the case that
199
* `dt_pwrmgr_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
200
* will return `kDtPwrmgrIrqCount`.
201
*/
202
dt_pwrmgr_irq_t
dt_pwrmgr_irq_from_plic_id
(
203
dt_pwrmgr_t
dt,
204
dt_plic_irq_id_t
irq);
205
206
207
/**
208
* Get the alert ID of a pwrmgr alert for a given instance.
209
*
210
* **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
211
* instances where the instance is not connected, the return value is unspecified.
212
*
213
* @param dt Instance of pwrmgr.
214
* @param alert A pwrmgr alert.
215
* @return The Alert Handler alert ID of the alert of this instance.
216
*/
217
dt_alert_id_t
dt_pwrmgr_alert_to_alert_id
(
218
dt_pwrmgr_t
dt,
219
dt_pwrmgr_alert_t
alert);
220
221
/**
222
* Convert a global alert ID to a local pwrmgr alert type.
223
*
224
* @param dt Instance of pwrmgr.
225
* @param alert A global alert ID that belongs to this instance.
226
* @return The pwrmgr alert, or `kDtPwrmgrAlertCount`.
227
*
228
* **Note:** This function assumes that the global alert ID belongs to the
229
* instance of pwrmgr passed in parameter. In other words, it must be the case
230
* that `dt_pwrmgr_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
231
* this function will return `kDtPwrmgrAlertCount`.
232
*/
233
dt_pwrmgr_alert_t
dt_pwrmgr_alert_from_alert_id
(
234
dt_pwrmgr_t
dt,
235
dt_alert_id_t
alert);
236
237
238
239
/**
240
* Get the clock signal connected to a clock port of an instance.
241
*
242
* @param dt Instance of pwrmgr.
243
* @param clk Clock port.
244
* @return Clock signal.
245
*/
246
dt_clock_t
dt_pwrmgr_clock
(
247
dt_pwrmgr_t
dt,
248
dt_pwrmgr_clock_t
clk);
249
250
/**
251
* Get the reset signal connected to a reset port of an instance.
252
*
253
* @param dt Instance of pwrmgr.
254
* @param rst Reset port.
255
* @return Reset signal.
256
*/
257
dt_reset_t
dt_pwrmgr_reset
(
258
dt_pwrmgr_t
dt,
259
dt_pwrmgr_reset_t
rst);
260
261
262
263
/**
264
* Description of a wakeup source.
265
*
266
* A wakeup source is always identified by the instance ID of the module where it comes from.
267
* Some instances can have several wakeup signals, e.g. the pinmux has two (`pin` and `usb`).
268
* For such IPs, it is not sufficient to know the instance, we also need to know which
269
* signal triggered the wakeup. The `wakeup` index can be used to distinguish between those.
270
* This value should be casted to the `dt_<ip>_wakeup_t` type of the corresponding IP.
271
* For example, if the `pwrmgr` has two `pinmux` wakeup sources as described above, it's
272
* two wakeup sources will be described as follows:
273
* ```c
274
* {.inst_id = kDtInstanceIdPinmux, .wakeup = kDtPinmuxWakeupPinWkupReq}, // for `pin`
275
* {.inst_id = kDtInstanceIdPinmux, .wakeup = kDtPinmuxWakeupUsbWkupReq}, // for `usb`
276
* ```
277
*/
278
typedef
struct
dt_pwrmgr_wakeup_src
{
279
dt_instance_id_t
inst_id
;
/**< Instance ID of the source of this wakeup. */
280
size_t
wakeup
;
/**< Index of the wakeup signal for that instance. */
281
}
dt_pwrmgr_wakeup_src_t
;
282
283
284
/**
285
* Get the number of wakeup sources.
286
*
287
* @param dt Instance of pwrmgr.
288
* @return Number of wakeup sources.
289
*/
290
size_t
dt_pwrmgr_wakeup_src_count
(
dt_pwrmgr_t
dt);
291
292
/**
293
* Get the description of a wakeup source.
294
*
295
* The wakeup sources are ordered as they appear in the registers.
296
*
297
* @param dt Instance of pwrmgr.
298
* @param idx Index of the wakeup source, between 0 and `dt_pwrmgr_wakeup_src_count(dt)-1`.
299
* @return Description of the source.
300
*/
301
dt_pwrmgr_wakeup_src_t
dt_pwrmgr_wakeup_src
(
dt_pwrmgr_t
dt,
size_t
idx);
302
303
/**
304
* Description of a reset request source.
305
*
306
* A reset request source is always identified by the instance ID of the module where it comes
307
* from. In principle, some instances could have several reset requests. If this is the case,
308
* the `rst_req` can be used to distinguish between those. It should be cast to the
309
* `dt_<ip>_reset_req_t` type of the corresponding IP.
310
*/
311
typedef
struct
dt_pwrmgr_reset_req_src
{
312
dt_instance_id_t
inst_id
;
/**< Instance ID of the source of this reset request. */
313
size_t
reset_req
;
/**< Index of the reset request signal for that instance. */
314
}
dt_pwrmgr_reset_req_src_t
;
315
316
317
/**
318
* Get the number of peripheral reset requests.
319
*
320
* @param dt Instance of pwrmgr.
321
* @return Number of reset requests.
322
*/
323
size_t
dt_pwrmgr_reset_request_src_count
(
dt_pwrmgr_t
dt);
324
325
/**
326
* Get the description of a reset request.
327
*
328
* The reset requests are ordered as they appear in the registers.
329
*
330
* @param dt Instance of pwrmgr.
331
* @param idx Index of the reset request source, between 0 and
332
* `dt_pwrmgr_reset_request_src_count(dt)-1`.
333
* @return Description of the reset.
334
*/
335
dt_pwrmgr_reset_req_src_t
dt_pwrmgr_reset_request_src
(
dt_pwrmgr_t
dt,
size_t
idx);
336
337
338
339
#endif
// OPENTITAN_DT_PWRMGR_H_
(earlgrey)
hw
top
dt
dt_pwrmgr.h
Return to
OpenTitan Documentation