Line data Source code
1 0 : /* 2 : * Copyright (c) 2018 Nordic Semiconductor ASA 3 : * 4 : * SPDX-License-Identifier: Apache-2.0 5 : */ 6 : #ifndef ZEPHYR_INCLUDE_LOGGING_LOG_CTRL_H_ 7 : #define ZEPHYR_INCLUDE_LOGGING_LOG_CTRL_H_ 8 : 9 : #include <zephyr/kernel.h> 10 : #include <zephyr/logging/log_backend.h> 11 : #include <zephyr/logging/log_msg.h> 12 : #include <zephyr/logging/log_internal.h> 13 : 14 : #ifdef __cplusplus 15 : extern "C" { 16 : #endif 17 : 18 : /** 19 : * @brief Logger 20 : * @defgroup logger Logger system 21 : * @since 1.13 22 : * @ingroup logging 23 : * @{ 24 : * @} 25 : */ 26 : 27 : /** 28 : * @brief Logger control API 29 : * @defgroup log_ctrl Logger control API 30 : * @since 1.13 31 : * @ingroup logger 32 : * @{ 33 : */ 34 : 35 0 : typedef log_timestamp_t (*log_timestamp_get_t)(void); 36 : 37 : /** @brief Function system initialization of the logger. 38 : * 39 : * Function is called during start up to allow logging before user can 40 : * explicitly initialize the logger. 41 : */ 42 1 : void log_core_init(void); 43 : 44 : /** 45 : * @brief Function for user initialization of the logger. 46 : * 47 : */ 48 1 : void log_init(void); 49 : 50 : /** @brief Trigger the log processing thread to process logs immediately. 51 : * 52 : * @note Function has no effect when CONFIG_LOG_MODE_IMMEDIATE is set. 53 : */ 54 1 : void log_thread_trigger(void); 55 : 56 : /** 57 : * @brief Function for providing thread which is processing logs. 58 : * 59 : * See CONFIG_LOG_PROCESS_TRIGGER_THRESHOLD. 60 : * 61 : * @note Function has asserts and has no effect when CONFIG_LOG_PROCESS_THREAD is set. 62 : * 63 : * @param process_tid Process thread id. Used to wake up the thread. 64 : */ 65 1 : void log_thread_set(k_tid_t process_tid); 66 : 67 : /** 68 : * @brief Function for providing timestamp function. 69 : * 70 : * @param timestamp_getter Timestamp function. 71 : * @param freq Timestamping frequency. 72 : * 73 : * @return 0 on success or error. 74 : */ 75 1 : int log_set_timestamp_func(log_timestamp_get_t timestamp_getter, 76 : uint32_t freq); 77 : 78 : /** 79 : * @brief Switch the logger subsystem to the panic mode. 80 : * 81 : * Returns immediately if the logger is already in the panic mode. 82 : * 83 : * @details On panic the logger subsystem informs all backends about panic mode. 84 : * Backends must switch to blocking mode or halt. All pending logs 85 : * are flushed after switching to panic mode. In panic mode, all log 86 : * messages must be processed in the context of the call. 87 : */ 88 1 : __syscall void log_panic(void); 89 : 90 : /** 91 : * @brief Process one pending log message. 92 : * 93 : * @retval true There are more messages pending to be processed. 94 : * @retval false No messages pending. 95 : */ 96 1 : __syscall bool log_process(void); 97 : 98 : /** 99 : * @brief Return number of buffered log messages. 100 : * 101 : * @return Number of currently buffered log messages. 102 : */ 103 1 : __syscall uint32_t log_buffered_cnt(void); 104 : 105 : /** @brief Get number of independent logger sources (modules and instances) 106 : * 107 : * @param domain_id Domain ID. 108 : * 109 : * @return Number of sources. 110 : */ 111 1 : uint32_t log_src_cnt_get(uint32_t domain_id); 112 : 113 : 114 : /** @brief Get name of the source (module or instance). 115 : * 116 : * @param domain_id Domain ID. 117 : * @param source_id Source ID. 118 : * 119 : * @return Source name or NULL if invalid arguments. 120 : */ 121 1 : const char *log_source_name_get(uint32_t domain_id, uint32_t source_id); 122 : 123 : /** @brief Return number of domains present in the system. 124 : * 125 : * There will be at least one local domain. 126 : * 127 : * @return Number of domains. 128 : */ 129 1 : static inline uint8_t log_domains_count(void) 130 : { 131 : return 1 + (IS_ENABLED(CONFIG_LOG_MULTIDOMAIN) ? z_log_ext_domain_count() : 0); 132 : } 133 : 134 : /** @brief Get name of the domain. 135 : * 136 : * @param domain_id Domain ID. 137 : * 138 : * @return Domain name. 139 : */ 140 1 : const char *log_domain_name_get(uint32_t domain_id); 141 : 142 : /** 143 : * @brief Function for finding source ID based on source name. 144 : * 145 : * @param name Source name 146 : * 147 : * @return Source ID or negative number when source ID is not found. 148 : */ 149 1 : int log_source_id_get(const char *name); 150 : 151 : /** 152 : * @brief Get source filter for the provided backend. 153 : * 154 : * @param backend Backend instance. 155 : * @param domain_id ID of the domain. 156 : * @param source_id Source (module or instance) ID. 157 : * @param runtime True for runtime filter or false for compiled in. 158 : * 159 : * @return Severity level. 160 : */ 161 1 : uint32_t log_filter_get(struct log_backend const *const backend, 162 : uint32_t domain_id, int16_t source_id, bool runtime); 163 : 164 : /** 165 : * @brief Set filter on given source for the provided backend. 166 : * 167 : * @param backend Backend instance. NULL for all backends (and frontend). 168 : * @param domain_id ID of the domain. 169 : * @param source_id Source (module or instance) ID. 170 : * @param level Severity level. 171 : * 172 : * @return Actual level set which may be limited by compiled level. If filter 173 : * was set for all backends then maximal level that was set is returned. 174 : */ 175 1 : __syscall uint32_t log_filter_set(struct log_backend const *const backend, 176 : uint32_t domain_id, int16_t source_id, 177 : uint32_t level); 178 : 179 : /** 180 : * @brief Get source filter for the frontend. 181 : * 182 : * @param source_id Source (module or instance) ID. 183 : * @param runtime True for runtime filter or false for compiled in. 184 : * 185 : * @return Severity level. 186 : */ 187 1 : uint32_t log_frontend_filter_get(int16_t source_id, bool runtime); 188 : 189 : /** 190 : * @brief Set filter on given source for the frontend. 191 : * 192 : * @param source_id Source (module or instance) ID. 193 : * @param level Severity level. 194 : * 195 : * @return Actual level set which may be limited by compiled level. 196 : */ 197 1 : __syscall uint32_t log_frontend_filter_set(int16_t source_id, uint32_t level); 198 : 199 : /** 200 : * 201 : * @brief Enable backend with initial maximum filtering level. 202 : * 203 : * @param backend Backend instance. 204 : * @param ctx User context. 205 : * @param level Severity level. 206 : */ 207 1 : void log_backend_enable(struct log_backend const *const backend, 208 : void *ctx, 209 : uint32_t level); 210 : 211 : /** 212 : * 213 : * @brief Disable backend. 214 : * 215 : * @param backend Backend instance. 216 : */ 217 1 : void log_backend_disable(struct log_backend const *const backend); 218 : 219 : /** 220 : * @brief Get backend by name. 221 : * 222 : * @param[in] backend_name Name of the backend as defined by the LOG_BACKEND_DEFINE. 223 : * 224 : * @retval Pointer to the backend instance if found, NULL if backend is not found. 225 : */ 226 1 : const struct log_backend *log_backend_get_by_name(const char *backend_name); 227 : 228 : /** @brief Sets logging format for all active backends. 229 : * 230 : * @param log_type Log format. 231 : * 232 : * @retval Pointer to the last backend that failed, NULL for success. 233 : */ 234 1 : const struct log_backend *log_format_set_all_active_backends(size_t log_type); 235 : 236 : /** 237 : * @brief Check if there is pending data to be processed by the logging subsystem. 238 : * 239 : * Function can be used to determine if all logs have been flushed. Function 240 : * returns false when deferred mode is not enabled. 241 : * 242 : * @retval true There is pending data. 243 : * @retval false No pending data to process. 244 : */ 245 1 : static inline bool log_data_pending(void) 246 : { 247 : return IS_ENABLED(CONFIG_LOG_MODE_DEFERRED) ? z_log_msg_pending() : false; 248 : } 249 : 250 : /** 251 : * @brief Configure tag used to prefix each message. 252 : * 253 : * @param tag Tag. 254 : * 255 : * @retval 0 on successful operation. 256 : * @retval -ENOTSUP if feature is disabled. 257 : * @retval -ENOMEM if string is longer than the buffer capacity. Tag will be trimmed. 258 : */ 259 1 : int log_set_tag(const char *tag); 260 : 261 : /** 262 : * @brief Get current memory usage. 263 : * 264 : * @param[out] buf_size Capacity of the buffer used for storing log messages. 265 : * @param[out] usage Number of bytes currently containing pending log messages. 266 : * 267 : * @retval -EINVAL if logging mode does not use the buffer. 268 : * @retval 0 successfully collected usage data. 269 : */ 270 1 : int log_mem_get_usage(uint32_t *buf_size, uint32_t *usage); 271 : 272 : /** 273 : * @brief Get maximum memory usage. 274 : * 275 : * Requires CONFIG_LOG_MEM_UTILIZATION option. 276 : * 277 : * @param[out] max Maximum number of bytes used for pending log messages. 278 : * 279 : * @retval -EINVAL if logging mode does not use the buffer. 280 : * @retval -ENOTSUP if instrumentation is not enabled. 281 : * not been enabled. 282 : * 283 : * @retval 0 successfully collected usage data. 284 : */ 285 1 : int log_mem_get_max_usage(uint32_t *max); 286 : 287 : #if defined(CONFIG_LOG) && !defined(CONFIG_LOG_MODE_MINIMAL) 288 : #define LOG_CORE_INIT() log_core_init() 289 : #define LOG_PANIC() log_panic() 290 : #if defined(CONFIG_LOG_FRONTEND_ONLY) 291 : #define LOG_INIT() 0 292 : #define LOG_PROCESS() false 293 : #else /* !CONFIG_LOG_FRONTEND_ONLY */ 294 : #define LOG_INIT() log_init() 295 : #define LOG_PROCESS() log_process() 296 : #endif /* !CONFIG_LOG_FRONTEND_ONLY */ 297 : #else 298 0 : #define LOG_CORE_INIT() do { } while (false) 299 0 : #define LOG_INIT() 0 300 0 : #define LOG_PANIC() /* Empty */ 301 0 : #define LOG_PROCESS() false 302 : #endif 303 : 304 : #include <zephyr/syscalls/log_ctrl.h> 305 : 306 : /** 307 : * @} 308 : */ 309 : 310 : #ifdef __cplusplus 311 : } 312 : #endif 313 : 314 : #endif /* ZEPHYR_INCLUDE_LOGGING_LOG_CTRL_H_ */
