KM3NeT CLB  2.0
KM3NeT CLB v2 Embedded Software
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
log.h
Go to the documentation of this file.
1 /*
2  * KM3NeT CLB v2 Firmware
3  * ----------------------
4  *
5  * Copyright 2013 KM3NeT Collaboration
6  *
7  * All Rights Reserved.
8  *
9  *
10  * File : log.h
11  * Created : 12 sept. 2013
12  * Author : Vincent van Beveren
13  */
14 
15 #ifndef LOG_H_
16 #define LOG_H_
17 
18 #include <stdbool.h>
19 #include <stdint.h>
20 
21 #include "util/macro.h"
22 
23 /**
24  * @file
25  *
26  * @ingroup util
27  *
28  * Implements a generic logger facility.
29  *
30  * The logger can define a lowest logging level during compile time. All
31  * logging statements lower than this level will be removed from the compile,
32  * thus saving space.
33  */
34 
35 /**
36  * @name Logging Options
37  *
38  * @see LOG_MODE
39  *
40  * \{
41  */
42 #define LOG_MODE_TRACE 1 //!< Log everything, including TRACING
43 #define LOG_MODE_DEBUG 2 //!< Log DEBUG and up.
44 #define LOG_MODE_INFO 3 //!< Log INFO and up
45 #define LOG_MODE_EXCEPT 4 //!< Log WARN, ERROR AND FATAL
46 #define LOG_MODE_NOTHING 5 //!< Log nothing
47 
48 /** \} */
49 
50 /**
51  * \def LOG_MODE
52  *
53  * Set the compile time supported log modes. Anything
54  * below this will be compiled away IF log<Level>() macro's
55  * are used.
56  */
57 #ifdef DEBUG
58 #define LOG_MODE LOG_MODE_DEBUG
59 #else
60 #define LOG_MODE LOG_MODE_INFO
61 #endif
62 
63 #define LOG_NO_NONE 0x0
64 
65 /**
66  * Logging levels.
67  */
68 typedef enum
69 {
70  logLevelTrace, //!< Trace, show detailed runtime information.
71  logLevelDebug, //!< Debug, shows information only interesting during debugging.
72  logLevelInfo, //!< Info, general information.
73  logLevelWarn, //!< System warning, system can continue.
74  logLevelError, //!< Error, system will continue, but may malfunction.
75  logLevelFatal, //!< Fatal, system can not continue and will reboot.
76  logLevelDisabled //!< Disabled, not really a level, but used to disable logging.
77 } LogLevel;
78 
79 /**
80  * Module info structure.
81  *
82  * This structure defines a logging unit. Usually one file. For each log
83  * invocation this structure needs to be passed to the logger, in order to see
84  * which module or object generated the logging statement.
85  */
86 typedef struct
87 {
88  const char * name;
89  LogLevel level;
90 } LogModInfo;
91 
92 /**
93  * \def LOG_LEVEL_DEFAULT
94  *
95  * The default logging level.
96  */
97 
98 #ifdef DEBUG
99 #define LOG_LEVEL_DEFAULT logLevelDebug
100 #else
101 #define LOG_LEVEL_DEFAULT logLevelInfo
102 #endif
103 
104 /**
105  * Define a logger for a module.
106  *
107  * Must be done INSIDE the C file, not in an header, since a variable named
108  * '_logModInfo' will be defined. Putting it in a header will cause name
109  * collisions.
110  *
111  * @param NAME the name, without quotes.
112  * @param LEVEL the level of the logger.
113  */
114 #define LOG_DEF_LVL(NAME, LEVEL) \
115  static LogModInfo _logModInfo = { .name = STR(NAME), .level = LEVEL };
116 
117 /**
118  * Define a logger for a module.
119  *
120  * Must be done INSIDE the C file, not in an header, since a variable named
121  * '_logModInfo' will be defined. Putting it in a header will cause name
122  * collisions.
123  *
124  * The level will be set to default. If you wish to specify a level use
125  * LOG_DEF_LVL().
126  *
127  * @param NAME the name, without quotes.
128  */
129 #define LOG_DEF(NAME, ...) \
130  LOG_DEF_LVL(NAME, LOG_LEVEL_DEFAULT)
131 
132 /**
133  * Write a logging statement.
134  *
135  * Normally internally used
136  *
137  * @param mod Pointer to the source module that generated the message.
138  * @param level The log level of the message.
139  * @param msg The actual message
140  * @param ... The parameters to be formatted into the mssage
141  */
142 void _logWrite(LogModInfo * mod, LogLevel level, const char * msg, ...);
143 
144 
145 #if LOG_MODE <= LOG_MODE_TRACE
146 /**
147  * Write a log message on trace level.
148  *
149  * Using this function allows the compiler to remove the call completely if
150  * the compile time level is higher than LOG_MODE_TRACE.
151  *
152  * @attention
153  * Assumes the usage of LOG_DEF() or LOG_DEF_LVL().
154  *
155  *
156  * @param MSG The message.
157  * @param NO The number with the message, or 0.
158  */
159 #define logTrace(MSG, ...) _logWrite(&_logModInfo, logLevelTrace, MSG, ## __VA_ARGS__)
160 #else
161 #define logTrace(MSG, ...)
162 #endif
163 
164 #if LOG_MODE <= LOG_MODE_DEBUG
165 
166 /**
167  * Write a log message with formatting on debug level.
168  *
169  * Using this function allows the compiler to remove the call completely if
170  * the compile time level is higher than LOG_MODE_DEBUG
171  *
172  * @attention
173  * Assumes the usage of LOG_DEF() or LOG_DEF_LVL().
174  *
175  *
176  * @param MSG The message.
177  */
178 #define logDebug(MSG, ...) \
179  _logWrite(&_logModInfo, logLevelDebug, MSG, ## __VA_ARGS__)
180 
181 
182 #else
183 #define logDebug(MSG, ...)
184 #endif
185 
186 
187 
188 #if LOG_MODE <= LOG_MODE_INFO
189 
190 /**
191  * Write a log message with formatting on info level.
192  *
193  * Using this function allows the compiler to remove the call completely if
194  * the compile time level is higher than LOG_MODE_INFO.
195  *
196  * @attention
197  * Assumes the usage of LOG_DEF() or LOG_DEF_LVL().
198  *
199  *
200  * @param MSG The message.
201  */
202 #define logInfo(MSG, ...) \
203  _logWrite(&_logModInfo, logLevelInfo, MSG, ## __VA_ARGS__)
204 #else
205 #define logInfo(MSG, ...)
206 #endif
207 
208 
209 /**
210  * Format a log message with warning level.
211  *
212  * @attention {
213  * Assumes the usage of LOG_DEF() or LOG_DEF_LVL().
214  * }
215  *
216  * @param MSG The formatting string.
217  * @param ... Parameters
218  */
219 #define logWarn(MSG, ...) \
220  _logWrite(&_logModInfo, logLevelWarn, MSG, ## __VA_ARGS__)
221 
222 /**
223  * Format a log message with fatal level.
224  *
225  * @attention {
226  * Assumes the usage of LOG_DEF() or LOG_DEF_LVL().
227  * }
228  *
229  * @param MSG The formatting string.
230  * @param ... Parameters
231  */
232 #define logError(MSG, ...) \
233  _logWrite(&_logModInfo, logLevelError, MSG, ## __VA_ARGS__)
234 
235 /**
236  * External dependency function.
237  *
238  * Function should output or store the given log line.
239  *
240  * @param level Log level
241  * @param logLine The logline to log.
242  */
243 void _logOut(LogLevel level, char * logLine);
244 
245 /**
246  * Enable logging.
247  *
248  * @param enable Set to true to enable logging, false to supress everything.
249  */
250 void logEnable(bool enable);
251 
252 /**
253  * Set the global log level.
254  *
255  * No matter what the log level is of the various modules, no messages will be
256  * displayed below this level.
257  *
258  * @param level The minum level to show.
259  */
260 void logSetGlobalLevel(LogLevel level);
261 
262 /**
263  * Stub function, which should return the current time
264  * in seconds, since whatever.
265  *
266  * @return A uint32_t with the current time in seconds.
267  */
268 uint32_t _logTime();
269 
270 
271 #ifdef __cplusplus
272 }
273 #endif
274 #endif /* LOG_H_ */
Disabled, not really a level, but used to disable logging.
Definition: log.h:76
uint32_t _logTime()
Stub function, which should return the current time in seconds, since whatever.
Definition: sys.c:201
Trace, show detailed runtime information.
Definition: log.h:70
void logEnable(bool enable)
Enable logging.
Definition: log.c:79
LogLevel
Logging levels.
Definition: log.h:68
System warning, system can continue.
Definition: log.h:73
void _logWrite(LogModInfo *mod, LogLevel level, const char *msg,...)
Write a logging statement.
Definition: log.c:66
Info, general information.
Definition: log.h:72
Module info structure.
Definition: log.h:86
Error, system will continue, but may malfunction.
Definition: log.h:74
Provides common macros.
void logSetGlobalLevel(LogLevel level)
Set the global log level.
Definition: log.c:85
Debug, shows information only interesting during debugging.
Definition: log.h:71
void _logOut(LogLevel level, char *logLine)
External dependency function.
Definition: sys.c:353
Fatal, system can not continue and will reboot.
Definition: log.h:75