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 englishbreakfast.
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 clock ports.
62
*
63
* Clock ports are guaranteed to be numbered consecutively from 0.
64
*/
65
typedef
enum
dt_pwrmgr_clock
{
66
kDtPwrmgrClockClk
= 0,
/**< Clock port clk_i */
67
kDtPwrmgrClockSlow
= 1,
/**< Clock port clk_slow_i */
68
kDtPwrmgrClockLc
= 2,
/**< Clock port clk_lc_i */
69
kDtPwrmgrClockEsc
= 3,
/**< Clock port clk_esc_i */
70
kDtPwrmgrClockCount = 4,
/**< \internal Number of clock ports */
71
}
dt_pwrmgr_clock_t
;
72
73
/**
74
* List of reset ports.
75
*
76
* Reset ports are guaranteed to be numbered consecutively from 0.
77
*/
78
typedef
enum
dt_pwrmgr_reset
{
79
kDtPwrmgrResetRst
= 0,
/**< Reset port rst_ni */
80
kDtPwrmgrResetMain
= 1,
/**< Reset port rst_main_ni */
81
kDtPwrmgrResetSlow
= 2,
/**< Reset port rst_slow_ni */
82
kDtPwrmgrResetLc
= 3,
/**< Reset port rst_lc_ni */
83
kDtPwrmgrResetEsc
= 4,
/**< Reset port rst_esc_ni */
84
kDtPwrmgrResetCount = 5,
/**< \internal Number of reset ports */
85
}
dt_pwrmgr_reset_t
;
86
87
/**
88
* List of supported hardware features.
89
*/
90
#define OPENTITAN_PWRMGR_HAS_STARTUP_LIFE_CYCLE_INITIALIZATION 1
91
#define OPENTITAN_PWRMGR_HAS_CLOCK_CONTROL_IO_IN_LOW_POWER 1
92
#define OPENTITAN_PWRMGR_HAS_CLOCK_CONTROL_MAIN_IN_LOW_POWER 1
93
#define OPENTITAN_PWRMGR_HAS_CLOCK_CONTROL_USB_IN_LOW_POWER 1
94
#define OPENTITAN_PWRMGR_HAS_CLOCK_CONTROL_USB_WHEN_ACTIVE 1
95
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_ENTRY 1
96
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_DISABLE_POWER 1
97
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_PINMUX_AON_PIN_WKUP_REQ_WAKEUP_ENABLE 1
98
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_PINMUX_AON_PIN_WKUP_REQ_WAKEUP_REQUEST 1
99
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_PINMUX_AON_USB_WKUP_REQ_WAKEUP_ENABLE 1
100
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_PINMUX_AON_USB_WKUP_REQ_WAKEUP_REQUEST 1
101
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_AON_TIMER_AON_WKUP_REQ_WAKEUP_ENABLE 1
102
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_AON_TIMER_AON_WKUP_REQ_WAKEUP_REQUEST 1
103
#define OPENTITAN_PWRMGR_HAS_LOW_POWER_WAKE_INFO 1
104
#define OPENTITAN_PWRMGR_HAS_RESET_CHECK_ROM_INTEGRITY 1
105
#define OPENTITAN_PWRMGR_HAS_RESET_AON_TIMER_AON_AON_TIMER_RST_REQ_ENABLE 1
106
#define OPENTITAN_PWRMGR_HAS_RESET_AON_TIMER_AON_AON_TIMER_RST_REQ_REQUEST 1
107
#define OPENTITAN_PWRMGR_HAS_RESET_ESCALATION_REQUEST 1
108
#define OPENTITAN_PWRMGR_HAS_RESET_ESCALATION_TIMEOUT 1
109
#define OPENTITAN_PWRMGR_HAS_RESET_SW_RST_REQUEST 1
110
#define OPENTITAN_PWRMGR_HAS_RESET_MAIN_POWER_GLITCH_RESET 1
111
#define OPENTITAN_PWRMGR_HAS_RESET_NDM_RESET_REQUEST 1
112
#define OPENTITAN_PWRMGR_HAS_RESET_POR_REQUEST 1
113
114
115
116
/**
117
* Get the pwrmgr instance from an instance ID
118
*
119
* For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
120
*
121
* @param inst_id Instance ID.
122
* @return A pwrmgr instance.
123
*
124
* **Note:** This function only makes sense if the instance ID has device type pwrmgr,
125
* otherwise the returned value is unspecified.
126
*/
127
dt_pwrmgr_t
dt_pwrmgr_from_instance_id
(
dt_instance_id_t
inst_id);
128
129
/**
130
* Get the instance ID of an instance.
131
*
132
* @param dt Instance of pwrmgr.
133
* @return The instance ID of that instance.
134
*/
135
dt_instance_id_t
dt_pwrmgr_instance_id
(
dt_pwrmgr_t
dt);
136
137
/**
138
* Get the register base address of an instance.
139
*
140
* @param dt Instance of pwrmgr.
141
* @param reg_block The register block requested.
142
* @return The register base address of the requested block.
143
*/
144
uint32_t
dt_pwrmgr_reg_block
(
145
dt_pwrmgr_t
dt,
146
dt_pwrmgr_reg_block_t
reg_block);
147
148
/**
149
* Get the primary register base address of an instance.
150
*
151
* This is just a convenience function, equivalent to
152
* `dt_pwrmgr_reg_block(dt, kDtPwrmgrRegBlockCore)`
153
*
154
* @param dt Instance of pwrmgr.
155
* @return The register base address of the primary register block.
156
*/
157
static
inline
uint32_t dt_pwrmgr_primary_reg_block(
158
dt_pwrmgr_t
dt) {
159
return
dt_pwrmgr_reg_block
(dt, kDtPwrmgrRegBlockCore);
160
}
161
162
/**
163
* Get the PLIC ID of a pwrmgr IRQ for a given instance.
164
*
165
* If the instance is not connected to the PLIC, this function
166
* will return `kDtPlicIrqIdNone`.
167
*
168
* @param dt Instance of pwrmgr.
169
* @param irq A pwrmgr IRQ.
170
* @return The PLIC ID of the IRQ of this instance.
171
*/
172
dt_plic_irq_id_t
dt_pwrmgr_irq_to_plic_id
(
173
dt_pwrmgr_t
dt,
174
dt_pwrmgr_irq_t
irq);
175
176
/**
177
* Convert a global IRQ ID to a local pwrmgr IRQ type.
178
*
179
* @param dt Instance of pwrmgr.
180
* @param irq A PLIC ID that belongs to this instance.
181
* @return The pwrmgr IRQ, or `kDtPwrmgrIrqCount`.
182
*
183
* **Note:** This function assumes that the PLIC ID belongs to the instance
184
* of pwrmgr passed in parameter. In other words, it must be the case that
185
* `dt_pwrmgr_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
186
* will return `kDtPwrmgrIrqCount`.
187
*/
188
dt_pwrmgr_irq_t
dt_pwrmgr_irq_from_plic_id
(
189
dt_pwrmgr_t
dt,
190
dt_plic_irq_id_t
irq);
191
192
193
194
195
/**
196
* Get the clock signal connected to a clock port of an instance.
197
*
198
* @param dt Instance of pwrmgr.
199
* @param clk Clock port.
200
* @return Clock signal.
201
*/
202
dt_clock_t
dt_pwrmgr_clock
(
203
dt_pwrmgr_t
dt,
204
dt_pwrmgr_clock_t
clk);
205
206
/**
207
* Get the reset signal connected to a reset port of an instance.
208
*
209
* @param dt Instance of pwrmgr.
210
* @param rst Reset port.
211
* @return Reset signal.
212
*/
213
dt_reset_t
dt_pwrmgr_reset
(
214
dt_pwrmgr_t
dt,
215
dt_pwrmgr_reset_t
rst);
216
217
218
219
/**
220
* Description of a wakeup source.
221
*
222
* A wakeup source is always identified by the instance ID of the module where it comes from.
223
* Some instances can have several wakeup signals, e.g. the pinmux has two (`pin` and `usb`).
224
* For such IPs, it is not sufficient to know the instance, we also need to know which
225
* signal triggered the wakeup. The `wakeup` index can be used to distinguish between those.
226
* This value should be casted to the `dt_<ip>_wakeup_t` type of the corresponding IP.
227
* For example, if the `pwrmgr` has two `pinmux` wakeup sources as described above, it's
228
* two wakeup sources will be described as follows:
229
* ```c
230
* {.inst_id = kDtInstanceIdPinmux, .wakeup = kDtPinmuxWakeupPinWkupReq}, // for `pin`
231
* {.inst_id = kDtInstanceIdPinmux, .wakeup = kDtPinmuxWakeupUsbWkupReq}, // for `usb`
232
* ```
233
*/
234
typedef
struct
dt_pwrmgr_wakeup_src
{
235
dt_instance_id_t
inst_id
;
/**< Instance ID of the source of this wakeup. */
236
size_t
wakeup
;
/**< Index of the wakeup signal for that instance. */
237
}
dt_pwrmgr_wakeup_src_t
;
238
239
240
/**
241
* Get the number of wakeup sources.
242
*
243
* @param dt Instance of pwrmgr.
244
* @return Number of wakeup sources.
245
*/
246
size_t
dt_pwrmgr_wakeup_src_count
(
dt_pwrmgr_t
dt);
247
248
/**
249
* Get the description of a wakeup source.
250
*
251
* The wakeup sources are ordered as they appear in the registers.
252
*
253
* @param dt Instance of pwrmgr.
254
* @param idx Index of the wakeup source, between 0 and `dt_pwrmgr_wakeup_src_count(dt)-1`.
255
* @return Description of the source.
256
*/
257
dt_pwrmgr_wakeup_src_t
dt_pwrmgr_wakeup_src
(
dt_pwrmgr_t
dt,
size_t
idx);
258
259
/**
260
* Description of a reset request source.
261
*
262
* A reset request source is always identified by the instance ID of the module where it comes
263
* from. In principle, some instances could have several reset requests. If this is the case,
264
* the `rst_req` can be used to distinguish between those. It should be cast to the
265
* `dt_<ip>_reset_req_t` type of the corresponding IP.
266
*/
267
typedef
struct
dt_pwrmgr_reset_req_src
{
268
dt_instance_id_t
inst_id
;
/**< Instance ID of the source of this reset request. */
269
size_t
reset_req
;
/**< Index of the reset request signal for that instance. */
270
}
dt_pwrmgr_reset_req_src_t
;
271
272
273
/**
274
* Get the number of peripheral reset requests.
275
*
276
* @param dt Instance of pwrmgr.
277
* @return Number of reset requests.
278
*/
279
size_t
dt_pwrmgr_reset_request_src_count
(
dt_pwrmgr_t
dt);
280
281
/**
282
* Get the description of a reset request.
283
*
284
* The reset requests are ordered as they appear in the registers.
285
*
286
* @param dt Instance of pwrmgr.
287
* @param idx Index of the reset request source, between 0 and
288
* `dt_pwrmgr_reset_request_src_count(dt)-1`.
289
* @return Description of the reset.
290
*/
291
dt_pwrmgr_reset_req_src_t
dt_pwrmgr_reset_request_src
(
dt_pwrmgr_t
dt,
size_t
idx);
292
293
294
295
#ifdef __cplusplus
296
}
// extern "C"
297
#endif
// __cplusplus
298
299
#endif
// OPENTITAN_DT_PWRMGR_H_
(englishbreakfast)
hw
top
dt
dt_pwrmgr.h
Return to
OpenTitan Documentation