stam.h@ 57569

Last change on this file since 57569 was 57569, checked in by vboxsync, 9 years ago
stam.h: revert r102388.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 42.4 KB

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

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

source: vbox/trunk/include/VBox/vmm/stam.h@ 57569

Download in other formats: