1 /* 2 * Arm SCP/MCP Software 3 * Copyright (c) 2022, Arm Limited and Contributors. All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Description: 8 * System Control and Management Interface (SCMI) unit test support. 9 */ 10 #include <mod_scmi.h> 11 12 /*! 13 * \brief (UNIT Tests) SCMI module to transport entity API 14 */ 15 16 /*! 17 * \brief Check whether a channel is secure or non-secure. 18 * 19 * \param channel_id Channel identifier. 20 * \param[out] secure Channel security state. True if the channel 21 * is secure, or false if it is non-secure. 22 * 23 * \retval ::FWK_SUCCESS The operation succeeded. 24 * \retval ::FWK_E_PARAM An invalid parameter was encountered: 25 * - The `channel_id` parameter was not a valid system entity 26 * identifier. 27 * - The `secure` parameter was a null pointer value. 28 * \return One of the standard error codes for implementation-defined 29 * errors. 30 */ 31 int mod_scmi_to_transport_api_get_secure(fwk_id_t channel_id, bool *secure); 32 33 /*! 34 * \brief Get the maximum permitted payload size of a channel. 35 * 36 * \param channel_id Channel identifier. 37 * \param[out] size Maximum payload size in bytes. 38 * 39 * \retval ::FWK_SUCCESS The operation succeeded. 40 * \retval ::FWK_E_PARAM An invalid parameter was encountered: 41 * - The `channel_id` parameter was not a valid system entity 42 * identifier. 43 * - The `size` parameter was a null pointer value. 44 * \return One of the standard error codes for implementation-defined 45 * errors. 46 */ 47 int mod_scmi_to_transport_api_get_max_payload_size( 48 fwk_id_t channel_id, 49 size_t *size); 50 51 /*! 52 * \brief Get the SCMI message header from a channel. 53 * 54 * \param channel_id Channel identifier. 55 * \param[out] message_header SCMI message header. 56 * 57 * \retval ::FWK_SUCCESS The operation succeeded. 58 * \retval ::FWK_E_PARAM An invalid parameter was encountered: 59 * - The `channel_id` parameter was not a valid system entity 60 * identifier. 61 * - The `message_header` parameter was a null pointer value. 62 * \retval ::FWK_E_ACCESS No message is available to read. 63 * \return One of the standard error codes for implementation-defined 64 * errors. 65 */ 66 int mod_scmi_to_transport_api_get_message_header( 67 fwk_id_t channel_id, 68 uint32_t *message_header); 69 70 /*! 71 * \brief Get the SCMI payload from a channel. 72 * 73 * \param channel_id Channel identifier. 74 * \param[out] payload Pointer to the payload. 75 * \param[out] size Payload size. May be NULL, in which case the 76 * parameter should be ignored. 77 * 78 * \retval ::FWK_SUCCESS The operation succeeded. 79 * \retval ::FWK_E_PARAM An invalid parameter was encountered: 80 * - The `channel_id` parameter was not a valid system entity 81 * identifier. 82 * - The `payload` parameter was a null pointer value. 83 * - The `size` parameter was a null pointer value. 84 * \retval ::FWK_E_ACCESS No message is available to read. 85 * \return One of the standard error codes for implementation-defined 86 * errors. 87 */ 88 int mod_scmi_to_transport_api_get_payload( 89 fwk_id_t channel_id, 90 const void **payload, 91 size_t *size); 92 93 /*! 94 * \brief Write part of a payload to a channel. 95 * 96 * \param channel_id Channel identifier. 97 * \param offset Offset to begin writing at. 98 * \param payload Payload data to write. 99 * \param size Size of the payload data. 100 * 101 * \retval ::FWK_SUCCESS The operation succeeded. 102 * \retval ::FWK_E_PARAM An invalid parameter was encountered: 103 * - The `channel_id` parameter was not a valid system entity 104 * identifier. 105 * - The `payload` parameter was a null pointer value. 106 * - The offset and size provided are not within the bounds of the 107 * payload area. 108 * \return One of the standard error codes for implementation-defined 109 * errors. 110 */ 111 int mod_scmi_to_transport_api_write_payload( 112 fwk_id_t channel_id, 113 size_t offset, 114 const void *payload, 115 size_t size); 116 117 /*! 118 * \brief Respond to an SCMI message on a channel. 119 * 120 * \param channel_id Channel identifier. 121 * \param payload Payload data to write, or NULL if a payload has already 122 * been written. 123 * \param size Size of the payload source. 124 * 125 * \retval ::FWK_SUCCESS The operation succeeded. 126 * \retval ::FWK_E_PARAM An invalid parameter was encountered: 127 * - The `channel_id` parameter was not a valid system entity 128 * identifier. 129 * - The size given is less than the size of one paylout entry. 130 * \retval ::FWK_E_ACCESS No message is available to respond to. 131 * \return One of the standard error codes for implementation-defined 132 * errors. 133 */ 134 int mod_scmi_to_transport_api_respond( 135 fwk_id_t channel_id, 136 const void *payload, 137 size_t size); 138 139 /*! 140 * \brief Send a message on a channel. 141 * 142 * \param channel_id Channel identifier. 143 * \param message_header Message ID. 144 * \param payload Payload data to write. 145 * \param size Size of the payload source. 146 * 147 * \retval ::FWK_SUCCESS The operation succeeded. 148 * \retval ::FWK_E_PARAM An invalid parameter was encountered: 149 * - The `channel_id` parameter was not a valid system entity 150 * identifier. 151 * - The size given is less than the size of one paylout entry. 152 * \return One of the standard error codes for implementation-defined 153 * errors. 154 */ 155 int mod_scmi_to_transport_api_transmit( 156 fwk_id_t channel_id, 157 uint32_t message_header, 158 const void *payload, 159 size_t size, 160 bool request_ack_by_interrupt); 161 162 /*! 163 * \brief Release the transport channel context lock. 164 * 165 * \param channel_id Transport channel identifier. 166 * 167 * \retval ::FWK_SUCCESS The operation succeeded. 168 */ 169 int mod_scmi_to_transport_api_release_transport_channel_lock( 170 fwk_id_t channel_id); 171 172 /*! 173 * \brief Get the number of active agents. 174 * 175 * \param[out] agent_count Number of active agents. 176 * 177 * \retval ::FWK_SUCCESS The agent count was returned. 178 * \retval ::FWK_E_PARAM The parameter `agent_count` is equal to `NULL`. 179 */ 180 int mod_scmi_from_protocol_get_agent_count(unsigned int *agent_count); 181 182 /*! 183 * \brief Get the identifier of the agent associated with a service 184 * 185 * \param service_id Identifier of the service. 186 * \param[out] agent_id Agent identifier. 187 * 188 * \retval ::FWK_SUCCESS The agent identifier was returned. 189 * \retval ::FWK_E_PARAM An invalid parameter was encountered: 190 * - The `service_id` parameter was not a valid system entity 191 * identifier. 192 * - The `agent_id` parameter was a null pointer value. 193 * \retval ::FWK_E_INIT The service is not initialized. 194 * \retval ::FWK_E_STATE The service is in an invalid state. 195 */ 196 int mod_scmi_from_protocol_get_agent_id( 197 fwk_id_t service_id, 198 unsigned int *agent_id); 199 200 /*! 201 * \brief Get the type of the agent given its identifier. 202 * 203 * \details This API can be used by SCMI protocols to check the validity 204 * of an agent identifier. 205 * 206 * \param agent_id Identifier of the agent. 207 * \param[out] agent_type Agent type. 208 * 209 * \retval ::FWK_SUCCESS The agent identifier was returned. 210 * \retval ::FWK_E_PARAM An invalid parameter was encountered: 211 * - The `agent_id` parameter was not a valid system entity 212 * identifier. 213 * - The `agent_type` parameter was a null pointer value. 214 */ 215 int mod_scmi_from_protocol_get_agent_type( 216 uint32_t agent_id, 217 enum scmi_agent_type *agent_type); 218 219 /*! 220 * \brief Get the maximum permitted payload size of a channel associated 221 * with a service. 222 * 223 * \param service_id Service identifier. 224 * \param[out] size Maximum payload size in bytes. 225 * 226 * \retval ::FWK_SUCCESS The operation succeeded. 227 * \retval ::FWK_E_PARAM An invalid parameter was encountered: 228 * - The `service_id` parameter was not a valid system entity 229 * identifier. 230 * - The `size` parameter was a null pointer value. 231 * \retval ::FWK_E_INIT The service is not initialized. 232 * \retval ::FWK_E_STATE The service is in an invalid sate. 233 * \return One of the standard error codes for implementation-defined 234 * errors. 235 */ 236 int mod_scmi_from_protocol_get_max_payload_size( 237 fwk_id_t service_id, 238 size_t *size); 239 240 /*! 241 * \brief Write part of a payload through a service. 242 * 243 * \param service_id Service identifier. 244 * \param offset Offset to begin writing at. 245 * \param payload Payload data to write. 246 * \param size Size of the payload data. 247 * 248 * \retval ::FWK_SUCCESS The operation succeeded. 249 * \retval ::FWK_E_PARAM An invalid parameter was encountered: 250 * - The `service_id` parameter was not a valid system entity 251 * identifier. 252 * - The offset and size given were not within the bounds of the 253 * payload area. 254 * \return One of the standard error codes for implementation-defined 255 * errors. 256 */ 257 int mod_scmi_from_protocol_write_payload( 258 fwk_id_t service_id, 259 size_t offset, 260 const void *payload, 261 size_t size); 262 263 /*! 264 * \brief Respond to an SCMI message on a service. 265 * 266 * \param service_id Service identifier. 267 * \param payload Payload data to write, or NULL if a payload has already 268 * been written. 269 * \param size Size of the payload. 270 */ 271 int mod_scmi_from_protocol_respond( 272 fwk_id_t service_id, 273 const void *payload, 274 size_t size); 275 276 /*! 277 * \brief Send a notification to the agent on behalf on an SCMI service. 278 * 279 * \param service_id Service identifier. 280 * \param protocol_id Protocol identifier. 281 * \param message_id Message identifier. 282 * \param payload Payload data to write, or NULL if a payload has already 283 * been written. 284 * \param size Size of the payload in bytes. 285 */ 286 void mod_scmi_from_protocol_notify( 287 fwk_id_t service_id, 288 int protocol_id, 289 int message_id, 290 const void *payload, 291 size_t size); 292 293 /*! 294 * \brief Send an SCMI message 295 * 296 * \param scmi_message_id SCMI message identifier. 297 * \param scmi_protocol_id SCMI message protocol identifier. 298 * \param token SCMI message token. 299 * \param service_id SCMI service identifier. 300 * \param payload Payload data to write 301 * \param payload_size size of the payload in bytes. 302 * \param request_ack_by_interrupt flag to select whether acknowledgement 303 * interrupt is required for this message. 304 */ 305 int mod_scmi_from_protocol_send_message( 306 uint8_t scmi_message_id, 307 uint8_t scmi_protocol_id, 308 uint8_t token, 309 fwk_id_t service_id, 310 const void *payload, 311 size_t payload_size, 312 bool request_ack_by_interrupt); 313 314 /*! 315 * \brief Handle response SCMI message 316 * 317 * \param service_id Service identifier. 318 * 319 * \retval ::FWK_SUCCESS The operation succeeded. 320 */ 321 int mod_scmi_from_protocol_response_message_handler(fwk_id_t service_id); 322