1 /* 2 * Arm SCP/MCP Software 3 * Copyright (c) 2019-2021, Arm Limited and Contributors. All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Description: 8 * SCMI Reset Domain Protocol Support. 9 */ 10 11 #ifndef MOD_SCMI_RESET_DOMAIN_H 12 #define MOD_SCMI_RESET_DOMAIN_H 13 14 #include <fwk_id.h> 15 #include <mod_reset_domain.h> 16 #include <stdint.h> 17 #include <stdlib.h> 18 19 /*! 20 * \ingroup GroupModules Modules 21 * \defgroup GroupSCMI_RESET SCMI Reset Domain Management Protocol 22 * \{ 23 */ 24 25 /*! 26 * \brief Permission flags governing the ability to use certain SCMI commands 27 * to interact with a reset domain. 28 * 29 * \details Setting a permission flag for a reset domain enables the 30 * corresponding functionality for any agent that has visibilty of the 31 * reset domain through it's reset domain device table. 32 */ 33 enum mod_scmi_reset_domain_permissions { 34 /*! No permissions (at least one must be granted) */ 35 MOD_SCMI_RESET_DOMAIN_PERM_INVALID = 0, 36 37 /*! The reset domain's attributes can be queried */ 38 MOD_SCMI_RESET_DOMAIN_PERM_ATTRIBUTES = (1 << 0), 39 40 /*! The permission to reset the domain */ 41 MOD_SCMI_RESET_DOMAIN_PERM_RESET = (1 << 1), 42 }; 43 44 /*! 45 * \brief Reset domain device. 46 * 47 * \details Reset domain device structures are used in per-agent reset device 48 * tables. Each contains an identifier of an element that will be bound 49 * to in order to use the reset device. 50 */ 51 struct mod_scmi_reset_domain_device { 52 /*! 53 * \brief Reset element identifier. 54 * 55 * \details The module that owns the element must implement the Reset API 56 * that is defined by the \c reset module. 57 */ 58 fwk_id_t element_id; 59 60 /*! Mask of permission flags defined by reset domain configuration */ 61 uint8_t permissions; 62 63 }; 64 65 /*! 66 * \brief Agent descriptor. 67 * 68 * \details Describes an agent that uses the SCMI Reset Domain protocol. 69 * Provides a pointer to the agent's reset device table and the number of 70 * devices within the table. 71 */ 72 struct mod_scmi_reset_domain_agent { 73 /*! Pointer to a table of reset devices that are visible to the agent */ 74 const struct mod_scmi_reset_domain_device *device_table; 75 76 /*! 77 * \brief The number of \c mod_scmi_reset_domain_device structures in the 78 * table pointed to by \c device_table. 79 */ 80 uint8_t agent_domain_count; 81 }; 82 83 /*! 84 * \brief Module configuration. 85 */ 86 struct mod_scmi_reset_domain_config { 87 /*! 88 * \brief Pointer to the table of agent descriptors, used to provide 89 * per-agent views of reset in the system. 90 */ 91 const struct mod_scmi_reset_domain_agent *agent_table; 92 93 /*! Number of agents in ::mod_scmi_reset_domain_config::agent_table */ 94 unsigned int agent_count; 95 96 }; 97 98 /*! 99 * \brief SCMI Reset Domain APIs. 100 * 101 * \details APIs exported by SCMI Reset Domain Protocol. 102 */ 103 enum scmi_reset_domain_api_idx { 104 /*! Index for the SCMI protocol API */ 105 MOD_SCMI_RESET_DOMAIN_PROTOCOL_API, 106 107 /*! Number of APIs */ 108 MOD_SCMI_RESET_DOMAIN_API_COUNT 109 }; 110 111 /*! 112 * \defgroup GroupScmiResetDomainPolicyHandler Policy Handler 113 * 114 * \brief SCMI Reset Domain Policy Handler. 115 * 116 * \details The SCMI policy handlers are weak definitions to allow a platform 117 * to implement a policy appropriate to that platform. The SCMI 118 * reset domain policy functions may be overridden in the 119 * `product/<platform>/src` directory. 120 * 121 * \note The `mode`/`reset_state` values may be changed by the policy handler. 122 * \note See `product/juno/src/juno_scmi_clock.c` for an example policy 123 * handler. 124 * 125 * \{ 126 */ 127 128 /*! 129 * \brief Policy handler policies. 130 * 131 * \details These values are returned to the message handler by the policy 132 * handlers to determine whether the message handler should continue 133 * processing the message, or whether the request has been rejected. 134 */ 135 enum mod_scmi_reset_domain_policy_status { 136 /*! Do not execute the message handler */ 137 MOD_SCMI_RESET_DOMAIN_SKIP_MESSAGE_HANDLER, 138 139 /*! Execute the message handler */ 140 MOD_SCMI_RESET_DOMAIN_EXECUTE_MESSAGE_HANDLER, 141 }; 142 143 /*! 144 * 145 * \brief SCMI Reset Domain Reset Request command policy. 146 * 147 * \details This function determines whether the SCMI message handler should 148 * allow or reject the SCMI Reset Domain reset_request command. 149 * 150 * The SCMI policy handler is executed before the message handler is 151 * called. The SCMI protocol message handler will only continue if the 152 * policy handler both returns ::FWK_SUCCESS and sets the policy status to 153 * ::MOD_SCMI_RESET_DOMAIN_EXECUTE_MESSAGE_HANDLER. 154 * 155 * \param[out] policy_status Whether the command should be accepted or not. 156 * \param[in, out] mode Reset domain mode. 157 * \param[in, out] reset_state Reset domain state as defined in SCMIv2 158 * specification. 159 * \param[in] agent_id Identifier of the agent requesting the service. 160 * \param[in] domain_id Identifier of the reset domain. 161 * 162 * \retval ::FWK_SUCCESS The operation succeeded. 163 * 164 * \return Status code representing the result of the operation. 165 */ 166 int scmi_reset_domain_reset_request_policy( 167 enum mod_scmi_reset_domain_policy_status *policy_status, 168 enum mod_reset_domain_mode *mode, 169 uint32_t *reset_state, 170 uint32_t agent_id, 171 uint32_t domain_id); 172 /*! 173 * \} 174 */ 175 176 /*! 177 * \} 178 */ 179 180 #endif /* MOD_SCMI_RESET_DOMAIN_H */ 181