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