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