1 /*
2 * Copyright (c) 2018 Nordic Semiconductor ASA
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6 #ifndef ZEPHYR_INCLUDE_LOGGING_LOG_OUTPUT_H_
7 #define ZEPHYR_INCLUDE_LOGGING_LOG_OUTPUT_H_
8
9 #include <zephyr/logging/log_msg.h>
10 #include <zephyr/sys/util.h>
11 #include <stdarg.h>
12 #include <zephyr/sys/atomic.h>
13 #include <zephyr/kernel.h>
14
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18
19 /**
20 * @brief Log output API
21 * @defgroup log_output Log output API
22 * @ingroup logger
23 * @{
24 */
25
26 /**@defgroup LOG_OUTPUT_FLAGS Log output formatting flags.
27 * @{
28 */
29
30 /** @brief Flag forcing ANSI escape code colors, red (errors), yellow
31 * (warnings).
32 */
33 #define LOG_OUTPUT_FLAG_COLORS BIT(0)
34
35 /** @brief Flag forcing timestamp */
36 #define LOG_OUTPUT_FLAG_TIMESTAMP BIT(1)
37
38 /** @brief Flag forcing timestamp formatting. */
39 #define LOG_OUTPUT_FLAG_FORMAT_TIMESTAMP BIT(2)
40
41 /** @brief Flag forcing severity level prefix. */
42 #define LOG_OUTPUT_FLAG_LEVEL BIT(3)
43
44 /** @brief Flag preventing the logger from adding CR and LF characters. */
45 #define LOG_OUTPUT_FLAG_CRLF_NONE BIT(4)
46
47 /** @brief Flag forcing a single LF character for line breaks. */
48 #define LOG_OUTPUT_FLAG_CRLF_LFONLY BIT(5)
49
50 /** @brief Flag forcing syslog format specified in RFC 5424
51 */
52 #define LOG_OUTPUT_FLAG_FORMAT_SYSLOG BIT(6)
53
54 /** @brief Flag thread id or name prefix. */
55 #define LOG_OUTPUT_FLAG_THREAD BIT(7)
56
57 /**@} */
58
59 /** @brief Supported backend logging format types for use
60 * with log_format_set() API to switch log format at runtime.
61 */
62 #define LOG_OUTPUT_TEXT 0
63
64 #define LOG_OUTPUT_SYST 1
65
66 #define LOG_OUTPUT_DICT 2
67
68 #define LOG_OUTPUT_CUSTOM 3
69
70 /**
71 * @brief Prototype of the function processing output data.
72 *
73 * @param buf The buffer data.
74 * @param size The buffer size.
75 * @param ctx User context.
76 *
77 * @return Number of bytes processed, dropped or discarded.
78 *
79 * @note If the log output function cannot process all of the data, it is
80 * its responsibility to mark them as dropped or discarded by returning
81 * the corresponding number of bytes dropped or discarded to the caller.
82 */
83 typedef int (*log_output_func_t)(uint8_t *buf, size_t size, void *ctx);
84
85 /* @brief Control block structure for log_output instance. */
86 struct log_output_control_block {
87 atomic_t offset;
88 void *ctx;
89 const char *hostname;
90 };
91
92 /** @brief Log_output instance structure. */
93 struct log_output {
94 log_output_func_t func;
95 struct log_output_control_block *control_block;
96 uint8_t *buf;
97 size_t size;
98 };
99
100 /**
101 * @brief Typedef of the function pointer table "format_table".
102 *
103 * @param output Pointer to log_output struct.
104 * @param msg Pointer to log_msg struct.
105 * @param flags Flags used for text formatting options.
106 *
107 * @return Function pointer based on Kconfigs defined for backends.
108 */
109 typedef void (*log_format_func_t)(const struct log_output *output,
110 struct log_msg *msg, uint32_t flags);
111
112 /**
113 * @brief Declaration of the get routine for function pointer table format_table.
114 */
115 log_format_func_t log_format_func_t_get(uint32_t log_type);
116
117 /** @brief Create log_output instance.
118 *
119 * @param _name Instance name.
120 * @param _func Function for processing output data.
121 * @param _buf Pointer to the output buffer.
122 * @param _size Size of the output buffer.
123 */
124 #define LOG_OUTPUT_DEFINE(_name, _func, _buf, _size) \
125 static struct log_output_control_block _name##_control_block; \
126 static const struct log_output _name = { \
127 .func = _func, \
128 .control_block = &_name##_control_block, \
129 .buf = _buf, \
130 .size = _size, \
131 }
132
133 /** @brief Process log messages v2 to readable strings.
134 *
135 * Function is using provided context with the buffer and output function to
136 * process formatted string and output the data.
137 *
138 * @param log_output Pointer to the log output instance.
139 * @param msg Log message.
140 * @param flags Optional flags. See @ref LOG_OUTPUT_FLAGS.
141 */
142 void log_output_msg_process(const struct log_output *log_output,
143 struct log_msg *msg, uint32_t flags);
144
145 /** @brief Process input data to a readable string.
146 *
147 * @param log_output Pointer to the log output instance.
148 * @param timestamp Timestamp.
149 * @param domain Domain name string. Can be NULL.
150 * @param source Source name string. Can be NULL.
151 * @param tid Thread ID.
152 * @param level Criticality level.
153 * @param package Cbprintf package with a logging message string.
154 * @param data Data passed to hexdump API. Can bu NULL.
155 * @param data_len Data length.
156 * @param flags Formatting flags. See @ref LOG_OUTPUT_FLAGS.
157 */
158 void log_output_process(const struct log_output *log_output,
159 log_timestamp_t timestamp,
160 const char *domain,
161 const char *source,
162 const k_tid_t tid,
163 uint8_t level,
164 const uint8_t *package,
165 const uint8_t *data,
166 size_t data_len,
167 uint32_t flags);
168
169 /** @brief Process log messages v2 to SYS-T format.
170 *
171 * Function is using provided context with the buffer and output function to
172 * process formatted string and output the data in sys-t log output format.
173 *
174 * @param log_output Pointer to the log output instance.
175 * @param msg Log message.
176 * @param flags Optional flags. See @ref LOG_OUTPUT_FLAGS.
177 */
178 void log_output_msg_syst_process(const struct log_output *log_output,
179 struct log_msg *msg, uint32_t flags);
180
181 /** @brief Process dropped messages indication.
182 *
183 * Function prints error message indicating lost log messages.
184 *
185 * @param output Pointer to the log output instance.
186 * @param cnt Number of dropped messages.
187 */
188 void log_output_dropped_process(const struct log_output *output, uint32_t cnt);
189
190 /** @brief Flush output buffer.
191 *
192 * @param output Pointer to the log output instance.
193 */
194 void log_output_flush(const struct log_output *output);
195
196 /** @brief Function for setting user context passed to the output function.
197 *
198 * @param output Pointer to the log output instance.
199 * @param ctx User context.
200 */
log_output_ctx_set(const struct log_output * output,void * ctx)201 static inline void log_output_ctx_set(const struct log_output *output,
202 void *ctx)
203 {
204 output->control_block->ctx = ctx;
205 }
206
207 /** @brief Function for setting hostname of this device
208 *
209 * @param output Pointer to the log output instance.
210 * @param hostname Hostname of this device
211 */
log_output_hostname_set(const struct log_output * output,const char * hostname)212 static inline void log_output_hostname_set(const struct log_output *output,
213 const char *hostname)
214 {
215 output->control_block->hostname = hostname;
216 }
217
218 /** @brief Set timestamp frequency.
219 *
220 * @param freq Frequency in Hz.
221 */
222 void log_output_timestamp_freq_set(uint32_t freq);
223
224 /** @brief Convert timestamp of the message to us.
225 *
226 * @param timestamp Message timestamp
227 *
228 * @return Timestamp value in us.
229 */
230 uint64_t log_output_timestamp_to_us(log_timestamp_t timestamp);
231
232 /**
233 * @}
234 */
235
236
237 #ifdef __cplusplus
238 }
239 #endif
240
241 #endif /* ZEPHYR_INCLUDE_LOGGING_LOG_OUTPUT_H_ */
242
