log.h@ 8622

Last change on this file since 8622 was 8622, checked in by vboxsync, 17 years ago
Fixed logging macros causing mixed up output on smp machines (C99 only).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 52.2 KB

Line
1	/** @file
2	* IPRT - Logging.
3	*/
4
5	/*
6	* Copyright (C) 2006-2007 Sun Microsystems, Inc.
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*
25	* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26	* Clara, CA 95054 USA or visit http://www.sun.com if you need
27	* additional information or have any questions.
28	*/
29
30	#ifndef ___iprt_log_h
31	#define ___iprt_log_h
32
33	#include <iprt/cdefs.h>
34	#include <iprt/types.h>
35	#include <iprt/stdarg.h>
36
37	__BEGIN_DECLS
38
39	/** @defgroup grp_rt_log RTLog - Logging
40	* @ingroup grp_rt
41	* @{
42	*/
43
44	/**
45	* IPRT Logging Groups.
46	* (Remember to update RT_LOGGROUP_NAMES!)
47	*
48	* @remark It should be pretty obvious, but just to have
49	* mentioned it, the values are sorted alphabetically (using the
50	* english alphabet) except for _DEFAULT which is always first.
51	*
52	* If anyone might be wondering what the alphabet looks like:
53	* a b c d e f g h i j k l m n o p q r s t u v w x y z
54	*/
55	typedef enum RTLOGGROUP
56	{
57	/** Default logging group. */
58	RTLOGGROUP_DEFAULT,
59	RTLOGGROUP_DIR,
60	RTLOGGROUP_FILE,
61	RTLOGGROUP_FS,
62	RTLOGGROUP_LDR,
63	RTLOGGROUP_PATH,
64	RTLOGGROUP_PROCESS,
65	RTLOGGROUP_THREAD,
66	RTLOGGROUP_TIME,
67	RTLOGGROUP_TIMER,
68	RTLOGGROUP_ZIP = 31,
69	RTLOGGROUP_FIRST_USER = 32
70	} RTLOGGROUP;
71
72	/** @def RT_LOGGROUP_NAMES
73	* IPRT Logging group names.
74	*
75	* Must correspond 100% to RTLOGGROUP!
76	* Don't forget commas!
77	*
78	* @remark It should be pretty obvious, but just to have
79	* mentioned it, the values are sorted alphabetically (using the
80	* english alphabet) except for _DEFAULT which is always first.
81	*
82	* If anyone might be wondering what the alphabet looks like:
83	* a b c d e f g h i j k l m n o p q r s t u v w x y z
84	*/
85	#define RT_LOGGROUP_NAMES \
86	"DEFAULT", \
87	"RT_DIR", \
88	"RT_FILE", \
89	"RT_FS", \
90	"RT_LDR", \
91	"RT_PATH", \
92	"RT_PROCESS", \
93	"RT_THREAD", \
94	"RT_TIME", \
95	"RT_TIMER", \
96	"RT_10", \
97	"RT_11", \
98	"RT_12", \
99	"RT_13", \
100	"RT_14", \
101	"RT_15", \
102	"RT_16", \
103	"RT_17", \
104	"RT_18", \
105	"RT_19", \
106	"RT_20", \
107	"RT_21", \
108	"RT_22", \
109	"RT_23", \
110	"RT_24", \
111	"RT_25", \
112	"RT_26", \
113	"RT_27", \
114	"RT_28", \
115	"RT_29", \
116	"RT_30", \
117	"RT_ZIP" \
118
119
120	/** @def LOG_GROUP
121	* Active logging group.
122	*/
123	#ifndef LOG_GROUP
124	# define LOG_GROUP RTLOGGROUP_DEFAULT
125	#endif
126
127	/** @def LOG_INSTANCE
128	* Active logging instance.
129	*/
130	#ifndef LOG_INSTANCE
131	# define LOG_INSTANCE NULL
132	#endif
133
134	/** @def LOG_REL_INSTANCE
135	* Active release logging instance.
136	*/
137	#ifndef LOG_REL_INSTANCE
138	# define LOG_REL_INSTANCE NULL
139	#endif
140
141	/** @def LOG_FN_FMT
142	* You can use this to specify you desired way of printing __PRETTY_FUNCTION__
143	* if you dislike the default one.
144	*/
145	#ifndef LOG_FN_FMT
146	# define LOG_FN_FMT "%Rfn"
147	#endif
148
149	/** Logger structure. */
150	#ifdef IN_GC
151	typedef struct RTLOGGERGC RTLOGGER;
152	#else
153	typedef struct RTLOGGER RTLOGGER;
154	#endif
155	/** Pointer to logger structure. */
156	typedef RTLOGGER *PRTLOGGER;
157	/** Pointer to const logger structure. */
158	typedef const RTLOGGER *PCRTLOGGER;
159
160
161	/** Guest context logger structure. */
162	typedef struct RTLOGGERGC RTLOGGERGC;
163	/** Pointer to guest context logger structure. */
164	typedef RTLOGGERGC *PRTLOGGERGC;
165	/** Pointer to const guest context logger structure. */
166	typedef const RTLOGGERGC *PCRTLOGGERGC;
167
168
169	/**
170	* Logger function.
171	*
172	* @param pszFormat Format string.
173	* @param ... Optional arguments as specified in the format string.
174	*/
175	typedef DECLCALLBACK(void) FNRTLOGGER(const char *pszFormat, ...);
176	/** Pointer to logger function. */
177	typedef FNRTLOGGER *PFNRTLOGGER;
178
179	/**
180	* Flush function.
181	*
182	* @param pLogger Pointer to the logger instance which is to be flushed.
183	*/
184	typedef DECLCALLBACK(void) FNRTLOGFLUSH(PRTLOGGER pLogger);
185	/** Pointer to logger function. */
186	typedef FNRTLOGFLUSH *PFNRTLOGFLUSH;
187
188	/**
189	* Flush function.
190	*
191	* @param pLogger Pointer to the logger instance which is to be flushed.
192	*/
193	typedef DECLCALLBACK(void) FNRTLOGFLUSHGC(PRTLOGGERGC pLogger);
194	/** Pointer to logger function. */
195	typedef GCPTRTYPE(FNRTLOGFLUSHGC *) PFNRTLOGFLUSHGC;
196
197
198	/**
199	* Logger instance structure for GC.
200	*/
201	struct RTLOGGERGC
202	{
203	/** Pointer to temporary scratch buffer.
204	* This is used to format the log messages. */
205	char achScratch[16384];
206	/** Current scratch buffer position. */
207	RTUINT offScratch;
208	/** This is set if a prefix is pending. */
209	RTUINT fPendingPrefix;
210	/** Pointer to the logger function.
211	* This is actually pointer to a wrapper which will push a pointer to the
212	* instance pointer onto the stack before jumping to the real logger function.
213	* A very unfortunate hack to work around the missing variadic macro support in C++. */
214	GCPTRTYPE(PFNRTLOGGER) pfnLogger;
215	/** Pointer to the flush function. */
216	PFNRTLOGFLUSHGC pfnFlush;
217	/** Magic number (RTLOGGERGC_MAGIC). */
218	uint32_t u32Magic;
219	/** Logger instance flags - RTLOGFLAGS. */
220	RTUINT fFlags;
221	/** Number of groups in the afGroups member. */
222	RTUINT cGroups;
223	/** Group flags array - RTLOGGRPFLAGS.
224	* This member have variable length and may extend way beyond
225	* the declared size of 1 entry. */
226	RTUINT afGroups[1];
227	};
228
229	/** RTLOGGERGC::u32Magic value. (John Rogers Searle) */
230	#define RTLOGGERGC_MAGIC 0x19320731
231
232
233
234	#ifndef IN_GC
235	/**
236	* Logger instance structure.
237	*/
238	struct RTLOGGER
239	{
240	/** Pointer to temporary scratch buffer.
241	* This is used to format the log messages. */
242	char achScratch[16384];
243	/** Current scratch buffer position. */
244	RTUINT offScratch;
245	/** This is set if a prefix is pending. */
246	RTUINT fPendingPrefix;
247	/** Pointer to the logger function.
248	* This is actually pointer to a wrapper which will push a pointer to the
249	* instance pointer onto the stack before jumping to the real logger function.
250	* A very unfortunate hack to work around the missing variadic macro support in C++.
251	* (The memory is (not R0) allocated using RTMemExecAlloc().) */
252	PFNRTLOGGER pfnLogger;
253	/** Pointer to the flush function. */
254	PFNRTLOGFLUSH pfnFlush;
255	/** Mutex. */
256	RTSEMFASTMUTEX MutexSem;
257	/** Magic number. */
258	uint32_t u32Magic;
259	/** Logger instance flags - RTLOGFLAGS. */
260	RTUINT fFlags;
261	/** Destination flags - RTLOGDEST. */
262	RTUINT fDestFlags;
263	/** Handle to log file (if open). */
264	RTFILE File;
265	/** Pointer to filename.
266	* (The memory is allocated in the smae block as RTLOGGER.) */
267	char *pszFilename;
268	/** Pointer to the group name array.
269	* (The data is readonly and provided by the user.) */
270	const char * const *papszGroups;
271	/** The max number of groups that there is room for in afGroups and papszGroups.
272	* Used by RTLogCopyGroupAndFlags(). */
273	RTUINT cMaxGroups;
274	/** Number of groups in the afGroups and papszGroups members. */
275	RTUINT cGroups;
276	/** Group flags array - RTLOGGRPFLAGS.
277	* This member have variable length and may extend way beyond
278	* the declared size of 1 entry. */
279	RTUINT afGroups[1];
280	};
281
282	/** RTLOGGER::u32Magic value. (Avram Noam Chomsky) */
283	#define RTLOGGER_MAGIC 0x19281207
284
285	#endif
286
287
288	/**
289	* Logger flags.
290	*/
291	typedef enum RTLOGFLAGS
292	{
293	/** The logger instance is disabled for normal output. */
294	RTLOGFLAGS_DISABLED = 0x00000001,
295	/** The logger instance is using buffered output. */
296	RTLOGFLAGS_BUFFERED = 0x00000002,
297	/** The logger instance expands LF to CR/LF. */
298	RTLOGFLAGS_USECRLF = 0x00000010,
299	/** Show relative timestamps with PREFIX_TSC and PREFIX_TS */
300	RTLOGFLAGS_REL_TS = 0x00000020,
301	/** Show decimal timestamps with PREFIX_TSC and PREFIX_TS */
302	RTLOGFLAGS_DECIMAL_TS = 0x00000040,
303	/** New lines should be reprefixed with the CPU id (ApicID on intel/amd). */
304	RTLOGFLAGS_PREFIX_CPUID = 0x00010000,
305	/** New lines should be prefixed with the native process id. */
306	RTLOGFLAGS_PREFIX_PID = 0x00020000,
307	/** New lines should be prefixed with group flag number causing the output. */
308	RTLOGFLAGS_PREFIX_FLAG_NO = 0x00040000,
309	/** New lines should be prefixed with group flag name causing the output. */
310	RTLOGFLAGS_PREFIX_FLAG = 0x00080000,
311	/** New lines should be prefixed with group number. */
312	RTLOGFLAGS_PREFIX_GROUP_NO = 0x00100000,
313	/** New lines should be prefixed with group name. */
314	RTLOGFLAGS_PREFIX_GROUP = 0x00200000,
315	/** New lines should be prefixed with the native thread id. */
316	RTLOGFLAGS_PREFIX_TID = 0x00400000,
317	/** New lines should be prefixed with thread name. */
318	RTLOGFLAGS_PREFIX_THREAD = 0x00800000,
319	/** New lines should be prefixed with formatted timestamp since program start. */
320	RTLOGFLAGS_PREFIX_TIME_PROG = 0x04000000,
321	/** New lines should be prefixed with formatted timestamp (UCT). */
322	RTLOGFLAGS_PREFIX_TIME = 0x08000000,
323	/** New lines should be prefixed with milliseconds since program start. */
324	RTLOGFLAGS_PREFIX_MS_PROG = 0x10000000,
325	/** New lines should be prefixed with timestamp. */
326	RTLOGFLAGS_PREFIX_TSC = 0x20000000,
327	/** New lines should be prefixed with timestamp. */
328	RTLOGFLAGS_PREFIX_TS = 0x40000000,
329	/** The prefix mask. */
330	RTLOGFLAGS_PREFIX_MASK = 0x7cff0000
331	} RTLOGFLAGS;
332
333	/**
334	* Logger per group flags.
335	*/
336	typedef enum RTLOGGRPFLAGS
337	{
338	/** Enabled. */
339	RTLOGGRPFLAGS_ENABLED = 0x00000001,
340	/** Level 1 logging. */
341	RTLOGGRPFLAGS_LEVEL_1 = 0x00000002,
342	/** Level 2 logging. */
343	RTLOGGRPFLAGS_LEVEL_2 = 0x00000004,
344	/** Level 3 logging. */
345	RTLOGGRPFLAGS_LEVEL_3 = 0x00000008,
346	/** Level 4 logging. */
347	RTLOGGRPFLAGS_LEVEL_4 = 0x00000010,
348	/** Level 5 logging. */
349	RTLOGGRPFLAGS_LEVEL_5 = 0x00000020,
350	/** Level 6 logging. */
351	RTLOGGRPFLAGS_LEVEL_6 = 0x00000040,
352	/** Flow logging. */
353	RTLOGGRPFLAGS_FLOW = 0x00000080,
354
355	/** Lelik logging. */
356	RTLOGGRPFLAGS_LELIK = 0x00000100,
357	/** Michael logging. */
358	RTLOGGRPFLAGS_MICHAEL = 0x00000200,
359	/** dmik logging. */
360	RTLOGGRPFLAGS_DMIK = 0x00000400,
361	/** sunlover logging. */
362	RTLOGGRPFLAGS_SUNLOVER = 0x00000800,
363	/** Achim logging. */
364	RTLOGGRPFLAGS_ACHIM = 0x00001000,
365	/** Sander logging. */
366	RTLOGGRPFLAGS_SANDER = 0x00002000,
367	/** Klaus logging. */
368	RTLOGGRPFLAGS_KLAUS = 0x00004000,
369	/** Frank logging. */
370	RTLOGGRPFLAGS_FRANK = 0x00008000,
371	/** bird logging. */
372	RTLOGGRPFLAGS_BIRD = 0x00010000,
373	/** NoName logging. */
374	RTLOGGRPFLAGS_NONAME = 0x00020000
375	} RTLOGGRPFLAGS;
376
377	/**
378	* Logger destination type.
379	*/
380	typedef enum RTLOGDEST
381	{
382	/** Log to file. */
383	RTLOGDEST_FILE = 0x00000001,
384	/** Log to stdout. */
385	RTLOGDEST_STDOUT = 0x00000002,
386	/** Log to stderr. */
387	RTLOGDEST_STDERR = 0x00000004,
388	/** Log to debugger (win32 only). */
389	RTLOGDEST_DEBUGGER = 0x00000008,
390	/** Log to com port. */
391	RTLOGDEST_COM = 0x00000010,
392	/** Just a dummy flag to be used when no other flag applies. */
393	RTLOGDEST_DUMMY = 0x20000000,
394	/** Log to a user defined output stream. */
395	RTLOGDEST_USER = 0x40000000
396	} RTLOGDEST;
397
398
399	RTDECL(void) RTLogPrintfEx(void pvInstance, unsigned fFlags, unsigned iGroup, const char pszFormat, ...);
400
401
402	/*
403	* Determin whether logging is enabled and forcefully normalize the indicators.
404	*/
405	#if (defined(DEBUG) \|\| defined(LOG_ENABLED)) && !defined(LOG_DISABLED)
406	# undef LOG_DISABLED
407	# undef LOG_ENABLED
408	# define LOG_ENABLED
409	#else
410	# undef LOG_ENABLED
411	# undef LOG_DISABLED
412	# define LOG_DISABLED
413	#endif
414
415
416	/** @def LOG_USE_C99
417	* Governs the use of variadic macros.
418	*/
419	#ifndef LOG_USE_C99
420	# if defined(RT_ARCH_AMD64)
421	# define LOG_USE_C99
422	# endif
423	#endif
424
425
426	/** @def LogIt
427	* Write to specific logger if group enabled.
428	*/
429	#ifdef LOG_ENABLED
430	# if defined(LOG_USE_C99)
431	# define _LogRemoveParentheseis(...) __VA_ARGS__
432	# define _LogIt(pvInst, fFlags, iGroup, ...) RTLogLoggerEx((PRTLOGGER)pvInst, fFlags, iGroup, __VA_ARGS__)
433	# define LogIt(pvInst, fFlags, iGroup, fmtargs) _LogIt(pvInst, fFlags, iGroup, _LogRemoveParentheseis fmtargs)
434	# else
435	# define LogIt(pvInst, fFlags, iGroup, fmtargs) \
436	do \
437	{ \
438	register PRTLOGGER LogIt_pLogger = (PRTLOGGER)(pvInst) ? (PRTLOGGER)(pvInst) : RTLogDefaultInstance(); \
439	if (LogIt_pLogger) \
440	{ \
441	register unsigned LogIt_fFlags = LogIt_pLogger->afGroups[(unsigned)(iGroup) < LogIt_pLogger->cGroups ? (unsigned)(iGroup) : 0]; \
442	if ((LogIt_fFlags & ((fFlags) \| RTLOGGRPFLAGS_ENABLED)) == ((fFlags) \| RTLOGGRPFLAGS_ENABLED)) \
443	LogIt_pLogger->pfnLogger fmtargs; \
444	} \
445	} while (0)
446	# endif
447	#else
448	# define LogIt(pvInst, fFlags, iGroup, fmtargs) do { } while (0)
449	#endif
450
451
452	/** @def Log
453	* Level 1 logging.
454	*/
455	#define Log(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
456
457	/** @def Log2
458	* Level 2 logging.
459	*/
460	#define Log2(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, a)
461
462	/** @def Log3
463	* Level 3 logging.
464	*/
465	#define Log3(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, a)
466
467	/** @def Log4
468	* Level 4 logging.
469	*/
470	#define Log4(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, a)
471
472	/** @def Log5
473	* Level 5 logging.
474	*/
475	#define Log5(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, a)
476
477	/** @def Log6
478	* Level 6 logging.
479	*/
480	#define Log6(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, a)
481
482	/** @def LogFlow
483	* Logging of execution flow.
484	*/
485	#define LogFlow(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, a)
486
487	/** @def LogLelik
488	* lelik logging.
489	*/
490	#define LogLelik(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LELIK, LOG_GROUP, a)
491
492
493	/** @def LogMichael
494	* michael logging.
495	*/
496	#define LogMichael(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_MICHAEL, LOG_GROUP, a)
497
498	/** @def LogDmik
499	* dmik logging.
500	*/
501	#define LogDmik(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_DMIK, LOG_GROUP, a)
502
503	/** @def LogSunlover
504	* sunlover logging.
505	*/
506	#define LogSunlover(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_SUNLOVER, LOG_GROUP, a)
507
508	/** @def LogAchim
509	* Achim logging.
510	*/
511	#define LogAchim(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_ACHIM, LOG_GROUP, a)
512
513	/** @def LogSander
514	* Sander logging.
515	*/
516	#define LogSander(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_SANDER, LOG_GROUP, a)
517
518	/** @def LogKlaus
519	* klaus logging.
520	*/
521	#define LogKlaus(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_KLAUS, LOG_GROUP, a)
522
523	/** @def LogFrank
524	* frank logging.
525	*/
526	#define LogFrank(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FRANK, LOG_GROUP, a)
527
528	/** @def LogBird
529	* bird logging.
530	*/
531	#define LogBird(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_BIRD, LOG_GROUP, a)
532
533	/** @def LogNoName
534	* NoName logging.
535	*/
536	#define LogNoName(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_NONAME, LOG_GROUP, a)
537
538
539	/** @def LogWarning
540	* The same as Log(), but prepents a <tt>"WARNING! "</tt> string to the message.
541	*
542	* @param a Custom log message in format <tt>("string\n" [, args])</tt>.
543	*/
544	#if defined(LOG_USE_C99)
545	# define LogWarning(a) \
546	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "WARNING! %M", _LogRemoveParentheseis a )
547	#else
548	# define LogWarning(a) \
549	do { Log(("WARNING! ")); Log(a); } while (0)
550	#endif
551
552	/** @def LogTrace
553	* Macro to trace the execution flow: logs the file name, line number and
554	* function name. Can be easily searched for in log files using the
555	* ">>>>>" pattern (prepended to the beginning of each line).
556	*/
557	#define LogTrace() \
558	LogFlow((">>>>> %s (%d): " LOG_FN_FMT "\n", __FILE__, __LINE__, __PRETTY_FUNCTION__))
559
560	/** @def LogTraceMsg
561	* The same as LogTrace but logs a custom log message right after the trace line.
562	*
563	* @param a Custom log message in format <tt>("string\n" [, args])</tt>.
564	*/
565	#ifdef LOG_USE_C99
566	# define LogTraceMsg(a) \
567	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, ">>>>> %s (%d): %M" LOG_FN_FMT, __FILE__, __LINE__, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
568	#else
569	# define LogTraceMsg(a) \
570	do { LogFlow((">>>>> %s (%d): " LOG_FN_FMT, __FILE__, __LINE__, __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
571	#endif
572
573	/** @def LogFunc
574	* Level 1 logging inside C/C++ functions.
575	*
576	* Prepends the given log message with the function name followed by a
577	* semicolon and space.
578	*
579	* @param a Log message in format <tt>("string\n" [, args])</tt>.
580	*/
581	#ifdef LOG_USE_C99
582	# define LogFunc(a) \
583	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
584	#else
585	# define LogFunc(a) \
586	do { Log((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); Log(a); } while (0)
587	#endif
588
589	/** @def LogThisFunc
590	* The same as LogFunc but for class functions (methods): the resulting log
591	* line is additionally prepended with a hex value of \|this\| pointer.
592	*
593	* @param a Log message in format <tt>("string\n" [, args])</tt>.
594	*/
595	#ifdef LOG_USE_C99
596	# define LogThisFunc(a) \
597	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
598	#else
599	# define LogThisFunc(a) \
600	do { Log(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log(a); } while (0)
601	#endif
602
603	/** @def LogFlowFunc
604	* Macro to log the execution flow inside C/C++ functions.
605	*
606	* Prepends the given log message with the function name followed by
607	* a semicolon and space.
608	*
609	* @param a Log message in format <tt>("string\n" [, args])</tt>.
610	*/
611	#ifdef LOG_USE_C99
612	# define LogFlowFunc(a) \
613	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
614	#else
615	# define LogFlowFunc(a) \
616	do { LogFlow((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
617	#endif
618
619	/** @def LogWarningFunc
620	* The same as LogWarning(), but prepents the log message with the function name.
621	*
622	* @param a Log message in format <tt>("string\n" [, args])</tt>.
623	*/
624	#ifdef LOG_USE_C99
625	# define LogWarningFunc(a) \
626	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": WARNING! %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
627	#else
628	# define LogWarningFunc(a) \
629	do { Log((LOG_FN_FMT ": WARNING! ", __PRETTY_FUNCTION__)); Log(a); } while (0)
630	#endif
631
632	/** @def LogFlowThisFunc
633	* The same as LogFlowFunc but for class functions (methods): the resulting log
634	* line is additionally prepended with a hex value of \|this\| pointer.
635	*
636	* @param a Log message in format <tt>("string\n" [, args])</tt>.
637	*/
638	#ifdef LOG_USE_C99
639	# define LogFlowThisFunc(a) \
640	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
641	#else
642	# define LogFlowThisFunc(a) \
643	do { LogFlow(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
644	#endif
645
646	/** @def LogWarningThisFunc
647	* The same as LogWarningFunc() but for class functions (methods): the resulting
648	* log line is additionally prepended with a hex value of \|this\| pointer.
649	*
650	* @param a Log message in format <tt>("string\n" [, args])</tt>.
651	*/
652	#ifdef LOG_USE_C99
653	# define LogWarningThisFunc(a) \
654	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": WARNING! %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
655	#else
656	# define LogWarningThisFunc(a) \
657	do { Log(("{%p} " LOG_FN_FMT ": WARNING! ", this, __PRETTY_FUNCTION__)); Log(a); } while (0)
658	#endif
659
660	/** Shortcut to \|LogFlowFunc ("ENTER\n")\|, marks the beginnig of the function. */
661	#define LogFlowFuncEnter() LogFlowFunc(("ENTER\n"))
662
663	/** Shortcut to \|LogFlowFunc ("LEAVE\n")\|, marks the end of the function. */
664	#define LogFlowFuncLeave() LogFlowFunc(("LEAVE\n"))
665
666	/** Shortcut to \|LogFlowThisFunc ("ENTER\n")\|, marks the beginnig of the function. */
667	#define LogFlowThisFuncEnter() LogFlowThisFunc(("ENTER\n"))
668
669	/** Shortcut to \|LogFlowThisFunc ("LEAVE\n")\|, marks the end of the function. */
670	#define LogFlowThisFuncLeave() LogFlowThisFunc(("LEAVE\n"))
671
672	/** @def LogObjRefCnt
673	* Helper macro to print the current reference count of the given COM object
674	* to the log file.
675	*
676	* @param pObj Pointer to the object in question (must be a pointer to an
677	* IUnknown subclass or simply define COM-style AddRef() and
678	* Release() methods)
679	*
680	* @note Use it only for temporary debugging. It leaves dummy code even if
681	* logging is disabled.
682	*/
683	#define LogObjRefCnt(pObj) \
684	do { \
685	int refc = (pObj)->AddRef(); \
686	LogFlow((#pObj "{%p}.refCnt=%d\n", (pObj), refc - 1)); \
687	(pObj)->Release(); \
688	} while (0)
689
690
691	/** @def LogIsItEnabled
692	* Checks whether the specified logging group is enabled or not.
693	*/
694	#ifdef LOG_ENABLED
695	# define LogIsItEnabled(pvInst, fFlags, iGroup) \
696	LogIsItEnabledInternal((pvInst), (unsigned)(iGroup), (unsigned)(fFlags))
697	#else
698	# define LogIsItEnabled(pvInst, fFlags, iGroup) (false)
699	#endif
700
701	/** @def LogIsEnabled
702	* Checks whether level 1 logging is enabled.
703	*/
704	#define LogIsEnabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP)
705
706	/** @def LogIs2Enabled
707	* Checks whether level 2 logging is enabled.
708	*/
709	#define LogIs2Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP)
710
711	/** @def LogIs3Enabled
712	* Checks whether level 3 logging is enabled.
713	*/
714	#define LogIs3Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP)
715
716	/** @def LogIs4Enabled
717	* Checks whether level 4 logging is enabled.
718	*/
719	#define LogIs4Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP)
720
721	/** @def LogIs5Enabled
722	* Checks whether level 5 logging is enabled.
723	*/
724	#define LogIs5Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP)
725
726	/** @def LogIs6Enabled
727	* Checks whether level 6 logging is enabled.
728	*/
729	#define LogIs6Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP)
730
731	/** @def LogIsFlowEnabled
732	* Checks whether execution flow logging is enabled.
733	*/
734	#define LogIsFlowEnabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP)
735
736
737	#ifdef DOXYGEN_RUNNING
738	# define LOG_DISABLED
739	# define LOG_ENABLED
740	# define LOG_ENABLE_FLOW
741	#endif
742
743	/** @def LOG_DISABLED
744	* Use this compile time define to disable all logging macros. It can
745	* be overriden for each of the logging macros by the LOG_ENABLE*
746	* compile time defines.
747	*/
748
749	/** @def LOG_ENABLED
750	* Use this compile time define to enable logging when not in debug mode
751	* or LOG_DISABLED is set.
752	* This will enabled Log() only.
753	*/
754
755	/** @def LOG_ENABLE_FLOW
756	* Use this compile time define to enable flow logging when not in
757	* debug mode or LOG_DISABLED is defined.
758	* This will enable LogFlow() only.
759	*/
760
761
762
763	/** @name Release Logging
764	* @{
765	*/
766
767	/** @def LogIt
768	* Write to specific logger if group enabled.
769	*/
770	#if defined(LOG_USE_C99)
771	# define _LogRelRemoveParentheseis(...) __VA_ARGS__
772	# define _LogRelIt(pvInst, fFlags, iGroup, ...) RTLogLoggerEx((PRTLOGGER)pvInst, fFlags, iGroup, __VA_ARGS__)
773	# define LogRelIt(pvInst, fFlags, iGroup, fmtargs) \
774	do \
775	{ \
776	PRTLOGGER LogRelIt_pLogger = (PRTLOGGER)(pvInst) ? (PRTLOGGER)(pvInst) : RTLogRelDefaultInstance(); \
777	if (LogRelIt_pLogger) \
778	_LogRelIt(LogRelIt_pLogger, fFlags, iGroup, _LogRelRemoveParentheseis fmtargs); \
779	LogIt(LOG_INSTANCE, fFlags, iGroup, fmtargs); \
780	} while (0)
781	#else
782	# define LogRelIt(pvInst, fFlags, iGroup, fmtargs) \
783	do \
784	{ \
785	PRTLOGGER LogRelIt_pLogger = (PRTLOGGER)(pvInst) ? (PRTLOGGER)(pvInst) : RTLogRelDefaultInstance(); \
786	if (LogRelIt_pLogger) \
787	{ \
788	unsigned LogIt_fFlags = LogRelIt_pLogger->afGroups[(unsigned)(iGroup) < LogRelIt_pLogger->cGroups ? (unsigned)(iGroup) : 0]; \
789	if ((LogIt_fFlags & ((fFlags) \| RTLOGGRPFLAGS_ENABLED)) == ((fFlags) \| RTLOGGRPFLAGS_ENABLED)) \
790	LogRelIt_pLogger->pfnLogger fmtargs; \
791	} \
792	LogIt(LOG_INSTANCE, fFlags, iGroup, fmtargs); \
793	} while (0)
794	#endif
795
796
797	/** @def LogRel
798	* Level 1 logging.
799	*/
800	#define LogRel(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
801
802	/** @def LogRel2
803	* Level 2 logging.
804	*/
805	#define LogRel2(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, a)
806
807	/** @def LogRel3
808	* Level 3 logging.
809	*/
810	#define LogRel3(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, a)
811
812	/** @def LogRel4
813	* Level 4 logging.
814	*/
815	#define LogRel4(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, a)
816
817	/** @def LogRel5
818	* Level 5 logging.
819	*/
820	#define LogRel5(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, a)
821
822	/** @def LogRel6
823	* Level 6 logging.
824	*/
825	#define LogRel6(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, a)
826
827	/** @def LogRelFlow
828	* Logging of execution flow.
829	*/
830	#define LogRelFlow(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, a)
831
832	/** @def LogRelFunc
833	* Release logging. Prepends the given log message with the function name
834	* followed by a semicolon and space.
835	*/
836	#define LogRelFunc(a) \
837	do { LogRel((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); LogRel(a); } while (0)
838
839	/** @def LogRelThisFunc
840	* The same as LogRelFunc but for class functions (methods): the resulting log
841	* line is additionally prepended with a hex value of \|this\| pointer.
842	*/
843	#define LogRelThisFunc(a) \
844	do { LogRel(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); LogRel(a); } while (0)
845
846	/** @def LogRelLelik
847	* lelik logging.
848	*/
849	#define LogRelLelik(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LELIK, LOG_GROUP, a)
850
851	/** @def LogRelMichael
852	* michael logging.
853	*/
854	#define LogRelMichael(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_MICHAEL, LOG_GROUP, a)
855
856	/** @def LogRelDmik
857	* dmik logging.
858	*/
859	#define LogRelDmik(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_DMIK, LOG_GROUP, a)
860
861	/** @def LogRelSunlover
862	* sunlover logging.
863	*/
864	#define LogRelSunlover(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_SUNLOVER, LOG_GROUP, a)
865
866	/** @def LogRelAchim
867	* Achim logging.
868	*/
869	#define LogRelAchim(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_ACHIM, LOG_GROUP, a)
870
871	/** @def LogRelSander
872	* Sander logging.
873	*/
874	#define LogRelSander(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_SANDER, LOG_GROUP, a)
875
876	/** @def LogRelKlaus
877	* klaus logging.
878	*/
879	#define LogRelKlaus(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_KLAUS, LOG_GROUP, a)
880
881	/** @def LogRelFrank
882	* frank logging.
883	*/
884	#define LogRelFrank(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_FRANK, LOG_GROUP, a)
885
886	/** @def LogRelBird
887	* bird logging.
888	*/
889	#define LogRelBird(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_BIRD, LOG_GROUP, a)
890
891	/** @def LogRelNoName
892	* NoName logging.
893	*/
894	#define LogRelNoName(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_NONAME, LOG_GROUP, a)
895
896
897	/** @def LogRelIsItEnabled
898	* Checks whether the specified logging group is enabled or not.
899	*/
900	#define LogRelIsItEnabled(pvInst, fFlags, iGroup) \
901	LogRelIsItEnabledInternal((pvInst), (unsigned)(iGroup), (unsigned)(fFlags))
902
903	/** @def LogRelIsEnabled
904	* Checks whether level 1 logging is enabled.
905	*/
906	#define LogRelIsEnabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP)
907
908	/** @def LogRelIs2Enabled
909	* Checks whether level 2 logging is enabled.
910	*/
911	#define LogRelIs2Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP)
912
913	/** @def LogRelIs3Enabled
914	* Checks whether level 3 logging is enabled.
915	*/
916	#define LogRelIs3Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP)
917
918	/** @def LogRelIs4Enabled
919	* Checks whether level 4 logging is enabled.
920	*/
921	#define LogRelIs4Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP)
922
923	/** @def LogRelIs5Enabled
924	* Checks whether level 5 logging is enabled.
925	*/
926	#define LogRelIs5Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP)
927
928	/** @def LogRelIs6Enabled
929	* Checks whether level 6 logging is enabled.
930	*/
931	#define LogRelIs6Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP)
932
933	/** @def LogRelIsFlowEnabled
934	* Checks whether execution flow logging is enabled.
935	*/
936	#define LogRelIsFlowEnabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP)
937
938
939	#ifndef IN_GC
940	/**
941	* Sets the default release logger instance.
942	*
943	* @returns The old default instance.
944	* @param pLogger The new default release logger instance.
945	*/
946	RTDECL(PRTLOGGER) RTLogRelSetDefaultInstance(PRTLOGGER pLogger);
947	#endif /* !IN_GC */
948
949	/**
950	* Gets the default release logger instance.
951	*
952	* @returns Pointer to default release logger instance.
953	* @returns NULL if no default release logger instance available.
954	*/
955	RTDECL(PRTLOGGER) RTLogRelDefaultInstance(void);
956
957	/** Internal worker function.
958	* Don't call directly, use the LogRelIsItEnabled macro!
959	*/
960	DECLINLINE(bool) LogRelIsItEnabledInternal(void *pvInst, unsigned iGroup, unsigned fFlags)
961	{
962	register PRTLOGGER pLogger = (PRTLOGGER)pvInst ? (PRTLOGGER)pvInst : RTLogRelDefaultInstance();
963	if (pLogger)
964	{
965	register unsigned fGrpFlags = pLogger->afGroups[(unsigned)iGroup < pLogger->cGroups ? (unsigned)iGroup : 0];
966	if ((fGrpFlags & (fFlags \| RTLOGGRPFLAGS_ENABLED)) == (fFlags \| RTLOGGRPFLAGS_ENABLED))
967	return true;
968	}
969	return false;
970	}
971
972	/**
973	* Write to a logger instance, defaulting to the release one.
974	*
975	* This function will check whether the instance, group and flags makes up a
976	* logging kind which is currently enabled before writing anything to the log.
977	*
978	* @param pLogger Pointer to logger instance.
979	* @param fFlags The logging flags.
980	* @param iGroup The group.
981	* The value ~0U is reserved for compatability with RTLogLogger[V] and is
982	* only for internal usage!
983	* @param pszFormat Format string.
984	* @param ... Format arguments.
985	* @remark This is a worker function for LogRelIt.
986	*/
987	RTDECL(void) RTLogRelLogger(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, ...);
988
989	/**
990	* Write to a logger instance, defaulting to the release one.
991	*
992	* This function will check whether the instance, group and flags makes up a
993	* logging kind which is currently enabled before writing anything to the log.
994	*
995	* @param pLogger Pointer to logger instance. If NULL the default release instance is attempted.
996	* @param fFlags The logging flags.
997	* @param iGroup The group.
998	* The value ~0U is reserved for compatability with RTLogLogger[V] and is
999	* only for internal usage!
1000	* @param pszFormat Format string.
1001	* @param args Format arguments.
1002	*/
1003	RTDECL(void) RTLogRelLoggerV(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, va_list args);
1004
1005	/**
1006	* printf like function for writing to the default release log.
1007	*
1008	* @param pszFormat Printf like format string.
1009	* @param ... Optional arguments as specified in pszFormat.
1010	*
1011	* @remark The API doesn't support formatting of floating point numbers at the moment.
1012	*/
1013	RTDECL(void) RTLogRelPrintf(const char *pszFormat, ...);
1014
1015	/**
1016	* vprintf like function for writing to the default release log.
1017	*
1018	* @param pszFormat Printf like format string.
1019	* @param args Optional arguments as specified in pszFormat.
1020	*
1021	* @remark The API doesn't support formatting of floating point numbers at the moment.
1022	*/
1023	RTDECL(void) RTLogRelPrintfV(const char *pszFormat, va_list args);
1024
1025
1026	/** @} */
1027
1028
1029
1030	/** @name COM port logging
1031	* {
1032	*/
1033
1034	#ifdef DOXYGEN_RUNNING
1035	# define LOG_TO_COM
1036	# define LOG_NO_COM
1037	#endif
1038
1039	/** @def LOG_TO_COM
1040	* Redirects the normal loging macros to the serial versions.
1041	*/
1042
1043	/** @def LOG_NO_COM
1044	* Disables all LogCom* macros.
1045	*/
1046
1047	/** @def LogCom
1048	* Generic logging to serial port.
1049	*/
1050	#if defined(LOG_ENABLED) && !defined(LOG_NO_COM)
1051	# define LogCom(a) RTLogComPrintf a
1052	#else
1053	# define LogCom(a) do { } while (0)
1054	#endif
1055
1056	/** @def LogComFlow
1057	* Logging to serial port of execution flow.
1058	*/
1059	#if defined(LOG_ENABLED) && defined(LOG_ENABLE_FLOW) && !defined(LOG_NO_COM)
1060	# define LogComFlow(a) RTLogComPrintf a
1061	#else
1062	# define LogComFlow(a) do { } while (0)
1063	#endif
1064
1065	#ifdef LOG_TO_COM
1066	# undef Log
1067	# define Log(a) LogCom(a)
1068	# undef LogFlow
1069	# define LogFlow(a) LogComFlow(a)
1070	#endif
1071
1072	/** @} */
1073
1074
1075	/** @name Backdoor Logging
1076	* @{
1077	*/
1078
1079	#ifdef DOXYGEN_RUNNING
1080	# define LOG_TO_BACKDOOR
1081	# define LOG_NO_BACKDOOR
1082	#endif
1083
1084	/** @def LOG_TO_BACKDOOR
1085	* Redirects the normal logging macros to the backdoor versions.
1086	*/
1087
1088	/** @def LOG_NO_BACKDOOR
1089	* Disables all LogBackdoor* macros.
1090	*/
1091
1092	/** @def LogBackdoor
1093	* Generic logging to the VBox backdoor via port I/O.
1094	*/
1095	#if defined(LOG_ENABLED) && !defined(LOG_NO_BACKDOOR)
1096	# define LogBackdoor(a) RTLogBackdoorPrintf a
1097	#else
1098	# define LogBackdoor(a) do { } while (0)
1099	#endif
1100
1101	/** @def LogBackdoorFlow
1102	* Logging of execution flow messages to the backdoor I/O port.
1103	*/
1104	#if defined(LOG_ENABLED) && !defined(LOG_NO_BACKDOOR)
1105	# define LogBackdoorFlow(a) RTLogBackdoorPrintf a
1106	#else
1107	# define LogBackdoorFlow(a) do { } while (0)
1108	#endif
1109
1110	/** @def LogRelBackdoor
1111	* Release logging to the VBox backdoor via port I/O.
1112	*/
1113	#if !defined(LOG_NO_BACKDOOR)
1114	# define LogRelBackdoor(a) RTLogBackdoorPrintf a
1115	#else
1116	# define LogRelBackdoor(a) do { } while (0)
1117	#endif
1118
1119	#ifdef LOG_TO_BACKDOOR
1120	# undef Log
1121	# define Log(a) LogBackdoor(a)
1122	# undef LogFlow
1123	# define LogFlow(a) LogBackdoorFlow(a)
1124	# undef LogRel
1125	# define LogRel(a) LogRelBackdoor(a)
1126	#endif
1127
1128	/** @} */
1129
1130
1131
1132	/**
1133	* Gets the default logger instance.
1134	*
1135	* @returns Pointer to default logger instance.
1136	* @returns NULL if no default logger instance available.
1137	*/
1138	RTDECL(PRTLOGGER) RTLogDefaultInstance(void);
1139
1140	#ifndef IN_GC
1141	/**
1142	* Sets the default logger instance.
1143	*
1144	* @returns The old default instance.
1145	* @param pLogger The new default logger instance.
1146	*/
1147	RTDECL(PRTLOGGER) RTLogSetDefaultInstance(PRTLOGGER pLogger);
1148	#endif /* !IN_GC */
1149
1150	#ifdef IN_RING0
1151	/**
1152	* Changes the default logger instance for the current thread.
1153	*
1154	* @returns IPRT status code.
1155	* @param pLogger The logger instance. Pass NULL for deregistration.
1156	* @param uKey Associated key for cleanup purposes. If pLogger is NULL,
1157	* all instances with this key will be deregistered. So in
1158	* order to only deregister the instance associated with the
1159	* current thread use 0.
1160	*/
1161	RTDECL(int) RTLogSetDefaultInstanceThread(PRTLOGGER pLogger, uintptr_t uKey);
1162	#endif /* IN_RING0 */
1163
1164
1165	#ifdef LOG_ENABLED
1166	/** Internal worker function.
1167	* Don't call directly, use the LogIsItEnabled macro!
1168	*/
1169	DECLINLINE(bool) LogIsItEnabledInternal(void *pvInst, unsigned iGroup, unsigned fFlags)
1170	{
1171	register PRTLOGGER pLogger = (PRTLOGGER)pvInst ? (PRTLOGGER)pvInst : RTLogDefaultInstance();
1172	if (pLogger)
1173	{
1174	register unsigned fGrpFlags = pLogger->afGroups[(unsigned)iGroup < pLogger->cGroups ? (unsigned)iGroup : 0];
1175	if ((fGrpFlags & (fFlags \| RTLOGGRPFLAGS_ENABLED)) == (fFlags \| RTLOGGRPFLAGS_ENABLED))
1176	return true;
1177	}
1178	return false;
1179	}
1180	#endif
1181
1182
1183	#ifndef IN_GC
1184	/**
1185	* Creates the default logger instance for a iprt users.
1186	*
1187	* Any user of the logging features will need to implement
1188	* this or use the generic dummy.
1189	*
1190	* @returns Pointer to the logger instance.
1191	*/
1192	RTDECL(PRTLOGGER) RTLogDefaultInit(void);
1193
1194	/**
1195	* Create a logger instance.
1196	*
1197	* @returns iprt status code.
1198	*
1199	* @param ppLogger Where to store the logger instance.
1200	* @param fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
1201	* @param pszGroupSettings The initial group settings.
1202	* @param pszEnvVarBase Base name for the environment variables for this instance.
1203	* @param cGroups Number of groups in the array.
1204	* @param papszGroups Pointer to array of groups. This must stick around for the life of the
1205	* logger instance.
1206	* @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed if pszFilenameFmt specified.
1207	* @param pszFilenameFmt Log filename format string. Standard RTStrFormat().
1208	* @param ... Format arguments.
1209	*/
1210	RTDECL(int) RTLogCreate(PRTLOGGER ppLogger, RTUINT fFlags, const char pszGroupSettings,
1211	const char pszEnvVarBase, unsigned cGroups, const char const * papszGroups,
1212	RTUINT fDestFlags, const char *pszFilenameFmt, ...);
1213
1214	/**
1215	* Create a logger instance.
1216	*
1217	* @returns iprt status code.
1218	*
1219	* @param ppLogger Where to store the logger instance.
1220	* @param fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
1221	* @param pszGroupSettings The initial group settings.
1222	* @param pszEnvVarBase Base name for the environment variables for this instance.
1223	* @param cGroups Number of groups in the array.
1224	* @param papszGroups Pointer to array of groups. This must stick around for the life of the
1225	* logger instance.
1226	* @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed if pszFilenameFmt specified.
1227	* @param pszErrorMsg A buffer which is filled with an error message if something fails. May be NULL.
1228	* @param cchErrorMsg The size of the error message buffer.
1229	* @param pszFilenameFmt Log filename format string. Standard RTStrFormat().
1230	* @param ... Format arguments.
1231	*/
1232	RTDECL(int) RTLogCreateEx(PRTLOGGER ppLogger, RTUINT fFlags, const char pszGroupSettings,
1233	const char pszEnvVarBase, unsigned cGroups, const char const * papszGroups,
1234	RTUINT fDestFlags, char pszErrorMsg, size_t cchErrorMsg, const char pszFilenameFmt, ...);
1235
1236	/**
1237	* Create a logger instance.
1238	*
1239	* @returns iprt status code.
1240	*
1241	* @param ppLogger Where to store the logger instance.
1242	* @param fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
1243	* @param pszGroupSettings The initial group settings.
1244	* @param pszEnvVarBase Base name for the environment variables for this instance.
1245	* @param cGroups Number of groups in the array.
1246	* @param papszGroups Pointer to array of groups. This must stick around for the life of the
1247	* logger instance.
1248	* @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed if pszFilenameFmt specified.
1249	* @param pszErrorMsg A buffer which is filled with an error message if something fails. May be NULL.
1250	* @param cchErrorMsg The size of the error message buffer.
1251	* @param pszFilenameFmt Log filename format string. Standard RTStrFormat().
1252	* @param args Format arguments.
1253	*/
1254	RTDECL(int) RTLogCreateExV(PRTLOGGER ppLogger, RTUINT fFlags, const char pszGroupSettings,
1255	const char pszEnvVarBase, unsigned cGroups, const char const * papszGroups,
1256	RTUINT fDestFlags, char pszErrorMsg, size_t cchErrorMsg, const char pszFilenameFmt, va_list args);
1257
1258	/**
1259	* Create a logger instance for singled threaded ring-0 usage.
1260	*
1261	* @returns iprt status code.
1262	*
1263	* @param pLogger Where to create the logger instance.
1264	* @param cbLogger The amount of memory available for the logger instance.
1265	* @param pfnLogger Pointer to logger wrapper function for the clone.
1266	* @param pfnFlush Pointer to flush function for the clone.
1267	* @param fFlags Logger instance flags for the clone, a combination of the RTLOGFLAGS_* values.
1268	* @param fDestFlags The destination flags.
1269	*/
1270	RTDECL(int) RTLogCreateForR0(PRTLOGGER pLogger, size_t cbLogger, PFNRTLOGGER pfnLogger, PFNRTLOGFLUSH pfnFlush, RTUINT fFlags, RTUINT fDestFlags);
1271
1272	/**
1273	* Destroys a logger instance.
1274	*
1275	* The instance is flushed and all output destinations closed (where applicable).
1276	*
1277	* @returns iprt status code.
1278	* @param pLogger The logger instance which close destroyed.
1279	*/
1280	RTDECL(int) RTLogDestroy(PRTLOGGER pLogger);
1281
1282	/**
1283	* Create a logger instance clone for GC usage.
1284	*
1285	* @returns iprt status code.
1286	*
1287	* @param pLogger The logger instance to be cloned.
1288	* @param pLoggerGC Where to create the GC logger instance.
1289	* @param cbLoggerGC Amount of memory allocated to for the GC logger instance clone.
1290	* @param pfnLoggerGCPtr Pointer to logger wrapper function for this instance (GC Ptr).
1291	* @param pfnFlushGCPtr Pointer to flush function (GC Ptr).
1292	* @param fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
1293	*/
1294	RTDECL(int) RTLogCloneGC(PRTLOGGER pLogger, PRTLOGGERGC pLoggerGC, size_t cbLoggerGC,
1295	RTGCPTR pfnLoggerGCPtr, RTGCPTR pfnFlushGCPtr, RTUINT fFlags);
1296
1297	/**
1298	* Flushes a GC logger instance to a HC logger.
1299	*
1300	* @returns iprt status code.
1301	* @param pLogger The HC logger instance to flush pLoggerGC to.
1302	* If NULL the default logger is used.
1303	* @param pLoggerGC The GC logger instance to flush.
1304	*/
1305	RTDECL(void) RTLogFlushGC(PRTLOGGER pLogger, PRTLOGGERGC pLoggerGC);
1306
1307	/**
1308	* Flushes the buffer in one logger instance onto another logger.
1309	*
1310	* @returns iprt status code.
1311	*
1312	* @param pSrcLogger The logger instance to flush.
1313	* @param pDstLogger The logger instance to flush onto.
1314	* If NULL the default logger will be used.
1315	*/
1316	RTDECL(void) RTLogFlushToLogger(PRTLOGGER pSrcLogger, PRTLOGGER pDstLogger);
1317
1318	/**
1319	* Copies the group settings and flags from logger instance to another.
1320	*
1321	* @returns IPRT status code.
1322	* @param pDstLogger The destination logger instance.
1323	* @param pSrcLogger The source logger instance. If NULL the default one is used.
1324	* @param fFlagsOr OR mask for the flags.
1325	* @param fFlagsAnd AND mask for the flags.
1326	*/
1327	RTDECL(int) RTLogCopyGroupsAndFlags(PRTLOGGER pDstLogger, PCRTLOGGER pSrcLogger, unsigned fFlagsOr, unsigned fFlagsAnd);
1328
1329	/**
1330	* Updates the group settings for the logger instance using the specified
1331	* specification string.
1332	*
1333	* @returns iprt status code.
1334	* Failures can safely be ignored.
1335	* @param pLogger Logger instance (NULL for default logger).
1336	* @param pszVar Value to parse.
1337	*/
1338	RTDECL(int) RTLogGroupSettings(PRTLOGGER pLogger, const char *pszVar);
1339	#endif /* !IN_GC */
1340
1341	/**
1342	* Updates the flags for the logger instance using the specified
1343	* specification string.
1344	*
1345	* @returns iprt status code.
1346	* Failures can safely be ignored.
1347	* @param pLogger Logger instance (NULL for default logger).
1348	* @param pszVar Value to parse.
1349	*/
1350	RTDECL(int) RTLogFlags(PRTLOGGER pLogger, const char *pszVar);
1351
1352	/**
1353	* Flushes the specified logger.
1354	*
1355	* @param pLogger The logger instance to flush.
1356	* If NULL the default instance is used. The default instance
1357	* will not be initialized by this call.
1358	*/
1359	RTDECL(void) RTLogFlush(PRTLOGGER pLogger);
1360
1361	/**
1362	* Write to a logger instance.
1363	*
1364	* @param pLogger Pointer to logger instance.
1365	* @param pvCallerRet Ignored.
1366	* @param pszFormat Format string.
1367	* @param ... Format arguments.
1368	*/
1369	RTDECL(void) RTLogLogger(PRTLOGGER pLogger, void pvCallerRet, const char pszFormat, ...);
1370
1371	/**
1372	* Write to a logger instance.
1373	*
1374	* @param pLogger Pointer to logger instance.
1375	* @param pszFormat Format string.
1376	* @param args Format arguments.
1377	*/
1378	RTDECL(void) RTLogLoggerV(PRTLOGGER pLogger, const char *pszFormat, va_list args);
1379
1380	/**
1381	* Write to a logger instance.
1382	*
1383	* This function will check whether the instance, group and flags makes up a
1384	* logging kind which is currently enabled before writing anything to the log.
1385	*
1386	* @param pLogger Pointer to logger instance. If NULL the default logger instance will be attempted.
1387	* @param fFlags The logging flags.
1388	* @param iGroup The group.
1389	* The value ~0U is reserved for compatability with RTLogLogger[V] and is
1390	* only for internal usage!
1391	* @param pszFormat Format string.
1392	* @param ... Format arguments.
1393	* @remark This is a worker function of LogIt.
1394	*/
1395	RTDECL(void) RTLogLoggerEx(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, ...);
1396
1397	/**
1398	* Write to a logger instance.
1399	*
1400	* This function will check whether the instance, group and flags makes up a
1401	* logging kind which is currently enabled before writing anything to the log.
1402	*
1403	* @param pLogger Pointer to logger instance. If NULL the default logger instance will be attempted.
1404	* @param fFlags The logging flags.
1405	* @param iGroup The group.
1406	* The value ~0U is reserved for compatability with RTLogLogger[V] and is
1407	* only for internal usage!
1408	* @param pszFormat Format string.
1409	* @param args Format arguments.
1410	*/
1411	RTDECL(void) RTLogLoggerExV(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, va_list args);
1412
1413	/**
1414	* printf like function for writing to the default log.
1415	*
1416	* @param pszFormat Printf like format string.
1417	* @param ... Optional arguments as specified in pszFormat.
1418	*
1419	* @remark The API doesn't support formatting of floating point numbers at the moment.
1420	*/
1421	RTDECL(void) RTLogPrintf(const char *pszFormat, ...);
1422
1423	/**
1424	* vprintf like function for writing to the default log.
1425	*
1426	* @param pszFormat Printf like format string.
1427	* @param args Optional arguments as specified in pszFormat.
1428	*
1429	* @remark The API doesn't support formatting of floating point numbers at the moment.
1430	*/
1431	RTDECL(void) RTLogPrintfV(const char *pszFormat, va_list args);
1432
1433
1434	#ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/string.h */
1435	#define DECLARED_FNRTSTROUTPUT
1436	/**
1437	* Output callback.
1438	*
1439	* @returns number of bytes written.
1440	* @param pvArg User argument.
1441	* @param pachChars Pointer to an array of utf-8 characters.
1442	* @param cbChars Number of bytes in the character array pointed to by pachChars.
1443	*/
1444	typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void pvArg, const char pachChars, size_t cbChars);
1445	/** Pointer to callback function. */
1446	typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
1447	#endif
1448
1449	/**
1450	* Partial vsprintf worker implementation.
1451	*
1452	* @returns number of bytes formatted.
1453	* @param pfnOutput Output worker.
1454	* Called in two ways. Normally with a string an it's length.
1455	* For termination, it's called with NULL for string, 0 for length.
1456	* @param pvArg Argument to output worker.
1457	* @param pszFormat Format string.
1458	* @param args Argument list.
1459	*/
1460	RTDECL(size_t) RTLogFormatV(PFNRTSTROUTPUT pfnOutput, void pvArg, const char pszFormat, va_list args);
1461
1462	/**
1463	* Write log buffer to COM port.
1464	*
1465	* @param pach Pointer to the buffer to write.
1466	* @param cb Number of bytes to write.
1467	*/
1468	RTDECL(void) RTLogWriteCom(const char *pach, size_t cb);
1469
1470	/**
1471	* Prints a formatted string to the serial port used for logging.
1472	*
1473	* @returns Number of bytes written.
1474	* @param pszFormat Format string.
1475	* @param ... Optional arguments specified in the format string.
1476	*/
1477	RTDECL(size_t) RTLogComPrintf(const char *pszFormat, ...);
1478
1479	/**
1480	* Prints a formatted string to the serial port used for logging.
1481	*
1482	* @returns Number of bytes written.
1483	* @param pszFormat Format string.
1484	* @param args Optional arguments specified in the format string.
1485	*/
1486	RTDECL(size_t) RTLogComPrintfV(const char *pszFormat, va_list args);
1487
1488
1489	#if 0 /* not implemented yet */
1490
1491	/** Indicates that the semaphores shall be used to notify the other
1492	* part about buffer changes. */
1493	#define LOGHOOKBUFFER_FLAGS_SEMAPHORED 1
1494
1495	/**
1496	* Log Hook Buffer.
1497	* Use to commuicate between the logger and a log consumer.
1498	*/
1499	typedef struct RTLOGHOOKBUFFER
1500	{
1501	/** Write pointer. */
1502	volatile void *pvWrite;
1503	/** Read pointer. */
1504	volatile void *pvRead;
1505	/** Buffer start. */
1506	void *pvStart;
1507	/** Buffer end (exclusive). */
1508	void *pvEnd;
1509	/** Signaling semaphore used by the writer to wait on a full buffer.
1510	* Only used when indicated in flags. */
1511	void *pvSemWriter;
1512	/** Signaling semaphore used by the read to wait on an empty buffer.
1513	* Only used when indicated in flags. */
1514	void *pvSemReader;
1515	/** Buffer flags. Current reserved and set to zero. */
1516	volatile unsigned fFlags;
1517	} RTLOGHOOKBUFFER;
1518	/** Pointer to a log hook buffer. */
1519	typedef RTLOGHOOKBUFFER *PRTLOGHOOKBUFFER;
1520
1521
1522	/**
1523	* Register a logging hook.
1524	*
1525	* This type of logging hooks are expecting different threads acting
1526	* producer and consumer. They share a circular buffer which have two
1527	* pointers one for each end. When the buffer is full there are two
1528	* alternatives (indicated by a buffer flag), either wait for the
1529	* consumer to get it's job done, or to write a generic message saying
1530	* buffer overflow.
1531	*
1532	* Since the waiting would need a signal semaphore, we'll skip that for now.
1533	*
1534	* @returns iprt status code.
1535	* @param pBuffer Pointer to a logger hook buffer.
1536	*/
1537	RTDECL(int) RTLogRegisterHook(PRTLOGGER pLogger, PRTLOGHOOKBUFFER pBuffer);
1538
1539	/**
1540	* Deregister a logging hook registerd with RTLogRegisterHook().
1541	*
1542	* @returns iprt status code.
1543	* @param pBuffer Pointer to a logger hook buffer.
1544	*/
1545	RTDECL(int) RTLogDeregisterHook(PRTLOGGER pLogger, PRTLOGHOOKBUFFER pBuffer);
1546
1547	#endif /* not implemented yet */
1548
1549
1550
1551	/**
1552	* Write log buffer to a debugger (RTLOGDEST_DEBUGGER).
1553	*
1554	* @param pach What to write.
1555	* @param cb How much to write.
1556	* @remark When linking statically, this function can be replaced by defining your own.
1557	*/
1558	RTDECL(void) RTLogWriteDebugger(const char *pach, size_t cb);
1559
1560	/**
1561	* Write log buffer to a user defined output stream (RTLOGDEST_USER).
1562	*
1563	* @param pach What to write.
1564	* @param cb How much to write.
1565	* @remark When linking statically, this function can be replaced by defining your own.
1566	*/
1567	RTDECL(void) RTLogWriteUser(const char *pach, size_t cb);
1568
1569	/**
1570	* Write log buffer to stdout (RTLOGDEST_STDOUT).
1571	*
1572	* @param pach What to write.
1573	* @param cb How much to write.
1574	* @remark When linking statically, this function can be replaced by defining your own.
1575	*/
1576	RTDECL(void) RTLogWriteStdOut(const char *pach, size_t cb);
1577
1578	/**
1579	* Write log buffer to stdout (RTLOGDEST_STDERR).
1580	*
1581	* @param pach What to write.
1582	* @param cb How much to write.
1583	* @remark When linking statically, this function can be replaced by defining your own.
1584	*/
1585	RTDECL(void) RTLogWriteStdErr(const char *pach, size_t cb);
1586
1587	#ifdef VBOX
1588
1589	/**
1590	* Prints a formatted string to the backdoor port.
1591	*
1592	* @returns Number of bytes written.
1593	* @param pszFormat Format string.
1594	* @param ... Optional arguments specified in the format string.
1595	*/
1596	RTDECL(size_t) RTLogBackdoorPrintf(const char *pszFormat, ...);
1597
1598	/**
1599	* Prints a formatted string to the backdoor port.
1600	*
1601	* @returns Number of bytes written.
1602	* @param pszFormat Format string.
1603	* @param args Optional arguments specified in the format string.
1604	*/
1605	RTDECL(size_t) RTLogBackdoorPrintfV(const char *pszFormat, va_list args);
1606
1607	#endif /* VBOX */
1608
1609	__END_DECLS
1610
1611	/** @} */
1612
1613	#endif
1614

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/iprt/log.h@ 8622

Download in other formats: