VirtualBox

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

Last change on this file since 1 was 1, checked in by vboxsync, 55 years ago

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