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/config.h" 27 #include "pw_log/levels.h" 28 #include "pw_log/options.h" 29 30 // log_backend.h must ultimately resolve to a header that implements the macros 31 // required by the logging facade, as described below. 32 // 33 // Inputs: Macros the downstream user provides to control the logging system: 34 // 35 // PW_LOG_MODULE_NAME 36 // - The module name the backend should use 37 // 38 // PW_LOG_LEVEL 39 // - General log level setting. By default, logs below this level are 40 // excluded from the build. 41 // 42 // Outputs: Macros log_backend.h is expected to provide: 43 // 44 // PW_LOG(level, verbosity, module, flags, fmt, ...) 45 // - Required. 46 // Level - An integer level as defined by pw_log/levels.h for this log. 47 // Verbosity - An integer level as defined by pw_log/levels.h which is the 48 // minimum level which is enabled. 49 // Module - A string literal for the module name. 50 // Flags - Arbitrary flags the backend can leverage; user-defined. 51 // Example: HAS_PII - A log has personally-identifying data 52 // Example: HAS_DII - A log has device-identifying data 53 // Example: RELIABLE_DELIVERY - Ask backend to ensure the 54 // log is delivered; this may entail blocking other logs. 55 // Example: BEST_EFFORT - Don't deliver this log if it 56 // would mean blocking or dropping important-flagged logs 57 // 58 // PW_LOG_DEBUG(fmt, ...) 59 // PW_LOG_INFO(fmt, ...) 60 // PW_LOG_WARN(fmt, ...) 61 // PW_LOG_ERROR(fmt, ...) 62 // PW_LOG_CRITICAL(fmt, ...) 63 // - Optional. If not defined by the backend, the facade's default 64 // implementation defines these in terms of PW_LOG(). 65 // 66 #include "pw_log_backend/log_backend.h" 67 68 // The PW_LOG macro accepts the format string and its arguments in a variadic 69 // macro. The format string is not listed as a separate argument to avoid adding 70 // a comma after the format string when it has no arguments. 71 #define PW_LOG( \ 72 level, verbosity, module, flags, /* format string and arguments */...) \ 73 do { \ 74 if (PW_LOG_ENABLE_IF(level, verbosity, module, flags)) { \ 75 PW_HANDLE_LOG(level, module, flags, __VA_ARGS__); \ 76 } \ 77 } while (0) 78 79 // For backends that elect to only provide the general PW_LOG() macro and not 80 // specialized versions, define the standard PW_LOG_<level>() macros in terms 81 // of the general PW_LOG(). 82 #ifndef PW_LOG_DEBUG 83 #define PW_LOG_DEBUG(...) \ 84 PW_LOG(PW_LOG_LEVEL_DEBUG, \ 85 PW_LOG_LEVEL, \ 86 PW_LOG_MODULE_NAME, \ 87 PW_LOG_FLAGS, \ 88 __VA_ARGS__) 89 #endif // PW_LOG_DEBUG 90 91 #ifndef PW_LOG_INFO 92 #define PW_LOG_INFO(...) \ 93 PW_LOG(PW_LOG_LEVEL_INFO, \ 94 PW_LOG_LEVEL, \ 95 PW_LOG_MODULE_NAME, \ 96 PW_LOG_FLAGS, \ 97 __VA_ARGS__) 98 #endif // PW_LOG_INFO 99 100 #ifndef PW_LOG_WARN 101 #define PW_LOG_WARN(...) \ 102 PW_LOG(PW_LOG_LEVEL_WARN, \ 103 PW_LOG_LEVEL, \ 104 PW_LOG_MODULE_NAME, \ 105 PW_LOG_FLAGS, \ 106 __VA_ARGS__) 107 #endif // PW_LOG_WARN 108 109 #ifndef PW_LOG_ERROR 110 #define PW_LOG_ERROR(...) \ 111 PW_LOG(PW_LOG_LEVEL_ERROR, \ 112 PW_LOG_LEVEL, \ 113 PW_LOG_MODULE_NAME, \ 114 PW_LOG_FLAGS, \ 115 __VA_ARGS__) 116 #endif // PW_LOG_ERROR 117 118 #ifndef PW_LOG_CRITICAL 119 #define PW_LOG_CRITICAL(...) \ 120 PW_LOG(PW_LOG_LEVEL_CRITICAL, \ 121 PW_LOG_LEVEL, \ 122 PW_LOG_MODULE_NAME, \ 123 PW_LOG_FLAGS, \ 124 __VA_ARGS__) 125 #endif // PW_LOG_CRITICAL 126 127 #ifndef PW_LOG_EVERY_N 128 #define PW_LOG_EVERY_N(level, rate, ...) \ 129 do { \ 130 static uint32_t _pw_log_suppressor##__LINE__ = 0; \ 131 if (_pw_log_suppressor##__LINE__ == 0) { \ 132 PW_LOG( \ 133 level, PW_LOG_LEVEL, PW_LOG_MODULE_NAME, PW_LOG_FLAGS, __VA_ARGS__); \ 134 _pw_log_suppressor##__LINE__ = rate; \ 135 } else { \ 136 _pw_log_suppressor##__LINE__--; \ 137 } \ 138 } while (0) 139 #endif // PW_LOG_EVERY_N 140 141 // Default: Number of bits available for the log flags 142 // 143 // All log statements have a flags field, and this define is the number of bits 144 // available for the flags. Some backends restrict this for better efficiency. 145 // By default, pick a restricted but large enough value to work for most cases. 146 #ifndef PW_LOG_FLAG_BITS 147 #define PW_LOG_FLAG_BITS 2 148 #endif // PW_LOG_FLAG_BITS 149