VirtualBox

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

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

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