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 Process all pending log messages
100 : */
101 : #ifdef CONFIG_LOG_MODE_DEFERRED
102 : void log_flush(void);
103 : #else
104 1 : static inline void log_flush(void)
105 : {
106 : }
107 : #endif
108 :
109 : /**
110 : * @brief Return number of buffered log messages.
111 : *
112 : * @return Number of currently buffered log messages.
113 : */
114 1 : __syscall uint32_t log_buffered_cnt(void);
115 :
116 : /** @brief Get number of independent logger sources (modules and instances)
117 : *
118 : * @param domain_id Domain ID.
119 : *
120 : * @return Number of sources.
121 : */
122 1 : uint32_t log_src_cnt_get(uint32_t domain_id);
123 :
124 :
125 : /** @brief Get name of the source (module or instance).
126 : *
127 : * @param domain_id Domain ID.
128 : * @param source_id Source ID.
129 : *
130 : * @return Source name or NULL if invalid arguments.
131 : */
132 1 : const char *log_source_name_get(uint32_t domain_id, uint32_t source_id);
133 :
134 : /** @brief Return number of domains present in the system.
135 : *
136 : * There will be at least one local domain.
137 : *
138 : * @return Number of domains.
139 : */
140 1 : static inline uint8_t log_domains_count(void)
141 : {
142 : return 1 + (IS_ENABLED(CONFIG_LOG_MULTIDOMAIN) ? z_log_ext_domain_count() : 0);
143 : }
144 :
145 : /** @brief Get name of the domain.
146 : *
147 : * @param domain_id Domain ID.
148 : *
149 : * @return Domain name.
150 : */
151 1 : const char *log_domain_name_get(uint32_t domain_id);
152 :
153 : /**
154 : * @brief Function for finding source ID based on source name.
155 : *
156 : * @param name Source name
157 : *
158 : * @return Source ID or negative number when source ID is not found.
159 : */
160 1 : int log_source_id_get(const char *name);
161 :
162 : /**
163 : * @brief Get source filter for the provided backend.
164 : *
165 : * @param backend Backend instance.
166 : * @param domain_id ID of the domain.
167 : * @param source_id Source (module or instance) ID.
168 : * @param runtime True for runtime filter or false for compiled in.
169 : *
170 : * @return Severity level.
171 : */
172 1 : uint32_t log_filter_get(struct log_backend const *const backend,
173 : uint32_t domain_id, int16_t source_id, bool runtime);
174 :
175 : /**
176 : * @brief Set filter on given source for the provided backend.
177 : *
178 : * @param backend Backend instance. NULL for all backends (and frontend).
179 : * @param domain_id ID of the domain.
180 : * @param source_id Source (module or instance) ID.
181 : * @param level Severity level.
182 : *
183 : * @return Actual level set which may be limited by compiled level. If filter
184 : * was set for all backends then maximal level that was set is returned.
185 : */
186 1 : __syscall uint32_t log_filter_set(struct log_backend const *const backend,
187 : uint32_t domain_id, int16_t source_id,
188 : uint32_t level);
189 :
190 : /**
191 : * @brief Get source filter for the frontend.
192 : *
193 : * @param source_id Source (module or instance) ID.
194 : * @param runtime True for runtime filter or false for compiled in.
195 : *
196 : * @return Severity level.
197 : */
198 1 : uint32_t log_frontend_filter_get(int16_t source_id, bool runtime);
199 :
200 : /**
201 : * @brief Set filter on given source for the frontend.
202 : *
203 : * @param source_id Source (module or instance) ID.
204 : * @param level Severity level.
205 : *
206 : * @return Actual level set which may be limited by compiled level.
207 : */
208 1 : __syscall uint32_t log_frontend_filter_set(int16_t source_id, uint32_t level);
209 :
210 : /**
211 : *
212 : * @brief Enable backend with initial maximum filtering level.
213 : *
214 : * @param backend Backend instance.
215 : * @param ctx User context.
216 : * @param level Severity level.
217 : */
218 1 : void log_backend_enable(struct log_backend const *const backend,
219 : void *ctx,
220 : uint32_t level);
221 :
222 : /**
223 : *
224 : * @brief Disable backend.
225 : *
226 : * @param backend Backend instance.
227 : */
228 1 : void log_backend_disable(struct log_backend const *const backend);
229 :
230 : /**
231 : * @brief Get backend by name.
232 : *
233 : * @param[in] backend_name Name of the backend as defined by the LOG_BACKEND_DEFINE.
234 : *
235 : * @retval Pointer to the backend instance if found, NULL if backend is not found.
236 : */
237 1 : const struct log_backend *log_backend_get_by_name(const char *backend_name);
238 :
239 : /** @brief Sets logging format for all active backends.
240 : *
241 : * @param log_type Log format.
242 : *
243 : * @retval Pointer to the last backend that failed, NULL for success.
244 : */
245 1 : const struct log_backend *log_format_set_all_active_backends(size_t log_type);
246 :
247 : /**
248 : * @brief Check if there is pending data to be processed by the logging subsystem.
249 : *
250 : * Function can be used to determine if all logs have been flushed. Function
251 : * returns false when deferred mode is not enabled.
252 : *
253 : * @retval true There is pending data.
254 : * @retval false No pending data to process.
255 : */
256 1 : static inline bool log_data_pending(void)
257 : {
258 : return IS_ENABLED(CONFIG_LOG_MODE_DEFERRED) ? z_log_msg_pending() : false;
259 : }
260 :
261 : /**
262 : * @brief Configure tag used to prefix each message.
263 : *
264 : * @param tag Tag.
265 : *
266 : * @retval 0 on successful operation.
267 : * @retval -ENOTSUP if feature is disabled.
268 : * @retval -ENOMEM if string is longer than the buffer capacity. Tag will be trimmed.
269 : */
270 1 : int log_set_tag(const char *tag);
271 :
272 : /**
273 : * @brief Get current memory usage.
274 : *
275 : * @param[out] buf_size Capacity of the buffer used for storing log messages.
276 : * @param[out] usage Number of bytes currently containing pending log messages.
277 : *
278 : * @retval -EINVAL if logging mode does not use the buffer.
279 : * @retval 0 successfully collected usage data.
280 : */
281 1 : int log_mem_get_usage(uint32_t *buf_size, uint32_t *usage);
282 :
283 : /**
284 : * @brief Get maximum memory usage.
285 : *
286 : * Requires CONFIG_LOG_MEM_UTILIZATION option.
287 : *
288 : * @param[out] max Maximum number of bytes used for pending log messages.
289 : *
290 : * @retval -EINVAL if logging mode does not use the buffer.
291 : * @retval -ENOTSUP if instrumentation is not enabled.
292 : * not been enabled.
293 : *
294 : * @retval 0 successfully collected usage data.
295 : */
296 1 : int log_mem_get_max_usage(uint32_t *max);
297 :
298 : #if defined(CONFIG_LOG) && !defined(CONFIG_LOG_MODE_MINIMAL)
299 : #define LOG_CORE_INIT() log_core_init()
300 : #define LOG_PANIC() log_panic()
301 : #if defined(CONFIG_LOG_FRONTEND_ONLY)
302 : #define LOG_INIT() 0
303 : #define LOG_PROCESS() false
304 : #else /* !CONFIG_LOG_FRONTEND_ONLY */
305 : #define LOG_INIT() log_init()
306 : #define LOG_PROCESS() log_process()
307 : #endif /* !CONFIG_LOG_FRONTEND_ONLY */
308 : #else
309 0 : #define LOG_CORE_INIT() do { } while (false)
310 0 : #define LOG_INIT() 0
311 0 : #define LOG_PANIC() /* Empty */
312 0 : #define LOG_PROCESS() false
313 : #endif
314 :
315 : #include <zephyr/syscalls/log_ctrl.h>
316 :
317 : /**
318 : * @}
319 : */
320 :
321 : #ifdef __cplusplus
322 : }
323 : #endif
324 :
325 : #endif /* ZEPHYR_INCLUDE_LOGGING_LOG_CTRL_H_ */
|
