stam.h@ 32871

Last change on this file since 32871 was 32840, checked in by vboxsync, 14 years ago
fixed STAM_COUNTER_RESET
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	/** Hertz. */
219	STAMUNIT_HZ,
220	/** The end (exclusive). */
221	STAMUNIT_END
222	} STAMUNIT;
223
224
225	/** @def STAM_REL_U8_INC
226	* Increments a uint8_t sample by one.
227	*
228	* @param pCounter Pointer to the uint8_t variable to operate on.
229	*/
230	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
231	# define STAM_REL_U8_INC(pCounter) \
232	do { ++*(pCounter); } while (0)
233	#else
234	# define STAM_REL_U8_INC(pCounter) do { } while (0)
235	#endif
236	/** @def STAM_U8_INC
237	* Increments a uint8_t sample by one.
238	*
239	* @param pCounter Pointer to the uint8_t variable to operate on.
240	*/
241	#ifdef VBOX_WITH_STATISTICS
242	# define STAM_U8_INC(pCounter) STAM_REL_U8_INC(pCounter)
243	#else
244	# define STAM_U8_INC(pCounter) do { } while (0)
245	#endif
246
247
248	/** @def STAM_REL_U8_DEC
249	* Decrements a uint8_t sample by one.
250	*
251	* @param pCounter Pointer to the uint8_t variable to operate on.
252	*/
253	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
254	# define STAM_REL_U8_DEC(pCounter) \
255	do { --*(pCounter); } while (0)
256	#else
257	# define STAM_REL_U8_DEC(pCounter) do { } while (0)
258	#endif
259	/** @def STAM_U8_DEC
260	* Decrements a uint8_t sample by one.
261	*
262	* @param pCounter Pointer to the uint8_t variable to operate on.
263	*/
264	#ifdef VBOX_WITH_STATISTICS
265	# define STAM_U8_DEC(pCounter) STAM_REL_U8_DEC(pCounter)
266	#else
267	# define STAM_U8_DEC(pCounter) do { } while (0)
268	#endif
269
270
271	/** @def STAM_REL_U8_ADD
272	* Increments a uint8_t sample by a value.
273	*
274	* @param pCounter Pointer to the uint8_t variable to operate on.
275	* @param Addend The value to add.
276	*/
277	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
278	# define STAM_REL_U8_ADD(pCounter, Addend) \
279	do { *(pCounter) += (Addend); } while (0)
280	#else
281	# define STAM_REL_U8_ADD(pCounter, Addend) do { } while (0)
282	#endif
283	/** @def STAM_U8_ADD
284	* Increments a uint8_t sample by a value.
285	*
286	* @param pCounter Pointer to the uint8_t variable to operate on.
287	* @param Addend The value to add.
288	*/
289	#ifdef VBOX_WITH_STATISTICS
290	# define STAM_U8_ADD(pCounter, Addend) STAM_REL_U8_ADD(pCounter, Addend
291	#else
292	# define STAM_U8_ADD(pCounter, Addend) do { } while (0)
293	#endif
294
295
296	/** @def STAM_REL_U16_INC
297	* Increments a uint16_t sample by one.
298	*
299	* @param pCounter Pointer to the uint16_t variable to operate on.
300	*/
301	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
302	# define STAM_REL_U16_INC(pCounter) \
303	do { ++*(pCounter); } while (0)
304	#else
305	# define STAM_REL_U16_INC(pCounter) do { } while (0)
306	#endif
307	/** @def STAM_U16_INC
308	* Increments a uint16_t sample by one.
309	*
310	* @param pCounter Pointer to the uint16_t variable to operate on.
311	*/
312	#ifdef VBOX_WITH_STATISTICS
313	# define STAM_U16_INC(pCounter) STAM_REL_U16_INC(pCounter)
314	#else
315	# define STAM_U16_INC(pCounter) do { } while (0)
316	#endif
317
318
319	/** @def STAM_REL_U16_DEC
320	* Decrements a uint16_t sample by one.
321	*
322	* @param pCounter Pointer to the uint16_t variable to operate on.
323	*/
324	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
325	# define STAM_REL_U16_DEC(pCounter) \
326	do { --*(pCounter); } while (0)
327	#else
328	# define STAM_REL_U16_DEC(pCounter) do { } while (0)
329	#endif
330	/** @def STAM_U16_DEC
331	* Decrements a uint16_t sample by one.
332	*
333	* @param pCounter Pointer to the uint16_t variable to operate on.
334	*/
335	#ifdef VBOX_WITH_STATISTICS
336	# define STAM_U16_DEC(pCounter) STAM_REL_U16_DEC(pCounter)
337	#else
338	# define STAM_U16_DEC(pCounter) do { } while (0)
339	#endif
340
341
342	/** @def STAM_REL_U16_INC
343	* Increments a uint16_t sample by a value.
344	*
345	* @param pCounter Pointer to the uint16_t variable to operate on.
346	* @param Addend The value to add.
347	*/
348	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
349	# define STAM_REL_U16_ADD(pCounter, Addend) \
350	do { *(pCounter) += (Addend); } while (0)
351	#else
352	# define STAM_REL_U16_ADD(pCounter, Addend) do { } while (0)
353	#endif
354	/** @def STAM_U16_INC
355	* Increments a uint16_t sample by a value.
356	*
357	* @param pCounter Pointer to the uint16_t variable to operate on.
358	* @param Addend The value to add.
359	*/
360	#ifdef VBOX_WITH_STATISTICS
361	# define STAM_U16_ADD(pCounter, Addend) STAM_REL_U16_ADD(pCounter, Addend)
362	#else
363	# define STAM_U16_ADD(pCounter, Addend) do { } while (0)
364	#endif
365
366
367	/** @def STAM_REL_U32_INC
368	* Increments a uint32_t sample by one.
369	*
370	* @param pCounter Pointer to the uint32_t variable to operate on.
371	*/
372	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
373	# define STAM_REL_U32_INC(pCounter) \
374	do { ++*(pCounter); } while (0)
375	#else
376	# define STAM_REL_U32_INC(pCounter) do { } while (0)
377	#endif
378	/** @def STAM_U32_INC
379	* Increments a uint32_t sample by one.
380	*
381	* @param pCounter Pointer to the uint32_t variable to operate on.
382	*/
383	#ifdef VBOX_WITH_STATISTICS
384	# define STAM_U32_INC(pCounter) STAM_REL_U32_INC(pCounter)
385	#else
386	# define STAM_U32_INC(pCounter) do { } while (0)
387	#endif
388
389
390	/** @def STAM_REL_U32_DEC
391	* Decrements a uint32_t sample by one.
392	*
393	* @param pCounter Pointer to the uint32_t variable to operate on.
394	*/
395	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
396	# define STAM_REL_U32_DEC(pCounter) \
397	do { --*(pCounter); } while (0)
398	#else
399	# define STAM_REL_U32_DEC(pCounter) do { } while (0)
400	#endif
401	/** @def STAM_U32_DEC
402	* Decrements a uint32_t sample by one.
403	*
404	* @param pCounter Pointer to the uint32_t variable to operate on.
405	*/
406	#ifdef VBOX_WITH_STATISTICS
407	# define STAM_U32_DEC(pCounter) STAM_REL_U32_DEC(pCounter)
408	#else
409	# define STAM_U32_DEC(pCounter) do { } while (0)
410	#endif
411
412
413	/** @def STAM_REL_U32_ADD
414	* Increments a uint32_t sample by value.
415	*
416	* @param pCounter Pointer to the uint32_t variable to operate on.
417	* @param Addend The value to add.
418	*/
419	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
420	# define STAM_REL_U32_ADD(pCounter, Addend) \
421	do { *(pCounter) += (Addend); } while (0)
422	#else
423	# define STAM_REL_U32_ADD(pCounter, Addend) do { } while (0)
424	#endif
425	/** @def STAM_U32_ADD
426	* Increments a uint32_t sample by value.
427	*
428	* @param pCounter Pointer to the uint32_t variable to operate on.
429	* @param Addend The value to add.
430	*/
431	#ifdef VBOX_WITH_STATISTICS
432	# define STAM_U32_ADD(pCounter, Addend) STAM_REL_U32_ADD(pCounter, Addend)
433	#else
434	# define STAM_U32_ADD(pCounter, Addend) do { } while (0)
435	#endif
436
437
438	/** @def STAM_REL_U64_INC
439	* Increments a uint64_t sample by one.
440	*
441	* @param pCounter Pointer to the uint64_t variable to operate on.
442	*/
443	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
444	# define STAM_REL_U64_INC(pCounter) \
445	do { ++*(pCounter); } while (0)
446	#else
447	# define STAM_REL_U64_INC(pCounter) do { } while (0)
448	#endif
449	/** @def STAM_U64_INC
450	* Increments a uint64_t sample by one.
451	*
452	* @param pCounter Pointer to the uint64_t variable to operate on.
453	*/
454	#ifdef VBOX_WITH_STATISTICS
455	# define STAM_U64_INC(pCounter) STAM_REL_U64_INC(pCounter)
456	#else
457	# define STAM_U64_INC(pCounter) do { } while (0)
458	#endif
459
460
461	/** @def STAM_REL_U64_DEC
462	* Decrements a uint64_t sample by one.
463	*
464	* @param pCounter Pointer to the uint64_t variable to operate on.
465	*/
466	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
467	# define STAM_REL_U64_DEC(pCounter) \
468	do { --*(pCounter); } while (0)
469	#else
470	# define STAM_REL_U64_DEC(pCounter) do { } while (0)
471	#endif
472	/** @def STAM_U64_DEC
473	* Decrements a uint64_t sample by one.
474	*
475	* @param pCounter Pointer to the uint64_t variable to operate on.
476	*/
477	#ifdef VBOX_WITH_STATISTICS
478	# define STAM_U64_DEC(pCounter) STAM_REL_U64_DEC(pCounter)
479	#else
480	# define STAM_U64_DEC(pCounter) do { } while (0)
481	#endif
482
483
484	/** @def STAM_REL_U64_ADD
485	* Increments a uint64_t sample by a value.
486	*
487	* @param pCounter Pointer to the uint64_t variable to operate on.
488	* @param Addend The value to add.
489	*/
490	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
491	# define STAM_REL_U64_ADD(pCounter, Addend) \
492	do { *(pCounter) += (Addend); } while (0)
493	#else
494	# define STAM_REL_U64_ADD(pCounter, Addend) do { } while (0)
495	#endif
496	/** @def STAM_U64_ADD
497	* Increments a uint64_t sample by a value.
498	*
499	* @param pCounter Pointer to the uint64_t variable to operate on.
500	* @param Addend The value to add.
501	*/
502	#ifdef VBOX_WITH_STATISTICS
503	# define STAM_U64_ADD(pCounter, Addend) STAM_REL_U64_ADD(pCounter, Addend)
504	#else
505	# define STAM_U64_ADD(pCounter, Addend) do { } while (0)
506	#endif
507
508
509	/**
510	* Counter sample - STAMTYPE_COUNTER.
511	*/
512	typedef struct STAMCOUNTER
513	{
514	/** The current count. */
515	volatile uint64_t c;
516	} STAMCOUNTER;
517	/** Pointer to a counter. */
518	typedef STAMCOUNTER *PSTAMCOUNTER;
519	/** Pointer to a const counter. */
520	typedef const STAMCOUNTER *PCSTAMCOUNTER;
521
522
523	/** @def STAM_REL_COUNTER_INC
524	* Increments a counter sample by one.
525	*
526	* @param pCounter Pointer to the STAMCOUNTER structure to operate on.
527	*/
528	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
529	# define STAM_REL_COUNTER_INC(pCounter) \
530	do { (pCounter)->c++; } while (0)
531	#else
532	# define STAM_REL_COUNTER_INC(pCounter) do { } while (0)
533	#endif
534	/** @def STAM_COUNTER_INC
535	* Increments a counter sample by one.
536	*
537	* @param pCounter Pointer to the STAMCOUNTER structure to operate on.
538	*/
539	#ifdef VBOX_WITH_STATISTICS
540	# define STAM_COUNTER_INC(pCounter) STAM_REL_COUNTER_INC(pCounter)
541	#else
542	# define STAM_COUNTER_INC(pCounter) do { } while (0)
543	#endif
544
545
546	/** @def STAM_REL_COUNTER_DEC
547	* Decrements a counter sample by one.
548	*
549	* @param pCounter Pointer to the STAMCOUNTER structure to operate on.
550	*/
551	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
552	# define STAM_REL_COUNTER_DEC(pCounter) \
553	do { (pCounter)->c--; } while (0)
554	#else
555	# define STAM_REL_COUNTER_DEC(pCounter) do { } while (0)
556	#endif
557	/** @def STAM_COUNTER_DEC
558	* Decrements a counter sample by one.
559	*
560	* @param pCounter Pointer to the STAMCOUNTER structure to operate on.
561	*/
562	#ifdef VBOX_WITH_STATISTICS
563	# define STAM_COUNTER_DEC(pCounter) STAM_REL_COUNTER_DEC(pCounter)
564	#else
565	# define STAM_COUNTER_DEC(pCounter) do { } while (0)
566	#endif
567
568
569	/** @def STAM_REL_COUNTER_ADD
570	* Increments a counter sample by a value.
571	*
572	* @param pCounter Pointer to the STAMCOUNTER structure to operate on.
573	* @param Addend The value to add to the counter.
574	*/
575	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
576	# define STAM_REL_COUNTER_ADD(pCounter, Addend) \
577	do { (pCounter)->c += (Addend); } while (0)
578	#else
579	# define STAM_REL_COUNTER_ADD(pCounter, Addend) do { } while (0)
580	#endif
581	/** @def STAM_COUNTER_ADD
582	* Increments a counter sample by a value.
583	*
584	* @param pCounter Pointer to the STAMCOUNTER structure to operate on.
585	* @param Addend The value to add to the counter.
586	*/
587	#ifdef VBOX_WITH_STATISTICS
588	# define STAM_COUNTER_ADD(pCounter, Addend) STAM_REL_COUNTER_ADD(pCounter, Addend)
589	#else
590	# define STAM_COUNTER_ADD(pCounter, Addend) do { } while (0)
591	#endif
592
593
594	/** @def STAM_REL_COUNTER_RESET
595	* Resets the statistics sample.
596	*/
597	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
598	# define STAM_REL_COUNTER_RESET(pCounter) do { (pCounter)->c = 0; } while (0)
599	#else
600	# define STAM_REL_COUNTER_RESET(pCounter) do { } while (0)
601	#endif
602	/** @def STAM_COUNTER_RESET
603	* Resets the statistics sample.
604	*/
605	#ifdef VBOX_WITH_STATISTICS
606	# define STAM_COUNTER_RESET(pCounter) STAM_REL_COUNTER_RESET(pCounter)
607	#else
608	# define STAM_COUNTER_RESET(pCounter) do { } while (0)
609	#endif
610
611
612
613	/**
614	* Profiling sample - STAMTYPE_PROFILE.
615	*/
616	typedef struct STAMPROFILE
617	{
618	/** Number of periods. */
619	volatile uint64_t cPeriods;
620	/** Total count of ticks. */
621	volatile uint64_t cTicks;
622	/** Maximum tick count during a sampling. */
623	volatile uint64_t cTicksMax;
624	/** Minimum tick count during a sampling. */
625	volatile uint64_t cTicksMin;
626	} STAMPROFILE;
627	/** Pointer to a profile sample. */
628	typedef STAMPROFILE *PSTAMPROFILE;
629	/** Pointer to a const profile sample. */
630	typedef const STAMPROFILE *PCSTAMPROFILE;
631
632
633	/** @def STAM_REL_PROFILE_ADD_PERIOD
634	* Adds a period.
635	*
636	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
637	* @param cTicksInPeriod The number of tick (or whatever) of the preiod
638	* being added. This is only referenced once.
639	*/
640	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
641	# define STAM_REL_PROFILE_ADD_PERIOD(pProfile, cTicksInPeriod) \
642	do { \
643	uint64_t const StamPrefix_cTicks = (cTicksInPeriod); \
644	(pProfile)->cTicks += StamPrefix_cTicks; \
645	(pProfile)->cPeriods++; \
646	if ((pProfile)->cTicksMax < StamPrefix_cTicks) \
647	(pProfile)->cTicksMax = StamPrefix_cTicks; \
648	if ((pProfile)->cTicksMin > StamPrefix_cTicks) \
649	(pProfile)->cTicksMin = StamPrefix_cTicks; \
650	} while (0)
651	#else
652	# define STAM_REL_PROFILE_ADD_PERIOD(pProfile, cTicksInPeriod) do { } while (0)
653	#endif
654	/** @def STAM_PROFILE_ADD_PERIOD
655	* Adds a period.
656	*
657	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
658	* @param cTicksInPeriod The number of tick (or whatever) of the preiod
659	* being added. This is only referenced once.
660	*/
661	#ifdef VBOX_WITH_STATISTICS
662	# define STAM_PROFILE_ADD_PERIOD(pProfile, cTicksInPeriod) STAM_REL_PROFILE_ADD_PERIOD(pProfile, cTicksInPeriod)
663	#else
664	# define STAM_PROFILE_ADD_PERIOD(pProfile, cTicksInPeriod) do { } while (0)
665	#endif
666
667
668	/** @def STAM_REL_PROFILE_START
669	* Samples the start time of a profiling period.
670	*
671	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
672	* @param Prefix Identifier prefix used to internal variables.
673	*
674	* @remarks Declears a stack variable that will be used by related macros.
675	*/
676	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
677	# define STAM_REL_PROFILE_START(pProfile, Prefix) \
678	uint64_t Prefix##_tsStart; \
679	STAM_GET_TS(Prefix##_tsStart)
680	#else
681	# define STAM_REL_PROFILE_START(pProfile, Prefix) do { } while (0)
682	#endif
683	/** @def STAM_PROFILE_START
684	* Samples the start time of a profiling period.
685	*
686	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
687	* @param Prefix Identifier prefix used to internal variables.
688	*
689	* @remarks Declears a stack variable that will be used by related macros.
690	*/
691	#ifdef VBOX_WITH_STATISTICS
692	# define STAM_PROFILE_START(pProfile, Prefix) STAM_REL_PROFILE_START(pProfile, Prefix)
693	#else
694	# define STAM_PROFILE_START(pProfile, Prefix) do { } while (0)
695	#endif
696
697	/** @def STAM_REL_PROFILE_STOP
698	* Samples the stop time of a profiling period and updates the sample.
699	*
700	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
701	* @param Prefix Identifier prefix used to internal variables.
702	*/
703	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
704	# define STAM_REL_PROFILE_STOP(pProfile, Prefix) \
705	do { \
706	uint64_t Prefix##_cTicks; \
707	STAM_GET_TS(Prefix##_cTicks); \
708	Prefix##_cTicks -= Prefix##_tsStart; \
709	(pProfile)->cTicks += Prefix##_cTicks; \
710	(pProfile)->cPeriods++; \
711	if ((pProfile)->cTicksMax < Prefix##_cTicks) \
712	(pProfile)->cTicksMax = Prefix##_cTicks; \
713	if ((pProfile)->cTicksMin > Prefix##_cTicks) \
714	(pProfile)->cTicksMin = Prefix##_cTicks; \
715	} while (0)
716	#else
717	# define STAM_REL_PROFILE_STOP(pProfile, Prefix) do { } while (0)
718	#endif
719	/** @def STAM_PROFILE_STOP
720	* Samples the stop time of a profiling period and updates the sample.
721	*
722	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
723	* @param Prefix Identifier prefix used to internal variables.
724	*/
725	#ifdef VBOX_WITH_STATISTICS
726	# define STAM_PROFILE_STOP(pProfile, Prefix) STAM_REL_PROFILE_STOP(pProfile, Prefix)
727	#else
728	# define STAM_PROFILE_STOP(pProfile, Prefix) do { } while (0)
729	#endif
730
731
732	/** @def STAM_REL_PROFILE_STOP_EX
733	* Samples the stop time of a profiling period and updates both the sample
734	* and an attribution sample.
735	*
736	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
737	* @param pProfile2 Pointer to the STAMPROFILE structure which this
738	* interval should be attributed to as well. This may be NULL.
739	* @param Prefix Identifier prefix used to internal variables.
740	*/
741	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
742	# define STAM_REL_PROFILE_STOP_EX(pProfile, pProfile2, Prefix) \
743	do { \
744	uint64_t Prefix##_cTicks; \
745	STAM_GET_TS(Prefix##_cTicks); \
746	Prefix##_cTicks -= Prefix##_tsStart; \
747	(pProfile)->cTicks += Prefix##_cTicks; \
748	(pProfile)->cPeriods++; \
749	if ((pProfile)->cTicksMax < Prefix##_cTicks) \
750	(pProfile)->cTicksMax = Prefix##_cTicks; \
751	if ((pProfile)->cTicksMin > Prefix##_cTicks) \
752	(pProfile)->cTicksMin = Prefix##_cTicks; \
753	\
754	if ((pProfile2)) \
755	{ \
756	(pProfile2)->cTicks += Prefix##_cTicks; \
757	(pProfile2)->cPeriods++; \
758	if ((pProfile2)->cTicksMax < Prefix##_cTicks) \
759	(pProfile2)->cTicksMax = Prefix##_cTicks; \
760	if ((pProfile2)->cTicksMin > Prefix##_cTicks) \
761	(pProfile2)->cTicksMin = Prefix##_cTicks; \
762	} \
763	} while (0)
764	#else
765	# define STAM_REL_PROFILE_STOP_EX(pProfile, pProfile2, Prefix) do { } while (0)
766	#endif
767	/** @def STAM_PROFILE_STOP_EX
768	* Samples the stop time of a profiling period and updates both the sample
769	* and an attribution sample.
770	*
771	* @param pProfile Pointer to the STAMPROFILE structure to operate on.
772	* @param pProfile2 Pointer to the STAMPROFILE structure which this
773	* interval should be attributed to as well. This may be NULL.
774	* @param Prefix Identifier prefix used to internal variables.
775	*/
776	#ifdef VBOX_WITH_STATISTICS
777	# define STAM_PROFILE_STOP_EX(pProfile, pProfile2, Prefix) STAM_REL_PROFILE_STOP_EX(pProfile, pProfile2, Prefix)
778	#else
779	# define STAM_PROFILE_STOP_EX(pProfile, pProfile2, Prefix) do { } while (0)
780	#endif
781
782
783	/**
784	* Advanced profiling sample - STAMTYPE_PROFILE_ADV.
785	*
786	* Identical to a STAMPROFILE sample, but the start timestamp
787	* is stored after the STAMPROFILE structure so the sampling
788	* can start and stop in different functions.
789	*/
790	typedef struct STAMPROFILEADV
791	{
792	/** The STAMPROFILE core. */
793	STAMPROFILE Core;
794	/** The start timestamp. */
795	volatile uint64_t tsStart;
796	} STAMPROFILEADV;
797	/** Pointer to a advanced profile sample. */
798	typedef STAMPROFILEADV *PSTAMPROFILEADV;
799	/** Pointer to a const advanced profile sample. */
800	typedef const STAMPROFILEADV *PCSTAMPROFILEADV;
801
802
803	/** @def STAM_REL_PROFILE_ADV_START
804	* Samples the start time of a profiling period.
805	*
806	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
807	* @param Prefix Identifier prefix used to internal variables.
808	*/
809	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
810	# define STAM_REL_PROFILE_ADV_START(pProfileAdv, Prefix) \
811	STAM_GET_TS((pProfileAdv)->tsStart)
812	#else
813	# define STAM_REL_PROFILE_ADV_START(pProfileAdv, Prefix) do { } while (0)
814	#endif
815	/** @def STAM_PROFILE_ADV_START
816	* Samples the start time of a profiling period.
817	*
818	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
819	* @param Prefix Identifier prefix used to internal variables.
820	*/
821	#ifdef VBOX_WITH_STATISTICS
822	# define STAM_PROFILE_ADV_START(pProfileAdv, Prefix) STAM_REL_PROFILE_ADV_START(pProfileAdv, Prefix)
823	#else
824	# define STAM_PROFILE_ADV_START(pProfileAdv, Prefix) do { } while (0)
825	#endif
826
827
828	/** @def STAM_REL_PROFILE_ADV_STOP
829	* Samples the stop time of a profiling period (if running) and updates the
830	* sample.
831	*
832	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
833	* @param Prefix Identifier prefix used to internal variables.
834	*/
835	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
836	# define STAM_REL_PROFILE_ADV_STOP(pProfileAdv, Prefix) \
837	do { \
838	if ((pProfileAdv)->tsStart) \
839	{ \
840	uint64_t Prefix##_cTicks; \
841	STAM_GET_TS(Prefix##_cTicks); \
842	Prefix##_cTicks -= (pProfileAdv)->tsStart; \
843	(pProfileAdv)->tsStart = 0; \
844	(pProfileAdv)->Core.cTicks += Prefix##_cTicks; \
845	(pProfileAdv)->Core.cPeriods++; \
846	if ((pProfileAdv)->Core.cTicksMax < Prefix##_cTicks) \
847	(pProfileAdv)->Core.cTicksMax = Prefix##_cTicks; \
848	if ((pProfileAdv)->Core.cTicksMin > Prefix##_cTicks) \
849	(pProfileAdv)->Core.cTicksMin = Prefix##_cTicks; \
850	} \
851	} while (0)
852	#else
853	# define STAM_REL_PROFILE_ADV_STOP(pProfileAdv, Prefix) do { } while (0)
854	#endif
855	/** @def STAM_PROFILE_ADV_STOP
856	* Samples the stop time of a profiling period (if running) and updates the
857	* sample.
858	*
859	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
860	* @param Prefix Identifier prefix used to internal variables.
861	*/
862	#ifdef VBOX_WITH_STATISTICS
863	# define STAM_PROFILE_ADV_STOP(pProfileAdv, Prefix) STAM_REL_PROFILE_ADV_STOP(pProfileAdv, Prefix)
864	#else
865	# define STAM_PROFILE_ADV_STOP(pProfileAdv, Prefix) do { } while (0)
866	#endif
867
868
869	/** @def STAM_REL_PROFILE_ADV_STOP_START
870	* Stops one profile counter (if running) and starts another one.
871	*
872	* @param pProfileAdv1 Pointer to the STAMPROFILEADV structure to stop.
873	* @param pProfileAdv2 Pointer to the STAMPROFILEADV structure to start.
874	* @param Prefix Identifier prefix used to internal variables.
875	*/
876	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
877	# define STAM_REL_PROFILE_ADV_STOP_START(pProfileAdv1, pProfileAdv2, Prefix) \
878	do { \
879	uint64_t Prefix##_cTicks; \
880	STAM_GET_TS(Prefix##_cTicks); \
881	(pProfileAdv2)->tsStart = Prefix##_cTicks; \
882	if ((pProfileAdv1)->tsStart) \
883	{ \
884	Prefix##_cTicks -= (pProfileAdv1)->tsStart; \
885	(pProfileAdv1)->tsStart = 0; \
886	(pProfileAdv1)->Core.cTicks += Prefix##_cTicks; \
887	(pProfileAdv1)->Core.cPeriods++; \
888	if ((pProfileAdv1)->Core.cTicksMax < Prefix##_cTicks) \
889	(pProfileAdv1)->Core.cTicksMax = Prefix##_cTicks; \
890	if ((pProfileAdv1)->Core.cTicksMin > Prefix##_cTicks) \
891	(pProfileAdv1)->Core.cTicksMin = Prefix##_cTicks; \
892	} \
893	} while (0)
894	#else
895	# define STAM_REL_PROFILE_ADV_STOP_START(pProfileAdv1, pProfileAdv2, Prefix) \
896	do { } while (0)
897	#endif
898	/** @def STAM_PROFILE_ADV_STOP_START
899	* Samples the stop time of a profiling period (if running) and updates the
900	* sample.
901	*
902	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
903	* @param Prefix Identifier prefix used to internal variables.
904	*/
905	#ifdef VBOX_WITH_STATISTICS
906	# define STAM_PROFILE_ADV_STOP_START(pProfileAdv1, pProfileAdv2, Prefix) \
907	STAM_REL_PROFILE_ADV_STOP_START(pProfileAdv1, pProfileAdv2, Prefix)
908	#else
909	# define STAM_PROFILE_ADV_STOP_START(pProfileAdv1, pProfileAdv2, Prefix) \
910	do { } while (0)
911	#endif
912
913
914	/** @def STAM_REL_PROFILE_ADV_SUSPEND
915	* Suspends the sampling for a while. This can be useful to exclude parts
916	* covered by other samples without screwing up the count, and average+min times.
917	*
918	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
919	* @param Prefix Identifier prefix used to internal variables. The prefix
920	* must match that of the resume one since it stores the
921	* suspend time in a stack variable.
922	*/
923	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
924	# define STAM_REL_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix) \
925	uint64_t Prefix##_tsSuspend; \
926	STAM_GET_TS(Prefix##_tsSuspend)
927	#else
928	# define STAM_REL_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix) do { } while (0)
929	#endif
930	/** @def STAM_PROFILE_ADV_SUSPEND
931	* Suspends the sampling for a while. This can be useful to exclude parts
932	* covered by other samples without screwing up the count, and average+min times.
933	*
934	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
935	* @param Prefix Identifier prefix used to internal variables. The prefix
936	* must match that of the resume one since it stores the
937	* suspend time in a stack variable.
938	*/
939	#ifdef VBOX_WITH_STATISTICS
940	# define STAM_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix) STAM_REL_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix)
941	#else
942	# define STAM_PROFILE_ADV_SUSPEND(pProfileAdv, Prefix) do { } while (0)
943	#endif
944
945
946	/** @def STAM_REL_PROFILE_ADV_RESUME
947	* Counter to STAM_REL_PROFILE_ADV_SUSPEND.
948	*
949	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
950	* @param Prefix Identifier prefix used to internal variables. This must
951	* match the one used with the SUSPEND!
952	*/
953	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
954	# define STAM_REL_PROFILE_ADV_RESUME(pProfileAdv, Prefix) \
955	do { \
956	uint64_t Prefix##_tsNow; \
957	STAM_GET_TS(Prefix##_tsNow); \
958	(pProfileAdv)->tsStart += Prefix##_tsNow - Prefix##_tsSuspend; \
959	} while (0)
960	#else
961	# define STAM_REL_PROFILE_ADV_RESUME(pProfileAdv, Prefix) do { } while (0)
962	#endif
963	/** @def STAM_PROFILE_ADV_RESUME
964	* Counter to STAM_PROFILE_ADV_SUSPEND.
965	*
966	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
967	* @param Prefix Identifier prefix used to internal variables. This must
968	* match the one used with the SUSPEND!
969	*/
970	#ifdef VBOX_WITH_STATISTICS
971	# define STAM_PROFILE_ADV_RESUME(pProfileAdv, Prefix) STAM_REL_PROFILE_ADV_RESUME(pProfileAdv, Prefix)
972	#else
973	# define STAM_PROFILE_ADV_RESUME(pProfileAdv, Prefix) do { } while (0)
974	#endif
975
976
977	/** @def STAM_REL_PROFILE_ADV_STOP_EX
978	* Samples the stop time of a profiling period (if running) and updates both
979	* the sample and an attribution sample.
980	*
981	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
982	* @param pProfile2 Pointer to the STAMPROFILE structure which this
983	* interval should be attributed to as well. This may be NULL.
984	* @param Prefix Identifier prefix used to internal variables.
985	*/
986	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
987	# define STAM_REL_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix) \
988	do { \
989	if ((pProfileAdv)->tsStart) \
990	{ \
991	uint64_t Prefix##_cTicks; \
992	STAM_GET_TS(Prefix##_cTicks); \
993	Prefix##_cTicks -= (pProfileAdv)->tsStart; \
994	(pProfileAdv)->tsStart = 0; \
995	(pProfileAdv)->Core.cTicks += Prefix##_cTicks; \
996	(pProfileAdv)->Core.cPeriods++; \
997	if ((pProfileAdv)->Core.cTicksMax < Prefix##_cTicks) \
998	(pProfileAdv)->Core.cTicksMax = Prefix##_cTicks; \
999	if ((pProfileAdv)->Core.cTicksMin > Prefix##_cTicks) \
1000	(pProfileAdv)->Core.cTicksMin = Prefix##_cTicks; \
1001	if ((pProfile2)) \
1002	{ \
1003	(pProfile2)->cTicks += Prefix##_cTicks; \
1004	(pProfile2)->cPeriods++; \
1005	if ((pProfile2)->cTicksMax < Prefix##_cTicks) \
1006	(pProfile2)->cTicksMax = Prefix##_cTicks; \
1007	if ((pProfile2)->cTicksMin > Prefix##_cTicks) \
1008	(pProfile2)->cTicksMin = Prefix##_cTicks; \
1009	} \
1010	} \
1011	} while (0)
1012	#else
1013	# define STAM_REL_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix) do { } while (0)
1014	#endif
1015	/** @def STAM_PROFILE_ADV_STOP_EX
1016	* Samples the stop time of a profiling period (if running) and updates both
1017	* the sample and an attribution sample.
1018	*
1019	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
1020	* @param pProfile2 Pointer to the STAMPROFILE structure which this
1021	* interval should be attributed to as well. This may be NULL.
1022	* @param Prefix Identifier prefix used to internal variables.
1023	*/
1024	#ifdef VBOX_WITH_STATISTICS
1025	# define STAM_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix) STAM_REL_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix)
1026	#else
1027	# define STAM_PROFILE_ADV_STOP_EX(pProfileAdv, pProfile2, Prefix) do { } while (0)
1028	#endif
1029
1030	/** @def STAM_REL_PROFILE_ADV_IS_RUNNING
1031	* Checks if it is running.
1032	*
1033	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
1034	*/
1035	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
1036	# define STAM_REL_PROFILE_ADV_IS_RUNNING(pProfileAdv) (pProfileAdv)->tsStart
1037	#else
1038	# define STAM_REL_PROFILE_ADV_IS_RUNNING(pProfileAdv) (false)
1039	#endif
1040	/** @def STAM_PROFILE_ADV_IS_RUNNING
1041	* Checks if it is running.
1042	*
1043	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
1044	*/
1045	#ifdef VBOX_WITH_STATISTICS
1046	# define STAM_PROFILE_ADV_IS_RUNNING(pProfileAdv) STAM_REL_PROFILE_ADV_IS_RUNNING(pProfileAdv)
1047	#else
1048	# define STAM_PROFILE_ADV_IS_RUNNING(pProfileAdv) (false)
1049	#endif
1050
1051	/** @def STAM_REL_PROFILE_ADV_SET_STOPPED
1052	* Marks the profile counter as stopped.
1053	*
1054	* This is for avoiding screwups in twisty code.
1055	*
1056	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
1057	*/
1058	#ifndef VBOX_WITHOUT_RELEASE_STATISTICS
1059	# define STAM_REL_PROFILE_ADV_SET_STOPPED(pProfileAdv) do { (pProfileAdv)->tsStart = 0; } while (0)
1060	#else
1061	# define STAM_REL_PROFILE_ADV_SET_STOPPED(pProfileAdv) do { } while (0)
1062	#endif
1063	/** @def STAM_PROFILE_ADV_SET_STOPPED
1064	* Marks the profile counter as stopped.
1065	*
1066	* This is for avoiding screwups in twisty code.
1067	*
1068	* @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on.
1069	*/
1070	#ifdef VBOX_WITH_STATISTICS
1071	# define STAM_PROFILE_ADV_SET_STOPPED(pProfileAdv) STAM_REL_PROFILE_ADV_SET_STOPPED(pProfileAdv)
1072	#else
1073	# define STAM_PROFILE_ADV_SET_STOPPED(pProfileAdv) do { } while (0)
1074	#endif
1075
1076
1077	/**
1078	* Ratio of A to B, uint32_t types.
1079	* @remark Use STAM_STATS or STAM_REL_STATS for modifying A & B values.
1080	*/
1081	typedef struct STAMRATIOU32
1082	{
1083	/** Sample A. */
1084	uint32_t volatile u32A;
1085	/** Sample B. */
1086	uint32_t volatile u32B;
1087	} STAMRATIOU32;
1088	/** Pointer to a uint32_t ratio. */
1089	typedef STAMRATIOU32 *PSTAMRATIOU32;
1090	/** Pointer to const a uint32_t ratio. */
1091	typedef const STAMRATIOU32 *PCSTAMRATIOU32;
1092
1093
1094
1095
1096	/** @defgroup grp_stam_r3 The STAM Host Context Ring 3 API
1097	* @ingroup grp_stam
1098	* @{
1099	*/
1100
1101	VMMR3DECL(int) STAMR3InitUVM(PUVM pUVM);
1102	VMMR3DECL(void) STAMR3TermUVM(PUVM pUVM);
1103	VMMR3DECL(int) STAMR3RegisterU(PUVM pUVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
1104	const char pszName, STAMUNIT enmUnit, const char pszDesc);
1105	VMMR3DECL(int) STAMR3Register(PVM pVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
1106	const char pszName, STAMUNIT enmUnit, const char pszDesc);
1107
1108	/** @def STAM_REL_REG
1109	* Registers a statistics sample.
1110	*
1111	* @param pVM VM Handle.
1112	* @param pvSample Pointer to the sample.
1113	* @param enmType Sample type. This indicates what pvSample is pointing at.
1114	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
1115	* Further nesting is possible.
1116	* @param enmUnit Sample unit.
1117	* @param pszDesc Sample description.
1118	*/
1119	#define STAM_REL_REG(pVM, pvSample, enmType, pszName, enmUnit, pszDesc) \
1120	STAM_REL_STATS({ int rcStam = STAMR3Register(pVM, pvSample, enmType, STAMVISIBILITY_ALWAYS, pszName, enmUnit, pszDesc); \
1121	AssertRC(rcStam); })
1122	/** @def STAM_REG
1123	* Registers a statistics sample if statistics are enabled.
1124	*
1125	* @param pVM VM Handle.
1126	* @param pvSample Pointer to the sample.
1127	* @param enmType Sample type. This indicates what pvSample is pointing at.
1128	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
1129	* Further nesting is possible.
1130	* @param enmUnit Sample unit.
1131	* @param pszDesc Sample description.
1132	*/
1133	#define STAM_REG(pVM, pvSample, enmType, pszName, enmUnit, pszDesc) \
1134	STAM_STATS({STAM_REL_REG(pVM, pvSample, enmType, pszName, enmUnit, pszDesc);})
1135
1136	/** @def STAM_REL_REG_USED
1137	* Registers a statistics sample which only shows when used.
1138	*
1139	* @param pVM VM Handle.
1140	* @param pvSample Pointer to the sample.
1141	* @param enmType Sample type. This indicates what pvSample is pointing at.
1142	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
1143	* Further nesting is possible.
1144	* @param enmUnit Sample unit.
1145	* @param pszDesc Sample description.
1146	*/
1147	#define STAM_REL_REG_USED(pVM, pvSample, enmType, pszName, enmUnit, pszDesc) \
1148	STAM_REL_STATS({ int rcStam = STAMR3Register(pVM, pvSample, enmType, STAMVISIBILITY_USED, pszName, enmUnit, pszDesc); \
1149	AssertRC(rcStam);})
1150	/** @def STAM_REG_USED
1151	* Registers a statistics sample which only shows when used, if statistics are enabled.
1152	*
1153	* @param pVM VM Handle.
1154	* @param pvSample Pointer to the sample.
1155	* @param enmType Sample type. This indicates what pvSample is pointing at.
1156	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
1157	* Further nesting is possible.
1158	* @param enmUnit Sample unit.
1159	* @param pszDesc Sample description.
1160	*/
1161	#define STAM_REG_USED(pVM, pvSample, enmType, pszName, enmUnit, pszDesc) \
1162	STAM_STATS({ STAM_REL_REG_USED(pVM, pvSample, enmType, pszName, enmUnit, pszDesc); })
1163
1164	VMMR3DECL(int) STAMR3RegisterFU(PUVM pUVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1165	const char pszDesc, const char pszName, ...);
1166	VMMR3DECL(int) STAMR3RegisterF(PVM pVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1167	const char pszDesc, const char pszName, ...);
1168	VMMR3DECL(int) STAMR3RegisterVU(PUVM pUVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1169	const char pszDesc, const char pszName, va_list args);
1170	VMMR3DECL(int) STAMR3RegisterV(PVM pVM, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1171	const char pszDesc, const char pszName, va_list args);
1172
1173	/**
1174	* Resets the sample.
1175	* @param pVM The VM handle.
1176	* @param pvSample The sample registered using STAMR3RegisterCallback.
1177	*/
1178	typedef void FNSTAMR3CALLBACKRESET(PVM pVM, void *pvSample);
1179	/** Pointer to a STAM sample reset callback. */
1180	typedef FNSTAMR3CALLBACKRESET *PFNSTAMR3CALLBACKRESET;
1181
1182	/**
1183	* Prints the sample into the buffer.
1184	*
1185	* @param pVM The VM handle.
1186	* @param pvSample The sample registered using STAMR3RegisterCallback.
1187	* @param pszBuf The buffer to print into.
1188	* @param cchBuf The size of the buffer.
1189	*/
1190	typedef void FNSTAMR3CALLBACKPRINT(PVM pVM, void pvSample, char pszBuf, size_t cchBuf);
1191	/** Pointer to a STAM sample print callback. */
1192	typedef FNSTAMR3CALLBACKPRINT *PFNSTAMR3CALLBACKPRINT;
1193
1194	VMMR3DECL(int) STAMR3RegisterCallback(PVM pVM, void *pvSample, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1195	PFNSTAMR3CALLBACKRESET pfnReset, PFNSTAMR3CALLBACKPRINT pfnPrint,
1196	const char pszDesc, const char pszName, ...);
1197	VMMR3DECL(int) STAMR3RegisterCallbackV(PVM pVM, void *pvSample, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1198	PFNSTAMR3CALLBACKRESET pfnReset, PFNSTAMR3CALLBACKPRINT pfnPrint,
1199	const char pszDesc, const char pszName, va_list args);
1200	VMMR3DECL(int) STAMR3DeregisterU(PUVM pUVM, void *pvSample);
1201	VMMR3DECL(int) STAMR3Deregister(PVM pVM, void *pvSample);
1202
1203	/** @def STAM_REL_DEREG
1204	* Deregisters a statistics sample if statistics are enabled.
1205	*
1206	* @param pVM VM Handle.
1207	* @param pvSample Pointer to the sample.
1208	*/
1209	#define STAM_REL_DEREG(pVM, pvSample) \
1210	STAM_REL_STATS({ int rcStam = STAMR3Deregister(pVM, pvSample); AssertRC(rcStam); })
1211	/** @def STAM_DEREG
1212	* Deregisters a statistics sample if statistics are enabled.
1213	*
1214	* @param pVM VM Handle.
1215	* @param pvSample Pointer to the sample.
1216	*/
1217	#define STAM_DEREG(pVM, pvSample) \
1218	STAM_STATS({ STAM_REL_DEREG(pVM, pvSample); })
1219
1220	VMMR3DECL(int) STAMR3ResetU(PUVM pUVM, const char *pszPat);
1221	VMMR3DECL(int) STAMR3Reset(PVM pVM, const char *pszPat);
1222	VMMR3DECL(int) STAMR3SnapshotU(PUVM pUVM, const char pszPat, char ppszSnapshot, size_t pcchSnapshot, bool fWithDesc);
1223	VMMR3DECL(int) STAMR3Snapshot(PVM pVM, const char pszPat, char ppszSnapshot, size_t pcchSnapshot, bool fWithDesc);
1224	VMMR3DECL(int) STAMR3SnapshotFreeU(PUVM pUVM, char *pszSnapshot);
1225	VMMR3DECL(int) STAMR3SnapshotFree(PVM pVM, char *pszSnapshot);
1226	VMMR3DECL(int) STAMR3DumpU(PUVM pUVM, const char *pszPat);
1227	VMMR3DECL(int) STAMR3Dump(PVM pVM, const char *pszPat);
1228	VMMR3DECL(int) STAMR3DumpToReleaseLogU(PUVM pUVM, const char *pszPat);
1229	VMMR3DECL(int) STAMR3DumpToReleaseLog(PVM pVM, const char *pszPat);
1230	VMMR3DECL(int) STAMR3PrintU(PUVM pUVM, const char *pszPat);
1231	VMMR3DECL(int) STAMR3Print(PVM pVM, const char *pszPat);
1232
1233	/**
1234	* Callback function for STAMR3Enum().
1235	*
1236	* @returns non-zero to halt the enumeration.
1237	*
1238	* @param pszName The name of the sample.
1239	* @param enmType The type.
1240	* @param pvSample Pointer to the data. enmType indicates the format of this data.
1241	* @param enmUnit The unit.
1242	* @param enmVisibility The visibility.
1243	* @param pszDesc The description.
1244	* @param pvUser The pvUser argument given to STAMR3Enum().
1245	*/
1246	typedef DECLCALLBACK(int) FNSTAMR3ENUM(const char pszName, STAMTYPE enmType, void pvSample, STAMUNIT enmUnit,
1247	STAMVISIBILITY enmVisiblity, const char pszDesc, void pvUser);
1248	/** Pointer to a FNSTAMR3ENUM(). */
1249	typedef FNSTAMR3ENUM *PFNSTAMR3ENUM;
1250
1251	VMMR3DECL(int) STAMR3EnumU(PUVM pUVM, const char pszPat, PFNSTAMR3ENUM pfnEnum, void pvUser);
1252	VMMR3DECL(int) STAMR3Enum(PVM pVM, const char pszPat, PFNSTAMR3ENUM pfnEnum, void pvUser);
1253	VMMR3DECL(const char *) STAMR3GetUnit(STAMUNIT enmUnit);
1254
1255	/** @} */
1256
1257	/** @} */
1258
1259	RT_C_DECLS_END
1260
1261	#endif
1262

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

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

Download in other formats: