VirtualBox

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

Last change on this file since 3291 was 2981, checked in by vboxsync, 18 years ago

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