1 /* 2 * Copyright (c) 2020 Huawei Device Co., Ltd. 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 */ 15 16 /** 17 * @addtogroup hilog 18 * @{ 19 * 20 * @brief Provides logging functions. 21 * 22 * You can use this module to log code execution and locate code exceptions if any. 23 * This module collects, filters out, buffers, forwards, formats, and performs flow control on logs. 24 * 25 * @since 1.0 26 * @version 1.0 27 */ 28 29 /** 30 * @file hiview_log.h 31 * 32 * @brief Defines functions of the logging module. 33 * 34 * You can use these functions to output logs to locate code exceptions if any. 35 * Ensure that only valid logs are selected for output. If excessive logs are to be output or log levels specified 36 * for output are improper, flow control will be performed on logs and key logs may be filtered out. 37 * To reduce the OHOS resource usage, you need to register the information about modules requiring log output 38 * with the logging system before outputting logs. Logging functions for different levels (for example, 39 * {@link HILOG_LV_DEBUG}) are provided for ease in selecting logs at your desired level. 40 * 41 * @since 1.0 42 * @version 1.0 43 */ 44 45 #ifndef HOS_LITE_HIVIEW_LOG_H 46 #define HOS_LITE_HIVIEW_LOG_H 47 48 #include "ohos_types.h" 49 50 #ifdef __cplusplus 51 #if __cplusplus 52 extern "C" { 53 #endif 54 #endif /* End of #ifdef __cplusplus */ 55 56 extern const char * const FUN_ARG_S; 57 #define FUN_ARG_0 (&FUN_ARG_S[0]) 58 #define FUN_ARG_1 (&FUN_ARG_S[1]) 59 #define FUN_ARG_2 (&FUN_ARG_S[2]) 60 #define FUN_ARG_3 (&FUN_ARG_S[3]) 61 #define FUN_ARG_4 (&FUN_ARG_S[4]) 62 #define FUN_ARG_5 (&FUN_ARG_S[5]) 63 #define FUN_ARG_6 (&FUN_ARG_S[6]) 64 #define FUN_ARG_I (&FUN_ARG_S[7]) 65 #define FUN_ARG_NUM(...) ARGS_CHECK(FUN_ARG_NUM_(FUN_ARG_I, ##__VA_ARGS__, FUN_ARG_EX_())) 66 #define FUN_ARG_NUM_(...) FUN_ARG_EX(__VA_ARGS__) 67 #define FUN_ARG_EX(_0, _1, _2, _3, _4, _5, _6, N, ...) N 68 #define FUN_ARG_EX_() FUN_ARG_6, FUN_ARG_5, FUN_ARG_4, FUN_ARG_3, FUN_ARG_2, FUN_ARG_1, FUN_ARG_0 69 #define ARGS_CHECK(N) (TRUE ? N : FUN_ARG_I) 70 71 #define HILOG_LV_INVALID 0 72 #define HILOG_LV_DEBUG 1 73 #define HILOG_LV_INFO 2 74 #define HILOG_LV_WARN 3 75 #define HILOG_LV_ERROR 4 76 #define HILOG_LV_FATAL 5 77 #define HILOG_LV_MAX 6 78 #define SET_HASH_FLAG(val) ((val) | 0x8) 79 #define CHECK_HASH_FLAG(level_) (((level_) & 0x8) == 0x8) 80 #define CLEAR_HASH_FLAG(level_) ((level_) & 0x7) 81 82 /** 83 * @brief Enumerates logging module types. 84 * 85 * The module type must be globally unique. A maximum of 64 module types can be defined. 86 * 87 * @since 1.0 88 * @version 1.0 89 */ 90 typedef enum { 91 /** DFX */ 92 HILOG_MODULE_HIVIEW = 0, 93 /** System Ability Manager */ 94 HILOG_MODULE_SAMGR, 95 /** Update */ 96 HILOG_MODULE_UPDATE, 97 /** Ability Cross-platform Environment */ 98 HILOG_MODULE_ACE, 99 /** Third-party applications */ 100 HILOG_MODULE_APP, 101 /** Atomic Ability Framework */ 102 HILOG_MODULE_AAFWK, 103 /** Graphic */ 104 HILOG_MODULE_GRAPHIC, 105 /** Multimedia */ 106 HILOG_MODULE_MEDIA, 107 /** Distributed Schedule Service */ 108 HILOG_MODULE_DMS, 109 /** Sensors */ 110 HILOG_MODULE_SEN, 111 /** Security */ 112 HILOG_MODULE_SCY, 113 /** XTS */ 114 HILOG_MODULE_XTS, 115 /** SoftBus */ 116 HILOG_MODULE_SOFTBUS, 117 /** PowerMgr */ 118 HILOG_MODULE_POWERMGR, 119 /** UIKit */ 120 HILOG_MODULE_UIKIT, 121 /** Global sub-system */ 122 HILOG_MODULE_GLOBAL, 123 /** Data Manager */ 124 HILOG_MODULE_DATAMGR, 125 /** OEM Customize */ 126 HILOG_MODULE_OEM_CUSTOMIZE = 32, 127 /** Maximum number of modules */ 128 HILOG_MODULE_MAX = 64 129 } HiLogModuleType; 130 131 typedef enum { 132 LOG_MULTI_PARA_0 = 0, 133 LOG_MULTI_PARA_1 = 1, 134 LOG_MULTI_PARA_2 = 2, 135 LOG_MULTI_PARA_3 = 3, 136 LOG_MULTI_PARA_4 = 4, 137 LOG_MULTI_PARA_5 = 5, 138 LOG_MULTI_PARA_MAX = 6 139 } LogMultiParaIndex; 140 141 #pragma pack(1) 142 typedef struct { 143 uint8 head; 144 uint8 module; 145 uint8 level : 4; 146 uint8 valueNumber : 4; 147 uint8 task; 148 uint32 time; /* seconds */ 149 uint16 milli; /* millisecond, 0-999 */ 150 const char *fmt; 151 } HiLogCommon; 152 153 typedef struct { 154 HiLogCommon commonContent; 155 uint32 values[LOG_MULTI_PARA_MAX]; 156 } HiLogContent; 157 #pragma pack() 158 159 /** 160 * @brief Registers module information with the logging system. 161 * 162 * When a new module is defined, you need to use this function to register the module information with the logging 163 * system. If not registered, the logs of this module will not be output. \n 164 * 165 * @param id Identifies the module to be registered. The module ID, which must be globally unique, is defined in 166 * {@link HiLogModuleType}. 167 * @param name Indicates the module name. The value must be a static string of up to 15 uppercase and lowercase letters. 168 * Variables cannot be passed as module names. 169 * @return Returns <b>TRUE</b> if the registration is successful; returns <b>FALSE</b> otherwise. 170 * @since 1.0 171 * @version 1.0 172 */ 173 boolean HiLogRegisterModule(uint16 id, const char *name); 174 175 /** 176 * @brief Obtains the name of a registered module by module ID. 177 * 178 * @param id Identifies the module. The module ID, which must be globally unique, is defined in {@link HiLogModuleType}. 179 * @return Returns the string pointer to the module name if obtained; returns an empty string if the module ID is 180 * invalid or does not exist. 181 * @since 1.0 182 * @version 1.0 183 */ 184 const char *HiLogGetModuleName(uint8 id); 185 186 /* 187 * Interface for printing basic logs. Use the macro definition interface instead of directly using this interface. 188 * @param module Module ID. 189 * @param level Log Level. 190 * @param nums Parameters automatically generated by macro. 191 * @param fmt Format string. 192 * @attention Do not use this interface directly, you should use the HILOG_XXX interface. 193 */ 194 void HiLogPrintf(uint8 module, uint8 level, const char *nums, 195 const char *fmt, ...); 196 197 /* 198 * Interface for flush logs before the system restarts. 199 * @param syncFlag indicates synchronised flush or asynchronous flush. 200 * @attention Use this interface to flush logs to the UART or the files. 201 */ 202 void HiLogFlush(boolean syncFlag); 203 204 /* 205 * Definitions for function Pointer. 206 * @param data HiLogContent pointer. 207 * @param len log data length. 208 * @return function handle result. If TRUE is returned, the platform does not process, 209 * else the platform continues to process. 210 */ 211 typedef boolean (*HilogProc)(const HiLogContent *hilogContent, uint32 len); 212 213 /* 214 * Interface for register the Hilog handle. 215 * @param func Function Pointer. 216 */ 217 void HiLogRegisterProc(HilogProc func); 218 219 /* * 220 * Interface for deregister the Hilog handle. 221 * */ 222 void HiLogUnRegisterProc(HilogProc func); 223 224 /* 225 * Interface for get the Hilog Output to UART or file. 226 * @return The the hilog output option. 227 */ 228 uint32 HiLogGetConfigOption(void); 229 230 #ifndef FILE_PROC_DEFINED 231 #define FILE_PROC_DEFINED 232 /** 233 * Callback function prototype for file processing. 234 * 235 * @param path the path of the file to be processed. 236 * @param type the type of the file to be processed. 237 * @param event the type of event that triggered the function. 0 for file full. 238 **/ 239 typedef void (*FileProc)(const char *path, uint8 type, uint8 event); 240 #endif 241 242 /** 243 * Add a monitoring function when hilog file is full. 244 * 245 * @param func callback function. 246 * @param dest hilog output target file path. 247 **/ 248 void HiLogFileAddWatcher(FileProc func, const char *dest); 249 250 /** 251 * Remove monitoring of hilog file. 252 * 253 * @param func callback function. 254 **/ 255 void HiLogFileRemoveWatcher(FileProc func); 256 257 /** 258 * Process files according to mode. 259 * 260 * @param dest hilog output target file path. 261 * @param mode file processing mode. 0 for copy hilog file to dest and keep the 262 * content in the source file, 1 for rename hilog file to dest. 263 * @return 0 if success, otherwise -1. 264 **/ 265 int HiLogFileProc(const char *dest, uint8 mode); 266 267 /** 268 * Lock the hilog output target file. 269 * 270 **/ 271 void HiLogOutputFileLock(void); 272 273 /** 274 * Unlock the hilog output target file. 275 * 276 **/ 277 void HiLogOutputFileUnLock(void); 278 279 /** 280 * @brief Defines the pre-compiled macro for log levels. 281 * 282 * By default, logs at all levels are output in the compilation phase. You can set this pre-compiled macro to a specific 283 * log level so that logs at levels lower than that level wil be shielded. 284 * For example, if you want to shield logs lower than the ERROR level, set this macro to <b>HILOG_LV_ERROR</b>. 285 * In this way, only functions for outputting ERROR- and FATAL-level logs are retained during compilation. 286 * If you set this macro to <b>HILOG_LV_MAX</b>, functions for outputting logs at all levels will be disabled. 287 * 288 * @since 1.0 289 * @version 1.0 290 */ 291 #ifndef HILOG_COMPILE_LEVEL 292 #define HILOG_COMPILE_LEVEL HILOG_LV_DEBUG 293 #endif 294 295 /** 296 * @brief Outputs debug logs. 297 * 298 * @param mod Identifies the module. The module ID, which must be globally unique, is defined in 299 * {@link HiLogModuleType}. 300 * @param fmt Indicates the formatted string of log content. 301 * <ul> 302 * <li>A maximum of six variable parameters are supported. </li> 303 * <li>The format specifier \%s is not supported. If it is used, this function will return unpredictable 304 * results. </li> 305 * <li>Each formatted log record allows for a maximum of 128 characters. If the length of a log record exceeds 306 * 128 characters, the log record cannot be output. </li> 307 * </ul> 308 * @since 1.0 309 * @version 1.0 310 */ 311 #if HILOG_COMPILE_LEVEL <= HILOG_LV_DEBUG 312 #define HILOG_DEBUG(mod, fmt, ...) HiLogPrintf(mod, HILOG_LV_DEBUG, FUN_ARG_NUM(__VA_ARGS__), fmt, ##__VA_ARGS__) 313 #else 314 #define HILOG_DEBUG(mod, fmt, ...) 315 #endif 316 317 /** 318 * @brief Outputs informational logs. 319 * 320 * @param mod Identifies the module. The module ID, which must be globally unique, is defined in 321 * {@link HiLogModuleType}. 322 * @param fmt Indicates the formatted string of log content. 323 * <ul> 324 * <li>A maximum of six variable parameters are supported. </li> 325 * <li>The format specifier \%s is not supported. If it is used, this function will return unpredictable 326 * results. </li> 327 * <li>Each formatted log record allows for a maximum of 128 characters. If the length of a log record exceeds 328 * 128 characters, the log record cannot be output. </li> 329 * </ul> 330 * @since 1.0 331 * @version 1.0 332 */ 333 #if HILOG_COMPILE_LEVEL <= HILOG_LV_INFO 334 #define HILOG_INFO(mod, fmt, ...) HiLogPrintf(mod, HILOG_LV_INFO, FUN_ARG_NUM(__VA_ARGS__), fmt, ##__VA_ARGS__) 335 #else 336 #define HILOG_INFO(mod, fmt, ...) 337 #endif 338 339 /** 340 * @brief Outputs warning logs. 341 * 342 * @param mod Identifies the module. The module ID, which must be globally unique, is defined in 343 * {@link HiLogModuleType}. 344 * @param fmt Indicates the formatted string of log content. 345 * <ul> 346 * <li>A maximum of six variable parameters are supported. </li> 347 * <li>The format specifier \%s is not supported. If it is used, this function will return unpredictable 348 * results. </li> 349 * <li>Each formatted log record allows for a maximum of 128 characters. If the length of a log record exceeds 350 * 128 characters, the log record cannot be output. </li> 351 * </ul> 352 * @since 1.0 353 * @version 1.0 354 */ 355 #if HILOG_COMPILE_LEVEL <= HILOG_LV_WARN 356 #define HILOG_WARN(mod, fmt, ...) HiLogPrintf(mod, HILOG_LV_WARN, FUN_ARG_NUM(__VA_ARGS__), fmt, ##__VA_ARGS__) 357 #else 358 #define HILOG_WARN(mod, fmt, ...) 359 #endif 360 361 /** 362 * @brief Outputs error logs. 363 * 364 * @param mod Identifies the module. The module ID, which must be globally unique, is defined in 365 * {@link HiLogModuleType}. 366 * @param fmt Indicates the formatted string of log content. 367 * <ul> 368 * <li>A maximum of six variable parameters are supported. </li> 369 * <li>The format specifier \%s is not supported. If it is used, this function will return unpredictable 370 * results. </li> 371 * <li>Each formatted log record allows for a maximum of 128 characters. If the length of a log record exceeds 372 * 128 characters, the log record cannot be output. </li> 373 * </ul> 374 * @since 1.0 375 * @version 1.0 376 */ 377 #if HILOG_COMPILE_LEVEL <= HILOG_LV_ERROR 378 #define HILOG_ERROR(mod, fmt, ...) HiLogPrintf(mod, HILOG_LV_ERROR, FUN_ARG_NUM(__VA_ARGS__), fmt, ##__VA_ARGS__) 379 #else 380 #define HILOG_ERROR(mod, fmt, ...) 381 #endif 382 383 /** 384 * @brief Outputs fatal logs. 385 * 386 * @param mod Identifies the module. The module ID, which must be globally unique, is defined in 387 * {@link HiLogModuleType}. 388 * @param fmt Indicates the formatted string of log content. 389 * <ul> 390 * <li>A maximum of six variable parameters are supported. </li> 391 * <li>The format specifier \%s is not supported. If it is used, this function will return unpredictable 392 * results. </li> 393 * <li>Each formatted log record allows for a maximum of 128 characters. If the length of a log record exceeds 394 * 128 characters, the log record cannot be output. </li> 395 * </ul> 396 * @since 1.0 397 * @version 1.0 398 */ 399 #if HILOG_COMPILE_LEVEL <= HILOG_LV_FATAL 400 #define HILOG_FATAL(mod, fmt, ...) HiLogPrintf(mod, HILOG_LV_FATAL, FUN_ARG_NUM(__VA_ARGS__), fmt, ##__VA_ARGS__) 401 #else 402 #define HILOG_FATAL(mod, fmt, ...) 403 #endif 404 405 /* 406 * Interface for printing hash logs. 407 * @param module Module ID. 408 * @param level Log Level. 409 * @param nums Parameters automatically generated by macro. 410 * @param hash Hash of printing string. 411 * @attention Never use this interface directly, only for hash tools. 412 */ 413 void HILOG_HashPrintf(uint8 module, uint8 level, const char *nums, uint32 hash, ...); 414 415 /* 416 * Interface for printing debug hash logs. 417 * @param module Module ID. 418 * @param level Log Level. 419 * @param nums Parameters automatically generated by macro. 420 * @param hash Hash of printing string. 421 * @attention Never use this interface directly, only for hash tools. 422 */ 423 #if HILOG_COMPILE_LEVEL <= HILOG_LV_DEBUG 424 #define HILOG_DEBUG_HASH(mod, hash, ...) \ 425 HILOG_HashPrintf(mod, HILOG_LV_DEBUG, FUN_ARG_NUM(__VA_ARGS__), hash, ##__VA_ARGS__) 426 #else 427 #define HILOG_DEBUG_HASH(mod, hash, ...) 428 #endif 429 430 /* 431 * Interface for printing info hash logs. 432 * @param module Module ID. 433 * @param level Log Level. 434 * @param nums Parameters automatically generated by macro. 435 * @param hash Hash of printing string. 436 * @attention Never use this interface directly, only for hash tools. 437 */ 438 #if HILOG_COMPILE_LEVEL <= HILOG_LV_INFO 439 #define HILOG_INFO_HASH(mod, hash, ...) \ 440 HILOG_HashPrintf(mod, HILOG_LV_INFO, FUN_ARG_NUM(__VA_ARGS__), hash, ##__VA_ARGS__) 441 #else 442 #define HILOG_INFO_HASH(mod, hash, ...) 443 #endif 444 445 /* 446 * Interface for printing warning hash logs. 447 * @param module Module ID. 448 * @param level Log Level. 449 * @param nums Parameters automatically generated by macro. 450 * @param hash Hash of printing string. 451 * @attention Never use this interface directly, only for hash tools. 452 */ 453 #if HILOG_COMPILE_LEVEL <= HILOG_LV_WARN 454 #define HILOG_WARN_HASH(mod, hash, ...) \ 455 HILOG_HashPrintf(mod, HILOG_LV_WARN, FUN_ARG_NUM(__VA_ARGS__), hash, ##__VA_ARGS__) 456 #else 457 #define HILOG_WARN_HASH(mod, hash, ...) 458 #endif 459 460 /* 461 * Interface for printing error hash logs. 462 * @param module Module ID. 463 * @param level Log Level. 464 * @param nums Parameters automatically generated by macro. 465 * @param hash Hash of printing string. 466 * @attention Never use this interface directly, only for hash tools. 467 */ 468 #if HILOG_COMPILE_LEVEL <= HILOG_LV_ERROR 469 #define HILOG_ERROR_HASH(mod, hash, ...) \ 470 HILOG_HashPrintf(mod, HILOG_LV_ERROR, FUN_ARG_NUM(__VA_ARGS__), hash, ##__VA_ARGS__) 471 #else 472 #define HILOG_ERROR_HASH(mod, hash, ...) 473 #endif 474 475 /* 476 * Interface for printing fatal hash logs. 477 * @param module Module ID. 478 * @param level Log Level. 479 * @param nums Parameters automatically generated by macro. 480 * @param hash Hash of printing string. 481 * @attention Never use this interface directly, only for hash tools. 482 */ 483 #if HILOG_COMPILE_LEVEL <= HILOG_LV_FATAL 484 #define HILOG_FATAL_HASH(mod, hash, ...) \ 485 HILOG_HashPrintf(mod, HILOG_LV_FATAL, FUN_ARG_NUM(__VA_ARGS__), hash, ##__VA_ARGS__) 486 #else 487 #define HILOG_FATAL_HASH(mod, hash, ...) 488 #endif 489 490 /* 491 * Interface for get hilog level 492 * @return Returns current hilog level. 493 */ 494 uint32 HiLogGetLogLevel(void); 495 496 /* 497 * Interface for set hilog level 498 * @param level identifies the level to be set 499 * @return Returns <b>TRUE</b> if setting log level is successful; returns <b>FALSE</b> otherwise. 500 */ 501 boolean HiLogSetLogLevel(uint8 level); 502 503 #ifdef __cplusplus 504 #if __cplusplus 505 } 506 #endif 507 #endif /* End of #ifdef __cplusplus */ 508 509 #endif /* End of #ifndef HOS_LITE_HIVIEW_LOG_H */ 510 /** @} */ 511