stam.h@ 76558

Last change on this file since 76558 was 76558, checked in by vboxsync, 6 years ago
include/VBox: Use VBOX_INCLUDED_ rather than _vbox_ as header guard prefix, letting scm enforce this (thereby avoiding copy&paste errors like NativeEventQueue.h).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 43.7 KB

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

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

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

Download in other formats: