stam.h@ 30683

Last change on this file since 30683 was 30589, checked in by vboxsync, 14 years ago
VBox/stam.h: Added some new macros for STAMPROFILEADV and optimized a couple of existing ones.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 41.6 KB

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

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

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

Download in other formats: