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 // For compatibility with code that uses the deprecated PW_LOG_USE_SHORT_NAMES 65 // and PW_LOG_USE_ULTRA_SHORT_NAMES, include the appropriate headers. 66 // TODO(hepler): Remove this workaround when all users have migrated. 67 #if defined(PW_LOG_USE_SHORT_NAMES) && PW_LOG_USE_SHORT_NAMES == 1 68 #include "pw_log/short.h" 69 #endif // PW_LOG_USE_SHORT_NAMES 70 71 #if defined(PW_LOG_USE_ULTRA_SHORT_NAMES) && PW_LOG_USE_ULTRA_SHORT_NAMES == 1 72 #include "pw_log/shorter.h" 73 #endif // PW_LOG_USE_ULTRA_SHORT_NAMES 74 75 #ifndef PW_LOG 76 #define PW_LOG(level, flags, message, ...) \ 77 do { \ 78 if (PW_LOG_ENABLE_IF(level, flags)) { \ 79 PW_HANDLE_LOG(level, flags, message, __VA_ARGS__); \ 80 } \ 81 } while (0) 82 #endif // PW_LOG 83 84 // For backends that elect to only provide the general PW_LOG() macro and not 85 // specialized versions, define the standard PW_LOG_<level>() macros in terms 86 // of the general PW_LOG(). 87 #ifndef PW_LOG_DEBUG 88 #define PW_LOG_DEBUG(message, ...) \ 89 PW_LOG(PW_LOG_LEVEL_DEBUG, PW_LOG_DEFAULT_FLAGS, message, __VA_ARGS__) 90 #endif // PW_LOG_DEBUG 91 92 #ifndef PW_LOG_INFO 93 #define PW_LOG_INFO(message, ...) \ 94 PW_LOG(PW_LOG_LEVEL_INFO, PW_LOG_DEFAULT_FLAGS, message, __VA_ARGS__) 95 #endif // PW_LOG_INFO 96 97 #ifndef PW_LOG_WARN 98 #define PW_LOG_WARN(message, ...) \ 99 PW_LOG(PW_LOG_LEVEL_WARN, PW_LOG_DEFAULT_FLAGS, message, __VA_ARGS__) 100 #endif // PW_LOG_WARN 101 102 #ifndef PW_LOG_ERROR 103 #define PW_LOG_ERROR(message, ...) \ 104 PW_LOG(PW_LOG_LEVEL_ERROR, PW_LOG_DEFAULT_FLAGS, message, __VA_ARGS__) 105 #endif // PW_LOG_ERROR 106 107 #ifndef PW_LOG_CRITICAL 108 #define PW_LOG_CRITICAL(message, ...) \ 109 PW_LOG(PW_LOG_LEVEL_CRITICAL, PW_LOG_DEFAULT_FLAGS, message, __VA_ARGS__) 110 #endif // PW_LOG_CRITICAL 111 112 // Default: Number of bits available for the log level 113 // 114 // All log statements have a level, and this define is the number of bits 115 // available for the level. Some backends restrict this for better efficiency. 116 // By default, pick a restricted but large enough value to work for most cases. 117 #ifndef PW_LOG_LEVEL_BITS 118 #define PW_LOG_LEVEL_BITS 6 119 #endif // PW_LOG_LEVEL_BITS 120 121 // Default: Number of bits available for the log flags 122 // 123 // All log statements have a flags field, and this define is the number of bits 124 // available for the flags. Some backends restrict this for better efficiency. 125 // By default, pick a restricted but large enough value to work for most cases. 126 #ifndef PW_LOG_FLAG_BITS 127 #define PW_LOG_FLAG_BITS 10 128 #endif // PW_LOG_FLAG_BITS 129