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
#ifdef __cplusplus
11
extern
"C"
{
12
#endif
// __cplusplus
13
14
/**
15
* @file
16
* @brief Device Tables (DT) for IP pwrmgr and top darjeeling.
17
*
18
* This file contains the type definitions and global functions of the pwrmgr.
19
*/
20
21
#include "
dt_api.h
"
22
#include <stdint.h>
23
24
25
26
27
28
/**
29
* List of instances.
30
*/
31
typedef
enum
dt_pwrmgr
{
32
kDtPwrmgrAon
= 0,
/**< pwrmgr_aon */
33
kDtPwrmgrFirst = 0,
/**< \internal First instance */
34
kDtPwrmgrCount = 1,
/**< \internal Number of instances */
35
}
dt_pwrmgr_t
;
36
37
/**
38
* List of register blocks.
39
*
40
* Register blocks are guaranteed to start at 0 and to be consecutively numbered.
41
*/
42
typedef
enum
dt_pwrmgr_reg_block
{
43
kDtPwrmgrRegBlockCore = 0,
/**< */
44
kDtPwrmgrRegBlockCount = 1,
/**< \internal Number of register blocks */
45
}
dt_pwrmgr_reg_block_t
;
46
47
/** Primary register block (associated with the "primary" set of registers that control the IP). */
48
static
const
dt_pwrmgr_reg_block_t
kDtPwrmgrRegBlockPrimary = kDtPwrmgrRegBlockCore;
49
50
/**
51
* List of IRQs.
52
*
53
* IRQs are guaranteed to be numbered consecutively from 0.
54
*/
55
typedef
enum
dt_pwrmgr_irq
{
56
kDtPwrmgrIrqWakeup
= 0,
/**< Wake from low power state. See wake info for more details */
57
kDtPwrmgrIrqCount = 1,
/**< \internal Number of IRQs */
58
}
dt_pwrmgr_irq_t
;
59
60
/**
61
* List of Alerts.
62
*
63
* Alerts are guaranteed to be numbered consecutively from 0.
64
*/
65
typedef
enum
dt_pwrmgr_alert
{
66
kDtPwrmgrAlertFatalFault
= 0,
/**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
67
kDtPwrmgrAlertCount = 1,
/**< \internal Number of Alerts */
68
}
dt_pwrmgr_alert_t
;
69
70
/**
71
* List of clock ports.
72
*
73
* Clock ports are guaranteed to be numbered consecutively from 0.
74
*/
75
typedef
enum
dt_pwrmgr_clock
{
76
kDtPwrmgrClockClk
= 0,
/**< Clock port clk_i */
77
kDtPwrmgrClockSlow
= 1,
/**< Clock port clk_slow_i */
78
kDtPwrmgrClockLc
= 2,
/**< Clock port clk_lc_i */
79
kDtPwrmgrClockEsc
= 3,
/**< Clock port clk_esc_i */
80
kDtPwrmgrClockCount = 4,
/**< \internal Number of clock ports */
81
}
dt_pwrmgr_clock_t
;
82
83
/**
84
* List of reset ports.
85
*
86
* Reset ports are guaranteed to be numbered consecutively from 0.
87
*/
88
typedef
enum
dt_pwrmgr_reset
{
89
kDtPwrmgrResetRst
= 0,
/**< Reset port rst_ni */
90
kDtPwrmgrResetMain
= 1,
/**< Reset port rst_main_ni */
91
kDtPwrmgrResetSlow
= 2,
/**< Reset port rst_slow_ni */
92
kDtPwrmgrResetLc
= 3,
/**< Reset port rst_lc_ni */
93
kDtPwrmgrResetEsc
= 4,
/**< Reset port rst_esc_ni */
94
kDtPwrmgrResetCount = 5,
/**< \internal Number of reset ports */
95
}
dt_pwrmgr_reset_t
;
96
97
/**
98
* List of supported hardware features.
99
*/
100
#define OPENTITAN_PWRMGR_HAS_STARTUP_LIFE_CYCLE_INITIALIZATION 1
101
#define OPENTITAN_PWRMGR_HAS_CLOCK_CONTROL_IO_IN_LOW_POWER 1
102
#define OPENTITAN_PWRMGR_HAS_CLOCK_CONTROL_MAIN_IN_LOW_POWER 1
103
#define OPENTITAN_PWRMGR_HAS_CLOCK_CONTROL_USB_IN_LOW_POWER 1
104
#define OPENTITAN_PWRMGR_HAS_CLOCK_CONTROL_USB_WHEN_ACTIVE 1
105
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_ENTRY 1
106
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_DISABLE_POWER 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_AON_TIMER_AON_WKUP_REQ_WAKEUP_ENABLE 1
110
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_AON_TIMER_AON_WKUP_REQ_WAKEUP_REQUEST 1
111
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_SOC_PROXY_WKUP_INTERNAL_REQ_WAKEUP_ENABLE 1
112
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_SOC_PROXY_WKUP_INTERNAL_REQ_WAKEUP_REQUEST 1
113
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_SOC_PROXY_WKUP_EXTERNAL_REQ_WAKEUP_ENABLE 1
114
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_SOC_PROXY_WKUP_EXTERNAL_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_AON_TIMER_AON_AON_TIMER_RST_REQ_ENABLE 1
118
#define OPENTITAN_PWRMGR_HAS_RESET_AON_TIMER_AON_AON_TIMER_RST_REQ_REQUEST 1
119
#define OPENTITAN_PWRMGR_HAS_RESET_SOC_PROXY_RST_REQ_EXTERNAL_ENABLE 1
120
#define OPENTITAN_PWRMGR_HAS_RESET_SOC_PROXY_RST_REQ_EXTERNAL_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
#ifdef __cplusplus
340
}
// extern "C"
341
#endif
// __cplusplus
342
343
#endif
// OPENTITAN_DT_PWRMGR_H_
(darjeeling)
hw
top
dt
dt_pwrmgr.h
Return to
OpenTitan Documentation