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 /** Init */ 126 HILOG_MODULE_INIT, 127 /** OEM Customize */ 128 HILOG_MODULE_OEM_CUSTOMIZE = 32, 129 /** Maximum number of modules */ 130 HILOG_MODULE_MAX = 64 131 } HiLogModuleType; 132 133 typedef enum { 134 LOG_MULTI_PARA_0 = 0, 135 LOG_MULTI_PARA_1 = 1, 136 LOG_MULTI_PARA_2 = 2, 137 LOG_MULTI_PARA_3 = 3, 138 LOG_MULTI_PARA_4 = 4, 139 LOG_MULTI_PARA_5 = 5, 140 LOG_MULTI_PARA_MAX = 6 141 } LogMultiParaIndex; 142 143 #pragma pack(1) 144 typedef struct { 145 uint8 head; 146 uint8 module; 147 uint8 level : 4; 148 uint8 valueNumber : 4; 149 uint8 task; 150 uint32 time; /* seconds */ 151 uint16 milli; /* millisecond, 0-999 */ 152 const char *fmt; 153 } HiLogCommon; 154 155 typedef struct { 156 HiLogCommon commonContent; 157 uint32 values[LOG_MULTI_PARA_MAX]; 158 } HiLogContent; 159 #pragma pack() 160 161 /** 162 * @brief Registers module information with the logging system. 163 * 164 * When a new module is defined, you need to use this function to register the module information with the logging 165 * system. If not registered, the logs of this module will not be output. \n 166 * 167 * @param id Identifies the module to be registered. The module ID, which must be globally unique, is defined in 168 * {@link HiLogModuleType}. 169 * @param name Indicates the module name. The value must be a static string of up to 15 uppercase and lowercase letters. 170 * Variables cannot be passed as module names. 171 * @return Returns <b>TRUE</b> if the registration is successful; returns <b>FALSE</b> otherwise. 172 * @since 1.0 173 * @version 1.0 174 */ 175 boolean HiLogRegisterModule(uint16 id, const char *name); 176 177 /** 178 * @brief Obtains the name of a registered module by module ID. 179 * 180 * @param id Identifies the module. The module ID, which must be globally unique, is defined in {@link HiLogModuleType}. 181 * @return Returns the string pointer to the module name if obtained; returns an empty string if the module ID is 182 * invalid or does not exist. 183 * @since 1.0 184 * @version 1.0 185 */ 186 const char *HiLogGetModuleName(uint8 id); 187 188 /* 189 * Interface for printing basic logs. Use the macro definition interface instead of directly using this interface. 190 * @param module Module ID. 191 * @param level Log Level. 192 * @param nums Parameters automatically generated by macro. 193 * @param fmt Format string. 194 * @attention Do not use this interface directly, you should use the HILOG_XXX interface. 195 */ 196 void HiLogPrintf(uint8 module, uint8 level, const char *nums, 197 const char *fmt, ...); 198 199 /* 200 * Interface for flush logs before the system restarts. 201 * @param syncFlag indicates synchronised flush or asynchronous flush. 202 * @attention Use this interface to flush logs to the UART or the files. 203 */ 204 void HiLogFlush(boolean syncFlag); 205 206 /* 207 * Definitions for function Pointer. 208 * @param data HiLogContent pointer. 209 * @param len log data length. 210 * @return function handle result. If TRUE is returned, the platform does not process, 211 * else the platform continues to process. 212 */ 213 typedef boolean (*HilogProc)(const HiLogContent *hilogContent, uint32 len); 214 215 /* 216 * Interface for register the Hilog handle. 217 * @param func Function Pointer. 218 */ 219 void HiLogRegisterProc(HilogProc func); 220 221 /* * 222 * Interface for deregister the Hilog handle. 223 * */ 224 void HiLogUnRegisterProc(HilogProc func); 225 226 /* 227 * Interface for get the Hilog Output to UART or file. 228 * @return The the hilog output option. 229 */ 230 uint32 HiLogGetConfigOption(void); 231 232 #ifndef FILE_PROC_DEFINED 233 #define FILE_PROC_DEFINED 234 /** 235 * Callback function prototype for file processing. 236 * 237 * @param path the path of the file to be processed. 238 * @param type the type of the file to be processed. 239 * @param event the type of event that triggered the function. 0 for file full. 240 **/ 241 typedef void (*FileProc)(const char *path, uint8 type, uint8 event); 242 #endif 243 244 /** 245 * Add a monitoring function when hilog file is full. 246 * 247 * @param func callback function. 248 * @param dest hilog output target file path. 249 **/ 250 void HiLogFileAddWatcher(FileProc func, const char *dest); 251 252 /** 253 * Remove monitoring of hilog file. 254 * 255 * @param func callback function. 256 **/ 257 void HiLogFileRemoveWatcher(FileProc func); 258 259 /** 260 * Process files according to mode. 261 * 262 * @param dest hilog output target file path. 263 * @param mode file processing mode. 0 for copy hilog file to dest and keep the 264 * content in the source file, 1 for rename hilog file to dest. 265 * @return 0 if success, otherwise -1. 266 **/ 267 int HiLogFileProc(const char *dest, uint8 mode); 268 269 /** 270 * Lock the hilog output target file. 271 * 272 **/ 273 void HiLogOutputFileLock(void); 274 275 /** 276 * Unlock the hilog output target file. 277 * 278 **/ 279 void HiLogOutputFileUnLock(void); 280 281 /** 282 * @brief Defines the pre-compiled macro for log levels. 283 * 284 * By default, logs at all levels are output in the compilation phase. You can set this pre-compiled macro to a specific 285 * log level so that logs at levels lower than that level wil be shielded. 286 * For example, if you want to shield logs lower than the ERROR level, set this macro to <b>HILOG_LV_ERROR</b>. 287 * In this way, only functions for outputting ERROR- and FATAL-level logs are retained during compilation. 288 * If you set this macro to <b>HILOG_LV_MAX</b>, functions for outputting logs at all levels will be disabled. 289 * 290 * @since 1.0 291 * @version 1.0 292 */ 293 #ifndef HILOG_COMPILE_LEVEL 294 #define HILOG_COMPILE_LEVEL HILOG_LV_DEBUG 295 #endif 296 297 /** 298 * @brief Outputs debug logs. 299 * 300 * @param mod Identifies the module. The module ID, which must be globally unique, is defined in 301 * {@link HiLogModuleType}. 302 * @param fmt Indicates the formatted string of log content. 303 * <ul> 304 * <li>A maximum of six variable parameters are supported. </li> 305 * <li>The format specifier \%s is not supported. If it is used, this function will return unpredictable 306 * results. </li> 307 * <li>Each formatted log record allows for a maximum of 128 characters. If the length of a log record exceeds 308 * 128 characters, the log record cannot be output. </li> 309 * </ul> 310 * @since 1.0 311 * @version 1.0 312 */ 313 #if HILOG_COMPILE_LEVEL <= HILOG_LV_DEBUG 314 #define HILOG_DEBUG(mod, fmt, ...) HiLogPrintf(mod, HILOG_LV_DEBUG, FUN_ARG_NUM(__VA_ARGS__), fmt, ##__VA_ARGS__) 315 #else 316 #define HILOG_DEBUG(mod, fmt, ...) 317 #endif 318 319 /** 320 * @brief Outputs informational logs. 321 * 322 * @param mod Identifies the module. The module ID, which must be globally unique, is defined in 323 * {@link HiLogModuleType}. 324 * @param fmt Indicates the formatted string of log content. 325 * <ul> 326 * <li>A maximum of six variable parameters are supported. </li> 327 * <li>The format specifier \%s is not supported. If it is used, this function will return unpredictable 328 * results. </li> 329 * <li>Each formatted log record allows for a maximum of 128 characters. If the length of a log record exceeds 330 * 128 characters, the log record cannot be output. </li> 331 * </ul> 332 * @since 1.0 333 * @version 1.0 334 */ 335 #if HILOG_COMPILE_LEVEL <= HILOG_LV_INFO 336 #define HILOG_INFO(mod, fmt, ...) HiLogPrintf(mod, HILOG_LV_INFO, FUN_ARG_NUM(__VA_ARGS__), fmt, ##__VA_ARGS__) 337 #else 338 #define HILOG_INFO(mod, fmt, ...) 339 #endif 340 341 /** 342 * @brief Outputs warning logs. 343 * 344 * @param mod Identifies the module. The module ID, which must be globally unique, is defined in 345 * {@link HiLogModuleType}. 346 * @param fmt Indicates the formatted string of log content. 347 * <ul> 348 * <li>A maximum of six variable parameters are supported. </li> 349 * <li>The format specifier \%s is not supported. If it is used, this function will return unpredictable 350 * results. </li> 351 * <li>Each formatted log record allows for a maximum of 128 characters. If the length of a log record exceeds 352 * 128 characters, the log record cannot be output. </li> 353 * </ul> 354 * @since 1.0 355 * @version 1.0 356 */ 357 #if HILOG_COMPILE_LEVEL <= HILOG_LV_WARN 358 #define HILOG_WARN(mod, fmt, ...) HiLogPrintf(mod, HILOG_LV_WARN, FUN_ARG_NUM(__VA_ARGS__), fmt, ##__VA_ARGS__) 359 #else 360 #define HILOG_WARN(mod, fmt, ...) 361 #endif 362 363 /** 364 * @brief Outputs error logs. 365 * 366 * @param mod Identifies the module. The module ID, which must be globally unique, is defined in 367 * {@link HiLogModuleType}. 368 * @param fmt Indicates the formatted string of log content. 369 * <ul> 370 * <li>A maximum of six variable parameters are supported. </li> 371 * <li>The format specifier \%s is not supported. If it is used, this function will return unpredictable 372 * results. </li> 373 * <li>Each formatted log record allows for a maximum of 128 characters. If the length of a log record exceeds 374 * 128 characters, the log record cannot be output. </li> 375 * </ul> 376 * @since 1.0 377 * @version 1.0 378 */ 379 #if HILOG_COMPILE_LEVEL <= HILOG_LV_ERROR 380 #define HILOG_ERROR(mod, fmt, ...) HiLogPrintf(mod, HILOG_LV_ERROR, FUN_ARG_NUM(__VA_ARGS__), fmt, ##__VA_ARGS__) 381 #else 382 #define HILOG_ERROR(mod, fmt, ...) 383 #endif 384 385 /** 386 * @brief Outputs fatal logs. 387 * 388 * @param mod Identifies the module. The module ID, which must be globally unique, is defined in 389 * {@link HiLogModuleType}. 390 * @param fmt Indicates the formatted string of log content. 391 * <ul> 392 * <li>A maximum of six variable parameters are supported. </li> 393 * <li>The format specifier \%s is not supported. If it is used, this function will return unpredictable 394 * results. </li> 395 * <li>Each formatted log record allows for a maximum of 128 characters. If the length of a log record exceeds 396 * 128 characters, the log record cannot be output. </li> 397 * </ul> 398 * @since 1.0 399 * @version 1.0 400 */ 401 #if HILOG_COMPILE_LEVEL <= HILOG_LV_FATAL 402 #define HILOG_FATAL(mod, fmt, ...) HiLogPrintf(mod, HILOG_LV_FATAL, FUN_ARG_NUM(__VA_ARGS__), fmt, ##__VA_ARGS__) 403 #else 404 #define HILOG_FATAL(mod, fmt, ...) 405 #endif 406 407 /* 408 * Interface for printing hash logs. 409 * @param module Module ID. 410 * @param level Log Level. 411 * @param nums Parameters automatically generated by macro. 412 * @param hash Hash of printing string. 413 * @attention Never use this interface directly, only for hash tools. 414 */ 415 void HILOG_HashPrintf(uint8 module, uint8 level, const char *nums, uint32 hash, ...); 416 417 /* 418 * Interface for printing debug hash logs. 419 * @param module Module ID. 420 * @param level Log Level. 421 * @param nums Parameters automatically generated by macro. 422 * @param hash Hash of printing string. 423 * @attention Never use this interface directly, only for hash tools. 424 */ 425 #if HILOG_COMPILE_LEVEL <= HILOG_LV_DEBUG 426 #define HILOG_DEBUG_HASH(mod, hash, ...) \ 427 HILOG_HashPrintf(mod, HILOG_LV_DEBUG, FUN_ARG_NUM(__VA_ARGS__), hash, ##__VA_ARGS__) 428 #else 429 #define HILOG_DEBUG_HASH(mod, hash, ...) 430 #endif 431 432 /* 433 * Interface for printing info hash logs. 434 * @param module Module ID. 435 * @param level Log Level. 436 * @param nums Parameters automatically generated by macro. 437 * @param hash Hash of printing string. 438 * @attention Never use this interface directly, only for hash tools. 439 */ 440 #if HILOG_COMPILE_LEVEL <= HILOG_LV_INFO 441 #define HILOG_INFO_HASH(mod, hash, ...) \ 442 HILOG_HashPrintf(mod, HILOG_LV_INFO, FUN_ARG_NUM(__VA_ARGS__), hash, ##__VA_ARGS__) 443 #else 444 #define HILOG_INFO_HASH(mod, hash, ...) 445 #endif 446 447 /* 448 * Interface for printing warning hash logs. 449 * @param module Module ID. 450 * @param level Log Level. 451 * @param nums Parameters automatically generated by macro. 452 * @param hash Hash of printing string. 453 * @attention Never use this interface directly, only for hash tools. 454 */ 455 #if HILOG_COMPILE_LEVEL <= HILOG_LV_WARN 456 #define HILOG_WARN_HASH(mod, hash, ...) \ 457 HILOG_HashPrintf(mod, HILOG_LV_WARN, FUN_ARG_NUM(__VA_ARGS__), hash, ##__VA_ARGS__) 458 #else 459 #define HILOG_WARN_HASH(mod, hash, ...) 460 #endif 461 462 /* 463 * Interface for printing error hash logs. 464 * @param module Module ID. 465 * @param level Log Level. 466 * @param nums Parameters automatically generated by macro. 467 * @param hash Hash of printing string. 468 * @attention Never use this interface directly, only for hash tools. 469 */ 470 #if HILOG_COMPILE_LEVEL <= HILOG_LV_ERROR 471 #define HILOG_ERROR_HASH(mod, hash, ...) \ 472 HILOG_HashPrintf(mod, HILOG_LV_ERROR, FUN_ARG_NUM(__VA_ARGS__), hash, ##__VA_ARGS__) 473 #else 474 #define HILOG_ERROR_HASH(mod, hash, ...) 475 #endif 476 477 /* 478 * Interface for printing fatal hash logs. 479 * @param module Module ID. 480 * @param level Log Level. 481 * @param nums Parameters automatically generated by macro. 482 * @param hash Hash of printing string. 483 * @attention Never use this interface directly, only for hash tools. 484 */ 485 #if HILOG_COMPILE_LEVEL <= HILOG_LV_FATAL 486 #define HILOG_FATAL_HASH(mod, hash, ...) \ 487 HILOG_HashPrintf(mod, HILOG_LV_FATAL, FUN_ARG_NUM(__VA_ARGS__), hash, ##__VA_ARGS__) 488 #else 489 #define HILOG_FATAL_HASH(mod, hash, ...) 490 #endif 491 492 /* 493 * Interface for get hilog level 494 * @return Returns current hilog level. 495 */ 496 uint32 HiLogGetLogLevel(void); 497 498 /* 499 * Interface for set hilog level 500 * @param level identifies the level to be set 501 * @return Returns <b>TRUE</b> if setting log level is successful; returns <b>FALSE</b> otherwise. 502 */ 503 boolean HiLogSetLogLevel(uint8 level); 504 505 #ifdef __cplusplus 506 #if __cplusplus 507 } 508 #endif 509 #endif /* End of #ifdef __cplusplus */ 510 511 #endif /* End of #ifndef HOS_LITE_HIVIEW_LOG_H */ 512 /** @} */ 513