VirtualBox

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

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

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