log.h@ 4071

Last change on this file since 4071 was 4071, checked in by vboxsync, 17 years ago
Biggest check-in ever. New source code headers for all (C) innotek files.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 48.7 KB

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

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

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

Download in other formats: