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 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