stam.h@ 2889

Last change on this file since 2889 was 2244, checked in by vboxsync, 18 years ago
NS and PCT units.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 43.7 KB

Line
1	/** @file
2	* STAM - Statistics Manager.
3	*/
4
5	/*
6	* Copyright (C) 2006 InnoTek Systemberatung 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	* If you received this file as part of a commercial VirtualBox
17	* distribution, then only the terms of your commercial VirtualBox
18	* license agreement apply instead of the previous paragraph.
19	*/
20
21	#ifndef __VBox_stam_h__
22	#define __VBox_stam_h__
23
24
25	#include <VBox/cdefs.h>
26	#include <VBox/types.h>
27	#include <iprt/stdarg.h>
28	#ifdef _MSC_VER
29	# if _MSC_VER >= 1400
30	# include <intrin.h>
31	# endif
32	#endif
33
34	__BEGIN_DECLS
35
36	/** @defgroup grp_stam The Statistics Manager API
37	* @{
38	*/
39
40	#if defined(VBOX_WITHOUT_RELEASE_STATISTICS) && defined(VBOX_WITH_STATISTICS)
41	# error "Both VBOX_WITHOUT_RELEASE_STATISTICS and VBOX_WITH_STATISTICS are defined! Make up your mind!"
42	#endif
43
44
45	/** @def STAM_GET_TS
46	* Gets the CPU timestamp counter.
47	*
48	* @param u64 The 64-bit variable which the timestamp shall be saved in.
49	*/
50	#ifdef __GNUC__
51	# define STAM_GET_TS(u64) \
52	__asm__ __volatile__ ("rdtsc\n\t" : "=a" ( ((uint32_t )&(u64))[0] ), "=d" ( ((uint32_t )&(u64))[1]))
53	#elif _MSC_VER >= 1400
54	# pragma intrinsic(__rdtsc)
55	# define STAM_GET_TS(u64) \
56	do { (u64) = __rdtsc(); } while (0)
57	#else
58	# define STAM_GET_TS(u64) \
59	do { \
60	uint64_t u64Tmp; \
61	__asm { \
62	__asm rdtsc \
63	__asm mov dword ptr [u64Tmp], eax \
64	__asm mov dword ptr [u64Tmp + 4], edx \
65	} \
66	(u64) = u64Tmp; \
67	} while (0)
68	#endif
69
70
71	/** @def STAM_REL_STATS
72	* Code for inclusion only when VBOX_WITH_STATISTICS is defined.
73	* @param code A code block enclosed in {}.
74	*/
75	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
76	# define STAM_REL_STATS(code) do code while(0)
77	#else
78	# define STAM_REL_STATS(code) do {} while(0)
79	#endif
80	/** @def STAM_STATS
81	* Code for inclusion only when VBOX_WITH_STATISTICS is defined.
82	* @param code A code block enclosed in {}.
83	*/
84	#ifdef VBOX_WITH_STATISTICS
85	# define STAM_STATS(code) STAM_REL_STATS(code)
86	#else
87	# define STAM_STATS(code) do {} while(0)
88	#endif
89
90
91	/**
92	* Sample type.
93	*/
94	typedef enum STAMTYPE
95	{
96	/** Invalid entry. */
97	STAMTYPE_INVALID = 0,
98	/** Generic counter. */
99	STAMTYPE_COUNTER,
100	/** Profiling of an function. */
101	STAMTYPE_PROFILE,
102	/** Profiling of an operation. */
103	STAMTYPE_PROFILE_ADV,
104	/** Ratio of A to B, uint32_t types. Not reset. */
105	STAMTYPE_RATIO_U32,
106	/** Ratio of A to B, uint32_t types. Reset both to 0. */
107	STAMTYPE_RATIO_U32_RESET,
108	/** Callback. */
109	STAMTYPE_CALLBACK,
110	/** Generic unsigned 8-bit value. Not reset. */
111	STAMTYPE_U8,
112	/** Generic unsigned 8-bit value. Reset to 0. */
113	STAMTYPE_U8_RESET,
114	/** Generic hexadecimal unsigned 8-bit value. Not reset. */
115	STAMTYPE_X8,
116	/** Generic hexadecimal unsigned 8-bit value. Reset to 0. */
117	STAMTYPE_X8_RESET,
118	/** Generic unsigned 16-bit value. Not reset. */
119	STAMTYPE_U16,
120	/** Generic unsigned 16-bit value. Reset to 0. */
121	STAMTYPE_U16_RESET,
122	/** Generic hexadecimal unsigned 16-bit value. Not reset. */
123	STAMTYPE_X16,
124	/** Generic hexadecimal unsigned 16-bit value. Reset to 0. */
125	STAMTYPE_X16_RESET,
126	/** Generic unsigned 32-bit value. Not reset. */
127	STAMTYPE_U32,
128	/** Generic unsigned 32-bit value. Reset to 0. */
129	STAMTYPE_U32_RESET,
130	/** Generic hexadecimal unsigned 32-bit value. Not reset. */
131	STAMTYPE_X32,
132	/** Generic hexadecimal unsigned 32-bit value. Reset to 0. */
133	STAMTYPE_X32_RESET,
134	/** Generic unsigned 64-bit value. Not reset. */
135	STAMTYPE_U64,
136	/** Generic unsigned 64-bit value. Reset to 0. */
137	STAMTYPE_U64_RESET,
138	/** Generic hexadecimal unsigned 64-bit value. Not reset. */
139	STAMTYPE_X64,
140	/** Generic hexadecimal unsigned 64-bit value. Reset to 0. */
141	STAMTYPE_X64_RESET,
142	/** The end (exclusive). */
143	STAMTYPE_END
144	} STAMTYPE;
145
146	/**
147	* Sample visibility type.
148	*/
149	typedef enum STAMVISIBILITY
150	{
151	/** Invalid entry. */
152	STAMVISIBILITY_INVALID = 0,
153	/** Always visible. */
154	STAMVISIBILITY_ALWAYS,
155	/** Only visible when used (/hit). */
156	STAMVISIBILITY_USED,
157	/** Not visible in the GUI. */
158	STAMVISIBILITY_NOT_GUI,
159	/** The end (exclusive). */
160	STAMVISIBILITY_END
161	} STAMVISIBILITY;
162
163	/**
164	* Sample unit.
165	*/
166	typedef enum STAMUNIT
167	{
168	/** Invalid entry .*/
169	STAMUNIT_INVALID = 0,
170	/** No unit. */
171	STAMUNIT_NONE,
172	/** Number of calls. */
173	STAMUNIT_CALLS,
174	/** Count of whatever. */
175	STAMUNIT_COUNT,
176	/** Count of bytes. */
177	STAMUNIT_BYTES,
178	/** Count of bytes. */
179	STAMUNIT_PAGES,
180	/** Error count. */
181	STAMUNIT_ERRORS,
182	/** Number of occurences. */
183	STAMUNIT_OCCURENCES,
184	/** Ticks per call. */
185	STAMUNIT_TICKS_PER_CALL,
186	/** Ticks per occurence. */
187	STAMUNIT_TICKS_PER_OCCURENCE,
188	/** Ratio of good vs. bad. */
189	STAMUNIT_GOOD_BAD,
190	/** Megabytes. */
191	STAMUNIT_MEGABYTES,
192	/** Kilobytes. */
193	STAMUNIT_KILOBYTES,
194	/** Nano seconds. */
195	STAMUNIT_NS,
196	/** Nanoseconds per call. */
197	STAMUNIT_NS_PER_CALL,
198	/** Nanoseconds per call. */
199	STAMUNIT_NS_PER_OCCURENCE,
200	/** Percentage. */
201	STAMUNIT_PCT,
202	/** The end (exclusive). */
203	STAMUNIT_END
204	} STAMUNIT;
205
206
207	/** @def STAM_REL_U8_INC
208	* Increments a uint8_t sample by one.
209	*
210	* @param pCounter Pointer to the uint8_t variable to operate on.
211	*/
212	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
213	# define STAM_REL_U8_INC(pCounter) \
214	do { ++*(pCounter); } while (0)
215	#else
216	# define STAM_REL_U8_INC(pCounter) do { } while (0)
217	#endif
218	/** @def STAM_U8_INC
219	* Increments a uint8_t sample by one.
220	*
221	* @param pCounter Pointer to the uint8_t variable to operate on.
222	*/
223	#ifdef VBOX_WITH_STATISTICS
224	# define STAM_U8_INC(pCounter) STAM_REL_U8_INC(pCounter)
225	#else
226	# define STAM_U8_INC(pCounter) do { } while (0)
227	#endif
228
229
230	/** @def STAM_REL_U8_DEC
231	* Decrements a uint8_t sample by one.
232	*
233	* @param pCounter Pointer to the uint8_t variable to operate on.
234	*/
235	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
236	# define STAM_REL_U8_DEC(pCounter) \
237	do { --*(pCounter); } while (0)
238	#else
239	# define STAM_REL_U8_DEC(pCounter) do { } while (0)
240	#endif
241	/** @def STAM_U8_DEC
242	* Decrements a uint8_t sample by one.
243	*
244	* @param pCounter Pointer to the uint8_t variable to operate on.
245	*/
246	#ifdef VBOX_WITH_STATISTICS
247	# define STAM_U8_DEC(pCounter) STAM_REL_U8_DEC(pCounter)
248	#else
249	# define STAM_U8_DEC(pCounter) do { } while (0)
250	#endif
251
252
253	/** @def STAM_REL_U8_ADD
254	* Increments a uint8_t sample by a value.
255	*
256	* @param pCounter Pointer to the uint8_t variable to operate on.
257	* @param Addend The value to add.
258	*/
259	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
260	# define STAM_REL_U8_ADD(pCounter, Addend) \
261	do { *(pCounter) += (Addend); } while (0)
262	#else
263	# define STAM_REL_U8_ADD(pCounter, Addend) do { } while (0)
264	#endif
265	/** @def STAM_U8_ADD
266	* Increments a uint8_t sample by a value.
267	*
268	* @param pCounter Pointer to the uint8_t variable to operate on.
269	* @param Addend The value to add.
270	*/
271	#ifdef VBOX_WITH_STATISTICS
272	# define STAM_U8_ADD(pCounter, Addend) STAM_REL_U8_ADD(pCounter, Addend
273	#else
274	# define STAM_U8_ADD(pCounter, Addend) do { } while (0)
275	#endif
276
277
278	/** @def STAM_REL_U16_INC
279	* Increments a uint16_t sample by one.
280	*
281	* @param pCounter Pointer to the uint16_t variable to operate on.
282	*/
283	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
284	# define STAM_REL_U16_INC(pCounter) \
285	do { ++*(pCounter); } while (0)
286	#else
287	# define STAM_REL_U16_INC(pCounter) do { } while (0)
288	#endif
289	/** @def STAM_U16_INC
290	* Increments a uint16_t sample by one.
291	*
292	* @param pCounter Pointer to the uint16_t variable to operate on.
293	*/
294	#ifdef VBOX_WITH_STATISTICS
295	# define STAM_U16_INC(pCounter) STAM_REL_U16_INC(pCounter)
296	#else
297	# define STAM_U16_INC(pCounter) do { } while (0)
298	#endif
299
300
301	/** @def STAM_REL_U16_DEC
302	* Decrements a uint16_t sample by one.
303	*
304	* @param pCounter Pointer to the uint16_t variable to operate on.
305	*/
306	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
307	# define STAM_REL_U16_DEC(pCounter) \
308	do { --*(pCounter); } while (0)
309	#else
310	# define STAM_REL_U16_DEC(pCounter) do { } while (0)
311	#endif
312	/** @def STAM_U16_DEC
313	* Decrements a uint16_t sample by one.
314	*
315	* @param pCounter Pointer to the uint16_t variable to operate on.
316	*/
317	#ifdef VBOX_WITH_STATISTICS
318	# define STAM_U16_DEC(pCounter) STAM_REL_U16_DEC(pCounter)
319	#else
320	# define STAM_U16_DEC(pCounter) do { } while (0)
321	#endif
322
323
324	/** @def STAM_REL_U16_INC
325	* Increments a uint16_t sample by a value.
326	*
327	* @param pCounter Pointer to the uint16_t variable to operate on.
328	* @param Addend The value to add.
329	*/
330	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
331	# define STAM_REL_U16_ADD(pCounter, Addend) \
332	do { *(pCounter) += (Addend); } while (0)
333	#else
334	# define STAM_REL_U16_ADD(pCounter, Addend) do { } while (0)
335	#endif
336	/** @def STAM_U16_INC
337	* Increments a uint16_t sample by a value.
338	*
339	* @param pCounter Pointer to the uint16_t variable to operate on.
340	* @param Addend The value to add.
341	*/
342	#ifdef VBOX_WITH_STATISTICS
343	# define STAM_U16_ADD(pCounter, Addend) STAM_REL_U16_ADD(pCounter, Addend)
344	#else
345	# define STAM_U16_ADD(pCounter, Addend) do { } while (0)
346	#endif
347
348
349	/** @def STAM_REL_U32_INC
350	* Increments a uint32_t sample by one.
351	*
352	* @param pCounter Pointer to the uint32_t variable to operate on.
353	*/
354	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
355	# define STAM_REL_U32_INC(pCounter) \
356	do { ++*(pCounter); } while (0)
357	#else
358	# define STAM_REL_U32_INC(pCounter) do { } while (0)
359	#endif
360	/** @def STAM_U32_INC
361	* Increments a uint32_t sample by one.
362	*
363	* @param pCounter Pointer to the uint32_t variable to operate on.
364	*/
365	#ifdef VBOX_WITH_STATISTICS
366	# define STAM_U32_INC(pCounter) STAM_REL_U32_INC(pCounter)
367	#else
368	# define STAM_U32_INC(pCounter) do { } while (0)
369	#endif
370
371
372	/** @def STAM_REL_U32_DEC
373	* Decrements a uint32_t sample by one.
374	*
375	* @param pCounter Pointer to the uint32_t variable to operate on.
376	*/
377	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
378	# define STAM_REL_U32_DEC(pCounter) \
379	do { --*(pCounter); } while (0)
380	#else
381	# define STAM_REL_U32_DEC(pCounter) do { } while (0)
382	#endif
383	/** @def STAM_U32_DEC
384	* Decrements a uint32_t sample by one.
385	*
386	* @param pCounter Pointer to the uint32_t variable to operate on.
387	*/
388	#ifdef VBOX_WITH_STATISTICS
389	# define STAM_U32_DEC(pCounter) STAM_REL_U32_DEC(pCounter)
390	#else
391	# define STAM_U32_DEC(pCounter) do { } while (0)
392	#endif
393
394
395	/** @def STAM_REL_U32_ADD
396	* Increments a uint32_t sample by value.
397	*
398	* @param pCounter Pointer to the uint32_t variable to operate on.
399	* @param Addend The value to add.
400	*/
401	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
402	# define STAM_REL_U32_ADD(pCounter, Addend) \
403	do { *(pCounter) += (Addend); } while (0)
404	#else
405	# define STAM_REL_U32_ADD(pCounter, Addend) do { } while (0)
406	#endif
407	/** @def STAM_U32_ADD
408	* Increments a uint32_t sample by value.
409	*
410	* @param pCounter Pointer to the uint32_t variable to operate on.
411	* @param Addend The value to add.
412	*/
413	#ifdef VBOX_WITH_STATISTICS
414	# define STAM_U32_ADD(pCounter, Addend) STAM_REL_U32_ADD(pCounter, Addend)
415	#else
416	# define STAM_U32_ADD(pCounter, Addend) do { } while (0)
417	#endif
418
419
420	/** @def STAM_REL_U64_INC
421	* Increments a uint64_t sample by one.
422	*
423	* @param pCounter Pointer to the uint64_t variable to operate on.
424	*/
425	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
426	# define STAM_REL_U64_INC(pCounter) \
427	do { ++*(pCounter); } while (0)
428	#else
429	# define STAM_REL_U64_INC(pCounter) do { } while (0)
430	#endif
431	/** @def STAM_U64_INC
432	* Increments a uint64_t sample by one.
433	*
434	* @param pCounter Pointer to the uint64_t variable to operate on.
435	*/
436	#ifdef VBOX_WITH_STATISTICS
437	# define STAM_U64_INC(pCounter) STAM_REL_U64_INC(pCounter)
438	#else
439	# define STAM_U64_INC(pCounter) do { } while (0)
440	#endif
441
442
443	/** @def STAM_REL_U64_DEC
444	* Decrements a uint64_t sample by one.
445	*
446	* @param pCounter Pointer to the uint64_t variable to operate on.
447	*/
448	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
449	# define STAM_REL_U64_DEC(pCounter) \
450	do { --*(pCounter); } while (0)
451	#else
452	# define STAM_REL_U64_DEC(pCounter) do { } while (0)
453	#endif
454	/** @def STAM_U64_DEC
455	* Decrements a uint64_t sample by one.
456	*
457	* @param pCounter Pointer to the uint64_t variable to operate on.
458	*/
459	#ifdef VBOX_WITH_STATISTICS
460	# define STAM_U64_DEC(pCounter) STAM_REL_U64_DEC(pCounter)
461	#else
462	# define STAM_U64_DEC(pCounter) do { } while (0)
463	#endif
464
465
466	/** @def STAM_REL_U64_ADD
467	* Increments a uint64_t sample by a value.
468	*
469	* @param pCounter Pointer to the uint64_t variable to operate on.
470	* @param Addend The value to add.
471	*/
472	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
473	# define STAM_REL_U64_ADD(pCounter, Addend) \
474	do { *(pCounter) += (Addend); } while (0)
475	#else
476	# define STAM_REL_U64_ADD(pCounter, Addend) do { } while (0)
477	#endif
478	/** @def STAM_U64_ADD
479	* Increments a uint64_t sample by a value.
480	*
481	* @param pCounter Pointer to the uint64_t variable to operate on.
482	* @param Addend The value to add.
483	*/
484	#ifdef VBOX_WITH_STATISTICS
485	# define STAM_U64_ADD(pCounter, Addend) STAM_REL_U64_ADD(pCounter, Addend)
486	#else
487	# define STAM_U64_ADD(pCounter, Addend) do { } while (0)
488	#endif
489
490
491	/**
492	* Counter sample - STAMTYPE_COUNTER.
493	*/
494	typedef struct STAMCOUNTER
495	{
496	/** The current count. */
497	volatile uint64_t c;
498	} STAMCOUNTER;
499	/** Pointer to a counter. */
500	typedef STAMCOUNTER *PSTAMCOUNTER;
501	/** Pointer to a const counter. */
502	typedef const STAMCOUNTER *PCSTAMCOUNTER;
503
504
505	/** @def STAM_REL_COUNTER_INC
506	* Increments a counter sample by one.
507	*
508	* @param pCounter Pointer to the STAMCOUNTER structure to operate on.
509	*/
510	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
511	# define STAM_REL_COUNTER_INC(pCounter) \
512	do { (pCounter)->c++; } while (0)
513	#else
514	# define STAM_REL_COUNTER_INC(pCounter) do { } while (0)
515	#endif
516	/** @def STAM_COUNTER_INC
517	* Increments a counter sample by one.
518	*
519	* @param pCounter Pointer to the STAMCOUNTER structure to operate on.
520	*/
521	#ifdef VBOX_WITH_STATISTICS
522	# define STAM_COUNTER_INC(pCounter) STAM_REL_COUNTER_INC(pCounter)
523	#else
524	# define STAM_COUNTER_INC(pCounter) do { } while (0)
525	#endif
526
527
528	/** @def STAM_REL_COUNTER_DEC
529	* Decrements a counter sample by one.
530	*
531	* @param pCounter Pointer to the STAMCOUNTER structure to operate on.
532	*/
533	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
534	# define STAM_REL_COUNTER_DEC(pCounter) \
535	do { (pCounter)->c--; } while (0)
536	#else
537	# define STAM_REL_COUNTER_DEC(pCounter) do { } while (0)
538	#endif
539	/** @def STAM_COUNTER_DEC
540	* Decrements a counter sample by one.
541	*
542	* @param pCounter Pointer to the STAMCOUNTER structure to operate on.
543	*/
544	#ifdef VBOX_WITH_STATISTICS
545	# define STAM_COUNTER_DEC(pCounter) STAM_REL_COUNTER_DEC(pCounter)
546	#else
547	# define STAM_COUNTER_DEC(pCounter) do { } while (0)
548	#endif
549
550
551	/** @def STAM_REL_COUNTER_ADD
552	* Increments a counter sample by a value.
553	*
554	* @param pCounter Pointer to the STAMCOUNTER structure to operate on.
555	* @param Addend The value to add to the counter.
556	*/
557	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
558	# define STAM_REL_COUNTER_ADD(pCounter, Addend) \
559	do { (pCounter)->c += (Addend); } while (0)
560	#else
561	# define STAM_REL_COUNTER_ADD(pCounter, Addend) do { } while (0)
562	#endif
563	/** @def STAM_COUNTER_ADD
564	* Increments a counter sample by a value.
565	*
566	* @param pCounter Pointer to the STAMCOUNTER structure to operate on.
567	* @param Addend The value to add to the counter.
568	*/
569	#ifdef VBOX_WITH_STATISTICS
570	# define STAM_COUNTER_ADD(pCounter, Addend) STAM_REL_COUNTER_ADD(pCounter, Addend)
571	#else
572	# define STAM_COUNTER_ADD(pCounter, Addend) do { } while (0)
573	#endif
574
575
576	/** @def STAM_REL_COUNTER_RESET
577	* Resets the statistics sample.
578	*/
579	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
580	# define STAM_REL_COUNTER_RESET(pCounter) do { (pCounter)->c = 0; } while (0)
581	#else
582	# define STAM_REL_COUNTER_RESET(pCounter) do { } while (0)
583	#endif
584	/** @def STAM_COUNTER_RESET
585	* Resets the statistics sample.
586	*/
587	#ifndef VBOX_WITH_STATISTICS
588	# define STAM_COUNTER_RESET(pCounter) STAM_REL_COUNTER_RESET(pCounter)
589	#else
590	# define STAM_COUNTER_RESET(pCounter) do { } while (0)
591	#endif
592
593
594
595	/**
596	* Profiling sample - STAMTYPE_PROFILE.
597	*/
598	typedef struct STAMPROFILE
599	{
600	/** Number of periods. */
601	volatile uint64_t cPeriods;
602	/** Total count of ticks. */
603	volatile uint64_t cTicks;
604	/** Maximum tick count during a sampling. */
605	volatile uint64_t cTicksMax;
606	/** Minimum tick count during a sampling. */
607	volatile uint64_t cTicksMin;
608	} STAMPROFILE;
609	/** Pointer to a profile sample. */
610	typedef STAMPROFILE *PSTAMPROFILE;
611	/** Pointer to a const profile sample. */
612	typedef const STAMPROFILE *PCSTAMPROFILE;
613
614
615	/** @def STAM_REL_PROFILE_START
616	* Samples the start time of a profiling period.
617	*
618	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
619	* @param Prefix Identifier prefix used to internal variables.
620	*/
621	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
622	# define STAM_REL_PROFILE_START(pProfile, Prefix) \
623	uint64_t Prefix##_tsStart; \
624	STAM_GET_TS(Prefix##_tsStart)
625	#else
626	# define STAM_REL_PROFILE_START(pProfile, Prefix) do { } while (0)
627	#endif
628	/** @def STAM_PROFILE_START
629	* Samples the start time of a profiling period.
630	*
631	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
632	* @param Prefix Identifier prefix used to internal variables.
633	*/
634	#ifdef VBOX_WITH_STATISTICS
635	# define STAM_PROFILE_START(pProfile, Prefix) STAM_REL_PROFILE_START(pProfile, Prefix)
636	#else
637	# define STAM_PROFILE_START(pProfile, Prefix) do { } while (0)
638	#endif
639
640	/** @def STAM_REL_PROFILE_STOP
641	* Samples the stop time of a profiling period and updates the sample.
642	*
643	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
644	* @param Prefix Identifier prefix used to internal variables.
645	*/
646	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
647	# define STAM_REL_PROFILE_STOP(pProfile, Prefix) \
648	do { \
649	uint64_t Prefix##_cTicks; \
650	uint64_t Prefix##_tsStop; \
651	STAM_GET_TS(Prefix##_tsStop); \
652	Prefix##_cTicks = Prefix##_tsStop - Prefix##_tsStart; \
653	(pProfile)->cTicks += Prefix##_cTicks; \
654	(pProfile)->cPeriods++; \
655	if ((pProfile)->cTicksMax < Prefix##_cTicks) \
656	(pProfile)->cTicksMax = Prefix##_cTicks; \
657	if ((pProfile)->cTicksMin > Prefix##_cTicks) \
658	(pProfile)->cTicksMin = Prefix##_cTicks; \
659	} while (0)
660	#else
661	# define STAM_REL_PROFILE_STOP(pProfile, Prefix) do { } while (0)
662	#endif
663	/** @def STAM_PROFILE_STOP
664	* Samples the stop time of a profiling period and updates the sample.
665	*
666	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
667	* @param Prefix Identifier prefix used to internal variables.
668	*/
669	#ifdef VBOX_WITH_STATISTICS
670	# define STAM_PROFILE_STOP(pProfile, Prefix) STAM_REL_PROFILE_STOP(pProfile, Prefix)
671	#else
672	# define STAM_PROFILE_STOP(pProfile, Prefix) do { } while (0)
673	#endif
674
675
676	/** @def STAM_REL_PROFILE_STOP_EX
677	* Samples the stop time of a profiling period and updates both the sample
678	* and an attribution sample.
679	*
680	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
681	* @param pProfile2 Pointer to the STAMPROFILE structure which this
682	* interval should be attributed too. This may be NULL.
683	* @param Prefix Identifier prefix used to internal variables.
684	*/
685	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
686	# define STAM_REL_PROFILE_STOP_EX(pProfile, pProfile2, Prefix) \
687	do { \
688	uint64_t Prefix##_cTicks; \
689	uint64_t Prefix##_tsStop; \
690	STAM_GET_TS(Prefix##_tsStop); \
691	Prefix##_cTicks = Prefix##_tsStop - Prefix##_tsStart; \
692	(pProfile)->cTicks += Prefix##_cTicks; \
693	(pProfile)->cPeriods++; \
694	if ((pProfile)->cTicksMax < Prefix##_cTicks) \
695	(pProfile)->cTicksMax = Prefix##_cTicks; \
696	if ((pProfile)->cTicksMin > Prefix##_cTicks) \
697	(pProfile)->cTicksMin = Prefix##_cTicks; \
698	\
699	if ((pProfile2)) \
700	{ \
701	(pProfile2)->cTicks += Prefix##_cTicks; \
702	(pProfile2)->cPeriods++; \
703	if ((pProfile2)->cTicksMax < Prefix##_cTicks) \
704	(pProfile2)->cTicksMax = Prefix##_cTicks; \
705	if ((pProfile2)->cTicksMin > Prefix##_cTicks) \
706	(pProfile2)->cTicksMin = Prefix##_cTicks; \
707	} \
708	} while (0)
709	#else
710	# define STAM_REL_PROFILE_STOP_EX(pProfile, pProfile2, Prefix) do { } while (0)
711	#endif
712	/** @def STAM_PROFILE_STOP_EX
713	* Samples the stop time of a profiling period and updates both the sample
714	* and an attribution sample.
715	*
716	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
717	* @param pProfile2 Pointer to the STAMPROFILE structure which this
718	* interval should be attributed too. This may be NULL.
719	* @param Prefix Identifier prefix used to internal variables.
720	*/
721	#ifdef VBOX_WITH_STATISTICS
722	# define STAM_PROFILE_STOP_EX(pProfile, pProfile2, Prefix) STAM_REL_PROFILE_STOP_EX(pProfile, pProfile2, Prefix)
723	#else
724	# define STAM_PROFILE_STOP_EX(pProfile, pProfile2, Prefix) do { } while (0)
725	#endif
726
727
728	/**
729	* Advanced profiling sample - STAMTYPE_PROFILE_ADV.
730	*
731	* Identical to a STAMPROFILE sample, but the start timestamp
732	* is stored after the STAMPROFILE structure so the sampling
733	* can start and stop in different functions.
734	*/
735	typedef struct STAMPROFILEADV
736	{
737	/** The STAMPROFILE core. */
738	STAMPROFILE Core;
739	/** The start timestamp. */
740	volatile uint64_t tsStart;
741	} STAMPROFILEADV;
742	/** Pointer to a advanced profile sample. */
743	typedef STAMPROFILEADV *PSTAMPROFILEADV;
744	/** Pointer to a const advanced profile sample. */
745	typedef const STAMPROFILEADV *PCSTAMPROFILEADV;
746
747
748	/** @def STAM_REL_PROFILE_ADV_START
749	* Samples the start time of a profiling period.
750	*
751	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
752	* @param Prefix Identifier prefix used to internal variables.
753	*/
754	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
755	# define STAM_REL_PROFILE_ADV_START(pProfileAdv, Prefix) \
756	STAM_GET_TS((pProfileAdv)->tsStart)
757	#else
758	# define STAM_REL_PROFILE_ADV_START(pProfileAdv, Prefix) do { } while (0)
759	#endif
760	/** @def STAM_PROFILE_ADV_START
761	* Samples the start time of a profiling period.
762	*
763	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
764	* @param Prefix Identifier prefix used to internal variables.
765	*/
766	#ifdef VBOX_WITH_STATISTICS
767	# define STAM_PROFILE_ADV_START(pProfileAdv, Prefix) STAM_REL_PROFILE_ADV_START(pProfileAdv, Prefix)
768	#else
769	# define STAM_PROFILE_ADV_START(pProfileAdv, Prefix) do { } while (0)
770	#endif
771
772
773	/** @def STAM_REL_PROFILE_ADV_STOP
774	* Samples the stop time of a profiling period and updates the sample.
775	*
776	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
777	* @param Prefix Identifier prefix used to internal variables.
778	*/
779	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
780	# define STAM_REL_PROFILE_ADV_STOP(pProfileAdv, Prefix) \
781	do { \
782	uint64_t Prefix##_tsStop; \
783	STAM_GET_TS(Prefix##_tsStop); \
784	if ((pProfileAdv)->tsStart) \
785	{ \
786	uint64_t Prefix##_cTicks = Prefix##_tsStop - (pProfileAdv)->tsStart; \
787	(pProfileAdv)->tsStart = 0; \
788	(pProfileAdv)->Core.cTicks += Prefix##_cTicks; \
789	(pProfileAdv)->Core.cPeriods++; \
790	if ((pProfileAdv)->Core.cTicksMax < Prefix##_cTicks) \
791	(pProfileAdv)->Core.cTicksMax = Prefix##_cTicks; \
792	if ((pProfileAdv)->Core.cTicksMin > Prefix##_cTicks) \
793	(pProfileAdv)->Core.cTicksMin = Prefix##_cTicks; \
794	} \
795	} while (0)
796	#else
797	# define STAM_REL_PROFILE_ADV_STOP(pProfileAdv, Prefix) do { } while (0)
798	#endif
799	/** @def STAM_PROFILE_ADV_STOP
800	* Samples the stop time of a profiling period and updates the sample.
801	*
802	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
803	* @param Prefix Identifier prefix used to internal variables.
804	*/
805	#ifdef VBOX_WITH_STATISTICS
806	# define STAM_PROFILE_ADV_STOP(pProfileAdv, Prefix) STAM_REL_PROFILE_ADV_STOP(pProfileAdv, Prefix)
807	#else
808	# define STAM_PROFILE_ADV_STOP(pProfileAdv, Prefix) do { } while (0)
809	#endif
810
811
812	/** @def STAM_REL_PROFILE_ADV_SUSPEND
813	* Suspends the sampling for a while. This can be useful to exclude parts
814	* covered by other samples without screwing up the count, and average+min times.
815	*
816	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
817	* @param Prefix Identifier prefix used to internal variables. The prefix
818	* must match that of the resume one since it stores the
819	* suspend time in a stack variable.
820	*/
821	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
822	# define STAM_REL_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix) \
823	uint64_t Prefix##_tsSuspend; \
824	STAM_GET_TS(Prefix##_tsSuspend)
825	#else
826	# define STAM_REL_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix) do { } while (0)
827	#endif
828	/** @def STAM_PROFILE_ADV_SUSPEND
829	* Suspends the sampling for a while. This can be useful to exclude parts
830	* covered by other samples without screwing up the count, and average+min times.
831	*
832	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
833	* @param Prefix Identifier prefix used to internal variables. The prefix
834	* must match that of the resume one since it stores the
835	* suspend time in a stack variable.
836	*/
837	#ifdef VBOX_WITH_STATISTICS
838	# define STAM_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix) STAM_REL_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix)
839	#else
840	# define STAM_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix) do { } while (0)
841	#endif
842
843
844	/** @def STAM_REL_PROFILE_ADV_RESUME
845	* Counter to STAM_REL_PROFILE_ADV_SUSPEND.
846	*
847	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
848	* @param Prefix Identifier prefix used to internal variables. This must
849	* match the one used with the SUSPEND!
850	*/
851	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
852	# define STAM_REL_PROFILE_ADV_RESUME(pProfileAdv, Prefix) \
853	do { \
854	uint64_t Prefix##_tsNow; \
855	STAM_GET_TS(Prefix##_tsNow); \
856	(pProfileAdv)->tsStart += Prefix##_tsNow - Prefix##_tsSuspend; \
857	} while (0)
858	#else
859	# define STAM_REL_PROFILE_ADV_RESUME(pProfileAdv, Prefix) do { } while (0)
860	#endif
861	/** @def STAM_PROFILE_ADV_RESUME
862	* Counter to STAM_PROFILE_ADV_SUSPEND.
863	*
864	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
865	* @param Prefix Identifier prefix used to internal variables. This must
866	* match the one used with the SUSPEND!
867	*/
868	#ifdef VBOX_WITH_STATISTICS
869	# define STAM_PROFILE_ADV_RESUME(pProfileAdv, Prefix) STAM_REL_PROFILE_ADV_RESUME(pProfileAdv, Prefix)
870	#else
871	# define STAM_PROFILE_ADV_RESUME(pProfileAdv, Prefix) do { } while (0)
872	#endif
873
874
875	/** @def STAM_REL_PROFILE_ADV_STOP_EX
876	* Samples the stop time of a profiling period and updates both the sample
877	* and an attribution sample.
878	*
879	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
880	* @param pProfile2 Pointer to the STAMPROFILE structure which this
881	* interval should be attributed too. This may be NULL.
882	* @param Prefix Identifier prefix used to internal variables.
883	*/
884	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
885	# define STAM_REL_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix) \
886	do { \
887	uint64_t Prefix##_tsStop; \
888	STAM_GET_TS(Prefix##_tsStop); \
889	if ((pProfileAdv)->tsStart) \
890	{ \
891	uint64_t Prefix##_cTicks = Prefix##_tsStop - (pProfileAdv)->tsStart; \
892	(pProfileAdv)->tsStart = 0; \
893	(pProfileAdv)->Core.cTicks += Prefix##_cTicks; \
894	(pProfileAdv)->Core.cPeriods++; \
895	if ((pProfileAdv)->Core.cTicksMax < Prefix##_cTicks) \
896	(pProfileAdv)->Core.cTicksMax = Prefix##_cTicks; \
897	if ((pProfileAdv)->Core.cTicksMin > Prefix##_cTicks) \
898	(pProfileAdv)->Core.cTicksMin = Prefix##_cTicks; \
899	if ((pProfile2)) \
900	{ \
901	(pProfile2)->cTicks += Prefix##_cTicks; \
902	(pProfile2)->cPeriods++; \
903	if ((pProfile2)->cTicksMax < Prefix##_cTicks) \
904	(pProfile2)->cTicksMax = Prefix##_cTicks; \
905	if ((pProfile2)->cTicksMin > Prefix##_cTicks) \
906	(pProfile2)->cTicksMin = Prefix##_cTicks; \
907	} \
908	} \
909	} while (0)
910	#else
911	# define STAM_REL_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix) do { } while (0)
912	#endif
913	/** @def STAM_PROFILE_ADV_STOP_EX
914	* Samples the stop time of a profiling period and updates both the sample
915	* and an attribution sample.
916	*
917	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
918	* @param pProfile2 Pointer to the STAMPROFILE structure which this
919	* interval should be attributed too. This may be NULL.
920	* @param Prefix Identifier prefix used to internal variables.
921	*/
922	#ifdef VBOX_WITH_STATISTICS
923	# define STAM_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix) STAM_REL_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix)
924	#else
925	# define STAM_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix) do { } while (0)
926	#endif
927
928
929	/**
930	* Ratio of A to B, uint32_t types.
931	* @remark Use STAM_STATS or STAM_REL_STATS for modifying A & B values.
932	*/
933	typedef struct STAMRATIOU32
934	{
935	/** Sample A. */
936	uint32_t volatile u32A;
937	/** Sample B. */
938	uint32_t volatile u32B;
939	} STAMRATIOU32;
940	/** Pointer to a uint32_t ratio. */
941	typedef STAMRATIOU32 *PSTAMRATIOU32;
942	/** Pointer to const a uint32_t ratio. */
943	typedef const STAMRATIOU32 *PCSTAMRATIOU32;
944
945
946
947
948	/** @defgroup grp_stam_r3 The STAM Host Context Ring 3 API
949	* @ingroup grp_stam
950	* @{
951	*/
952
953	/**
954	* Initializes the STAM.
955	*
956	* @returns VBox status code.
957	* @param pVM The VM to operate on.
958	*/
959	STAMR3DECL(int) STAMR3Init(PVM pVM);
960
961	/**
962	* Applies relocations to data and code managed by this
963	* component. This function will be called at init and
964	* whenever the VMM need to relocate it self inside the GC.
965	*
966	* @param pVM The VM.
967	*/
968	STAMR3DECL(void) STAMR3Relocate(PVM pVM);
969
970	/**
971	* Terminates the STAM.
972	*
973	* Termination means cleaning up and freeing all resources,
974	* the VM it self is at this point powered off or suspended.
975	*
976	* @returns VBox status code.
977	* @param pVM The VM to operate on.
978	*/
979	STAMR3DECL(int) STAMR3Term(PVM pVM);
980
981	/**
982	* Registers a sample with the statistics mamanger.
983	*
984	* Statistics are maintained on a per VM basis and should therefore
985	* be registered during the VM init stage. However, there is not problem
986	* registering temporary samples or samples for hotpluggable devices. Samples
987	* can be deregisterd using the STAMR3Deregister() function, but note that
988	* this is only necessary for temporary samples or hotpluggable devices.
989	*
990	* It is not possible to register the same sample twice.
991	*
992	* @returns VBox status.
993	* @param pVM The VM handle.
994	* @param pvSample Pointer to the sample.
995	* @param enmType Sample type. This indicates what pvSample is pointing at.
996	* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
997	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
998	* Further nesting is possible.
999	* @param enmUnit Sample unit.
1000	* @param pszDesc Sample description.
1001	*/
1002	STAMR3DECL(int) STAMR3Register(PVM pVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
1003	const char pszName, STAMUNIT enmUnit, const char pszDesc);
1004
1005	/** @def STAM_REL_REG
1006	* Registers a statistics sample.
1007	*
1008	* @param pVM VM Handle.
1009	* @param pvSample Pointer to the sample.
1010	* @param enmType Sample type. This indicates what pvSample is pointing at.
1011	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
1012	* Further nesting is possible.
1013	* @param enmUnit Sample unit.
1014	* @param pszDesc Sample description.
1015	*/
1016	#define STAM_REL_REG(pVM, pvSample, enmType, pszName, enmUnit, pszDesc) \
1017	STAM_REL_STATS({ int rcStam = STAMR3Register(pVM, pvSample, enmType, STAMVISIBILITY_ALWAYS, pszName, enmUnit, pszDesc); \
1018	AssertRC(rcStam); })
1019	/** @def STAM_REG
1020	* Registers a statistics sample if statistics are enabled.
1021	*
1022	* @param pVM VM Handle.
1023	* @param pvSample Pointer to the sample.
1024	* @param enmType Sample type. This indicates what pvSample is pointing at.
1025	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
1026	* Further nesting is possible.
1027	* @param enmUnit Sample unit.
1028	* @param pszDesc Sample description.
1029	*/
1030	#define STAM_REG(pVM, pvSample, enmType, pszName, enmUnit, pszDesc) \
1031	STAM_STATS({STAM_REL_REG(pVM, pvSample, enmType, pszName, enmUnit, pszDesc);})
1032
1033	/** @def STAM_REL_REG_USED
1034	* Registers a statistics sample which only shows when used.
1035	*
1036	* @param pVM VM Handle.
1037	* @param pvSample Pointer to the sample.
1038	* @param enmType Sample type. This indicates what pvSample is pointing at.
1039	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
1040	* Further nesting is possible.
1041	* @param enmUnit Sample unit.
1042	* @param pszDesc Sample description.
1043	*/
1044	#define STAM_REL_REG_USED(pVM, pvSample, enmType, pszName, enmUnit, pszDesc) \
1045	STAM_REL_STATS({ int rcStam = STAMR3Register(pVM, pvSample, enmType, STAMVISIBILITY_USED, pszName, enmUnit, pszDesc); \
1046	AssertRC(rcStam);})
1047	/** @def STAM_REG_USED
1048	* Registers a statistics sample which only shows when used, if statistics are enabled.
1049	*
1050	* @param pVM VM Handle.
1051	* @param pvSample Pointer to the sample.
1052	* @param enmType Sample type. This indicates what pvSample is pointing at.
1053	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
1054	* Further nesting is possible.
1055	* @param enmUnit Sample unit.
1056	* @param pszDesc Sample description.
1057	*/
1058	#define STAM_REG_USED(pVM, pvSample, enmType, pszName, enmUnit, pszDesc) \
1059	STAM_STATS({ STAM_REL_REG_USED(pVM, pvSample, enmType, pszName, enmUnit, pszDesc); })
1060
1061	/**
1062	* Same as STAMR3Register except that the name is specified in a
1063	* RTStrPrintf like fashion.
1064	*
1065	* @returns VBox status.
1066	* @param pVM The VM handle.
1067	* @param pvSample Pointer to the sample.
1068	* @param enmType Sample type. This indicates what pvSample is pointing at.
1069	* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
1070	* @param enmUnit Sample unit.
1071	* @param pszDesc Sample description.
1072	* @param pszName The sample name format string.
1073	* @param ... Arguments to the format string.
1074	*/
1075	STAMR3DECL(int) STAMR3RegisterF(PVM pVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1076	const char pszDesc, const char pszName, ...);
1077
1078	/**
1079	* Same as STAMR3Register except that the name is specified in a
1080	* RTStrPrintfV like fashion.
1081	*
1082	* @returns VBox status.
1083	* @param pVM The VM handle.
1084	* @param pvSample Pointer to the sample.
1085	* @param enmType Sample type. This indicates what pvSample is pointing at.
1086	* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
1087	* @param enmUnit Sample unit.
1088	* @param pszDesc Sample description.
1089	* @param pszName The sample name format string.
1090	* @param args Arguments to the format string.
1091	*/
1092	STAMR3DECL(int) STAMR3RegisterV(PVM pVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1093	const char pszDesc, const char pszName, va_list args);
1094
1095	/**
1096	* Resets the sample.
1097	* @param pVM The VM handle.
1098	* @param pvSample The sample registered using STAMR3RegisterCallback.
1099	*/
1100	typedef void FNSTAMR3CALLBACKRESET(PVM pVM, void *pvSample);
1101	/** Pointer to a STAM sample reset callback. */
1102	typedef FNSTAMR3CALLBACKRESET *PFNSTAMR3CALLBACKRESET;
1103
1104	/**
1105	* Prints the sample into the buffer.
1106	*
1107	* @param pVM The VM handle.
1108	* @param pvSample The sample registered using STAMR3RegisterCallback.
1109	* @param pszBuf The buffer to print into.
1110	* @param cchBuf The size of the buffer.
1111	*/
1112	typedef void FNSTAMR3CALLBACKPRINT(PVM pVM, void pvSample, char pszBuf, size_t cchBuf);
1113	/** Pointer to a STAM sample print callback. */
1114	typedef FNSTAMR3CALLBACKPRINT *PFNSTAMR3CALLBACKPRINT;
1115
1116	/**
1117	* Similar to STAMR3Register except for the two callbacks, the implied type (STAMTYPE_CALLBACK),
1118	* and name given in an RTStrPrintf like fashion.
1119	*
1120	* @returns VBox status.
1121	* @param pVM The VM handle.
1122	* @param pvSample Pointer to the sample.
1123	* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
1124	* @param enmUnit Sample unit.
1125	* @param pfnReset Callback for resetting the sample. NULL should be used if the sample can't be reset.
1126	* @param pfnPrint Print the sample.
1127	* @param pszDesc Sample description.
1128	* @param pszName The sample name format string.
1129	* @param ... Arguments to the format string.
1130	* @remark There is currently no device or driver variant of this API. Add one if it should become necessary!
1131	*/
1132	STAMR3DECL(int) STAMR3RegisterCallback(PVM pVM, void *pvSample, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1133	PFNSTAMR3CALLBACKRESET pfnReset, PFNSTAMR3CALLBACKPRINT pfnPrint,
1134	const char pszDesc, const char pszName, ...);
1135
1136	/**
1137	* Same as STAMR3RegisterCallback() except for the ellipsis which is a va_list here.
1138	*
1139	* @returns VBox status.
1140	* @param pVM The VM handle.
1141	* @param pvSample Pointer to the sample.
1142	* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
1143	* @param enmUnit Sample unit.
1144	* @param pfnReset Callback for resetting the sample. NULL should be used if the sample can't be reset.
1145	* @param pfnPrint Print the sample.
1146	* @param pszDesc Sample description.
1147	* @param pszName The sample name format string.
1148	* @param args Arguments to the format string.
1149	* @remark There is currently no device or driver variant of this API. Add one if it should become necessary!
1150	*/
1151	STAMR3DECL(int) STAMR3RegisterCallbackV(PVM pVM, void *pvSample, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1152	PFNSTAMR3CALLBACKRESET pfnReset, PFNSTAMR3CALLBACKPRINT pfnPrint,
1153	const char pszDesc, const char pszName, va_list args);
1154
1155	/**
1156	* Deregisters all samples previously registered by STAMR3Register(),
1157	* STAMR3RegisterF(), STAMR3RegisterV() or STAMR3RegisterCallback().
1158	*
1159	* This is intended used for devices which can be unplugged and for
1160	* temporary samples.
1161	*
1162	* @returns VBox status.
1163	* @param pVM The VM handle.
1164	* @param pvSample Pointer to the register sample.
1165	*/
1166	STAMR3DECL(int) STAMR3Deregister(PVM pVM, void *pvSample);
1167
1168	/** @def STAM_REL_DEREG
1169	* Deregisters a statistics sample if statistics are enabled.
1170	*
1171	* @param pVM VM Handle.
1172	* @param pvSample Pointer to the sample.
1173	*/
1174	#define STAM_REL_DEREG(pVM, pvSample) \
1175	STAM_REL_STATS({ int rcStam = STAMR3Deregister(pVM, pvSample); AssertRC(rcStam); })
1176	/** @def STAM_DEREG
1177	* Deregisters a statistics sample if statistics are enabled.
1178	*
1179	* @param pVM VM Handle.
1180	* @param pvSample Pointer to the sample.
1181	*/
1182	#define STAM_DEREG(pVM, pvSample) \
1183	STAM_STATS({ STAM_REL_DEREG(pVM, pvSample); })
1184
1185	/**
1186	* Resets statistics for the specified VM.
1187	* It's possible to select a subset of the samples.
1188	*
1189	* @returns VBox status. (Basically, it cannot fail.)
1190	* @param pVM The VM handle.
1191	* @param pszPat The name matching pattern. See somewhere_where_this_is_described_in_detail.
1192	* If NULL all samples are reset.
1193	*/
1194	STAMR3DECL(int) STAMR3Reset(PVM pVM, const char *pszPat);
1195
1196	/**
1197	* Get a snapshot of the statistics.
1198	* It's possible to select a subset of the samples.
1199	*
1200	* @returns VBox status. (Basically, it cannot fail.)
1201	* @param pVM The VM handle.
1202	* @param pszPat The name matching pattern. See somewhere_where_this_is_described_in_detail.
1203	* If NULL all samples are reset.
1204	* @param ppszSnapshot Where to store the pointer to the snapshot data.
1205	* The format of the snapshot should be XML, but that will have to be discussed
1206	* when this function is implemented.
1207	* The returned pointer must be freed by calling STAMR3SnapshotFree().
1208	* @param cchSnapshot Where to store the size of the snapshot data. (Excluding the trailing '\0')
1209	*/
1210	STAMR3DECL(int) STAMR3Snapshot(PVM pVM, const char pszPat, char ppszSnapshot, size_t pcchSnapshot);
1211
1212	/**
1213	* Releases a statistics snapshot returned by STAMR3Snapshot().
1214	*
1215	* @returns VBox status.
1216	* @param pVM The VM handle.
1217	* @param pszSnapshot The snapshot data pointer returned by STAMR3Snapshot().
1218	* NULL is allowed.
1219	*/
1220	STAMR3DECL(int) STAMR3SnapshotFree(PVM pVM, char *pszSnapshot);
1221
1222	/**
1223	* Dumps the selected statistics to the log.
1224	*
1225	* @returns VBox status.
1226	* @param pVM The VM handle.
1227	* @param pszPat The name matching pattern. See somewhere_where_this_is_described_in_detail.
1228	* If NULL all samples are reset.
1229	*/
1230	STAMR3DECL(int) STAMR3Dump(PVM pVM, const char *pszPat);
1231
1232	/**
1233	* Dumps the selected statistics to the release log.
1234	*
1235	* @returns VBox status.
1236	* @param pVM The VM handle.
1237	* @param pszPat The name matching pattern. See somewhere_where_this_is_described_in_detail.
1238	* If NULL all samples are written to the log.
1239	*/
1240	STAMR3DECL(int) STAMR3DumpToReleaseLog(PVM pVM, const char *pszPat);
1241
1242	/**
1243	* Prints the selected statistics to standard out.
1244	*
1245	* @returns VBox status.
1246	* @param pVM The VM handle.
1247	* @param pszPat The name matching pattern. See somewhere_where_this_is_described_in_detail.
1248	* If NULL all samples are reset.
1249	*/
1250	STAMR3DECL(int) STAMR3Print(PVM pVM, const char *pszPat);
1251
1252	/**
1253	* Callback function for STAMR3Enum().
1254	*
1255	* @returns non-zero to halt the enumeration.
1256	*
1257	* @param pszName The name of the sample.
1258	* @param enmType The type.
1259	* @param pvSample Pointer to the data. enmType indicates the format of this data.
1260	* @param enmUnit The unit.
1261	* @param enmVisibility The visibility.
1262	* @param pszDesc The description.
1263	* @param pvUser The pvUser argument given to STAMR3Enum().
1264	*/
1265	typedef DECLCALLBACK(int) FNSTAMR3ENUM(const char pszName, STAMTYPE enmType, void pvSample, STAMUNIT enmUnit,
1266	STAMVISIBILITY enmVisiblity, const char pszDesc, void pvUser);
1267	/** Pointer to a FNSTAMR3ENUM(). */
1268	typedef FNSTAMR3ENUM *PFNSTAMR3ENUM;
1269
1270	/**
1271	* Enumerate the statistics by the means of a callback function.
1272	*
1273	* @returns Whatever the callback returns.
1274	*
1275	* @param pVM The VM handle.
1276	* @param pszPat The pattern to match samples.
1277	* @param pfnEnum The callback function.
1278	* @param pvUser The pvUser argument of the callback function.
1279	*/
1280	STAMR3DECL(int) STAMR3Enum(PVM pVM, const char pszPat, PFNSTAMR3ENUM pfnEnum, void pvUser);
1281
1282	/**
1283	* Get the unit string.
1284	*
1285	* @returns Pointer to read only unit string.
1286	* @param enmUnit The unit.
1287	*/
1288	STAMR3DECL(const char *) STAMR3GetUnit(STAMUNIT enmUnit);
1289
1290	/** @} */
1291
1292	/** @} */
1293
1294	__END_DECLS
1295
1296	#endif

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

source: vbox/trunk/include/VBox/stam.h@ 2889

Download in other formats: