/*
 * Copyright (c) 2016, Freescale Semiconductor, Inc.
 * Copyright 2017-2020 NXP
 *
 * SPDX-License-Identifier: BSD-3-Clause
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * o Redistributions of source code must retain the above copyright notice, this list
 *   of conditions and the following disclaimer.
 *
 * o Redistributions in binary form must reproduce the above copyright notice, this
 *   list of conditions and the following disclaimer in the documentation and/or
 *   other materials provided with the distribution.
 *
 * o Neither the name of the copyright holder nor the names of its
 *   contributors may be used to endorse or promote products derived from this
 *   software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/*!
 * Header file containing the public API for the System Controller (SC)
 * Power Management (PM) function. This includes functions for power state
 * control, clock control, reset control, and wake-up event control.
 *
 * @addtogroup PM_SVC PM: Power Management Service
 *
 * Module for the Power Management (PM) service.
 *
 * @includedoc pm/details.dox
 *
 * @{
 */

#ifndef SC_PM_API_H
#define SC_PM_API_H

/* Includes */

#include "main/types.h"
#include "svc/rm/rm_api.h"

/* Defines */

/*!
 * @name Defines for type widths
 */
/*@{*/
#define SC_PM_POWER_MODE_W      2U      /*!< Width of sc_pm_power_mode_t */
#define SC_PM_CLOCK_MODE_W      3U      /*!< Width of sc_pm_clock_mode_t */
#define SC_PM_RESET_TYPE_W      2U      /*!< Width of sc_pm_reset_type_t */
#define SC_PM_RESET_REASON_W    4U      /*!< Width of sc_pm_reset_reason_t */
/*@}*/

/*!
 * @name Defines for clock indexes (sc_pm_clk_t)
 */
/*@{*/
/*@}*/

/*!
 * @name Defines for ALL parameters
 */
/*@{*/
#define SC_PM_CLK_ALL   ((sc_pm_clk_t) UINT8_MAX)   /*!< All clocks */
/*@}*/

/*!
 * @name Defines for sc_pm_power_mode_t
 */
/*@{*/
#define SC_PM_PW_MODE_OFF       0U      /*!< Power off */
#define SC_PM_PW_MODE_STBY      1U      /*!< Power in standby */
#define SC_PM_PW_MODE_LP        2U      /*!< Power in low-power */
#define SC_PM_PW_MODE_ON        3U      /*!< Power on */
/*@}*/

/*!
 * @name Defines for sc_pm_clk_t
 */
/*@{*/
#define SC_PM_CLK_SLV_BUS       0U      /*!< Slave bus clock */
#define SC_PM_CLK_MST_BUS       1U      /*!< Master bus clock */
#define SC_PM_CLK_PER           2U      /*!< Peripheral clock */
#define SC_PM_CLK_PHY           3U      /*!< Phy clock */
#define SC_PM_CLK_MISC          4U      /*!< Misc clock */
#define SC_PM_CLK_MISC0         0U      /*!< Misc 0 clock */
#define SC_PM_CLK_MISC1         1U      /*!< Misc 1 clock */
#define SC_PM_CLK_MISC2         2U      /*!< Misc 2 clock */
#define SC_PM_CLK_MISC3         3U      /*!< Misc 3 clock */
#define SC_PM_CLK_MISC4         4U      /*!< Misc 4 clock */
#define SC_PM_CLK_CPU           2U      /*!< CPU clock */
#define SC_PM_CLK_PLL           4U      /*!< PLL */
#define SC_PM_CLK_BYPASS        4U      /*!< Bypass clock */
/*@}*/

/*!
 * @name Defines for sc_pm_clk_parent_t
 */
/*@{*/
#define SC_PM_PARENT_XTAL              0U    /*!< Parent is XTAL */
#define SC_PM_PARENT_PLL0              1U    /*!< Parent is PLL0 */
#define SC_PM_PARENT_PLL1              2U    /*!< Parent is PLL1 or PLL0/2 */
#define SC_PM_PARENT_PLL2              3U    /*!< Parent in PLL2 or PLL0/4 */
#define SC_PM_PARENT_BYPS              4U    /*!< Parent is a bypass clock. */
/*@}*/

/*!
 * @name Defines for sc_pm_reset_type_t
 */
/*@{*/
#define SC_PM_RESET_TYPE_COLD          0U    /*!< Cold reset */
#define SC_PM_RESET_TYPE_WARM          1U    /*!< Warm reset */
#define SC_PM_RESET_TYPE_BOARD         2U    /*!< Board reset */
/*@}*/

/*!
 * @name Defines for sc_pm_reset_reason_t
 */
/*@{*/
#define SC_PM_RESET_REASON_POR         0U    /*!< Power on reset */
#define SC_PM_RESET_REASON_JTAG        1U    /*!< JTAG reset */
#define SC_PM_RESET_REASON_SW          2U    /*!< Software reset */
#define SC_PM_RESET_REASON_WDOG        3U    /*!< Partition watchdog reset */
#define SC_PM_RESET_REASON_LOCKUP      4U    /*!< SCU lockup reset */
#define SC_PM_RESET_REASON_SNVS        5U    /*!< SNVS reset */
#define SC_PM_RESET_REASON_TEMP        6U    /*!< Temp panic reset */
#define SC_PM_RESET_REASON_MSI         7U    /*!< MSI reset */
#define SC_PM_RESET_REASON_UECC        8U    /*!< ECC reset */
#define SC_PM_RESET_REASON_SCFW_WDOG   9U    /*!< SCFW watchdog reset */
#define SC_PM_RESET_REASON_ROM_WDOG    10U   /*!< SCU ROM watchdog reset */
#define SC_PM_RESET_REASON_SECO        11U   /*!< SECO reset */
#define SC_PM_RESET_REASON_SCFW_FAULT  12U   /*!< SCFW fault reset */
#define SC_PM_RESET_REASON_V2X_DEBUG   13U   /*!< V2X debug switch */
/*@}*/

/*!
 * @name Defines for sc_pm_sys_if_t
 */
/*@{*/
#define SC_PM_SYS_IF_INTERCONNECT       0U   /*!< System interconnect */
#define SC_PM_SYS_IF_MU                 1U   /*!< AP -> SCU message units */
#define SC_PM_SYS_IF_OCMEM              2U   /*!< On-chip memory (ROM/OCRAM) */
#define SC_PM_SYS_IF_DDR                3U   /*!< DDR memory */
/*@}*/

/*!
 * @name Defines for sc_pm_wake_src_t
 */
/*@{*/
#define SC_PM_WAKE_SRC_NONE             0U   /*!< No wake source, used for self-kill */
#define SC_PM_WAKE_SRC_SCU              1U   /*!< Wakeup from SCU to resume CPU (IRQSTEER & GIC powered down) */
#define SC_PM_WAKE_SRC_IRQSTEER         2U   /*!< Wakeup from IRQSTEER to resume CPU (GIC powered down) */
#define SC_PM_WAKE_SRC_IRQSTEER_GIC     3U   /*!< Wakeup from IRQSTEER+GIC to wake CPU  (GIC clock gated) */
#define SC_PM_WAKE_SRC_GIC              4U   /*!< Wakeup from GIC to wake CPU */
/*@}*/

/* Types */

/*!
 * This type is used to declare a power mode. Note resources only use
 * SC_PM_PW_MODE_OFF and SC_PM_PW_MODE_ON. The other modes are used only
 * as system power modes.
 */
typedef uint8_t sc_pm_power_mode_t;

/*!
 * This type is used to declare a clock.
 */
typedef uint8_t sc_pm_clk_t;

/*!
 * This type is used to declare the clock parent.
 */
typedef uint8_t sc_pm_clk_parent_t;

/*!
 * This type is used to declare clock rates.
 */
typedef uint32_t sc_pm_clock_rate_t;

/*!
 * This type is used to declare a desired reset type.
 */
typedef uint8_t sc_pm_reset_type_t;

/*!
 * This type is used to declare a reason for a reset.
 */
typedef uint8_t sc_pm_reset_reason_t;

/*!
 * This type is used to specify a system-level interface to be power managed.
 */
typedef uint8_t sc_pm_sys_if_t;

/*!
 * This type is used to specify a wake source for CPU resources.
 */
typedef uint8_t sc_pm_wake_src_t;

/* Functions */

/*!
 * @name Power Functions
 * @{
 */

/*!
 * This function sets the system power mode. Only the owner of the
 * SC_R_SYSTEM resource or a partition with access permissions to
 * SC_R_SYSTEM can do this.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     mode        power mode to apply
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid mode,
 * - SC_ERR_NOACCESS if caller does not have SC_R_SYSTEM access
 *
 * @see sc_pm_set_sys_power_mode().
 */
sc_err_t sc_pm_set_sys_power_mode(sc_ipc_t ipc, sc_pm_power_mode_t mode);

/*!
 * This function sets the power mode of a partition.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     pt          handle of partition
 * @param[in]     mode        power mode to apply
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid partition or mode != SC_PM_PW_MODE_OFF,
 * - SC_ERR_NOACCESS if caller's partition is not the owner or
 *   parent of \a pt
 *
 * This function can only be used to turn off a partition by calling
 * with mode equal to SC_PM_PW_MODE_OFF. After turning off, the partition
 * can be booted with sc_pm_reboot_partition() or sc_pm_boot(). It cannot
 * be used to turn off the calling partition as the MU could not return
 * the an error response.
 *
 * For dynamic power management of a partition, use
 * sc_pm_req_low_power_mode(), sc_pm_req_cpu_low_power_mode(),
 * and sc_pm_req_sys_if_power_mode() with a WFI for controlled power
 * state transitions.
 */
sc_err_t sc_pm_set_partition_power_mode(sc_ipc_t ipc, sc_rm_pt_t pt,
    sc_pm_power_mode_t mode);

/*!
 * This function gets the power mode of a partition.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     pt          handle of partition
 * @param[out]    mode        pointer to return power mode
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid partition
 */
sc_err_t sc_pm_get_sys_power_mode(sc_ipc_t ipc, sc_rm_pt_t pt,
    sc_pm_power_mode_t *mode);

/*!
 * This function sends a wake interrupt to a partition.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     pt          handle of partition to wake
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * An SC_IRQ_SW_WAKE interrupt is sent to all MUs owned by the
 * partition that have this interrupt enabled. The CPU using an
 * MU will exit a low-power state to service the MU interrupt.
 *
 * Return errors:
 * - SC_ERR_PARM if invalid partition
 */
sc_err_t sc_pm_partition_wake(sc_ipc_t ipc, sc_rm_pt_t pt);

/*!
 * This function sets the power mode of a resource.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the resource
 * @param[in]     mode        power mode to apply
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid resource or mode,
 * - SC_ERR_PARM if resource is the MU used to make the call,
 * - SC_ERR_NOACCESS if caller's partition is not the resource owner
 *   or parent of the owner
 *
 * Resources must be at SC_PM_PW_MODE_LP mode or higher to access them,
 * otherwise the master will get a bus error or hang.
 *
 * Note some resources are still not accessible even when powered up if bus
 * transactions go through a fabric not powered up. Examples of this are
 * resources in display and capture subsystems which require the display
 * controller or the imaging subsystem to be powered up first.
 *
 * Note that resources are grouped into power domains by the underlying
 * hardware. If any resource in the domain is on, the entire power domain
 * will be on. Other power domains required to access the resource will
 * also be turned on. Bus clocks required to access the peripheral will be
 * turned on. Refer to the SoC RM for more info on power domains and access
 * infrastructure (bus fabrics, clock domains, etc.).
 *
 * When the resource transitions to the SC_PM_PW_MODE_OFF, all of the settings,
 * including clock rate, will be lost; immaterial of the state of other
 * resources in the same power domain.
 */
sc_err_t sc_pm_set_resource_power_mode(sc_ipc_t ipc, sc_rsrc_t resource,
    sc_pm_power_mode_t mode);

/*!
 * This function sets the power mode for all the resources owned
 * by a child partition.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     pt          handle of child partition
 * @param[in]     mode        power mode to apply
 * @param[in]     exclude     resource to exclude
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid partition or mode,
 * - SC_ERR_NOACCESS if caller's partition is not the parent
 *   (with grant) of \a pt
 *
 * This functions loops through all the resources owned by \a pt
 * and sets the power mode to \a mode. It will skip setting
 * \a exclude (SC_R_LAST to skip none).
 *
 * This function can only be called by the parent. It is used to
 * implement some aspects of virtualization.
 */
sc_err_t sc_pm_set_resource_power_mode_all(sc_ipc_t ipc,
    sc_rm_pt_t pt, sc_pm_power_mode_t mode, sc_rsrc_t exclude);

/*!
 * This function gets the power mode of a resource.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the resource
 * @param[out]    mode        pointer to return power mode
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Note only SC_PM_PW_MODE_OFF and SC_PM_PW_MODE_ON are valid. The value
 * returned does not reflect the power mode of the partition.
 */
sc_err_t sc_pm_get_resource_power_mode(sc_ipc_t ipc, sc_rsrc_t resource,
    sc_pm_power_mode_t *mode);

/*!
 * This function specifies the low power mode some of the resources
 * can enter based on their state. This API is only valid for the
 * following resources : SC_R_A53, SC_R_A53_0, SC_R_A53_1, SC_R_A53_2,
 * SC_R_A53_3, SC_R_A72, SC_R_A72_0, SC_R_A72_1, SC_R_CC1, SC_R_A35,
 * SC_R_A35_0, SC_R_A35_1, SC_R_A35_2, SC_R_A35_3.
 * For all other resources it will return SC_ERR_PARAM.
 * This function will set the low power mode the cores, cluster
 * and cluster associated resources will enter when all the cores
 * in a given cluster execute WFI.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the resource
 * @param[in]     mode        power mode to apply
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 */
sc_err_t sc_pm_req_low_power_mode(sc_ipc_t ipc, sc_rsrc_t resource,
    sc_pm_power_mode_t mode);

/*!
 * This function requests low-power mode entry for CPU/cluster
 * resources. This API is only valid for the following resources:
 * SC_R_A53, SC_R_A53_x, SC_R_A72, SC_R_A72_x, SC_R_A35, SC_R_A35_x,
 * SC_R_CCI. For all other resources it will return SC_ERR_PARAM.
 * For individual core resources, the specified power mode
 * and wake source will be applied after the core has entered
 * WFI.  For cluster resources, the specified power mode is
 * applied after all cores in the cluster have entered low-power mode.
 * For multicluster resources, the specified power mode is applied
 * after all clusters have reached low-power mode.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the resource
 * @param[in]     mode        power mode to apply
 * @param[in]     wake_src    wake source for low-power exit
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 */
sc_err_t sc_pm_req_cpu_low_power_mode(sc_ipc_t ipc, sc_rsrc_t resource,
    sc_pm_power_mode_t mode, sc_pm_wake_src_t wake_src);

/*!
 * This function is used to set the resume address of a CPU.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the CPU resource
 * @param[in]     address     64-bit resume address
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid resource or address,
 * - SC_ERR_NOACCESS if caller's partition is not the parent of the
 *   resource (CPU) owner
 *
 * Note the address is limited by the hardware implementation. See the
 * [CPU Start Address](@ref BOOT_ADDR) section in the Porting Guide.
 */
sc_err_t sc_pm_set_cpu_resume_addr(sc_ipc_t ipc, sc_rsrc_t resource,
    sc_faddr_t address);

/*!
 * This function is used to set parameters for CPU resume from
 * low-power mode.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the CPU resource
 * @param[in]     isPrimary   set SC_TRUE if primary wake CPU
 * @param[in]     address     64-bit resume address
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid resource or address,
 * - SC_ERR_NOACCESS if caller's partition is not the parent of the
 *   resource (CPU) owner
 *
 * Note the address is limited by the hardware implementation. See the
 * [CPU Start Address](@ref BOOT_ADDR) section in the Porting Guide.
 */
sc_err_t sc_pm_set_cpu_resume(sc_ipc_t ipc, sc_rsrc_t resource,
    sc_bool_t isPrimary, sc_faddr_t address);

/*!
 * This function requests the power mode configuration for system-level
 * interfaces including messaging units, interconnect, and memories. This API
 * is only valid for the following resources : SC_R_A53, SC_R_A72, and
 * SC_R_M4_x_PID_y.  For all other resources, it will return SC_ERR_PARAM.
 * The requested power mode will be captured and applied to system-level
 * resources as system conditions allow.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the resource
 * @param[in]     sys_if      system-level interface to be configured
 * @param[in]     hpm         high-power mode for the system interface
 * @param[in]     lpm         low-power mode for the system interface
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 */
sc_err_t sc_pm_req_sys_if_power_mode(sc_ipc_t ipc, sc_rsrc_t resource,
    sc_pm_sys_if_t sys_if, sc_pm_power_mode_t hpm, sc_pm_power_mode_t lpm);

/* @} */

/*!
 * @name Clock/PLL Functions
 * @{
 */

/*!
 * This function sets the rate of a resource's clock/PLL.
 *
 * @param[in]      ipc         IPC handle
 * @param[in]      resource    ID of the resource
 * @param[in]      clk         clock/PLL to affect
 * @param[in,out]  rate        pointer to rate
 *
 * Note the actual rate is returned in \a rate.
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid resource or clock/PLL,
 * - SC_ERR_NOACCESS if caller's partition is not the resource owner
 *   or parent of the owner,
 * - SC_ERR_UNAVAILABLE if clock/PLL not applicable to this resource,
 * - SC_ERR_LOCKED if rate locked (usually because shared clock/PLL)
 *
 * Refer to the [Clock List](@ref CLOCKS) for valid clock/PLL values.
 */
sc_err_t sc_pm_set_clock_rate(sc_ipc_t ipc, sc_rsrc_t resource,
    sc_pm_clk_t clk, sc_pm_clock_rate_t *rate);

/*!
 * This function gets the rate of a resource's clock/PLL.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the resource
 * @param[in]     clk         clock/PLL to affect
 * @param[out]    rate        pointer to return rate
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid resource or clock/PLL,
 * - SC_ERR_NOACCESS if caller's partition is not the resource owner
 *   or parent of the owner,
 * - SC_ERR_UNAVAILABLE if clock/PLL not applicable to this resource
 *
 * This function returns the actual clock rate of the hardware. This rate
 * may be different from the original requested clock rate if the resource
 * is set to a low power mode.
 *
 * Refer to the [Clock List](@ref CLOCKS) for valid clock/PLL values.
 */
sc_err_t sc_pm_get_clock_rate(sc_ipc_t ipc, sc_rsrc_t resource,
    sc_pm_clk_t clk, sc_pm_clock_rate_t *rate);

