1 /*
2  * Arm SCP/MCP Software
3  * Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  *
7  */
8 
9 #ifndef MOD_SCMI_POWER_DOMAIN_H
10 #define MOD_SCMI_POWER_DOMAIN_H
11 
12 #include <fwk_id.h>
13 
14 #ifdef BUILD_HAS_MOD_DEBUG
15 
16 /*!
17  * \ingroup GroupModules Modules
18  * \defgroup GroupSCMIPowerDomain SCMI Power Domain
19  * \{
20  */
21 
22 /*!
23  * \brief SCMI Power domain module configuration.
24  */
25 struct mod_scmi_pd_config {
26 
27     /*!
28      * \brief Identifier of the debug power domain.
29      *
30      * \details This identifier is required only for platforms using the debug
31      *      module.
32      *
33      * \note Only one element is supported at the moment.
34      *
35      */
36     fwk_id_t debug_pd_id;
37 
38     /*!
39      * \brief Identifier of one the debug module devices.
40      *
41      * \details This identifier is required only for platforms using the debug
42      *      module.
43      */
44     fwk_id_t debug_id;
45 };
46 #endif
47 
48 /*!
49  * \defgroup GroupScmiPowerPolicyHandlers Policy Handlers
50  *
51  * \brief SCMI Power Policy Handlers.
52  *
53  * \details The SCMI policy handlers are weak definitions to allow a platform
54  *      to implement a policy appropriate to that platform. The SCMI
55  *      power domain policy functions may be overridden in the
56  *      `product/<platform>/src` directory.
57  *
58  * \note The `state` value may be changed by the policy handler.
59  * \note See `product/juno/src/juno_scmi_clock.c` for an example policy
60  *      handler.
61  *
62  * \{
63  */
64 
65 /*!
66  * \brief Policy handler policies.
67  *
68  * \details These values are returned to the message handler by the policy
69  *      handlers to determine whether the message handler should continue
70  *      processing the message, or whether the request has been rejected.
71  */
72 enum mod_scmi_pd_policy_status {
73     /*! Do not execute the message handler */
74     MOD_SCMI_PD_SKIP_MESSAGE_HANDLER,
75 
76     /*! Execute the message handler */
77     MOD_SCMI_PD_EXECUTE_MESSAGE_HANDLER,
78 };
79 
80 /*!
81  * \brief SCMI Power Domain State Set command policy.
82  *
83  * \details This function determines whether the SCMI message handler should
84  *      allow or reject a given SCMI Power Domain State Set command.
85  *
86  *      The SCMI policy handler is executed before the message handler is
87  *      called. The SCMI protocol message handler will only continue if the
88  *      policy handler both returns ::FWK_SUCCESS and sets the policy status to
89  *      ::MOD_SCMI_CLOCK_EXECUTE_MESSAGE_HANDLER.
90  *
91  *      The SCMI policy handlers have default weak implementations that allow a
92  *      platform to implement a policy appropriate for that platform.
93  *
94  * \note The state data may be changed by the policy handler.
95  *
96  * \note See `product/juno/src/juno_scmi_clock.c` for an example policy
97  *      handler.
98  *
99  * \param[out] policy_status Whether the command should be accepted or not.
100  * \param[in, out] state Pointer to the requested state.
101  * \param[in] agent_id Identifier of the agent requesting the service.
102  * \param[in] pd_id Element identifier of the power domain.
103  *
104  * \retval ::FWK_SUCCESS The operation succeeded.
105  *
106  * \return Status code representing the result of the operation.
107  */
108 int scmi_pd_power_state_set_policy(
109     enum mod_scmi_pd_policy_status *policy_status,
110     uint32_t *state,
111     unsigned int agent_id,
112     fwk_id_t pd_id);
113 
114 /*!
115  * \}
116  */
117 
118 #endif /* MOD_SCMI_POWER_DOMAIN_H */
119