1 /** 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * Description: header file for diag api. 15 */ 16 17 #ifndef SOC_ZDIAG_H 18 #define SOC_ZDIAG_H 19 20 #include <stdint.h> 21 #include <stdbool.h> 22 #include "errcode.h" 23 #include "diag_config.h" 24 #include "common_def.h" 25 26 /** 27 * @defgroup include_middleware_utils_dfx_zdiag_api Diag 28 * @ingroup include_middleware_utils 29 * @{ 30 */ 31 32 /** 33 * @if Eng 34 * @brief Diag option. 35 * @else 36 * @brief option选项，当前存放对端地址 37 * @endif 38 */ 39 typedef struct { 40 diag_addr peer_addr; /*!< @if Eng peer addr. 41 @else 地址 @endif */ 42 uint8_t pad[3]; /*!< @if Eng pad. 43 @else 预留字段 @endif */ 44 } diag_option_t; 45 46 /** 47 * @if Eng 48 * @brief Init value of diag_option_t. 49 * @else 50 * @brief diag_option的初始值 51 * @endif 52 */ 53 #define DIAG_OPTION_INIT_VAL {0, {0, 0, 0}} 54 55 /** 56 * @if Eng 57 * @brief Pointer to zdiag cmd function. 58 * @else 59 * @brief diag命令行函数指针 60 * @endif 61 */ 62 typedef errcode_t (*zdiag_cmd_f)(uint16_t cmd_id, void *cmd_param, uint16_t cmd_param_size, diag_option_t *option); 63 64 /** 65 * @if Eng 66 * @brief Structure for registration command. 67 * @else 68 * @brief diag命令注册结构体 69 * @endif 70 */ 71 typedef struct { 72 uint16_t min_id; /*!< @if Eng Minimum DIAG ID. 73 @else Diag最小命令ID @endif */ 74 uint16_t max_id; /*!< @if Eng Maximum DIAG ID. 75 @else Diag最大命令ID @endif */ 76 zdiag_cmd_f fn_input_cmd; /*!< @if Eng This Handler is used to process the HSO command. 77 @else Diag命令处理函数 @endif */ 78 } zdiag_cmd_reg_obj_t; 79 80 /** 81 * @if Eng 82 * @brief Structure for statistics obj. 83 * @else 84 * @brief 统计量注册结构体 85 * @endif 86 */ 87 typedef struct { 88 uint16_t id; /*!< @if Eng Statistics ID. 89 @else 统计量ID @endif */ 90 uint16_t array_cnt; /*!< @if Eng Number of statistic structures. 91 @else 统计量数量 @endif */ 92 uint32_t stat_packet_size; /*!< @if Eng Size of a single statistic structure (unit: byte). 93 @else 每个统计量的大小 @endif */ 94 void *stat_packet; /*!< @if Eng Pointer to the statistic structure. 95 @else 指向统计量的指针 @endif */ 96 } zdiag_sys_stat_obj_t; 97 98 /** 99 * @if Eng 100 * @brief Structure for diag ack. 101 * @else 102 * @brief diag应答结构体 103 * @endif 104 */ 105 typedef struct { 106 uint16_t sn; /*!< @if Eng cmd sn. 107 @else 命令sn @endif */ 108 uint8_t ctrl; /*!< @if Eng ack mode. 109 @else 应答模式 @endif */ 110 uint8_t pad; 111 uint16_t cmd_id; /*!< @if Eng cmd id. 112 @else 应答id @endif */ 113 uint16_t param_size; /*!< @if Eng param size. 114 @else 应答内容大小 @endif */ 115 uint8_t *param; /*!< @if Eng data. 116 @else 应答内容 @endif */ 117 } msp_diag_ack_param_t; 118 119 /** 120 * @if Eng 121 * @brief Registers the command handling function. 122 * @par Description: The DIAG subsystem supports a function to register diag command. You can run 123 * uapi_zdiag_register_cmd to register new commands. 124 * @param [in] cmd_tbl Command table, which must be declared as a constant array 125 * and transmitted to this parameter. 126 * @param [in] cmd_num Number of commands. The value cannot be 0. 127 * @retval ERRCODE_SUCC Success 128 * @retval Others ERRCODE_FAIL or other error num. 129 * @par Depends: 130 * @li soc_zdiag.h 131 * @else 132 * @brief diag命令注册接口 133 * @par 说明: DIAG模块提供了diag命令行注册的功能. 用户可以调用uapi_zdiag_register_cmd函数注册新的命令 134 * @param [in] cmd_tbl diag命令注册表 135 * @param [in] cmd_num 命令条数 136 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 137 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值 138 * @par 依赖: 139 * @li soc_zdiag.h 140 * @endif 141 */ 142 errcode_t uapi_zdiag_register_cmd(const zdiag_cmd_reg_obj_t *cmd_tbl, uint16_t cmd_num); 143 144 /** 145 * @if Eng 146 * @brief Unregisters the command handling function. 147 * @par Description: The DIAG subsystem supports a function to unregister diag command. You can run 148 * uapi_zdiag_unregister_cmd to unregister new commands. 149 * @param [in] cmd_tbl Command table, which must be declared as a constant array 150 * and transmitted to this parameter. 151 * @param [in] cmd_num Number of commands. The value cannot be 0. 152 * @retval ERRCODE_SUCC Success 153 * @retval Others ERRCODE_FAIL or other error num. 154 * @par Depends: 155 * @li soc_zdiag.h 156 * @else 157 * @brief diag命令解注册接口 158 * @par 说明: DIAG模块提供了diag命令行解注册的功能. 用户可以调用uapi_zdiag_unregister_cmd函数可将已注册得命令行表清除 159 * @param [in] cmd_tbl diag命令注册表 160 * @param [in] cmd_num 命令条数 161 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 162 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值 163 * @par 依赖: 164 * @li soc_zdiag.h 165 * @endif 166 */ 167 errcode_t uapi_zdiag_unregister_cmd(const zdiag_cmd_reg_obj_t *cmd_tbl, uint16_t cmd_num); 168 169 /** 170 * @if Eng 171 * @brief Reports DIAG packets. 172 * @par Description: Reports DIAG channel packets to the DIAG client. 173 * @param [in] cmd_id DIAG data packet ID. For example, if the packet ID is the same as the command 174 * request ID, use the cmd_id parameter in the command callback function diag_cmd_f_prv. 175 * @param [in] option Use the option parameter notify the DIAG subsystem 176 * whether the packet is a local packet or a remote packet. 177 * @param [in] packet Buffer address of the data packet. 178 * @param [in] packet_size Data packet size (unit: byte). 179 * @param [in] sync Synchronous or asynchronous DIAG packet pushing. TRUE indicates that the 180 * packets are pushed synchronously and the operation is blocked. FALSE indicates the packets 181 * are pushed asynchronously (with the memory allocated, the packet is cashed by the OS queue 182 * before being pushed), and the operation is not blocked. 183 * @retval ERRCODE_SUCC Success 184 * @retval Others ERRCODE_FAIL or other error num. 185 * @par Depends: 186 * @li soc_zdiag.h 187 * @else 188 * @brief diag报文上报接口 189 * @par 说明: 上报报文给DIAG客户端 190 * @param [in] cmd_id 报文上报ID 191 * @param [in] option option选项，用来识别报文是本地报文还是远端报文 192 * @param [in] packet 数据包地址 193 * @param [in] packet_size 数据包大小 194 * @param [in] sync 上报方式，同步或者异步 195 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 196 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值 197 * @par 依赖: 198 * @li soc_zdiag.h 199 * @endif 200 */ 201 errcode_t uapi_zdiag_report_packet(uint16_t cmd_id, diag_option_t *option, const uint8_t *packet, uint16_t packet_size, 202 bool sync); 203 204 /** 205 * @if Eng 206 * @brief Reports multiple DIAG critical packets. 207 * @par Description: Reports multiple DIAG channel critical packets to the DIAG client. 208 * @param [in] cmd_id DIAG data packet ID. For example, if the packet ID is the same as the command 209 * request ID, use the cmd_id parameter in the command callback function diag_cmd_f_prv. 210 * @param [in] option Use the option parameter notify the DIAG subsystem 211 * whether the packet is a local packet or a remote packet. 212 * @param [in] packet the pointer to the buffer address of the data packet. 213 * @param [in] packet_size Data packet size (unit: byte). 214 * @param [in] pkt_cnt the number of packets 215 * @retval ERRCODE_SUCC Success 216 * @retval Others ERRCODE_FAIL or other error num. 217 * @par Depends: 218 * @li soc_zdiag.h 219 * @else 220 * @brief diag上报多个关键报文 221 * @par 说明: 上报多个关键报文给DIAG客户端 222 * @param [in] cmd_id 报文上报ID 223 * @param [in] option option选项，用来识别报文是本地报文还是远端报文 224 * @param [in] packet 指向数据指针数组的指针 225 * @param [in] packet_size 指向数据包大小数组的指针 226 * @param [in] pkt_cnt 数据包个数 227 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 228 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值 229 * @par 依赖: 230 * @li soc_zdiag.h 231 * @endif 232 */ 233 errcode_t uapi_zdiag_report_packets_critical(uint16_t cmd_id, diag_option_t *option, uint8_t **packet, 234 uint16_t *packet_size, uint8_t pkt_cnt); 235 236 /** 237 * @if Eng 238 * @brief Reports multiple DIAG normal packets. 239 * @par Description: Reports multiple DIAG channel normal packets to the DIAG client. 240 * @param [in] cmd_id DIAG data packet ID. For example, if the packet ID is the same as the command 241 * request ID, use the cmd_id parameter in the command callback function diag_cmd_f_prv. 242 * @param [in] option Use the option parameter notify the DIAG subsystem 243 * whether the packet is a local packet or a remote packet. 244 * @param [in] packet the pointer to the buffer address of the data packet. 245 * @param [in] packet_size Data packet size (unit: byte). 246 * @param [in] pkt_cnt the number of packets 247 * @retval ERRCODE_SUCC Success 248 * @retval Others ERRCODE_FAIL or other error num. 249 * @par Depends: 250 * @li soc_zdiag.h 251 * @else 252 * @brief diag上报多个普通报文 253 * @par 说明: 上报多个普通报文给DIAG客户端 254 * @param [in] cmd_id 报文上报ID 255 * @param [in] option option选项，用来识别报文是本地报文还是远端报文 256 * @param [in] packet 指向数据指针数组的指针 257 * @param [in] packet_size 指向数据包大小数组的指针 258 * @param [in] pkt_cnt 数据包个数 259 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 260 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值 261 * @par 依赖: 262 * @li soc_zdiag.h 263 * @endif 264 */ 265 errcode_t uapi_zdiag_report_packets_normal(uint16_t cmd_id, diag_option_t *option, uint8_t **packet, 266 uint16_t *packet_size, uint8_t pkt_cnt); 267 268 /** 269 * @if Eng 270 * @brief Reports message to the DIAG client 271 * @par Description: Reports message to the DIAG client 272 * @param [in] module_id The source module id of the print log. 273 * @param [in] msg_id The message id of the print log. 274 * @param [in] buf The print buffer. 275 * @param [in] buf_size The buffer size. 276 * @param [in] level The level of the print log. 277 * @retval ERRCODE_SUCC Success 278 * @retval Others ERRCODE_FAIL or other error num. 279 * @par Depends: 280 * @li soc_zdiag.h 281 * @else 282 * @brief 消息上报接口 283 * @par 说明: 上报消息给DIAG客户端 284 * @param [in] module_id 模块id 285 * @param [in] msg_id 消息id 286 * @param [in] buf 上报内容 287 * @param [in] buf_size 内容大小 288 * @param [in] level 日志级别 289 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 290 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值 291 * @par 依赖: 292 * @li soc_zdiag.h 293 * @endif 294 */ 295 errcode_t uapi_diag_report_sys_msg(uint32_t module_id, uint32_t msg_id, const uint8_t *buf, 296 uint16_t buf_size, uint8_t level); 297 298 /** 299 * @if Eng 300 * @brief Registers the ind handling function. 301 * @par Description: The DIAG subsystem supports a function to register ind. 302 * @param [in] cmd_tbl Command table, which must be declared as a constant array 303 * and transmitted to this parameter. 304 * @param [in] cmd_num Number of commands. 305 * @retval ERRCODE_SUCC Success 306 * @retval Others ERRCODE_FAIL or other error num. 307 * @par Depends: 308 * @li soc_zdiag.h 309 * @else 310 * @brief 应答注册接口 311 * @par 说明: diag模块提供应答注册函数 312 * @param [in] cmd_tbl 注册应答表 313 * @param [in] cmd_num 应答个数 314 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 315 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值 316 * @par 依赖: 317 * @li soc_zdiag.h 318 * @endif 319 */ 320 errcode_t uapi_zdiag_register_ind(const zdiag_cmd_reg_obj_t *cmd_tbl, uint16_t cmd_num); 321 322 /** 323 * @if Eng 324 * @brief Run cmd process func with cmd ID. 325 * @par Description: Run cmd process func with cmd ID. 326 * @param [in] cmd_id DIAG command request ID. 327 * @param [in] data Buffer address of the data packet. 328 * @param [in] data_size Data packet size (unit: byte). 329 * @param [in] option Use the option parameter notify the DIAG subsystem 330 * whether the packet is a local packet or a remote packet. 331 * @retval ERRCODE_SUCC Success 332 * @retval Others ERRCODE_FAIL or other error num. 333 * @par Depends: 334 * @li soc_zdiag.h 335 * @else 336 * @brief 命令执行接口 337 * @par 说明: 命令执行接口 338 * @param [in] cmd_id 命令ID 339 * @param [in] data 数据内容 340 * @param [in] data_size 数据大小 341 * @param [in] option option选项，用来识别报文是本地报文还是远端报文 342 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 343 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值 344 * @par 依赖: 345 * @li soc_zdiag.h 346 * @endif 347 */ 348 errcode_t uapi_diag_run_cmd(uint16_t cmd_id, uint8_t *data, uint16_t data_size, diag_option_t *option); 349 350 /** 351 * @if Eng 352 * @brief Reports ack packets. 353 * @par Description: Reports DIAG ack packets to the DIAG client. 354 * @param [in] ack ack param. 355 * @param [in] option Use the option parameter notify the DIAG subsystem 356 * whether the packet is a local packet or a remote packet. 357 * @retval ERRCODE_SUCC Success 358 * @retval Others ERRCODE_FAIL or other error num. 359 * @par Depends: 360 * @li soc_zdiag.h 361 * @else 362 * @brief ack数据包上报接口 363 * @par 说明: 上报ack数据包给DIAG客户端 364 * @param [in] ack ack内容 365 * @param [in] option option选项，用来识别报文是本地报文还是远端报文 366 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 367 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值 368 * @par 依赖: 369 * @li soc_zdiag.h 370 * @endif 371 */ 372 errcode_t uapi_zdiag_report_ack(msp_diag_ack_param_t *ack, diag_option_t *option); 373 374 /** 375 * @if Eng 376 * @brief Registers statistic objects handling function. 377 * @par Description: The DIAG subsystem supports a function to register statistic objects. You can run 378 * uapi_zdiag_register_stat_obj to register a new stat obj. 379 * @param [in] stat_obj_tbl Pointer to stat obj table, which must be declared 380 * as a constant array and transmitted to this parameter. 381 * @param [in] obj_num Number of objects. 382 * @retval ERRCODE_SUCC Success 383 * @retval Others ERRCODE_FAIL or other error num. 384 * @par Depends: 385 * @li soc_zdiag.h 386 * @else 387 * @brief 统计量注册接口 388 * @par 说明: DIAG模块提供了统计量注册函数, 用户可以调用uapi_zdiag_register_stat_obj接口注册新的统计量 389 * @param [in] stat_obj_tbl 统计量注册表 390 * @param [in] obj_num 统计量个数 391 * @retval ERRCODE_SUCC 成功返回#ERRCODE_SUCC 392 * @retval Others 失败返回#ERRCODE_FAIL或其他返回值 393 * @par 依赖: 394 * @li soc_zdiag.h 395 * @endif 396 */ 397 errcode_t uapi_zdiag_register_stat_obj(const zdiag_sys_stat_obj_t *stat_obj_tbl, uint16_t obj_num); 398 399 /** 400 * @} 401 */ 402 403 #endif /* SOC_ZDIAG_H */ 404