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 #ifndef MOD_DEBUG_H 9 #define MOD_DEBUG_H 10 11 #include <fwk_event.h> 12 #include <fwk_id.h> 13 #include <fwk_module_idx.h> 14 15 #include <stdint.h> 16 17 /*! 18 * \ingroup GroupModules 19 * \defgroup GroupDebug Debug HAL 20 * \{ 21 */ 22 23 /*! 24 * \brief Debug events public indices. 25 */ 26 enum mod_debug_public_event_idx { 27 MOD_DEBUG_PUBLIC_EVENT_IDX_REQ_ENABLE_GET, 28 MOD_DEBUG_PUBLIC_EVENT_IDX_REQ_ENABLE_SET, 29 MOD_DEBUG_PUBLIC_EVENT_IDX_COUNT 30 }; 31 32 /*! 33 * \brief Debug subsystems end-users. 34 */ 35 enum scp_debug_user { 36 /*! Represents another module of the SCP firmware */ 37 SCP_DEBUG_USER_SCP, 38 39 /*! Represents an agent, the request comes from an AP */ 40 SCP_DEBUG_USER_AP, 41 42 /*! Represents a debug driver, the request comes from the hardware */ 43 SCP_DEBUG_USER_DAP, 44 45 /*! Number of SCP Debug users */ 46 SCP_DEBUG_USER_COUNT 47 }; 48 49 /*! 50 * \brief Debug API indices. 51 */ 52 enum mod_debug_api_idx { 53 /*! Index of the Debug HAL API */ 54 MOD_DEBUG_API_IDX_HAL, 55 56 /*! Index of the Driver input API */ 57 MOD_DEBUG_API_IDX_DRIVER_INPUT, 58 59 /*! Number of APIs for the Debug module*/ 60 MOD_DEBUG_API_IDX_COUNT, 61 }; 62 63 /*! 64 * \brief Debug element configuration data. 65 */ 66 struct mod_debug_dev_config { 67 /*! Identifier of the debug driver */ 68 fwk_id_t driver_id; 69 70 /*! Identifier of the debug driver api*/ 71 fwk_id_t driver_api_id; 72 }; 73 74 /*! 75 * \brief Debug API. 76 */ 77 struct mod_debug_api { 78 /*! 79 * \brief Enable or disable the Debug functionality. 80 * 81 * \param id Debug device identifier. 82 * 83 * \param enable Targeted state for Debug, true for enabled, false 84 * otherwise. 85 * 86 * \param user_id The user requesting the Debug functionality. 87 * 88 * \retval ::FWK_SUCCESS The operation succeeded. 89 * \retval ::FWK_PENDING The operation has been acknowledged. 90 * \retval ::FWK_E_PARAM One or more parameters were incorrect. 91 * \retval ::FWK_E_BUSY Another request is already being processed. 92 * \retval ::FWK_E_ACCESS The specified user doesn't have the permission to 93 * perform the requested action. 94 * \return One of the standard framework error codes. 95 */ 96 int (*set_enabled)(fwk_id_t id, bool enable, enum scp_debug_user user_id); 97 98 /*! 99 * \brief Get the status of the Debug functionality. 100 * 101 * \param id Debug device identifier. 102 * 103 * \param[out] enabled State of Debug, true for enabled, false 104 * otherwise. 105 * 106 * \param user_id The user requesting the Debug enabled status. 107 * 108 * \retval ::FWK_SUCCESS The operation succeeded. 109 * \retval ::FWK_PENDING The operation has been acknowledged. 110 * \retval ::FWK_E_PARAM One or more parameters were incorrect. 111 * \retval ::FWK_E_BUSY Another request is already being processed. 112 * \retval ::FWK_E_ACCESS The specified user doesn't have the permission to 113 * perform the requested action. 114 * \return One of the standard framework error codes. 115 */ 116 int (*get_enabled)(fwk_id_t id, bool *enabled, enum scp_debug_user user_id); 117 118 /*! 119 * \brief Reset the Debug functionality. 120 * 121 * \param id Debug device identifier. 122 * 123 * \retval ::FWK_E_SUPPORT The operation is not supported. 124 * \return One of the standard framework error codes. 125 */ 126 int (*reset)(fwk_id_t id); 127 128 /*! 129 * \brief Terminate the Debug functionality. 130 * 131 * \param id Debug device identifier. 132 * 133 * \retval ::FWK_E_SUPPORT The operation is not supported. 134 * \return One of the standard framework error codes. 135 */ 136 int (*end)(fwk_id_t id); 137 }; 138 139 /*! 140 * \brief Debug Driver API. 141 */ 142 struct mod_debug_driver_api { 143 /*! 144 * \brief Enable or disable the driver. 145 * 146 * \param id Debug driver identifier. 147 * 148 * \param enable Targeted state the driver true for enabled, false 149 * otherwise. 150 * 151 * \param user_id The user requesting the Debug driver functionality. 152 * 153 * \retval ::FWK_SUCCESS The operation succeeded. 154 * \retval ::FWK_PENDING The operation has been acknowledged. 155 * \retval ::FWK_E_BUSY Another request is already being processed. 156 * \return One of the standard framework error codes. 157 */ 158 int (*set_enabled)(fwk_id_t id, bool enable, enum scp_debug_user user_id); 159 160 /*! 161 * \brief Get the status of the driver. 162 * 163 * \param id Debug driver identifier. 164 * 165 * \param[out] enabled State of Debug, true for enabled, false 166 * otherwise. 167 * 168 * \param user_id The user requesting the Debug driver enabled status. 169 * 170 * \retval ::FWK_SUCCESS The operation succeeded. 171 * \retval ::FWK_PENDING The operation has been acknowledged. 172 * \retval ::FWK_E_BUSY Another request is already being processed. 173 * \return One of the standard framework error codes. 174 */ 175 int (*get_enabled)(fwk_id_t id, bool *enabled, enum scp_debug_user user_id); 176 }; 177 178 /*! 179 * \brief Parameters of the response event. 180 */ 181 struct mod_debug_response_params { 182 /*! 183 * \brief Status of the operation requested. 184 */ 185 int status; 186 187 /*! 188 * \brief Status of the Debug. 189 */ 190 bool enabled; 191 }; 192 193 /*! 194 * \brief Debug Driver Input API. 195 */ 196 struct mod_debug_driver_input_api { 197 /*! 198 * \brief Signal the module of a Debug Power request. 199 * This call is expected to come from the DAP user. 200 * 201 * \param id Debug driver identifier. 202 * 203 * \param enable Perform the request in enable or disable mode. 204 * 205 * \param user_id The requesting user. 206 * 207 * \retval ::FWK_SUCCESS The operation succeeded. 208 * \return One of the standard framework error codes. 209 */ 210 int (*enable)(fwk_id_t id, bool enable, enum scp_debug_user user_id); 211 212 /*! 213 * \brief Signal the module that the request has been completed. 214 * 215 * \param id Debug driver identifier. 216 * 217 * \param response The response data structure. 218 */ 219 void (*request_complete)(fwk_id_t id, 220 struct mod_debug_response_params *response); 221 }; 222 223 /*! 224 * \brief Get enable event identifier. 225 * 226 * \details Clients which expect to receive a response event from this module 227 * should use this identifier to properly identify the response. 228 */ 229 static const fwk_id_t mod_debug_event_id_req_enable_get = 230 FWK_ID_EVENT_INIT(FWK_MODULE_IDX_DEBUG, 231 MOD_DEBUG_PUBLIC_EVENT_IDX_REQ_ENABLE_GET); 232 233 /*! 234 * \brief Set enable event identifier. 235 * 236 * \details Clients which expect to receive a response event from this module 237 * should use this identifier to properly identify the response. 238 */ 239 static const fwk_id_t mod_debug_event_id_req_enable_set = 240 FWK_ID_EVENT_INIT(FWK_MODULE_IDX_DEBUG, 241 MOD_DEBUG_PUBLIC_EVENT_IDX_REQ_ENABLE_SET); 242 243 /*! 244 * \} 245 */ 246 #endif /* MOD_DEBUG_H */ 247