1 // Copyright 2020 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://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, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 15 // This file describes Pigweed's public user-facing logging API. 16 // 17 // THIS PUBLIC API IS NOT STABLE OR COMPLETE! 18 // 19 // Key functionality is still missing: 20 // 21 // - API for controlling verbosity at run time 22 // - API for querying if logging is enabled for the given level or flags 23 // 24 #pragma once 25 26 #include "pw_log/levels.h" 27 #include "pw_log/options.h" 28 29 // log_backend.h must ultimately resolve to a header that implements the macros 30 // required by the logging facade, as described below. 31 // 32 // Inputs: Macros the downstream user provides to control the logging system: 33 // 34 // PW_LOG_MODULE_NAME 35 // - The module name the backend should use 36 // 37 // PW_LOG_LEVEL 38 // - General log level setting. By default, logs below this level are 39 // excluded from the build. 40 // 41 // Outputs: Macros log_backend.h is expected to provide: 42 // 43 // PW_LOG(level, flags, fmt, ...) 44 // - Required. 45 // Level - An integer level as defined by pw_log/levels.h 46 // Flags - Arbitrary flags the backend can leverage; user-defined. 47 // Example: HAS_PII - A log has personally-identifying data 48 // Example: HAS_DII - A log has device-identifying data 49 // Example: RELIABLE_DELIVERY - Ask backend to ensure the 50 // log is delivered; this may entail blocking other logs. 51 // Example: BEST_EFFORT - Don't deliver this log if it 52 // would mean blocking or dropping important-flagged logs 53 // 54 // PW_LOG_DEBUG(fmt, ...) 55 // PW_LOG_INFO(fmt, ...) 56 // PW_LOG_WARN(fmt, ...) 57 // PW_LOG_ERROR(fmt, ...) 58 // PW_LOG_CRITICAL(fmt, ...) 59 // - Optional. If not defined by the backend, the facade's default 60 // implementation defines these in terms of PW_LOG(). 61 // 62 #include "pw_log_backend/log_backend.h" 63 64 // The PW_LOG macro accepts the format string and its arguments in a variadic 65 // macro. The format string is not listed as a separate argument to avoid adding 66 // a comma after the format string when it has no arguments. 67 #ifndef PW_LOG 68 #define PW_LOG(level, module, flags, /* format string and arguments */...) \ 69 do { \ 70 if (PW_LOG_ENABLE_IF(level, module, flags)) { \ 71 PW_HANDLE_LOG(level, module, flags, __VA_ARGS__); \ 72 } \ 73 } while (0) 74 #endif // PW_LOG 75 76 // For backends that elect to only provide the general PW_LOG() macro and not 77 // specialized versions, define the standard PW_LOG_<level>() macros in terms 78 // of the general PW_LOG(). 79 #ifndef PW_LOG_DEBUG 80 #define PW_LOG_DEBUG(...) \ 81 PW_LOG(PW_LOG_LEVEL_DEBUG, PW_LOG_MODULE_NAME, PW_LOG_FLAGS, __VA_ARGS__) 82 #endif // PW_LOG_DEBUG 83 84 #ifndef PW_LOG_INFO 85 #define PW_LOG_INFO(...) \ 86 PW_LOG(PW_LOG_LEVEL_INFO, PW_LOG_MODULE_NAME, PW_LOG_FLAGS, __VA_ARGS__) 87 #endif // PW_LOG_INFO 88 89 #ifndef PW_LOG_WARN 90 #define PW_LOG_WARN(...) \ 91 PW_LOG(PW_LOG_LEVEL_WARN, PW_LOG_MODULE_NAME, PW_LOG_FLAGS, __VA_ARGS__) 92 #endif // PW_LOG_WARN 93 94 #ifndef PW_LOG_ERROR 95 #define PW_LOG_ERROR(...) \ 96 PW_LOG(PW_LOG_LEVEL_ERROR, PW_LOG_MODULE_NAME, PW_LOG_FLAGS, __VA_ARGS__) 97 #endif // PW_LOG_ERROR 98 99 #ifndef PW_LOG_CRITICAL 100 #define PW_LOG_CRITICAL(...) \ 101 PW_LOG(PW_LOG_LEVEL_CRITICAL, PW_LOG_MODULE_NAME, PW_LOG_FLAGS, __VA_ARGS__) 102 #endif // PW_LOG_CRITICAL 103 104 // Default: Number of bits available for the log flags 105 // 106 // All log statements have a flags field, and this define is the number of bits 107 // available for the flags. Some backends restrict this for better efficiency. 108 // By default, pick a restricted but large enough value to work for most cases. 109 #ifndef PW_LOG_FLAG_BITS 110 #define PW_LOG_FLAG_BITS 2 111 #endif // PW_LOG_FLAG_BITS 112