/*!
 * This function enables/disables a resource's clock.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the resource
 * @param[in]     clk         clock to affect
 * @param[in]     enable      enable if SC_TRUE; otherwise disabled
 * @param[in]     autog       HW auto clock gating
 *
 * If \a resource is SC_R_ALL then all resources owned will be affected.
 * No error will be returned.
 *
 * If \a clk is SC_PM_CLK_ALL, then an error will be returned if any
 * of the available clocks returns an error.
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid resource or clock,
 * - SC_ERR_NOACCESS if caller's partition is not the resource owner
 *   or parent (with grant) of the owner,
 * - SC_ERR_UNAVAILABLE if clock not applicable to this resource
 *
 * Refer to the [Clock List](@ref CLOCKS) for valid clock values.
 */
sc_err_t sc_pm_clock_enable(sc_ipc_t ipc, sc_rsrc_t resource,
    sc_pm_clk_t clk, sc_bool_t enable, sc_bool_t autog);

/*!
 * This function sets the parent of a resource's clock.
 * This function should only be called when the clock is disabled.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the resource
 * @param[in]     clk         clock to affect
 * @param[in]     parent      New parent of the clock
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid resource or clock,
 * - SC_ERR_NOACCESS if caller's partition is not the resource owner
 *   or parent (with grant) of the owner,
 * - SC_ERR_UNAVAILABLE if clock not applicable to this resource
 * - SC_ERR_BUSY if clock is currently enabled.
 * - SC_ERR_NOPOWER if resource not powered
 *
 * Refer to the [Clock List](@ref CLOCKS) for valid clock values.
 */
sc_err_t sc_pm_set_clock_parent(sc_ipc_t ipc, sc_rsrc_t resource,
    sc_pm_clk_t clk, sc_pm_clk_parent_t parent);

/*!
 * This function gets the parent of a resource's clock.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the resource
 * @param[in]     clk         clock to affect
 * @param[out]     parent     pointer to return parent of clock
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid resource or clock,
 * - SC_ERR_NOACCESS if caller's partition is not the resource owner
 *   or parent of the owner,
 * - SC_ERR_UNAVAILABLE if clock not applicable to this resource
 *
 * Refer to the [Clock List](@ref CLOCKS) for valid clock values.
 */
sc_err_t sc_pm_get_clock_parent(sc_ipc_t ipc, sc_rsrc_t resource,
    sc_pm_clk_t clk, sc_pm_clk_parent_t *parent);

/* @} */

/*!
 * @name Reset Functions
 * @{
 */

/*!
 * This function is used to reset the system. Only the owner of the
 * SC_R_SYSTEM resource or a partition with access permissions to
 * SC_R_SYSTEM can do this.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     type        reset type
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid type,
 * - SC_ERR_NOACCESS if caller cannot access SC_R_SYSTEM
 *
 * If this function returns, then the reset did not occur due to an
 * invalid parameter.
 */
sc_err_t sc_pm_reset(sc_ipc_t ipc, sc_pm_reset_type_t type);

/*!
 * This function gets a caller's reset reason.
 *
 * @param[in]     ipc         IPC handle
 * @param[out]    reason      pointer to return the reset reason
 *
 * This function returns the reason a partition was reset. If the reason
 * is POR, then the system reset reason will be returned.
 *
 * Note depending on the connection of the WDOG_OUT signal and the OTP
 * programming of the PMIC, some resets may trigger a system POR
 * and the original reason will be lost.
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 */
sc_err_t sc_pm_reset_reason(sc_ipc_t ipc, sc_pm_reset_reason_t *reason);

/*!
 * This function gets the partition that caused a reset.
 *
 * @param[in]     ipc         IPC handle
 * @param[out]    pt          pointer to return the resetting partition
 *
 * If the reset reason obtained via sc_pm_reset_reason() is POR then the
 * result from this function will be 0. Some SECO causes of reset will
 * also return 0.
 *
 * Note depending on the connection of the WDOG_OUT signal and the OTP
 * programming of the PMIC, some resets may trigger a system POR
 * and the partition info will be lost.
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 */
sc_err_t sc_pm_get_reset_part(sc_ipc_t ipc, sc_rm_pt_t *pt);

/*!
 * This function is used to boot a partition.
 *
 * @param[in]     ipc           IPC handle
 * @param[in]     pt            handle of partition to boot
 * @param[in]     resource_cpu  ID of the CPU resource to start
 * @param[in]     boot_addr     64-bit boot address
 * @param[in]     resource_mu   ID of the MU that must be powered
 * @param[in]     resource_dev  ID of the boot device that must be powered
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid partition, resource, or addr,
 * - SC_ERR_NOACCESS if caller's partition is not the parent of the
 *   partition to boot
 *
 * This must be used to boot a partition. Only a partition booted this
 * way can be rebooted using the watchdog, sc_pm_boot() or
 * sc_pm_reboot_partition().
 *
 * Note the address is limited by the hardware implementation. See the
 * [CPU Start Address](@ref BOOT_ADDR) section in the Porting Guide.
 */
sc_err_t sc_pm_boot(sc_ipc_t ipc, sc_rm_pt_t pt,
    sc_rsrc_t resource_cpu, sc_faddr_t boot_addr,
    sc_rsrc_t resource_mu, sc_rsrc_t resource_dev);

/*!
 * This function is used to change the boot parameters for a partition.
 *
 * @param[in]     ipc           IPC handle
 * @param[in]     resource_cpu  ID of the CPU resource to start
 * @param[in]     boot_addr     64-bit boot address
 * @param[in]     resource_mu   ID of the MU that must be powered (0=none)
 * @param[in]     resource_dev  ID of the boot device that must be powered (0=none)
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid resource, or addr
 *
 * This function can be used to change the boot parameters for a partition.
 * This can be useful if a partitions reboots differently from the initial
 * boot done via sc_pm_boot() or via ROM.
 *
 * Note the address is limited by the hardware implementation. See the
 * [CPU Start Address](@ref BOOT_ADDR) section in the Porting Guide.
 */
sc_err_t sc_pm_set_boot_parm(sc_ipc_t ipc,
    sc_rsrc_t resource_cpu, sc_faddr_t boot_addr,
    sc_rsrc_t resource_mu, sc_rsrc_t resource_dev);

/*!
 * This function is used to reboot the caller's partition.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     type        reset type
 *
 * If \a type is SC_PM_RESET_TYPE_COLD, then most peripherals owned by
 * the calling partition will be reset if possible. SC state (partitions,
 * power, clocks, etc.) is reset. The boot SW of the booting CPU must be
 * able to handle peripherals that that are not reset.
 *
 * If \a type is SC_PM_RESET_TYPE_WARM or SC_PM_RESET_TYPE_BOARD, then
 * does nothing.
 *
 * If this function returns, then the reset did not occur due to an
 * invalid parameter.
 */
void sc_pm_reboot(sc_ipc_t ipc, sc_pm_reset_type_t type);

/*!
 * This function is used to reboot a partition.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     pt          handle of partition to reboot
 * @param[in]     type        reset type
 *
 * If \a type is SC_PM_RESET_TYPE_COLD, then most peripherals owned by
 * the calling partition will be reset if possible. SC state (partitions,
 * power, clocks, etc.) is reset. The boot SW of the booting CPU must be
 * able to handle peripherals that that are not reset.
 *
 * If \a type is SC_PM_RESET_TYPE_WARM or SC_PM_RESET_TYPE_BOARD, then
 * returns SC_ERR_PARM as these are not supported.
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid partition or type
 * - SC_ERR_NOACCESS if caller's partition is not the parent of \a pt
 *   and the caller does not have access to SC_R_SYSTEM
 *
 * Most peripherals owned by the partition will be reset if
 * possible. SC state (partitions, power, clocks, etc.) is reset. The
 * boot SW of the booting CPU must be able to handle peripherals that
 * that are not reset.
 *
 * If board_reboot_part() returns a non-0 mask, then the reboot will
 * be delayed until all partitions indicated in the mask have called
 * sc_pm_reboot_continue() to continue the boot.
 */
