stam.h@ 32780

Last change on this file since 32780 was 30684, checked in by vboxsync, 14 years ago
TM: Added resettable accounting stats. Count the halts and execution periods.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 43.0 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_ADD_PERIOD
632	* Adds a period.
633	*
634	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
635	* @param cTicksInPeriod The number of tick (or whatever) of the preiod
636	* being added. This is only referenced once.
637	*/
638	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
639	# define STAM_REL_PROFILE_ADD_PERIOD(pProfile, cTicksInPeriod) \
640	do { \
641	uint64_t const StamPrefix_cTicks = (cTicksInPeriod); \
642	(pProfile)->cTicks += StamPrefix_cTicks; \
643	(pProfile)->cPeriods++; \
644	if ((pProfile)->cTicksMax < StamPrefix_cTicks) \
645	(pProfile)->cTicksMax = StamPrefix_cTicks; \
646	if ((pProfile)->cTicksMin > StamPrefix_cTicks) \
647	(pProfile)->cTicksMin = StamPrefix_cTicks; \
648	} while (0)
649	#else
650	# define STAM_REL_PROFILE_ADD_PERIOD(pProfile, cTicksInPeriod) do { } while (0)
651	#endif
652	/** @def STAM_PROFILE_ADD_PERIOD
653	* Adds a period.
654	*
655	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
656	* @param cTicksInPeriod The number of tick (or whatever) of the preiod
657	* being added. This is only referenced once.
658	*/
659	#ifdef VBOX_WITH_STATISTICS
660	# define STAM_PROFILE_ADD_PERIOD(pProfile, cTicksInPeriod) STAM_REL_PROFILE_ADD_PERIOD(pProfile, cTicksInPeriod)
661	#else
662	# define STAM_PROFILE_ADD_PERIOD(pProfile, cTicksInPeriod) do { } while (0)
663	#endif
664
665
666	/** @def STAM_REL_PROFILE_START
667	* Samples the start time of a profiling period.
668	*
669	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
670	* @param Prefix Identifier prefix used to internal variables.
671	*
672	* @remarks Declears a stack variable that will be used by related macros.
673	*/
674	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
675	# define STAM_REL_PROFILE_START(pProfile, Prefix) \
676	uint64_t Prefix##_tsStart; \
677	STAM_GET_TS(Prefix##_tsStart)
678	#else
679	# define STAM_REL_PROFILE_START(pProfile, Prefix) do { } while (0)
680	#endif
681	/** @def STAM_PROFILE_START
682	* Samples the start time of a profiling period.
683	*
684	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
685	* @param Prefix Identifier prefix used to internal variables.
686	*
687	* @remarks Declears a stack variable that will be used by related macros.
688	*/
689	#ifdef VBOX_WITH_STATISTICS
690	# define STAM_PROFILE_START(pProfile, Prefix) STAM_REL_PROFILE_START(pProfile, Prefix)
691	#else
692	# define STAM_PROFILE_START(pProfile, Prefix) do { } while (0)
693	#endif
694
695	/** @def STAM_REL_PROFILE_STOP
696	* Samples the stop time of a profiling period and updates the sample.
697	*
698	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
699	* @param Prefix Identifier prefix used to internal variables.
700	*/
701	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
702	# define STAM_REL_PROFILE_STOP(pProfile, Prefix) \
703	do { \
704	uint64_t Prefix##_cTicks; \
705	STAM_GET_TS(Prefix##_cTicks); \
706	Prefix##_cTicks -= Prefix##_tsStart; \
707	(pProfile)->cTicks += Prefix##_cTicks; \
708	(pProfile)->cPeriods++; \
709	if ((pProfile)->cTicksMax < Prefix##_cTicks) \
710	(pProfile)->cTicksMax = Prefix##_cTicks; \
711	if ((pProfile)->cTicksMin > Prefix##_cTicks) \
712	(pProfile)->cTicksMin = Prefix##_cTicks; \
713	} while (0)
714	#else
715	# define STAM_REL_PROFILE_STOP(pProfile, Prefix) do { } while (0)
716	#endif
717	/** @def STAM_PROFILE_STOP
718	* Samples the stop time of a profiling period and updates the sample.
719	*
720	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
721	* @param Prefix Identifier prefix used to internal variables.
722	*/
723	#ifdef VBOX_WITH_STATISTICS
724	# define STAM_PROFILE_STOP(pProfile, Prefix) STAM_REL_PROFILE_STOP(pProfile, Prefix)
725	#else
726	# define STAM_PROFILE_STOP(pProfile, Prefix) do { } while (0)
727	#endif
728
729
730	/** @def STAM_REL_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	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
740	# define STAM_REL_PROFILE_STOP_EX(pProfile, pProfile2, Prefix) \
741	do { \
742	uint64_t Prefix##_cTicks; \
743	STAM_GET_TS(Prefix##_cTicks); \
744	Prefix##_cTicks -= Prefix##_tsStart; \
745	(pProfile)->cTicks += Prefix##_cTicks; \
746	(pProfile)->cPeriods++; \
747	if ((pProfile)->cTicksMax < Prefix##_cTicks) \
748	(pProfile)->cTicksMax = Prefix##_cTicks; \
749	if ((pProfile)->cTicksMin > Prefix##_cTicks) \
750	(pProfile)->cTicksMin = Prefix##_cTicks; \
751	\
752	if ((pProfile2)) \
753	{ \
754	(pProfile2)->cTicks += Prefix##_cTicks; \
755	(pProfile2)->cPeriods++; \
756	if ((pProfile2)->cTicksMax < Prefix##_cTicks) \
757	(pProfile2)->cTicksMax = Prefix##_cTicks; \
758	if ((pProfile2)->cTicksMin > Prefix##_cTicks) \
759	(pProfile2)->cTicksMin = Prefix##_cTicks; \
760	} \
761	} while (0)
762	#else
763	# define STAM_REL_PROFILE_STOP_EX(pProfile, pProfile2, Prefix) do { } while (0)
764	#endif
765	/** @def STAM_PROFILE_STOP_EX
766	* Samples the stop time of a profiling period and updates both the sample
767	* and an attribution sample.
768	*
769	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
770	* @param pProfile2 Pointer to the STAMPROFILE structure which this
771	* interval should be attributed to as well. This may be NULL.
772	* @param Prefix Identifier prefix used to internal variables.
773	*/
774	#ifdef VBOX_WITH_STATISTICS
775	# define STAM_PROFILE_STOP_EX(pProfile, pProfile2, Prefix) STAM_REL_PROFILE_STOP_EX(pProfile, pProfile2, Prefix)
776	#else
777	# define STAM_PROFILE_STOP_EX(pProfile, pProfile2, Prefix) do { } while (0)
778	#endif
779
780
781	/**
782	* Advanced profiling sample - STAMTYPE_PROFILE_ADV.
783	*
784	* Identical to a STAMPROFILE sample, but the start timestamp
785	* is stored after the STAMPROFILE structure so the sampling
786	* can start and stop in different functions.
787	*/
788	typedef struct STAMPROFILEADV
789	{
790	/** The STAMPROFILE core. */
791	STAMPROFILE Core;
792	/** The start timestamp. */
793	volatile uint64_t tsStart;
794	} STAMPROFILEADV;
795	/** Pointer to a advanced profile sample. */
796	typedef STAMPROFILEADV *PSTAMPROFILEADV;
797	/** Pointer to a const advanced profile sample. */
798	typedef const STAMPROFILEADV *PCSTAMPROFILEADV;
799
800
801	/** @def STAM_REL_PROFILE_ADV_START
802	* Samples the start time of a profiling period.
803	*
804	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
805	* @param Prefix Identifier prefix used to internal variables.
806	*/
807	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
808	# define STAM_REL_PROFILE_ADV_START(pProfileAdv, Prefix) \
809	STAM_GET_TS((pProfileAdv)->tsStart)
810	#else
811	# define STAM_REL_PROFILE_ADV_START(pProfileAdv, Prefix) do { } while (0)
812	#endif
813	/** @def STAM_PROFILE_ADV_START
814	* Samples the start time of a profiling period.
815	*
816	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
817	* @param Prefix Identifier prefix used to internal variables.
818	*/
819	#ifdef VBOX_WITH_STATISTICS
820	# define STAM_PROFILE_ADV_START(pProfileAdv, Prefix) STAM_REL_PROFILE_ADV_START(pProfileAdv, Prefix)
821	#else
822	# define STAM_PROFILE_ADV_START(pProfileAdv, Prefix) do { } while (0)
823	#endif
824
825
826	/** @def STAM_REL_PROFILE_ADV_STOP
827	* Samples the stop time of a profiling period (if running) and updates the
828	* sample.
829	*
830	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
831	* @param Prefix Identifier prefix used to internal variables.
832	*/
833	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
834	# define STAM_REL_PROFILE_ADV_STOP(pProfileAdv, Prefix) \
835	do { \
836	if ((pProfileAdv)->tsStart) \
837	{ \
838	uint64_t Prefix##_cTicks; \
839	STAM_GET_TS(Prefix##_cTicks); \
840	Prefix##_cTicks -= (pProfileAdv)->tsStart; \
841	(pProfileAdv)->tsStart = 0; \
842	(pProfileAdv)->Core.cTicks += Prefix##_cTicks; \
843	(pProfileAdv)->Core.cPeriods++; \
844	if ((pProfileAdv)->Core.cTicksMax < Prefix##_cTicks) \
845	(pProfileAdv)->Core.cTicksMax = Prefix##_cTicks; \
846	if ((pProfileAdv)->Core.cTicksMin > Prefix##_cTicks) \
847	(pProfileAdv)->Core.cTicksMin = Prefix##_cTicks; \
848	} \
849	} while (0)
850	#else
851	# define STAM_REL_PROFILE_ADV_STOP(pProfileAdv, Prefix) do { } while (0)
852	#endif
853	/** @def STAM_PROFILE_ADV_STOP
854	* Samples the stop time of a profiling period (if running) and updates the
855	* sample.
856	*
857	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
858	* @param Prefix Identifier prefix used to internal variables.
859	*/
860	#ifdef VBOX_WITH_STATISTICS
861	# define STAM_PROFILE_ADV_STOP(pProfileAdv, Prefix) STAM_REL_PROFILE_ADV_STOP(pProfileAdv, Prefix)
862	#else
863	# define STAM_PROFILE_ADV_STOP(pProfileAdv, Prefix) do { } while (0)
864	#endif
865
866
867	/** @def STAM_REL_PROFILE_ADV_STOP_START
868	* Stops one profile counter (if running) and starts another one.
869	*
870	* @param pProfileAdv1 Pointer to the STAMPROFILEADV structure to stop.
871	* @param pProfileAdv2 Pointer to the STAMPROFILEADV structure to start.
872	* @param Prefix Identifier prefix used to internal variables.
873	*/
874	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
875	# define STAM_REL_PROFILE_ADV_STOP_START(pProfileAdv1, pProfileAdv2, Prefix) \
876	do { \
877	uint64_t Prefix##_cTicks; \
878	STAM_GET_TS(Prefix##_cTicks); \
879	(pProfileAdv2)->tsStart = Prefix##_cTicks; \
880	if ((pProfileAdv1)->tsStart) \
881	{ \
882	Prefix##_cTicks -= (pProfileAdv1)->tsStart; \
883	(pProfileAdv1)->tsStart = 0; \
884	(pProfileAdv1)->Core.cTicks += Prefix##_cTicks; \
885	(pProfileAdv1)->Core.cPeriods++; \
886	if ((pProfileAdv1)->Core.cTicksMax < Prefix##_cTicks) \
887	(pProfileAdv1)->Core.cTicksMax = Prefix##_cTicks; \
888	if ((pProfileAdv1)->Core.cTicksMin > Prefix##_cTicks) \
889	(pProfileAdv1)->Core.cTicksMin = Prefix##_cTicks; \
890	} \
891	} while (0)
892	#else
893	# define STAM_REL_PROFILE_ADV_STOP_START(pProfileAdv1, pProfileAdv2, Prefix) \
894	do { } while (0)
895	#endif
896	/** @def STAM_PROFILE_ADV_STOP_START
897	* Samples the stop time of a profiling period (if running) and updates the
898	* sample.
899	*
900	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
901	* @param Prefix Identifier prefix used to internal variables.
902	*/
903	#ifdef VBOX_WITH_STATISTICS
904	# define STAM_PROFILE_ADV_STOP_START(pProfileAdv1, pProfileAdv2, Prefix) \
905	STAM_REL_PROFILE_ADV_STOP_START(pProfileAdv1, pProfileAdv2, Prefix)
906	#else
907	# define STAM_PROFILE_ADV_STOP_START(pProfileAdv1, pProfileAdv2, Prefix) \
908	do { } while (0)
909	#endif
910
911
912	/** @def STAM_REL_PROFILE_ADV_SUSPEND
913	* Suspends the sampling for a while. This can be useful to exclude parts
914	* covered by other samples without screwing up the count, and average+min times.
915	*
916	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
917	* @param Prefix Identifier prefix used to internal variables. The prefix
918	* must match that of the resume one since it stores the
919	* suspend time in a stack variable.
920	*/
921	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
922	# define STAM_REL_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix) \
923	uint64_t Prefix##_tsSuspend; \
924	STAM_GET_TS(Prefix##_tsSuspend)
925	#else
926	# define STAM_REL_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix) do { } while (0)
927	#endif
928	/** @def STAM_PROFILE_ADV_SUSPEND
929	* Suspends the sampling for a while. This can be useful to exclude parts
930	* covered by other samples without screwing up the count, and average+min times.
931	*
932	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
933	* @param Prefix Identifier prefix used to internal variables. The prefix
934	* must match that of the resume one since it stores the
935	* suspend time in a stack variable.
936	*/
937	#ifdef VBOX_WITH_STATISTICS
938	# define STAM_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix) STAM_REL_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix)
939	#else
940	# define STAM_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix) do { } while (0)
941	#endif
942
943
944	/** @def STAM_REL_PROFILE_ADV_RESUME
945	* Counter to STAM_REL_PROFILE_ADV_SUSPEND.
946	*
947	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
948	* @param Prefix Identifier prefix used to internal variables. This must
949	* match the one used with the SUSPEND!
950	*/
951	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
952	# define STAM_REL_PROFILE_ADV_RESUME(pProfileAdv, Prefix) \
953	do { \
954	uint64_t Prefix##_tsNow; \
955	STAM_GET_TS(Prefix##_tsNow); \
956	(pProfileAdv)->tsStart += Prefix##_tsNow - Prefix##_tsSuspend; \
957	} while (0)
958	#else
959	# define STAM_REL_PROFILE_ADV_RESUME(pProfileAdv, Prefix) do { } while (0)
960	#endif
961	/** @def STAM_PROFILE_ADV_RESUME
962	* Counter to STAM_PROFILE_ADV_SUSPEND.
963	*
964	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
965	* @param Prefix Identifier prefix used to internal variables. This must
966	* match the one used with the SUSPEND!
967	*/
968	#ifdef VBOX_WITH_STATISTICS
969	# define STAM_PROFILE_ADV_RESUME(pProfileAdv, Prefix) STAM_REL_PROFILE_ADV_RESUME(pProfileAdv, Prefix)
970	#else
971	# define STAM_PROFILE_ADV_RESUME(pProfileAdv, Prefix) do { } while (0)
972	#endif
973
974
975	/** @def STAM_REL_PROFILE_ADV_STOP_EX
976	* Samples the stop time of a profiling period (if running) and updates both
977	* the sample and an attribution sample.
978	*
979	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
980	* @param pProfile2 Pointer to the STAMPROFILE structure which this
981	* interval should be attributed to as well. This may be NULL.
982	* @param Prefix Identifier prefix used to internal variables.
983	*/
984	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
985	# define STAM_REL_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix) \
986	do { \
987	if ((pProfileAdv)->tsStart) \
988	{ \
989	uint64_t Prefix##_cTicks; \
990	STAM_GET_TS(Prefix##_cTicks); \
991	Prefix##_cTicks -= (pProfileAdv)->tsStart; \
992	(pProfileAdv)->tsStart = 0; \
993	(pProfileAdv)->Core.cTicks += Prefix##_cTicks; \
994	(pProfileAdv)->Core.cPeriods++; \
995	if ((pProfileAdv)->Core.cTicksMax < Prefix##_cTicks) \
996	(pProfileAdv)->Core.cTicksMax = Prefix##_cTicks; \
997	if ((pProfileAdv)->Core.cTicksMin > Prefix##_cTicks) \
998	(pProfileAdv)->Core.cTicksMin = Prefix##_cTicks; \
999	if ((pProfile2)) \
1000	{ \
1001	(pProfile2)->cTicks += Prefix##_cTicks; \
1002	(pProfile2)->cPeriods++; \
1003	if ((pProfile2)->cTicksMax < Prefix##_cTicks) \
1004	(pProfile2)->cTicksMax = Prefix##_cTicks; \
1005	if ((pProfile2)->cTicksMin > Prefix##_cTicks) \
1006	(pProfile2)->cTicksMin = Prefix##_cTicks; \
1007	} \
1008	} \
1009	} while (0)
1010	#else
1011	# define STAM_REL_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix) do { } while (0)
1012	#endif
1013	/** @def STAM_PROFILE_ADV_STOP_EX
1014	* Samples the stop time of a profiling period (if running) and updates both
1015	* the sample and an attribution sample.
1016	*
1017	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
1018	* @param pProfile2 Pointer to the STAMPROFILE structure which this
1019	* interval should be attributed to as well. This may be NULL.
1020	* @param Prefix Identifier prefix used to internal variables.
1021	*/
1022	#ifdef VBOX_WITH_STATISTICS
1023	# define STAM_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix) STAM_REL_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix)
1024	#else
1025	# define STAM_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix) do { } while (0)
1026	#endif
1027
1028	/** @def STAM_REL_PROFILE_ADV_IS_RUNNING
1029	* Checks if it is running.
1030	*
1031	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
1032	*/
1033	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
1034	# define STAM_REL_PROFILE_ADV_IS_RUNNING(pProfileAdv) (pProfileAdv)->tsStart
1035	#else
1036	# define STAM_REL_PROFILE_ADV_IS_RUNNING(pProfileAdv) (false)
1037	#endif
1038	/** @def STAM_PROFILE_ADV_IS_RUNNING
1039	* Checks if it is running.
1040	*
1041	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
1042	*/
1043	#ifdef VBOX_WITH_STATISTICS
1044	# define STAM_PROFILE_ADV_IS_RUNNING(pProfileAdv) STAM_REL_PROFILE_ADV_IS_RUNNING(pProfileAdv)
1045	#else
1046	# define STAM_PROFILE_ADV_IS_RUNNING(pProfileAdv) (false)
1047	#endif
1048
1049	/** @def STAM_REL_PROFILE_ADV_SET_STOPPED
1050	* Marks the profile counter as stopped.
1051	*
1052	* This is for avoiding screwups in twisty code.
1053	*
1054	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
1055	*/
1056	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
1057	# define STAM_REL_PROFILE_ADV_SET_STOPPED(pProfileAdv) do { (pProfileAdv)->tsStart = 0; } while (0)
1058	#else
1059	# define STAM_REL_PROFILE_ADV_SET_STOPPED(pProfileAdv) do { } while (0)
1060	#endif
1061	/** @def STAM_PROFILE_ADV_SET_STOPPED
1062	* Marks the profile counter as stopped.
1063	*
1064	* This is for avoiding screwups in twisty code.
1065	*
1066	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
1067	*/
1068	#ifdef VBOX_WITH_STATISTICS
1069	# define STAM_PROFILE_ADV_SET_STOPPED(pProfileAdv) STAM_REL_PROFILE_ADV_SET_STOPPED(pProfileAdv)
1070	#else
1071	# define STAM_PROFILE_ADV_SET_STOPPED(pProfileAdv) do { } while (0)
1072	#endif
1073
1074
1075	/**
1076	* Ratio of A to B, uint32_t types.
1077	* @remark Use STAM_STATS or STAM_REL_STATS for modifying A & B values.
1078	*/
1079	typedef struct STAMRATIOU32
1080	{
1081	/** Sample A. */
1082	uint32_t volatile u32A;
1083	/** Sample B. */
1084	uint32_t volatile u32B;
1085	} STAMRATIOU32;
1086	/** Pointer to a uint32_t ratio. */
1087	typedef STAMRATIOU32 *PSTAMRATIOU32;
1088	/** Pointer to const a uint32_t ratio. */
1089	typedef const STAMRATIOU32 *PCSTAMRATIOU32;
1090
1091
1092
1093
1094	/** @defgroup grp_stam_r3 The STAM Host Context Ring 3 API
1095	* @ingroup grp_stam
1096	* @{
1097	*/
1098
1099	VMMR3DECL(int) STAMR3InitUVM(PUVM pUVM);
1100	VMMR3DECL(void) STAMR3TermUVM(PUVM pUVM);
1101	VMMR3DECL(int) STAMR3RegisterU(PUVM pUVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
1102	const char pszName, STAMUNIT enmUnit, const char pszDesc);
1103	VMMR3DECL(int) STAMR3Register(PVM pVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
1104	const char pszName, STAMUNIT enmUnit, const char pszDesc);
1105
1106	/** @def STAM_REL_REG
1107	* Registers a statistics sample.
1108	*
1109	* @param pVM VM Handle.
1110	* @param pvSample Pointer to the sample.
1111	* @param enmType Sample type. This indicates what pvSample is pointing at.
1112	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
1113	* Further nesting is possible.
1114	* @param enmUnit Sample unit.
1115	* @param pszDesc Sample description.
1116	*/
1117	#define STAM_REL_REG(pVM, pvSample, enmType, pszName, enmUnit, pszDesc) \
1118	STAM_REL_STATS({ int rcStam = STAMR3Register(pVM, pvSample, enmType, STAMVISIBILITY_ALWAYS, pszName, enmUnit, pszDesc); \
1119	AssertRC(rcStam); })
1120	/** @def STAM_REG
1121	* Registers a statistics sample if statistics are enabled.
1122	*
1123	* @param pVM VM Handle.
1124	* @param pvSample Pointer to the sample.
1125	* @param enmType Sample type. This indicates what pvSample is pointing at.
1126	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
1127	* Further nesting is possible.
1128	* @param enmUnit Sample unit.
1129	* @param pszDesc Sample description.
1130	*/
1131	#define STAM_REG(pVM, pvSample, enmType, pszName, enmUnit, pszDesc) \
1132	STAM_STATS({STAM_REL_REG(pVM, pvSample, enmType, pszName, enmUnit, pszDesc);})
1133
1134	/** @def STAM_REL_REG_USED
1135	* Registers a statistics sample which only shows when used.
1136	*
1137	* @param pVM VM Handle.
1138	* @param pvSample Pointer to the sample.
1139	* @param enmType Sample type. This indicates what pvSample is pointing at.
1140	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
1141	* Further nesting is possible.
1142	* @param enmUnit Sample unit.
1143	* @param pszDesc Sample description.
1144	*/
1145	#define STAM_REL_REG_USED(pVM, pvSample, enmType, pszName, enmUnit, pszDesc) \
1146	STAM_REL_STATS({ int rcStam = STAMR3Register(pVM, pvSample, enmType, STAMVISIBILITY_USED, pszName, enmUnit, pszDesc); \
1147	AssertRC(rcStam);})
1148	/** @def STAM_REG_USED
1149	* Registers a statistics sample which only shows when used, if statistics are enabled.
1150	*
1151	* @param pVM VM Handle.
1152	* @param pvSample Pointer to the sample.
1153	* @param enmType Sample type. This indicates what pvSample is pointing at.
1154	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
1155	* Further nesting is possible.
1156	* @param enmUnit Sample unit.
1157	* @param pszDesc Sample description.
1158	*/
1159	#define STAM_REG_USED(pVM, pvSample, enmType, pszName, enmUnit, pszDesc) \
1160	STAM_STATS({ STAM_REL_REG_USED(pVM, pvSample, enmType, pszName, enmUnit, pszDesc); })
1161
1162	VMMR3DECL(int) STAMR3RegisterFU(PUVM pUVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1163	const char pszDesc, const char pszName, ...);
1164	VMMR3DECL(int) STAMR3RegisterF(PVM pVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1165	const char pszDesc, const char pszName, ...);
1166	VMMR3DECL(int) STAMR3RegisterVU(PUVM pUVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1167	const char pszDesc, const char pszName, va_list args);
1168	VMMR3DECL(int) STAMR3RegisterV(PVM pVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1169	const char pszDesc, const char pszName, va_list args);
1170
1171	/**
1172	* Resets the sample.
1173	* @param pVM The VM handle.
1174	* @param pvSample The sample registered using STAMR3RegisterCallback.
1175	*/
1176	typedef void FNSTAMR3CALLBACKRESET(PVM pVM, void *pvSample);
1177	/** Pointer to a STAM sample reset callback. */
1178	typedef FNSTAMR3CALLBACKRESET *PFNSTAMR3CALLBACKRESET;
1179
1180	/**
1181	* Prints the sample into the buffer.
1182	*
1183	* @param pVM The VM handle.
1184	* @param pvSample The sample registered using STAMR3RegisterCallback.
1185	* @param pszBuf The buffer to print into.
1186	* @param cchBuf The size of the buffer.
1187	*/
1188	typedef void FNSTAMR3CALLBACKPRINT(PVM pVM, void pvSample, char pszBuf, size_t cchBuf);
1189	/** Pointer to a STAM sample print callback. */
1190	typedef FNSTAMR3CALLBACKPRINT *PFNSTAMR3CALLBACKPRINT;
1191
1192	VMMR3DECL(int) STAMR3RegisterCallback(PVM pVM, void *pvSample, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1193	PFNSTAMR3CALLBACKRESET pfnReset, PFNSTAMR3CALLBACKPRINT pfnPrint,
1194	const char pszDesc, const char pszName, ...);
1195	VMMR3DECL(int) STAMR3RegisterCallbackV(PVM pVM, void *pvSample, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1196	PFNSTAMR3CALLBACKRESET pfnReset, PFNSTAMR3CALLBACKPRINT pfnPrint,
1197	const char pszDesc, const char pszName, va_list args);
1198	VMMR3DECL(int) STAMR3DeregisterU(PUVM pUVM, void *pvSample);
1199	VMMR3DECL(int) STAMR3Deregister(PVM pVM, void *pvSample);
1200
1201	/** @def STAM_REL_DEREG
1202	* Deregisters a statistics sample if statistics are enabled.
1203	*
1204	* @param pVM VM Handle.
1205	* @param pvSample Pointer to the sample.
1206	*/
1207	#define STAM_REL_DEREG(pVM, pvSample) \
1208	STAM_REL_STATS({ int rcStam = STAMR3Deregister(pVM, pvSample); AssertRC(rcStam); })
1209	/** @def STAM_DEREG
1210	* Deregisters a statistics sample if statistics are enabled.
1211	*
1212	* @param pVM VM Handle.
1213	* @param pvSample Pointer to the sample.
1214	*/
1215	#define STAM_DEREG(pVM, pvSample) \
1216	STAM_STATS({ STAM_REL_DEREG(pVM, pvSample); })
1217
1218	VMMR3DECL(int) STAMR3ResetU(PUVM pUVM, const char *pszPat);
1219	VMMR3DECL(int) STAMR3Reset(PVM pVM, const char *pszPat);
1220	VMMR3DECL(int) STAMR3SnapshotU(PUVM pUVM, const char pszPat, char ppszSnapshot, size_t pcchSnapshot, bool fWithDesc);
1221	VMMR3DECL(int) STAMR3Snapshot(PVM pVM, const char pszPat, char ppszSnapshot, size_t pcchSnapshot, bool fWithDesc);
1222	VMMR3DECL(int) STAMR3SnapshotFreeU(PUVM pUVM, char *pszSnapshot);
1223	VMMR3DECL(int) STAMR3SnapshotFree(PVM pVM, char *pszSnapshot);
1224	VMMR3DECL(int) STAMR3DumpU(PUVM pUVM, const char *pszPat);
1225	VMMR3DECL(int) STAMR3Dump(PVM pVM, const char *pszPat);
1226	VMMR3DECL(int) STAMR3DumpToReleaseLogU(PUVM pUVM, const char *pszPat);
1227	VMMR3DECL(int) STAMR3DumpToReleaseLog(PVM pVM, const char *pszPat);
1228	VMMR3DECL(int) STAMR3PrintU(PUVM pUVM, const char *pszPat);
1229	VMMR3DECL(int) STAMR3Print(PVM pVM, const char *pszPat);
1230
1231	/**
1232	* Callback function for STAMR3Enum().
1233	*
1234	* @returns non-zero to halt the enumeration.
1235	*
1236	* @param pszName The name of the sample.
1237	* @param enmType The type.
1238	* @param pvSample Pointer to the data. enmType indicates the format of this data.
1239	* @param enmUnit The unit.
1240	* @param enmVisibility The visibility.
1241	* @param pszDesc The description.
1242	* @param pvUser The pvUser argument given to STAMR3Enum().
1243	*/
1244	typedef DECLCALLBACK(int) FNSTAMR3ENUM(const char pszName, STAMTYPE enmType, void pvSample, STAMUNIT enmUnit,
1245	STAMVISIBILITY enmVisiblity, const char pszDesc, void pvUser);
1246	/** Pointer to a FNSTAMR3ENUM(). */
1247	typedef FNSTAMR3ENUM *PFNSTAMR3ENUM;
1248
1249	VMMR3DECL(int) STAMR3EnumU(PUVM pUVM, const char pszPat, PFNSTAMR3ENUM pfnEnum, void pvUser);
1250	VMMR3DECL(int) STAMR3Enum(PVM pVM, const char pszPat, PFNSTAMR3ENUM pfnEnum, void pvUser);
1251	VMMR3DECL(const char *) STAMR3GetUnit(STAMUNIT enmUnit);
1252
1253	/** @} */
1254
1255	/** @} */
1256
1257	RT_C_DECLS_END
1258
1259	#endif
1260

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

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

Download in other formats: