1 /* 2 * Copyright (c) 2016, Freescale Semiconductor, Inc. 3 * Copyright 2017-2020 NXP 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Redistribution and use in source and binary forms, with or without modification, 8 * are permitted provided that the following conditions are met: 9 * 10 * o Redistributions of source code must retain the above copyright notice, this list 11 * of conditions and the following disclaimer. 12 * 13 * o Redistributions in binary form must reproduce the above copyright notice, this 14 * list of conditions and the following disclaimer in the documentation and/or 15 * other materials provided with the distribution. 16 * 17 * o Neither the name of the copyright holder nor the names of its 18 * contributors may be used to endorse or promote products derived from this 19 * software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 22 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 23 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 25 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 28 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /*! 34 * Header file containing the public API for the System Controller (SC) 35 * Power Management (PM) function. This includes functions for power state 36 * control, clock control, reset control, and wake-up event control. 37 * 38 * @addtogroup PM_SVC PM: Power Management Service 39 * 40 * Module for the Power Management (PM) service. 41 * 42 * @includedoc pm/details.dox 43 * 44 * @{ 45 */ 46 47 #ifndef SC_PM_API_H 48 #define SC_PM_API_H 49 50 /* Includes */ 51 52 #include "main/types.h" 53 #include "svc/rm/rm_api.h" 54 55 /* Defines */ 56 57 /*! 58 * @name Defines for type widths 59 */ 60 /*@{*/ 61 #define SC_PM_POWER_MODE_W 2U /*!< Width of sc_pm_power_mode_t */ 62 #define SC_PM_CLOCK_MODE_W 3U /*!< Width of sc_pm_clock_mode_t */ 63 #define SC_PM_RESET_TYPE_W 2U /*!< Width of sc_pm_reset_type_t */ 64 #define SC_PM_RESET_REASON_W 4U /*!< Width of sc_pm_reset_reason_t */ 65 /*@}*/ 66 67 /*! 68 * @name Defines for clock indexes (sc_pm_clk_t) 69 */ 70 /*@{*/ 71 /*@}*/ 72 73 /*! 74 * @name Defines for ALL parameters 75 */ 76 /*@{*/ 77 #define SC_PM_CLK_ALL ((sc_pm_clk_t) UINT8_MAX) /*!< All clocks */ 78 /*@}*/ 79 80 /*! 81 * @name Defines for sc_pm_power_mode_t 82 */ 83 /*@{*/ 84 #define SC_PM_PW_MODE_OFF 0U /*!< Power off */ 85 #define SC_PM_PW_MODE_STBY 1U /*!< Power in standby */ 86 #define SC_PM_PW_MODE_LP 2U /*!< Power in low-power */ 87 #define SC_PM_PW_MODE_ON 3U /*!< Power on */ 88 /*@}*/ 89 90 /*! 91 * @name Defines for sc_pm_clk_t 92 */ 93 /*@{*/ 94 #define SC_PM_CLK_SLV_BUS 0U /*!< Slave bus clock */ 95 #define SC_PM_CLK_MST_BUS 1U /*!< Master bus clock */ 96 #define SC_PM_CLK_PER 2U /*!< Peripheral clock */ 97 #define SC_PM_CLK_PHY 3U /*!< Phy clock */ 98 #define SC_PM_CLK_MISC 4U /*!< Misc clock */ 99 #define SC_PM_CLK_MISC0 0U /*!< Misc 0 clock */ 100 #define SC_PM_CLK_MISC1 1U /*!< Misc 1 clock */ 101 #define SC_PM_CLK_MISC2 2U /*!< Misc 2 clock */ 102 #define SC_PM_CLK_MISC3 3U /*!< Misc 3 clock */ 103 #define SC_PM_CLK_MISC4 4U /*!< Misc 4 clock */ 104 #define SC_PM_CLK_CPU 2U /*!< CPU clock */ 105 #define SC_PM_CLK_PLL 4U /*!< PLL */ 106 #define SC_PM_CLK_BYPASS 4U /*!< Bypass clock */ 107 /*@}*/ 108 109 /*! 110 * @name Defines for sc_pm_clk_parent_t 111 */ 112 /*@{*/ 113 #define SC_PM_PARENT_XTAL 0U /*!< Parent is XTAL */ 114 #define SC_PM_PARENT_PLL0 1U /*!< Parent is PLL0 */ 115 #define SC_PM_PARENT_PLL1 2U /*!< Parent is PLL1 or PLL0/2 */ 116 #define SC_PM_PARENT_PLL2 3U /*!< Parent in PLL2 or PLL0/4 */ 117 #define SC_PM_PARENT_BYPS 4U /*!< Parent is a bypass clock. */ 118 /*@}*/ 119 120 /*! 121 * @name Defines for sc_pm_reset_type_t 122 */ 123 /*@{*/ 124 #define SC_PM_RESET_TYPE_COLD 0U /*!< Cold reset */ 125 #define SC_PM_RESET_TYPE_WARM 1U /*!< Warm reset */ 126 #define SC_PM_RESET_TYPE_BOARD 2U /*!< Board reset */ 127 /*@}*/ 128 129 /*! 130 * @name Defines for sc_pm_reset_reason_t 131 */ 132 /*@{*/ 133 #define SC_PM_RESET_REASON_POR 0U /*!< Power on reset */ 134 #define SC_PM_RESET_REASON_JTAG 1U /*!< JTAG reset */ 135 #define SC_PM_RESET_REASON_SW 2U /*!< Software reset */ 136 #define SC_PM_RESET_REASON_WDOG 3U /*!< Partition watchdog reset */ 137 #define SC_PM_RESET_REASON_LOCKUP 4U /*!< SCU lockup reset */ 138 #define SC_PM_RESET_REASON_SNVS 5U /*!< SNVS reset */ 139 #define SC_PM_RESET_REASON_TEMP 6U /*!< Temp panic reset */ 140 #define SC_PM_RESET_REASON_MSI 7U /*!< MSI reset */ 141 #define SC_PM_RESET_REASON_UECC 8U /*!< ECC reset */ 142 #define SC_PM_RESET_REASON_SCFW_WDOG 9U /*!< SCFW watchdog reset */ 143 #define SC_PM_RESET_REASON_ROM_WDOG 10U /*!< SCU ROM watchdog reset */ 144 #define SC_PM_RESET_REASON_SECO 11U /*!< SECO reset */ 145 #define SC_PM_RESET_REASON_SCFW_FAULT 12U /*!< SCFW fault reset */ 146 #define SC_PM_RESET_REASON_V2X_DEBUG 13U /*!< V2X debug switch */ 147 /*@}*/ 148 149 /*! 150 * @name Defines for sc_pm_sys_if_t 151 */ 152 /*@{*/ 153 #define SC_PM_SYS_IF_INTERCONNECT 0U /*!< System interconnect */ 154 #define SC_PM_SYS_IF_MU 1U /*!< AP -> SCU message units */ 155 #define SC_PM_SYS_IF_OCMEM 2U /*!< On-chip memory (ROM/OCRAM) */ 156 #define SC_PM_SYS_IF_DDR 3U /*!< DDR memory */ 157 /*@}*/ 158 159 /*! 160 * @name Defines for sc_pm_wake_src_t 161 */ 162 /*@{*/ 163 #define SC_PM_WAKE_SRC_NONE 0U /*!< No wake source, used for self-kill */ 164 #define SC_PM_WAKE_SRC_SCU 1U /*!< Wakeup from SCU to resume CPU (IRQSTEER & GIC powered down) */ 165 #define SC_PM_WAKE_SRC_IRQSTEER 2U /*!< Wakeup from IRQSTEER to resume CPU (GIC powered down) */ 166 #define SC_PM_WAKE_SRC_IRQSTEER_GIC 3U /*!< Wakeup from IRQSTEER+GIC to wake CPU (GIC clock gated) */ 167 #define SC_PM_WAKE_SRC_GIC 4U /*!< Wakeup from GIC to wake CPU */ 168 /*@}*/ 169 170 /* Types */ 171 172 /*! 173 * This type is used to declare a power mode. Note resources only use 174 * SC_PM_PW_MODE_OFF and SC_PM_PW_MODE_ON. The other modes are used only 175 * as system power modes. 176 */ 177 typedef uint8_t sc_pm_power_mode_t; 178 179 /*! 180 * This type is used to declare a clock. 181 */ 182 typedef uint8_t sc_pm_clk_t; 183 184 /*! 185 * This type is used to declare the clock parent. 186 */ 187 typedef uint8_t sc_pm_clk_parent_t; 188 189 /*! 190 * This type is used to declare clock rates. 191 */ 192 typedef uint32_t sc_pm_clock_rate_t; 193 194 /*! 195 * This type is used to declare a desired reset type. 196 */ 197 typedef uint8_t sc_pm_reset_type_t; 198 199 /*! 200 * This type is used to declare a reason for a reset. 201 */ 202 typedef uint8_t sc_pm_reset_reason_t; 203 204 /*! 205 * This type is used to specify a system-level interface to be power managed. 206 */ 207 typedef uint8_t sc_pm_sys_if_t; 208 209 /*! 210 * This type is used to specify a wake source for CPU resources. 211 */ 212 typedef uint8_t sc_pm_wake_src_t; 213 214 /* Functions */ 215 216 /*! 217 * @name Power Functions 218 * @{ 219 */ 220 221 /*! 222 * This function sets the system power mode. Only the owner of the 223 * SC_R_SYSTEM resource or a partition with access permissions to 224 * SC_R_SYSTEM can do this. 225 * 226 * @param[in] ipc IPC handle 227 * @param[in] mode power mode to apply 228 * 229 * @return Returns an error code (SC_ERR_NONE = success). 230 * 231 * Return errors: 232 * - SC_ERR_PARM if invalid mode, 233 * - SC_ERR_NOACCESS if caller does not have SC_R_SYSTEM access 234 * 235 * @see sc_pm_set_sys_power_mode(). 236 */ 237 sc_err_t sc_pm_set_sys_power_mode(sc_ipc_t ipc, sc_pm_power_mode_t mode); 238 239 /*! 240 * This function sets the power mode of a partition. 241 * 242 * @param[in] ipc IPC handle 243 * @param[in] pt handle of partition 244 * @param[in] mode power mode to apply 245 * 246 * @return Returns an error code (SC_ERR_NONE = success). 247 * 248 * Return errors: 249 * - SC_ERR_PARM if invalid partition or mode != SC_PM_PW_MODE_OFF, 250 * - SC_ERR_NOACCESS if caller's partition is not the owner or 251 * parent of \a pt 252 * 253 * This function can only be used to turn off a partition by calling 254 * with mode equal to SC_PM_PW_MODE_OFF. After turning off, the partition 255 * can be booted with sc_pm_reboot_partition() or sc_pm_boot(). It cannot 256 * be used to turn off the calling partition as the MU could not return 257 * the an error response. 258 * 259 * For dynamic power management of a partition, use 260 * sc_pm_req_low_power_mode(), sc_pm_req_cpu_low_power_mode(), 261 * and sc_pm_req_sys_if_power_mode() with a WFI for controlled power 262 * state transitions. 263 */ 264 sc_err_t sc_pm_set_partition_power_mode(sc_ipc_t ipc, sc_rm_pt_t pt, 265 sc_pm_power_mode_t mode); 266 267 /*! 268 * This function gets the power mode of a partition. 269 * 270 * @param[in] ipc IPC handle 271 * @param[in] pt handle of partition 272 * @param[out] mode pointer to return power mode 273 * 274 * @return Returns an error code (SC_ERR_NONE = success). 275 * 276 * Return errors: 277 * - SC_ERR_PARM if invalid partition 278 */ 279 sc_err_t sc_pm_get_sys_power_mode(sc_ipc_t ipc, sc_rm_pt_t pt, 280 sc_pm_power_mode_t *mode); 281 282 /*! 283 * This function sends a wake interrupt to a partition. 284 * 285 * @param[in] ipc IPC handle 286 * @param[in] pt handle of partition to wake 287 * 288 * @return Returns an error code (SC_ERR_NONE = success). 289 * 290 * An SC_IRQ_SW_WAKE interrupt is sent to all MUs owned by the 291 * partition that have this interrupt enabled. The CPU using an 292 * MU will exit a low-power state to service the MU interrupt. 293 * 294 * Return errors: 295 * - SC_ERR_PARM if invalid partition 296 */ 297 sc_err_t sc_pm_partition_wake(sc_ipc_t ipc, sc_rm_pt_t pt); 298 299 /*! 300 * This function sets the power mode of a resource. 301 * 302 * @param[in] ipc IPC handle 303 * @param[in] resource ID of the resource 304 * @param[in] mode power mode to apply 305 * 306 * @return Returns an error code (SC_ERR_NONE = success). 307 * 308 * Return errors: 309 * - SC_ERR_PARM if invalid resource or mode, 310 * - SC_ERR_PARM if resource is the MU used to make the call, 311 * - SC_ERR_NOACCESS if caller's partition is not the resource owner 312 * or parent of the owner 313 * 314 * Resources must be at SC_PM_PW_MODE_LP mode or higher to access them, 315 * otherwise the master will get a bus error or hang. 316 * 317 * Note some resources are still not accessible even when powered up if bus 318 * transactions go through a fabric not powered up. Examples of this are 319 * resources in display and capture subsystems which require the display 320 * controller or the imaging subsystem to be powered up first. 321 * 322 * Note that resources are grouped into power domains by the underlying 323 * hardware. If any resource in the domain is on, the entire power domain 324 * will be on. Other power domains required to access the resource will 325 * also be turned on. Bus clocks required to access the peripheral will be 326 * turned on. Refer to the SoC RM for more info on power domains and access 327 * infrastructure (bus fabrics, clock domains, etc.). 328 * 329 * When the resource transitions to the SC_PM_PW_MODE_OFF, all of the settings, 330 * including clock rate, will be lost; immaterial of the state of other 331 * resources in the same power domain. 332 */ 333 sc_err_t sc_pm_set_resource_power_mode(sc_ipc_t ipc, sc_rsrc_t resource, 334 sc_pm_power_mode_t mode); 335 336 /*! 337 * This function sets the power mode for all the resources owned 338 * by a child partition. 339 * 340 * @param[in] ipc IPC handle 341 * @param[in] pt handle of child partition 342 * @param[in] mode power mode to apply 343 * @param[in] exclude resource to exclude 344 * 345 * @return Returns an error code (SC_ERR_NONE = success). 346 * 347 * Return errors: 348 * - SC_ERR_PARM if invalid partition or mode, 349 * - SC_ERR_NOACCESS if caller's partition is not the parent 350 * (with grant) of \a pt 351 * 352 * This functions loops through all the resources owned by \a pt 353 * and sets the power mode to \a mode. It will skip setting 354 * \a exclude (SC_R_LAST to skip none). 355 * 356 * This function can only be called by the parent. It is used to 357 * implement some aspects of virtualization. 358 */ 359 sc_err_t sc_pm_set_resource_power_mode_all(sc_ipc_t ipc, 360 sc_rm_pt_t pt, sc_pm_power_mode_t mode, sc_rsrc_t exclude); 361 362 /*! 363 * This function gets the power mode of a resource. 364 * 365 * @param[in] ipc IPC handle 366 * @param[in] resource ID of the resource 367 * @param[out] mode pointer to return power mode 368 * 369 * @return Returns an error code (SC_ERR_NONE = success). 370 * 371 * Note only SC_PM_PW_MODE_OFF and SC_PM_PW_MODE_ON are valid. The value 372 * returned does not reflect the power mode of the partition. 373 */ 374 sc_err_t sc_pm_get_resource_power_mode(sc_ipc_t ipc, sc_rsrc_t resource, 375 sc_pm_power_mode_t *mode); 376 377 /*! 378 * This function specifies the low power mode some of the resources 379 * can enter based on their state. This API is only valid for the 380 * following resources : SC_R_A53, SC_R_A53_0, SC_R_A53_1, SC_R_A53_2, 381 * SC_R_A53_3, SC_R_A72, SC_R_A72_0, SC_R_A72_1, SC_R_CC1, SC_R_A35, 382 * SC_R_A35_0, SC_R_A35_1, SC_R_A35_2, SC_R_A35_3. 383 * For all other resources it will return SC_ERR_PARAM. 384 * This function will set the low power mode the cores, cluster 385 * and cluster associated resources will enter when all the cores 386 * in a given cluster execute WFI. 387 * 388 * @param[in] ipc IPC handle 389 * @param[in] resource ID of the resource 390 * @param[in] mode power mode to apply 391 * 392 * @return Returns an error code (SC_ERR_NONE = success). 393 * 394 */ 395 sc_err_t sc_pm_req_low_power_mode(sc_ipc_t ipc, sc_rsrc_t resource, 396 sc_pm_power_mode_t mode); 397 398 /*! 399 * This function requests low-power mode entry for CPU/cluster 400 * resources. This API is only valid for the following resources: 401 * SC_R_A53, SC_R_A53_x, SC_R_A72, SC_R_A72_x, SC_R_A35, SC_R_A35_x, 402 * SC_R_CCI. For all other resources it will return SC_ERR_PARAM. 403 * For individual core resources, the specified power mode 404 * and wake source will be applied after the core has entered 405 * WFI. For cluster resources, the specified power mode is 406 * applied after all cores in the cluster have entered low-power mode. 407 * For multicluster resources, the specified power mode is applied 408 * after all clusters have reached low-power mode. 409 * 410 * @param[in] ipc IPC handle 411 * @param[in] resource ID of the resource 412 * @param[in] mode power mode to apply 413 * @param[in] wake_src wake source for low-power exit 414 * 415 * @return Returns an error code (SC_ERR_NONE = success). 416 * 417 */ 418 sc_err_t sc_pm_req_cpu_low_power_mode(sc_ipc_t ipc, sc_rsrc_t resource, 419 sc_pm_power_mode_t mode, sc_pm_wake_src_t wake_src); 420 421 /*! 422 * This function is used to set the resume address of a CPU. 423 * 424 * @param[in] ipc IPC handle 425 * @param[in] resource ID of the CPU resource 426 * @param[in] address 64-bit resume address 427 * 428 * @return Returns an error code (SC_ERR_NONE = success). 429 * 430 * Return errors: 431 * - SC_ERR_PARM if invalid resource or address, 432 * - SC_ERR_NOACCESS if caller's partition is not the parent of the 433 * resource (CPU) owner 434 * 435 * Note the address is limited by the hardware implementation. See the 436 * [CPU Start Address](@ref BOOT_ADDR) section in the Porting Guide. 437 */ 438 sc_err_t sc_pm_set_cpu_resume_addr(sc_ipc_t ipc, sc_rsrc_t resource, 439 sc_faddr_t address); 440 441 /*! 442 * This function is used to set parameters for CPU resume from 443 * low-power mode. 444 * 445 * @param[in] ipc IPC handle 446 * @param[in] resource ID of the CPU resource 447 * @param[in] isPrimary set SC_TRUE if primary wake CPU 448 * @param[in] address 64-bit resume address 449 * 450 * @return Returns an error code (SC_ERR_NONE = success). 451 * 452 * Return errors: 453 * - SC_ERR_PARM if invalid resource or address, 454 * - SC_ERR_NOACCESS if caller's partition is not the parent of the 455 * resource (CPU) owner 456 * 457 * Note the address is limited by the hardware implementation. See the 458 * [CPU Start Address](@ref BOOT_ADDR) section in the Porting Guide. 459 */ 460 sc_err_t sc_pm_set_cpu_resume(sc_ipc_t ipc, sc_rsrc_t resource, 461 sc_bool_t isPrimary, sc_faddr_t address); 462 463 /*! 464 * This function requests the power mode configuration for system-level 465 * interfaces including messaging units, interconnect, and memories. This API 466 * is only valid for the following resources : SC_R_A53, SC_R_A72, and 467 * SC_R_M4_x_PID_y. For all other resources, it will return SC_ERR_PARAM. 468 * The requested power mode will be captured and applied to system-level 469 * resources as system conditions allow. 470 * 471 * @param[in] ipc IPC handle 472 * @param[in] resource ID of the resource 473 * @param[in] sys_if system-level interface to be configured 474 * @param[in] hpm high-power mode for the system interface 475 * @param[in] lpm low-power mode for the system interface 476 * 477 * @return Returns an error code (SC_ERR_NONE = success). 478 * 479 */ 480 sc_err_t sc_pm_req_sys_if_power_mode(sc_ipc_t ipc, sc_rsrc_t resource, 481 sc_pm_sys_if_t sys_if, sc_pm_power_mode_t hpm, sc_pm_power_mode_t lpm); 482 483 /* @} */ 484 485 /*! 486 * @name Clock/PLL Functions 487 * @{ 488 */ 489 490 /*! 491 * This function sets the rate of a resource's clock/PLL. 492 * 493 * @param[in] ipc IPC handle 494 * @param[in] resource ID of the resource 495 * @param[in] clk clock/PLL to affect 496 * @param[in,out] rate pointer to rate 497 * 498 * Note the actual rate is returned in \a rate. 499 * 500 * @return Returns an error code (SC_ERR_NONE = success). 501 * 502 * Return errors: 503 * - SC_ERR_PARM if invalid resource or clock/PLL, 504 * - SC_ERR_NOACCESS if caller's partition is not the resource owner 505 * or parent of the owner, 506 * - SC_ERR_UNAVAILABLE if clock/PLL not applicable to this resource, 507 * - SC_ERR_LOCKED if rate locked (usually because shared clock/PLL) 508 * 509 * Refer to the [Clock List](@ref CLOCKS) for valid clock/PLL values. 510 */ 511 sc_err_t sc_pm_set_clock_rate(sc_ipc_t ipc, sc_rsrc_t resource, 512 sc_pm_clk_t clk, sc_pm_clock_rate_t *rate); 513 514 /*! 515 * This function gets the rate of a resource's clock/PLL. 516 * 517 * @param[in] ipc IPC handle 518 * @param[in] resource ID of the resource 519 * @param[in] clk clock/PLL to affect 520 * @param[out] rate pointer to return rate 521 * 522 * @return Returns an error code (SC_ERR_NONE = success). 523 * 524 * Return errors: 525 * - SC_ERR_PARM if invalid resource or clock/PLL, 526 * - SC_ERR_NOACCESS if caller's partition is not the resource owner 527 * or parent of the owner, 528 * - SC_ERR_UNAVAILABLE if clock/PLL not applicable to this resource 529 * 530 * This function returns the actual clock rate of the hardware. This rate 531 * may be different from the original requested clock rate if the resource 532 * is set to a low power mode. 533 * 534 * Refer to the [Clock List](@ref CLOCKS) for valid clock/PLL values. 535 */ 536 sc_err_t sc_pm_get_clock_rate(sc_ipc_t ipc, sc_rsrc_t resource, 537 sc_pm_clk_t clk, sc_pm_clock_rate_t *rate); 538 539 /*! 540 * This function enables/disables a resource's clock. 541 * 542 * @param[in] ipc IPC handle 543 * @param[in] resource ID of the resource 544 * @param[in] clk clock to affect 545 * @param[in] enable enable if SC_TRUE; otherwise disabled 546 * @param[in] autog HW auto clock gating 547 * 548 * If \a resource is SC_R_ALL then all resources owned will be affected. 549 * No error will be returned. 550 * 551 * If \a clk is SC_PM_CLK_ALL, then an error will be returned if any 552 * of the available clocks returns an error. 553 * 554 * @return Returns an error code (SC_ERR_NONE = success). 555 * 556 * Return errors: 557 * - SC_ERR_PARM if invalid resource or clock, 558 * - SC_ERR_NOACCESS if caller's partition is not the resource owner 559 * or parent (with grant) of the owner, 560 * - SC_ERR_UNAVAILABLE if clock not applicable to this resource 561 * 562 * Refer to the [Clock List](@ref CLOCKS) for valid clock values. 563 */ 564 sc_err_t sc_pm_clock_enable(sc_ipc_t ipc, sc_rsrc_t resource, 565 sc_pm_clk_t clk, sc_bool_t enable, sc_bool_t autog); 566 567 /*! 568 * This function sets the parent of a resource's clock. 569 * This function should only be called when the clock is disabled. 570 * 571 * @param[in] ipc IPC handle 572 * @param[in] resource ID of the resource 573 * @param[in] clk clock to affect 574 * @param[in] parent New parent of the clock 575 * 576 * @return Returns an error code (SC_ERR_NONE = success). 577 * 578 * Return errors: 579 * - SC_ERR_PARM if invalid resource or clock, 580 * - SC_ERR_NOACCESS if caller's partition is not the resource owner 581 * or parent (with grant) of the owner, 582 * - SC_ERR_UNAVAILABLE if clock not applicable to this resource 583 * - SC_ERR_BUSY if clock is currently enabled. 584 * - SC_ERR_NOPOWER if resource not powered 585 * 586 * Refer to the [Clock List](@ref CLOCKS) for valid clock values. 587 */ 588 sc_err_t sc_pm_set_clock_parent(sc_ipc_t ipc, sc_rsrc_t resource, 589 sc_pm_clk_t clk, sc_pm_clk_parent_t parent); 590 591 /*! 592 * This function gets the parent of a resource's clock. 593 * 594 * @param[in] ipc IPC handle 595 * @param[in] resource ID of the resource 596 * @param[in] clk clock to affect 597 * @param[out] parent pointer to return parent of clock 598 * 599 * @return Returns an error code (SC_ERR_NONE = success). 600 * 601 * Return errors: 602 * - SC_ERR_PARM if invalid resource or clock, 603 * - SC_ERR_NOACCESS if caller's partition is not the resource owner 604 * or parent of the owner, 605 * - SC_ERR_UNAVAILABLE if clock not applicable to this resource 606 * 607 * Refer to the [Clock List](@ref CLOCKS) for valid clock values. 608 */ 609 sc_err_t sc_pm_get_clock_parent(sc_ipc_t ipc, sc_rsrc_t resource, 610 sc_pm_clk_t clk, sc_pm_clk_parent_t *parent); 611 612 /* @} */ 613 614 /*! 615 * @name Reset Functions 616 * @{ 617 */ 618 619 /*! 620 * This function is used to reset the system. Only the owner of the 621 * SC_R_SYSTEM resource or a partition with access permissions to 622 * SC_R_SYSTEM can do this. 623 * 624 * @param[in] ipc IPC handle 625 * @param[in] type reset type 626 * 627 * @return Returns an error code (SC_ERR_NONE = success). 628 * 629 * Return errors: 630 * - SC_ERR_PARM if invalid type, 631 * - SC_ERR_NOACCESS if caller cannot access SC_R_SYSTEM 632 * 633 * If this function returns, then the reset did not occur due to an 634 * invalid parameter. 635 */ 636 sc_err_t sc_pm_reset(sc_ipc_t ipc, sc_pm_reset_type_t type); 637 638 /*! 639 * This function gets a caller's reset reason. 640 * 641 * @param[in] ipc IPC handle 642 * @param[out] reason pointer to return the reset reason 643 * 644 * This function returns the reason a partition was reset. If the reason 645 * is POR, then the system reset reason will be returned. 646 * 647 * Note depending on the connection of the WDOG_OUT signal and the OTP 648 * programming of the PMIC, some resets may trigger a system POR 649 * and the original reason will be lost. 650 * 651 * @return Returns an error code (SC_ERR_NONE = success). 652 */ 653 sc_err_t sc_pm_reset_reason(sc_ipc_t ipc, sc_pm_reset_reason_t *reason); 654 655 /*! 656 * This function gets the partition that caused a reset. 657 * 658 * @param[in] ipc IPC handle 659 * @param[out] pt pointer to return the resetting partition 660 * 661 * If the reset reason obtained via sc_pm_reset_reason() is POR then the 662 * result from this function will be 0. Some SECO causes of reset will 663 * also return 0. 664 * 665 * Note depending on the connection of the WDOG_OUT signal and the OTP 666 * programming of the PMIC, some resets may trigger a system POR 667 * and the partition info will be lost. 668 * 669 * @return Returns an error code (SC_ERR_NONE = success). 670 */ 671 sc_err_t sc_pm_get_reset_part(sc_ipc_t ipc, sc_rm_pt_t *pt); 672 673 /*! 674 * This function is used to boot a partition. 675 * 676 * @param[in] ipc IPC handle 677 * @param[in] pt handle of partition to boot 678 * @param[in] resource_cpu ID of the CPU resource to start 679 * @param[in] boot_addr 64-bit boot address 680 * @param[in] resource_mu ID of the MU that must be powered 681 * @param[in] resource_dev ID of the boot device that must be powered 682 * 683 * @return Returns an error code (SC_ERR_NONE = success). 684 * 685 * Return errors: 686 * - SC_ERR_PARM if invalid partition, resource, or addr, 687 * - SC_ERR_NOACCESS if caller's partition is not the parent of the 688 * partition to boot 689 * 690 * This must be used to boot a partition. Only a partition booted this 691 * way can be rebooted using the watchdog, sc_pm_boot() or 692 * sc_pm_reboot_partition(). 693 * 694 * Note the address is limited by the hardware implementation. See the 695 * [CPU Start Address](@ref BOOT_ADDR) section in the Porting Guide. 696 */ 697 sc_err_t sc_pm_boot(sc_ipc_t ipc, sc_rm_pt_t pt, 698 sc_rsrc_t resource_cpu, sc_faddr_t boot_addr, 699 sc_rsrc_t resource_mu, sc_rsrc_t resource_dev); 700 701 /*! 702 * This function is used to change the boot parameters for a partition. 703 * 704 * @param[in] ipc IPC handle 705 * @param[in] resource_cpu ID of the CPU resource to start 706 * @param[in] boot_addr 64-bit boot address 707 * @param[in] resource_mu ID of the MU that must be powered (0=none) 708 * @param[in] resource_dev ID of the boot device that must be powered (0=none) 709 * 710 * @return Returns an error code (SC_ERR_NONE = success). 711 * 712 * Return errors: 713 * - SC_ERR_PARM if invalid resource, or addr 714 * 715 * This function can be used to change the boot parameters for a partition. 716 * This can be useful if a partitions reboots differently from the initial 717 * boot done via sc_pm_boot() or via ROM. 718 * 719 * Note the address is limited by the hardware implementation. See the 720 * [CPU Start Address](@ref BOOT_ADDR) section in the Porting Guide. 721 */ 722 sc_err_t sc_pm_set_boot_parm(sc_ipc_t ipc, 723 sc_rsrc_t resource_cpu, sc_faddr_t boot_addr, 724 sc_rsrc_t resource_mu, sc_rsrc_t resource_dev); 725 726 /*! 727 * This function is used to reboot the caller's partition. 728 * 729 * @param[in] ipc IPC handle 730 * @param[in] type reset type 731 * 732 * If \a type is SC_PM_RESET_TYPE_COLD, then most peripherals owned by 733 * the calling partition will be reset if possible. SC state (partitions, 734 * power, clocks, etc.) is reset. The boot SW of the booting CPU must be 735 * able to handle peripherals that that are not reset. 736 * 737 * If \a type is SC_PM_RESET_TYPE_WARM or SC_PM_RESET_TYPE_BOARD, then 738 * does nothing. 739 * 740 * If this function returns, then the reset did not occur due to an 741 * invalid parameter. 742 */ 743 void sc_pm_reboot(sc_ipc_t ipc, sc_pm_reset_type_t type); 744 745 /*! 746 * This function is used to reboot a partition. 747 * 748 * @param[in] ipc IPC handle 749 * @param[in] pt handle of partition to reboot 750 * @param[in] type reset type 751 * 752 * If \a type is SC_PM_RESET_TYPE_COLD, then most peripherals owned by 753 * the calling partition will be reset if possible. SC state (partitions, 754 * power, clocks, etc.) is reset. The boot SW of the booting CPU must be 755 * able to handle peripherals that that are not reset. 756 * 757 * If \a type is SC_PM_RESET_TYPE_WARM or SC_PM_RESET_TYPE_BOARD, then 758 * returns SC_ERR_PARM as these are not supported. 759 * 760 * @return Returns an error code (SC_ERR_NONE = success). 761 * 762 * Return errors: 763 * - SC_ERR_PARM if invalid partition or type 764 * - SC_ERR_NOACCESS if caller's partition is not the parent of \a pt 765 * and the caller does not have access to SC_R_SYSTEM 766 * 767 * Most peripherals owned by the partition will be reset if 768 * possible. SC state (partitions, power, clocks, etc.) is reset. The 769 * boot SW of the booting CPU must be able to handle peripherals that 770 * that are not reset. 771 * 772 * If board_reboot_part() returns a non-0 mask, then the reboot will 773 * be delayed until all partitions indicated in the mask have called 774 * sc_pm_reboot_continue() to continue the boot. 775 */ 776 sc_err_t sc_pm_reboot_partition(sc_ipc_t ipc, sc_rm_pt_t pt, 777 sc_pm_reset_type_t type); 778 779 /*! 780 * This function is used to continue the reboot a partition. 781 * 782 * @param[in] ipc IPC handle 783 * @param[in] pt handle of partition to continue 784 * 785 * @return Returns an error code (SC_ERR_NONE = success). 786 * 787 * Return errors: 788 * - SC_ERR_PARM if invalid partition 789 */ 790 sc_err_t sc_pm_reboot_continue(sc_ipc_t ipc, sc_rm_pt_t pt); 791 792 /*! 793 * This function is used to start/stop a CPU. 794 * 795 * @param[in] ipc IPC handle 796 * @param[in] resource ID of the CPU resource 797 * @param[in] enable start if SC_TRUE; otherwise stop 798 * @param[in] address 64-bit boot address 799 * 800 * @return Returns an error code (SC_ERR_NONE = success). 801 * 802 * Return errors: 803 * - SC_ERR_PARM if invalid resource or address, 804 * - SC_ERR_NOACCESS if caller's partition is not the parent of the 805 * resource (CPU) owner 806 * 807 * This function is usually used to start a secondary CPU in the 808 * same partition as the caller. It is not used to start the first 809 * CPU in a dedicated partition. That would be started by calling 810 * sc_pm_boot(). 811 * 812 * A CPU started with sc_pm_cpu_start() will not restart as a result 813 * of a watchdog event or calling sc_pm_reboot() or sc_pm_reboot_partition(). 814 * Those will reboot that partition which will start the CPU started with 815 * sc_pm_boot(). 816 * 817 * Note the address is limited by the hardware implementation. See the 818 * [CPU Start Address](@ref BOOT_ADDR) section in the Porting Guide. 819 */ 820 sc_err_t sc_pm_cpu_start(sc_ipc_t ipc, sc_rsrc_t resource, sc_bool_t enable, 821 sc_faddr_t address); 822 823 /*! 824 * This function is used to reset a CPU. 825 * 826 * @param[in] ipc IPC handle 827 * @param[in] resource ID of the CPU resource 828 * @param[in] address 64-bit boot address 829 * 830 * This function does not return anything as the calling core may have been 831 * reset. It can still fail if the resource or address is invalid. It can also 832 * fail if the caller's partition is not the owner of the CPU, not the parent 833 * of the CPU resource owner, or has access to SC_R_SYSTEM. Will also fail if 834 * the resource is not powered on. No indication of failure is returned. 835 * 836 * Note this just resets the CPU. None of the peripherals or bus fabric used by 837 * the CPU is reset. State configured in the SCFW is not reset. The SW running 838 * on the core has to understand and deal with this. 839 * 840 * The address is limited by the hardware implementation. See the 841 * [CPU Start Address](@ref BOOT_ADDR) section in the Porting Guide. 842 */ 843 void sc_pm_cpu_reset(sc_ipc_t ipc, sc_rsrc_t resource, sc_faddr_t address); 844 845 /*! 846 * This function is used to reset a peripheral. 847 * 848 * @param[in] ipc IPC handle 849 * @param[in] resource resource to reset 850 * 851 * This function will reset a resource. Most resources cannot be reset unless 852 * the SoC design specifically allows it. In the case on MUs, the IPC/RPC 853 * protocol is also reset. Note a caller cannot reset an MU that this API 854 * call is sent on. 855 * 856 * @return Returns an error code (SC_ERR_NONE = success). 857 * 858 * Return errors: 859 * - SC_ERR_PARM if invalid resource, 860 * - SC_ERR_PARM if resource is the MU used to make the call, 861 * - SC_ERR_NOACCESS if caller's partition is not the resource owner or parent 862 * (with grant) of the owner, 863 * - SC_ERR_BUSY if the resource cannot be reset due to power state of buses, 864 * - SC_ERR_UNAVAILABLE if the resource cannot be reset due to hardware limitations 865 */ 866 sc_err_t sc_pm_resource_reset(sc_ipc_t ipc, sc_rsrc_t resource); 867 868 /*! 869 * This function returns a bool indicating if a partition was started. 870 * 871 * @param[in] ipc IPC handle 872 * @param[in] pt handle of partition to check 873 * 874 * @return Returns a bool (SC_TRUE = started). 875 * 876 * Note this indicates if a partition was started. It does not indicate if a 877 * partition is currently running or in a low power state. 878 */ 879 sc_bool_t sc_pm_is_partition_started(sc_ipc_t ipc, sc_rm_pt_t pt); 880 881 /* @} */ 882 883 #endif /* SC_PM_API_H */ 884 885 /**@}*/ 886 887