sc_err_t sc_pm_reboot_partition(sc_ipc_t ipc, sc_rm_pt_t pt,
    sc_pm_reset_type_t type);

/*!
 * This function is used to continue the reboot a partition.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     pt          handle of partition to continue
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid partition
 */
sc_err_t sc_pm_reboot_continue(sc_ipc_t ipc, sc_rm_pt_t pt);

/*!
 * This function is used to start/stop a CPU.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the CPU resource
 * @param[in]     enable      start if SC_TRUE; otherwise stop
 * @param[in]     address     64-bit boot address
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid resource or address,
 * - SC_ERR_NOACCESS if caller's partition is not the parent of the
 *   resource (CPU) owner
 *
 * This function is usually used to start a secondary CPU in the
 * same partition as the caller. It is not used to start the first
 * CPU in a dedicated partition. That would be started by calling
 * sc_pm_boot().
 *
 * A CPU started with sc_pm_cpu_start() will not restart as a result
 * of a watchdog event or calling sc_pm_reboot() or sc_pm_reboot_partition().
 * Those will reboot that partition which will start the CPU started with
 * sc_pm_boot().
 *
 * Note the address is limited by the hardware implementation. See the
 * [CPU Start Address](@ref BOOT_ADDR) section in the Porting Guide.
 */
sc_err_t sc_pm_cpu_start(sc_ipc_t ipc, sc_rsrc_t resource, sc_bool_t enable,
    sc_faddr_t address);

/*!
 * This function is used to reset a CPU.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    ID of the CPU resource
 * @param[in]     address     64-bit boot address
 *
 * This function does not return anything as the calling core may have been
 * reset. It can still fail if the resource or address is invalid. It can also
 * fail if the caller's partition is not the owner of the CPU, not the parent
 * of the CPU resource owner, or has access to SC_R_SYSTEM. Will also fail if
 * the resource is not powered on. No indication of failure is returned.
 *
 * Note this just resets the CPU. None of the peripherals or bus fabric used by
 * the CPU is reset. State configured in the SCFW is not reset. The SW running
 * on the core has to understand and deal with this.
 *
 * The address is limited by the hardware implementation. See the
 * [CPU Start Address](@ref BOOT_ADDR) section in the Porting Guide.
 */
void sc_pm_cpu_reset(sc_ipc_t ipc, sc_rsrc_t resource, sc_faddr_t address);

/*!
 * This function is used to reset a peripheral.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     resource    resource to reset
 *
 * This function will reset a resource. Most resources cannot be reset unless
 * the SoC design specifically allows it. In the case on MUs, the IPC/RPC
 * protocol is also reset. Note a caller cannot reset an MU that this API
 * call is sent on.
 *
 * @return Returns an error code (SC_ERR_NONE = success).
 *
 * Return errors:
 * - SC_ERR_PARM if invalid resource,
 * - SC_ERR_PARM if resource is the MU used to make the call,
 * - SC_ERR_NOACCESS if caller's partition is not the resource owner or parent
 *   (with grant) of the owner,
 * - SC_ERR_BUSY if the resource cannot be reset due to power state of buses,
 * - SC_ERR_UNAVAILABLE if the resource cannot be reset due to hardware limitations
 */
sc_err_t sc_pm_resource_reset(sc_ipc_t ipc, sc_rsrc_t resource);

/*!
 * This function returns a bool indicating if a partition was started.
 *
 * @param[in]     ipc         IPC handle
 * @param[in]     pt          handle of partition to check
 *
 * @return Returns a bool (SC_TRUE = started).
 *
 * Note this indicates if a partition was started. It does not indicate if a
 * partition is currently running or in a low power state.
 */
sc_bool_t sc_pm_is_partition_started(sc_ipc_t ipc, sc_rm_pt_t pt);

/* @} */

#endif /* SC_PM_API_H */

/**@}*/

