VirtualBox

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

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

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