VirtualBox

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

Last change on this file since 5999 was 5999, checked in by vboxsync, 17 years ago

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette