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 * PSC Driver API
9 *
10 * This header provides the Power and Sleep Controller (PSC) driver interface
11 * including data structures for power domains and LPSC modules, state
12 * management functions, reset control, and module dependency handling.
13 */
14
15 #ifndef TI_PSC_H
16 #define TI_PSC_H
17
18 #include <ti_device.h>
19 #include <ti_pm_types.h>
20
21 /*
22 * Indicates that no device is mapped to this PSC module
23 *
24 * Used in device-to-PSC mapping tables to indicate that a PSC module
25 * has no associated device.
26 */
27 #define TI_PSC_DEV_NONE 7U
28
29 /*
30 * Indicates that multiple devices are mapped to this PSC module
31 *
32 * Used in device-to-PSC mapping tables to indicate that a PSC module
33 * controls multiple devices. The actual device list is stored elsewhere.
34 */
35 #define TI_PSC_DEV_MULTIPLE 6U
36
37 /*
38 * Flag indicating that the power domain exists and is valid
39 *
40 * Set in ti_psc_pd_data.flags to indicate that this power domain is
41 * present and the information in the record is valid.
42 */
43 #define TI_PSC_PD_EXISTS BIT(0)
44
45 /*
46 * Flag indicating that the power domain is always on
47 *
48 * Set in ti_psc_pd_data.flags to indicate that this power domain cannot
49 * be powered down and is always active.
50 */
51 #define TI_PSC_PD_ALWAYSON BIT(1)
52
53 /*
54 * Flag indicating that the power domain has dependencies
55 *
56 * Set in ti_psc_pd_data.flags to indicate that this power domain depends
57 * on another power domain being active. The dependency is specified in
58 * the depends field.
59 */
60 #define TI_PSC_PD_DEPENDS BIT(2)
61
62 /*
63 * PSC power domain constant data
64 *
65 * This structure contains the constant configuration data for a PSC power
66 * domain, including its characteristics, dependencies, and clock requirements.
67 * This data is typically stored in ROM or const data sections.
68 */
69 struct ti_psc_pd_data {
70 /*
71 * Power domain configuration flags
72 *
73 * Combination of TI_PSC_PD_EXISTS, TI_PSC_PD_ALWAYSON, and TI_PSC_PD_DEPENDS
74 * flags indicating the power domain's characteristics.
75 */
76 uint8_t flags;
77
78 /*
79 * Index of the power domain this one depends on
80 *
81 * If TI_PSC_PD_DEPENDS is set in flags, this field contains the ti_pd_idx_t
82 * of the power domain that must be active before this one can be enabled.
83 */
84 uint8_t depends;
85
86 /*
87 * Clock dependencies for power domain transitions
88 *
89 * Some domains need a clock running in order to transition. This
90 * is the id of that clock. If no such clock is needed, set to
91 * an invalid clock id (0). We currently support only 3 clocks.
92 */
93 ti_clk_idx_t clock_dep[3];
94 };
95
96 /*
97 * PSC power domain dynamic data
98 *
99 * This structure contains the runtime state information for a PSC power
100 * domain, tracking its usage and power-up enablement status. This data
101 * changes during system operation.
102 */
103 struct ti_psc_pd {
104 /*
105 * Reference count tracking power domain usage
106 *
107 * Number of modules or users currently requiring this power domain
108 * to be active. The domain can only be powered down when this
109 * count reaches zero.
110 */
111 uint8_t use_count;
112
113 /*
114 * Power-up enable status
115 *
116 * True if this power domain is enabled for power-up operations,
117 * false otherwise. This is used to track the requested state of
118 * the power domain.
119 */
120 bool pwr_up_enabled;
121 };
122
123 /* Module is present, information in record is valid */
124 #define TI_LPSC_MODULE_EXISTS BIT(0)
125
126 /* Module is not capable of clock gating */
127 #define TI_LPSC_NO_CLOCK_GATING BIT(1)
128
129 /* Module depends on another module listed in depends field */
130 #define TI_LPSC_DEPENDS BIT(2)
131
132 /* Module implements configurable reset isolation */
133 #define TI_LPSC_HAS_RESET_ISO BIT(3)
134
135 /* Module implements a local reset */
136 #define TI_LPSC_HAS_LOCAL_RESET BIT(4)
137
138 /* States that enable module reset are disallowed */
139 #define TI_LPSC_NO_MODULE_RESET BIT(5)
140
141 /*
142 * Set if the module data points to a dev_list, false it a dev_array is
143 * embedded.
144 */
145 #define TI_LPSC_DEVICES_LIST BIT(6)
146
147 /*
148 * LPSC module constant configuration data
149 *
150 * This structure contains the constant configuration data for a Local Power
151 * Sleep Controller (LPSC) module, including device associations, dependencies,
152 * clock requirements, and module characteristics. This data is typically stored
153 * in ROM or const data sections and defines the static properties of each
154 * LPSC module in the system.
155 */
156 struct ti_lpsc_module_data {
157 /*
158 * Device-to-LPSC module association
159 *
160 * Which devices are members of which PSC module is duplicated in the
161 * list of devices. However, it is duplicated here so that the entire
162 * list of devices does not need to be looped through to find that
163 * information. It could be generated dynamically but is stored in this
164 * way to save memory.
165 */
166 union {
167 /*
168 * Embedded device array for small device lists
169 *
170 * If there are 4 or less devices, they can be stored here,
171 * terminated by the 4th device or TI_DEV_ID_NONE. This avoids
172 * the need for a separate pointer and saves memory.
173 */
174 ti_dev_idx_t dev_array[sizeof(void *) / sizeof(ti_dev_idx_t)];
175
176 /*
177 * Pointer to external device list for large device lists
178 *
179 * More than 4 devices must be stored in a separate list,
180 * terminated by TI_DEV_ID_NONE. The TI_LPSC_DEVICES_LIST flag must be
181 * set when this field is used instead of dev_array.
182 */
183 const ti_dev_idx_t *dev_list;
184 } lpsc_dev;
185
186 /*
187 * Clock dependencies for module transitions
188 *
189 * Some modules need a clock running in order to transition. This
190 * is the id of that clock. If no such clock is needed, set to
191 * an invalid clock id (0). We currently support only one clock,
192 * this causes the structure size to be 8 bytes in the case of an
193 * 8 bit ti_clk_idx_t and 12 bytes for a 16 bit ti_clk_idx_t.
194 */
195 ti_clk_idx_t clock_dep[1];
196
197 /*
198 * Module configuration flags
199 *
200 * Combination of TI_LPSC_MODULE_EXISTS, TI_LPSC_NO_CLOCK_GATING, TI_LPSC_DEPENDS,
201 * TI_LPSC_HAS_RESET_ISO, TI_LPSC_HAS_LOCAL_RESET, TI_LPSC_NO_MODULE_RESET, and
202 * TI_LPSC_DEVICES_LIST flags indicating the module's characteristics and
203 * capabilities.
204 */
205 uint8_t flags;
206
207 /*
208 * Index of the LPSC module this one depends on
209 *
210 * If TI_LPSC_DEPENDS is set in flags, this field contains the ti_lpsc_idx_t
211 * of the LPSC module that must be active before this one can be enabled.
212 */
213 ti_lpsc_idx_t depends;
214
215 /*
216 * PSC index of the dependency module
217 *
218 * If TI_LPSC_DEPENDS is set in flags, this field contains the ti_psc_idx_t
219 * of the PSC that controls the dependency module. This allows for
220 * cross-PSC dependencies.
221 */
222 uint8_t depends_psc_idx;
223
224 /*
225 * Power domain index this module belongs to
226 *
227 * The ti_pd_idx_t of the power domain that controls this LPSC module.
228 * The module can only be active when its power domain is powered up.
229 */
230 uint8_t powerdomain;
231 };
232
233 /*
234 * LPSC module dynamic runtime data
235 *
236 * This structure contains the runtime state information for an LPSC module,
237 * tracking its usage, power state, reset status, and loss count. This data
238 * changes during system operation as modules are enabled, disabled, and reset.
239 */
240 struct ti_lpsc_module {
241 /*
242 * Module reset loss counter
243 *
244 * Incremented after module reset. This value is used to detect when
245 * a module has undergone a reset and lost its state, allowing drivers
246 * to know when reinitialization is necessary.
247 */
248 uint32_t loss_count;
249
250 /*
251 * Active usage reference count
252 *
253 * Non-zero if module should be active (clocks running). Incremented
254 * by ti_lpsc_module_get() and decremented by ti_lpsc_module_put().
255 * The module transitions to enabled state when this count is non-zero.
256 */
257 uint8_t use_count;
258
259 /*
260 * Retention reference count
261 *
262 * Non-zero if module should be powered-up but may be clock-gated.
263 * Incremented by ti_lpsc_module_ret_get() and decremented by
264 * ti_lpsc_module_ret_put(). This allows the module to retain state
265 * while saving power by stopping clocks.
266 */
267 uint8_t ret_count;
268
269 /*
270 * Current programmed software state
271 *
272 * Current programmed state of the module (MDSTAT_STATE_[...]).
273 * Reflects the state written to hardware and may differ from the
274 * actual hardware state during transitions.
275 */
276 uint8_t sw_state;
277
278 /*
279 * Module reset retention flag
280 *
281 * True if the module is forced on due to a module reset. In this
282 * case sw_state indicates SWRSTDISABLE but this module holds
283 * a reference count to its powerdomain. This prevents the power
284 * domain from being disabled while a reset is active.
285 */
286 bool sw_mrst_ret;
287
288 /*
289 * Power-up enable status
290 *
291 * Non-zero if the module power-up has been enabled. This tracks
292 * whether the module is currently in a power-up enabled state.
293 */
294 uint8_t pwr_up_enabled;
295
296 /*
297 * Power-up retention status
298 *
299 * Non-zero if the module is in power-up retention mode. This allows
300 * the module to maintain state while in a low-power configuration.
301 */
302 uint8_t pwr_up_ret;
303
304 /*
305 * Module reset active flag
306 *
307 * True if host has requested a module reset. This indicates that
308 * a reset operation is currently active or pending for this module.
309 */
310 uint8_t mrst_active;
311 };
312
313 /*
314 * PSC driver operations structure
315 *
316 * Global constant structure containing the PSC driver operations and
317 * callbacks. This structure implements the ti_drv interface for PSC
318 * devices and is used by the device management framework to interact
319 * with PSC hardware.
320 */
321 extern const struct ti_drv psc_drv;
322
323 struct ti_soc_device_data;
324
325 /*
326 * Array of devices controlled by multiple PSC modules
327 *
328 * Global constant array containing pointers to device data structures for
329 * devices that are controlled by multiple PSC modules. This allows the
330 * system to handle complex device-to-PSC mappings where a single device
331 * may require coordination across multiple PSC modules. The array is
332 * terminated by a NULL pointer.
333 */
334 extern const struct ti_soc_device_data *const soc_psc_multiple_domains[];
335
336 /*
337 * Get the index of a power domain within its PSC
338 *
339 * Calculates the power domain index by determining the offset of the
340 * power domain structure within the PSC's power domain array.
341 */
342 ti_pd_idx_t ti_psc_pd_idx(struct ti_device *psc_dev, const struct ti_psc_pd *pd);
343
344 /**
345 * ti_psc_pd_wait() - Wait for a power domain transition to complete
346 * @psc_dev: The PSC device that controls this power domain.
347 * @pd: Pointer to the power domain to wait for.
348 *
349 * Polls the hardware status registers until the power domain transition
350 * completes. This function blocks until the power domain reaches its
351 * target state.
352 */
353 void ti_psc_pd_wait(struct ti_device *psc_dev, struct ti_psc_pd *pd);
354
355 /**
356 * ti_psc_pd_get() - Increment power domain reference count and enable if needed
357 * @psc_dev: The PSC device that controls this power domain.
358 * @pd: Pointer to the power domain to enable.
359 *
360 * Increments the use_count for the power domain and powers it up if this
361 * is the first reference. Also handles dependency power domains recursively.
362 */
363 void ti_psc_pd_get(struct ti_device *psc_dev, struct ti_psc_pd *pd);
364
365 /**
366 * ti_psc_pd_put() - Decrement power domain reference count and disable if unused
367 * @psc_dev: The PSC device that controls this power domain.
368 * @pd: Pointer to the power domain to potentially disable.
369 *
370 * Decrements the use_count for the power domain and powers it down if
371 * the count reaches zero. Also handles dependency power domains recursively.
372 */
373 void ti_psc_pd_put(struct ti_device *psc_dev, struct ti_psc_pd *pd);
374
375 /*
376 * Get the index of an LPSC module within its PSC
377 *
378 * Calculates the LPSC module index by determining the offset of the
379 * module structure within the PSC's module array.
380 */
381 ti_lpsc_idx_t ti_lpsc_module_idx(struct ti_device *psc_dev, const struct ti_lpsc_module *module);
382
383 /**
384 * ti_lpsc_module_get() - Increment LPSC module active reference count and enable
385 * @psc_dev: The PSC device that controls this module.
386 * @module: Pointer to the LPSC module to enable.
387 *
388 * Increments the use_count for the module and enables it (clocks running)
389 * if this is the first reference. Also handles power domain and dependency
390 * modules recursively. The module will be fully powered and clocked.
391 */
392 void ti_lpsc_module_get(struct ti_device *psc_dev, struct ti_lpsc_module *module);
393
394 /**
395 * ti_lpsc_module_put() - Decrement LPSC module active reference count and disable if unused
396 * @psc_dev: The PSC device that controls this module.
397 * @module: Pointer to the LPSC module to potentially disable.
398 *
399 * Decrements the use_count for the module. If the count reaches zero and
400 * ret_count is also zero, the module is disabled. Also handles power domain
401 * and dependency modules recursively.
402 */
403 void ti_lpsc_module_put(struct ti_device *psc_dev, struct ti_lpsc_module *module);
404
405 /**
406 * ti_lpsc_module_ret_get() - Increment LPSC module retention reference count
407 * @psc_dev: The PSC device that controls this module.
408 * @module: Pointer to the LPSC module to put in retention mode.
409 *
410 * Increments the ret_count for the module, ensuring it remains powered
411 * but allowing clock gating. The module retains its state while saving
412 * power. Also handles power domain and dependency modules recursively.
413 */
414 void ti_lpsc_module_ret_get(struct ti_device *psc_dev, struct ti_lpsc_module *module);
415
416 /**
417 * ti_lpsc_module_ret_put() - Decrement LPSC module retention reference count
418 * @psc_dev: The PSC device that controls this module.
419 * @module: Pointer to the LPSC module to release from retention mode.
420 *
421 * Decrements the ret_count for the module. If both ret_count and use_count
422 * reach zero, the module can be fully disabled. Also handles power domain
423 * and dependency modules recursively.
424 */
425 void ti_lpsc_module_ret_put(struct ti_device *psc_dev, struct ti_lpsc_module *module);
426
427 /**
428 * ti_lpsc_module_wait() - Wait for an LPSC module transition to complete
429 * @psc_dev: The PSC device that controls this module.
430 * @module: Pointer to the LPSC module to wait for.
431 *
432 * Polls the hardware status registers until the module transition completes.
433 * This function blocks until the module reaches its target state.
434 */
435 void ti_lpsc_module_wait(struct ti_device *psc_dev, struct ti_lpsc_module *module);
436
437 /**
438 * ti_lpsc_module_set_reset_iso() - Set the reset isolation flag for a PSC module
439 * @psc_dev: The PSC device that controls this module.
440 * @module: The PSC module to modify.
441 * @enable: True to enable reset isolation, false to disable.
442 *
443 * This directly modifies the hardware state.
444 */
445 void ti_lpsc_module_set_reset_iso(struct ti_device *psc_dev,
446 struct ti_lpsc_module *module, bool enable);
447
448 /**
449 * ti_lpsc_module_get_reset_iso() - Get the reset isolation setting from a PSC module.
450 * @psc_dev: The PSC device that controls this module.
451 * @module: The PSC module to query.
452 *
453 * This queries the true hardware state.
454 *
455 * Return: True if reset isolation is enabled for this module, false if otherwise.
456 */
457 bool ti_lpsc_module_get_reset_iso(struct ti_device *psc_dev,
458 struct ti_lpsc_module *module);
459
460 /**
461 * ti_lpsc_module_set_local_reset() - Set/clear the local reset state of a PSC module
462 * @psc_dev: The PSC device that controls this module.
463 * @module: The PSC module to modify.
464 * @enable: True to enable local reset, false to release local reset.
465 *
466 * The function of the local reset is module specific and only available on
467 * certain modules. The most common use is to hold processors (such as the ICSS
468 * or DSP) in reset.
469 */
470 void ti_lpsc_module_set_local_reset(struct ti_device *psc_dev,
471 struct ti_lpsc_module *module, bool enable);
472
473 /**
474 * ti_lpsc_module_set_module_reset() - Set/clear the module reset state of a PSC module
475 * @psc_dev: The PSC device that controls this module.
476 * @module: The PSC module to modify.
477 * @enable: True to enable module reset, false to release module reset.
478 *
479 * The function of the module reset is module specific and only available on
480 * certain modules.
481 */
482 void ti_lpsc_module_set_module_reset(struct ti_device *psc_dev,
483 struct ti_lpsc_module *module, bool enable);
484
485 /**
486 * ti_lpsc_module_get_local_reset() - Get the local reset state from a PSC module.
487 * @psc_dev: The PSC device that controls this module.
488 * @module: The PSC module to query.
489 *
490 * This queries the true hardware state.
491 *
492 * Return: True if local reset is asserted for this module, false if otherwise.
493 */
494 bool ti_lpsc_module_get_local_reset(struct ti_device *psc_dev,
495 struct ti_lpsc_module *module);
496
497 /**
498 * ti_lpsc_module_get_module_reset() - Get the module reset state from a PSC module.
499 * @psc_dev: The PSC device that controls this module.
500 * @module: The PSC module to query.
501 *
502 * This queries the true hardware state.
503 *
504 * Return: True if module reset is asserted for this module, false if otherwise.
505 */
506 bool ti_lpsc_module_get_module_reset(struct ti_device *psc_dev,
507 const struct ti_lpsc_module *module);
508
509 /**
510 * ti_lpsc_module_get_state() - Get the module state from a PSC module.
511 * @psc_dev: The PSC device that controls this module.
512 * @module: The PSC module to query.
513 *
514 * This queries the true hardware state.
515 *
516 * Return: 0 for a disabled module, 1 for an enabled module, 2 for a module in transition.
517 */
518 uint32_t ti_lpsc_module_get_state(struct ti_device *psc_dev,
519 struct ti_lpsc_module *module);
520
521 /*
522 * Look up a PSC device by its index
523 *
524 * Searches the system for the PSC device with the specified index.
525 * This function is used to obtain a reference to a PSC device for
526 * subsequent operations.
527 */
528 struct ti_device *ti_psc_lookup(ti_psc_idx_t id);
529
530 /*
531 * Look up a power domain within a PSC device
532 *
533 * Returns a pointer to the power domain structure for the specified
534 * power domain index within the given PSC device.
535 */
536 struct ti_psc_pd *ti_psc_lookup_pd(struct ti_device *psc_dev, ti_pd_idx_t id);
537
538 /*
539 * Look up an LPSC module within a PSC device
540 *
541 * Returns a pointer to the LPSC module structure for the specified
542 * module index within the given PSC device.
543 */
544 struct ti_lpsc_module *ti_psc_lookup_lpsc(struct ti_device *psc_dev, ti_lpsc_idx_t id);
545
546 /**
547 * ti_psc_drop_pwr_up_ref() - Drop all power-up references across all PSC modules and domains
548 *
549 * Clears the pwr_up_enabled flags for all power domains and modules across
550 * all PSC devices in the system. This is typically called during system
551 * shutdown or when transitioning to a low-power state to release all
552 * power-up references and allow the system to power down completely.
553 */
554 void ti_psc_drop_pwr_up_ref(void);
555
556 /*
557 * PSC device dynamic runtime data
558 *
559 * This structure contains the runtime state information for a PSC device,
560 * including tracking of enabled power domains and modules. This data
561 * changes during system operation as power domains and modules are
562 * enabled and disabled.
563 */
564 struct ti_psc_data {
565 /*
566 * Linked list pointer to next PSC device
567 *
568 * Used to maintain a linked list of all PSC devices in the system.
569 * NULL indicates the end of the list.
570 */
571 struct ti_device *next;
572
573 /*
574 * Bit field of currently enabled power domains
575 *
576 * Each bit represents a power domain within this PSC. A set bit
577 * indicates the power domain is currently enabled. Bit position
578 * corresponds to the power domain index.
579 */
580 uint32_t pds_enabled;
581 };
582
583 /*
584 * PSC driver data structure
585 *
586 * This structure contains all the data needed for a PSC driver instance,
587 * including both constant configuration data and dynamic runtime data for
588 * power domains and LPSC modules. Each PSC device in the system has an
589 * associated ti_psc_drv_data structure that defines its complete state
590 * and configuration.
591 */
592 struct ti_psc_drv_data {
593 /*
594 * Base driver data structure
595 *
596 * Contains common driver data fields required by the device management
597 * framework. This must be the first member to allow casting between
598 * ti_drv_data and ti_psc_drv_data pointers.
599 */
600 struct ti_drv_data drv_data;
601
602 /*
603 * Pointer to dynamic runtime data
604 *
605 * Points to the ti_psc_data structure containing runtime state
606 * information for this PSC device, including enabled power domains
607 * and modules.
608 */
609 struct ti_psc_data *data;
610
611 /*
612 * Pointer to constant power domain data table
613 *
614 * Array of ti_psc_pd_data structures containing the constant
615 * configuration for each power domain in this PSC. The array
616 * has pd_count elements indexed by ti_pd_idx_t.
617 */
618 const struct ti_psc_pd_data *pd_data;
619
620 /*
621 * Pointer to dynamic power domain data table
622 *
623 * Array of ti_psc_pd structures containing the runtime state
624 * for each power domain in this PSC. The array has pd_count
625 * elements indexed by ti_pd_idx_t.
626 */
627 struct ti_psc_pd *powerdomains;
628
629 /*
630 * Pointer to constant LPSC module data table
631 *
632 * Array of ti_lpsc_module_data structures containing the constant
633 * configuration for each LPSC module in this PSC. The array has
634 * module_count elements indexed by ti_lpsc_idx_t.
635 */
636 const struct ti_lpsc_module_data *mod_data;
637
638 /*
639 * Pointer to dynamic LPSC module data table
640 *
641 * Array of ti_lpsc_module structures containing the runtime state
642 * for each LPSC module in this PSC. The array has module_count
643 * elements indexed by ti_lpsc_idx_t.
644 */
645 struct ti_lpsc_module *modules;
646
647 /*
648 * Total number of power domains in this PSC
649 *
650 * Defines the size of the pd_data and powerdomains arrays. Valid
651 * power domain indices range from 0 to (pd_count - 1).
652 */
653 ti_pd_idx_t pd_count;
654
655 /*
656 * Total number of LPSC modules in this PSC
657 *
658 * Defines the size of the mod_data and modules arrays. Valid
659 * LPSC module indices range from 0 to (module_count - 1).
660 */
661 ti_lpsc_idx_t module_count;
662
663 /*
664 * Index of this PSC in the system
665 *
666 * Unique identifier for this PSC device within the system. Used
667 * for PSC lookup operations and cross-PSC dependencies.
668 */
669 ti_psc_idx_t psc_idx;
670
671 /*
672 * Number of supported sleep/power states
673 *
674 * The total number of sleep modes or low-power states that this
675 * PSC supports. Used for power management and system suspend/resume
676 * operations.
677 */
678 uint8_t sleep_mode_count;
679
680 /* PSC register base address */
681 uint32_t base;
682 };
683
ti_to_psc_drv_data(const struct ti_drv_data * data)684 static inline const struct ti_psc_drv_data *ti_to_psc_drv_data(const struct ti_drv_data *data)
685 {
686 return ti_container_of(data, const struct ti_psc_drv_data, drv_data);
687 }
688
689 #endif /* TI_PSC_H */
690