1 /*
2 * Copyright (c) 2025-2026 Texas Instruments Incorporated - https://www.ti.com
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6
7 /*
8 * Device Power Management API
9 *
10 * This header provides device power management operations including device
11 * enable/disable, reset isolation, retention control, context loss tracking,
12 * and SoC-specific device initialization and state management functions.
13 */
14
15 #ifndef TI_DEVICE_PM_H
16 #define TI_DEVICE_PM_H
17
18 #include <stdbool.h>
19
20 /**
21 * ti_soc_device_get_state() - Get the current device state (SoC specific impl.)
22 * @dev: The device to query.
23 *
24 * Return: Non-zero if the device is enabled, zero if disabled.
25 */
26 uint32_t ti_soc_device_get_state(struct ti_device *dev);
27
28 /**
29 * ti_soc_device_set_reset_iso() - Set the reset isolation flag for a device (SoC specific impl.)
30 * @dev: The device to modify.
31 * @enable: True to enable reset isolation, false to disable.
32 */
33 void ti_soc_device_set_reset_iso(struct ti_device *dev, bool enable);
34
35 /**
36 * ti_soc_device_get_context_loss_count() - Get context loss count
37 * @device: The device to query.
38 *
39 * Return: The current loss count of the device.
40 */
41 uint32_t ti_soc_device_get_context_loss_count(struct ti_device *dev);
42
43 /**
44 * ti_soc_device_enable() - Enable a device (SoC specific impl.)
45 * @device: The device to modify.
46 */
47 void ti_soc_device_enable(struct ti_device *dev);
48
49 /**
50 * ti_soc_device_disable() - Disable a device (SoC specific impl.)
51 * @device: The device to modify.
52 * @domain_reset: True if the device is being disabled due to a domain reset.
53 */
54 void ti_soc_device_disable(struct ti_device *dev, bool domain_reset);
55
56 /**
57 * ti_soc_device_clear_flags() - Clear a device initialization flags
58 * @dev: The device to modify.
59 */
60 void ti_soc_device_clear_flags(struct ti_device *dev);
61
62 /**
63 * ti_soc_device_ret_enable() - Enable retention on a device (SoC specific impl.)
64 * @device: The device to modify.
65 */
66 void ti_soc_device_ret_enable(struct ti_device *dev);
67
68 /**
69 * ti_soc_device_ret_disable() - Disable retention on a device (SoC specific impl.)
70 * @device: The device to modify.
71 */
72 void ti_soc_device_ret_disable(struct ti_device *dev);
73
74 /**
75 * ti_soc_device_init() - Perform SoC level initialization of a device.
76 *
77 * The device to init.
78 *
79 * Return: 0 on success, -EAGAIN if device is not yet ready to be initialized.
80 */
81 int32_t ti_soc_device_init(struct ti_device *dev);
82
83 /**
84 * ti_soc_device_init_complete() - Notify SoC device impl. that device init is complete.
85 *
86 * This allows the SoC implementation to drop any extra references it's been
87 * holding during init.
88 */
89 void ti_soc_device_init_complete(void);
90
91 /**
92 * ti_device_disable() - Disables a device.
93 * @device: The device to modify.
94 * @domain_reset: True if the device is being disabled due to a domain reset.
95 *
96 * Performs the steps necessary to disable a device.
97 */
98 void ti_device_disable(struct ti_device *dev, bool domain_reset);
99
100 /**
101 * ti_device_set_state() - Enable/disable a device.
102 * @device: The device to modify.
103 * @host_idx: The index of the host making the request.
104 * @enable: True to enable the device, false to allow the PMMC to power down the device.
105 *
106 * This indicates the desired state of a device by the HLOS. If a device is
107 * enabled, the PMMC will make sure the device and its dependencies are
108 * ready. If the device is not enabled, the PMMC will opportunistically
109 * utilize power management modes of that device and its dependencies.
110 *
111 * Enabling a device (if disabled) increments the device's reference count.
112 * Disabling a device (if enabled) decrements the devices' reference count.
113 */
114 void ti_device_set_state(struct ti_device *dev, uint8_t host_idx, bool enable);
115
116 /**
117 * ti_device_set_retention() - Enable/disable retention on a device.
118 * @device: The device to modify.
119 * @retention: True to enable retention, false to disable it.
120 *
121 * When a device is in retention, but disabled, the PMMC can still perform
122 * power management tasks, but the device must keep its context. Enabling
123 * retention is a way save power, but still be able to bring the device back
124 * to full functionality quickly.
125 */
126 void ti_device_set_retention(struct ti_device *dev, bool retention);
127
128 /**
129 * ti_device_clear_flags() - Clear a device initialization flags
130 * @dev: The device to modify.
131 */
132 void ti_device_clear_flags(struct ti_device *dev);
133
134 /**
135 * ti_device_set_reset_iso() - Set the reset isolation flag for a device.
136 * @device: The device to modify.
137 * @enable: True to enable reset isolation, false to disable.
138 *
139 * The effect of reset isolation is device and SoC specific, but it generally
140 * prevents the device from undergoing reset with the rest of the SoC.
141 */
ti_device_set_reset_iso(struct ti_device * dev,bool enable)142 static inline void ti_device_set_reset_iso(struct ti_device *dev, bool enable)
143 {
144 ti_soc_device_set_reset_iso(dev, enable);
145 }
146
147 /* Return values for ti_device_get_state() and ti_soc_device_get_state() */
148 #define TI_DEVICE_STATE_DISABLED 0U /* Module is off (SwRstDisable) */
149 #define TI_DEVICE_STATE_ENABLED 1U /* Module is enabled or in retention */
150 #define TI_DEVICE_STATE_TRANSITIONING 2U /* Module is transitioning or domains mixed */
151
152 /**
153 * ti_device_get_state() - Get the current device state.
154 * @device: The device to query.
155 *
156 * Returns the current device state as configured by ti_device_set_state.
157 *
158 * Return: TI_DEVICE_STATE_DISABLED, TI_DEVICE_STATE_ENABLED, or
159 * TI_DEVICE_STATE_TRANSITIONING.
160 */
ti_device_get_state(struct ti_device * dev)161 static inline uint32_t ti_device_get_state(struct ti_device *dev)
162 {
163 return ti_soc_device_get_state(dev);
164 }
165
166 #endif /* TI_DEVICE_PM_H */
167