1 /*
2  * Arm SCP/MCP Software
3  * Copyright (c) 2015-2021, Arm Limited and Contributors. All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  */
7 
8 #ifndef MOD_SCMI_SYSTEM_POWER_H
9 #define MOD_SCMI_SYSTEM_POWER_H
10 
11 #include <fwk_id.h>
12 
13 #include <stdint.h>
14 
15 /*!
16  * \addtogroup GroupModules Modules
17  * \{
18  */
19 
20 /*!
21  * \defgroup GroupSCMI_SYS SCMI System Power Management Protocol
22  * \{
23  */
24 
25 /*!
26  * \brief SCMI system views.
27  */
28 enum mod_scmi_system_view {
29     /*! OSPM view of the system */
30     MOD_SCMI_SYSTEM_VIEW_OSPM,
31 
32     /*! Full view of the system */
33     MOD_SCMI_SYSTEM_VIEW_FULL,
34 
35     MOD_SCMI_SYSTEM_VIEW_COUNT,
36 };
37 
38 /*!
39  * \brief SCMI System Power Management Protocol configuration data.
40  */
41 struct mod_scmi_system_power_config {
42     /*! System view */
43     enum mod_scmi_system_view system_view;
44 
45     /*!
46      * \brief Identifier of the power domain to target for a system wake-up.
47      *
48      * \note This is only used with the OSPM view.
49      */
50     fwk_id_t wakeup_power_domain_id;
51 
52     /*!
53      * \brief Composite state for a system wake-up.
54      *
55      * \note This is only used with the OSPM view.
56      */
57     uint32_t wakeup_composite_state;
58 
59     /*!
60      * \brief System suspend state.
61      */
62     unsigned int system_suspend_state;
63 
64     /*!
65      * \brief Identifier of the alarm for graceful request timeout.
66      *
67      * \note This alarm is optional, if it is not used it must be set to
68      * FWK_ID_NONE
69      */
70     fwk_id_t alarm_id;
71 
72     /*!
73      * Timeout period to wait for graceful response (milliseconds)
74      */
75     uint32_t graceful_timeout;
76 };
77 
78 /*!
79  * \defgroup GroupScmiSystemPowerPolicyHandlers Policy Handlers
80  *
81  * \brief SCMI System Power Policy Handlers.
82  *
83  * \details The SCMI policy handlers are weak definitions to allow a platform
84  *      to implement a policy appropriate to that platform. The SCMI
85  *      system power policy functions may be overridden in the
86  *      `product/<platform>/src` directory.
87  *
88  * \note The `state` data may be modified by the policy handler.
89  * \note See `product/juno/src/juno_scmi_clock.c` for an example policy
90  *      handler.
91  *
92  * \{
93  */
94 
95 /*!
96  * \brief Policy handler policies.
97  *
98  * \details These values are returned to the message handler by the policy
99  *      handlers to determine whether the message handler should continue
100  *      processing the message, or whether the request has been rejected.
101  */
102 enum mod_scmi_sys_power_policy_status {
103     /*! Do not execute the message handler */
104     MOD_SCMI_SYS_POWER_SKIP_MESSAGE_HANDLER,
105 
106     /*! Execute the message handler */
107     MOD_SCMI_SYS_POWER_EXECUTE_MESSAGE_HANDLER,
108 };
109 
110 /*!
111  * \brief SCMI System Power State Set command policy.
112  *
113  * \details This function determines whether the SCMI message handler should
114  *      allow or reject a given SCMI  System Power State Set command.
115  *
116  *      The SCMI policy handler is executed before the message handler is
117  *      called. The SCMI protocol message handler will only continue if the
118  *      policy handler both returns ::FWK_SUCCESS and sets the policy status to
119  *      ::MOD_SCMI_CLOCK_EXECUTE_MESSAGE_HANDLER.
120  *
121  *      The SCMI policy handlers have default weak implementations that allow a
122  *      platform to implement a policy appropriate for that platform.
123  *
124  * \note See `product/juno/src/juno_scmi_clock.c` for an example policy
125  *      handler.
126  *
127  * \param[out] policy_status Whether the command should be accepted or not.
128  * \param[in, out] state Pointer to the requested state.
129  * \param[in] service_id Identifier of the service requesting the change.
130  * \param[in] graceful The set state request is graceful or not.
131  *
132  * \retval ::FWK_SUCCESS The operation succeeded.
133  *
134  * \return Status code representing the result of the operation.
135  */
136 int scmi_sys_power_state_set_policy(
137     enum mod_scmi_sys_power_policy_status *policy_status,
138     uint32_t *state,
139     fwk_id_t service_id,
140     bool graceful);
141 
142 /*!
143  * \}
144  */
145 
146 /*!
147  * \}
148  */
149 
150 /*!
151  * \}
152  */
153 
154 #endif /* MOD_SCMI_SYSTEM_POWER_H */
155