stam.h@ 64879

Last change on this file since 64879 was 62634, checked in by vboxsync, 8 years ago
includes: Workaround for C4668 & C4255 warnings in MSC and WDK headers.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 42.8 KB

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

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

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

Download in other formats: