stam.h revision 590bfe12ce22cd3716448fbb9f4dc51664bfe5e2
98N/A * STAM - Statistics Manager. 851N/A * Copyright (C) 2006-2007 Sun Microsystems, Inc. 98N/A * This file is part of VirtualBox Open Source Edition (OSE), as 98N/A * you can redistribute it and/or modify it under the terms of the GNU 98N/A * General Public License (GPL) as published by the Free Software 98N/A * Foundation, in version 2 as it comes in the "COPYING" file of the 98N/A * VirtualBox OSE distribution. VirtualBox OSE is distributed in the 98N/A * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. 98N/A * The contents of this file may alternatively be used under the terms 98N/A * of the Common Development and Distribution License Version 1.0 98N/A * (CDDL) only, as it comes in the "COPYING.CDDL" file of the 98N/A * VirtualBox OSE distribution, in which case the provisions of the 98N/A * CDDL are applicable instead of those of the GPL. 98N/A * You may elect to license modified versions of this file under the 98N/A * terms and conditions of either the GPL or the CDDL or both. 98N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa 98N/A * additional information or have any questions. 911N/A/** @defgroup grp_stam The Statistics Manager API 98N/A#
error "Both VBOX_WITHOUT_RELEASE_STATISTICS and VBOX_WITH_STATISTICS are defined! Make up your mind!" 98N/A/** @def STAM_GET_TS 493N/A * Gets the CPU timestamp counter. 98N/A * @param u64 The 64-bit variable which the timestamp shall be saved in. 112N/A /* This produces optimal assembler code for x86 but does not work for AMD64 ('A' means 'either rax or rdx') */ * Code for inclusion only when VBOX_WITH_STATISTICS is defined. * @param code A code block enclosed in {}. * Code for inclusion only when VBOX_WITH_STATISTICS is defined. * @param code A code block enclosed in {}. /** Profiling of an function. */ /** Profiling of an operation. */ /** Ratio of A to B, uint32_t types. Not reset. */ /** Ratio of A to B, uint32_t types. Reset both to 0. */ /** Generic unsigned 8-bit value. Not reset. */ /** Generic unsigned 8-bit value. Reset to 0. */ /** Generic hexadecimal unsigned 8-bit value. Not reset. */ /** Generic hexadecimal unsigned 8-bit value. Reset to 0. */ /** Generic unsigned 16-bit value. Not reset. */ /** Generic unsigned 16-bit value. Reset to 0. */ /** Generic hexadecimal unsigned 16-bit value. Not reset. */ /** Generic hexadecimal unsigned 16-bit value. Reset to 0. */ /** Generic unsigned 32-bit value. Not reset. */ /** Generic unsigned 32-bit value. Reset to 0. */ /** Generic hexadecimal unsigned 32-bit value. Not reset. */ /** Generic hexadecimal unsigned 32-bit value. Reset to 0. */ /** Generic unsigned 64-bit value. Not reset. */ /** Generic unsigned 64-bit value. Reset to 0. */ /** Generic hexadecimal unsigned 64-bit value. Not reset. */ /** Generic hexadecimal unsigned 64-bit value. Reset to 0. */ /** The end (exclusive). */ * Sample visibility type. /** Only visible when used (/hit). */ /** Not visible in the GUI. */ /** The end (exclusive). */ /** Count of whatever. */ /** Number of occurences. */ /** Ticks per occurence. */ /** Ratio of good vs. bad. */ /** Nanoseconds per call. */ /** Nanoseconds per call. */ /** The end (exclusive). */ * Increments a uint8_t sample by one. * @param pCounter Pointer to the uint8_t variable to operate on. * Increments a uint8_t sample by one. * @param pCounter Pointer to the uint8_t variable to operate on. * Decrements a uint8_t sample by one. * @param pCounter Pointer to the uint8_t variable to operate on. * Decrements a uint8_t sample by one. * @param pCounter Pointer to the uint8_t variable to operate on. * Increments a uint8_t sample by a value. * @param pCounter Pointer to the uint8_t variable to operate on. * @param Addend The value to add. * Increments a uint8_t sample by a value. * @param pCounter Pointer to the uint8_t variable to operate on. * @param Addend The value to add. /** @def STAM_REL_U16_INC * Increments a uint16_t sample by one. * @param pCounter Pointer to the uint16_t variable to operate on. * Increments a uint16_t sample by one. * @param pCounter Pointer to the uint16_t variable to operate on. /** @def STAM_REL_U16_DEC * Decrements a uint16_t sample by one. * @param pCounter Pointer to the uint16_t variable to operate on. * Decrements a uint16_t sample by one. * @param pCounter Pointer to the uint16_t variable to operate on. /** @def STAM_REL_U16_INC * Increments a uint16_t sample by a value. * @param pCounter Pointer to the uint16_t variable to operate on. * @param Addend The value to add. * Increments a uint16_t sample by a value. * @param pCounter Pointer to the uint16_t variable to operate on. * @param Addend The value to add. /** @def STAM_REL_U32_INC * Increments a uint32_t sample by one. * @param pCounter Pointer to the uint32_t variable to operate on. * Increments a uint32_t sample by one. * @param pCounter Pointer to the uint32_t variable to operate on. /** @def STAM_REL_U32_DEC * Decrements a uint32_t sample by one. * @param pCounter Pointer to the uint32_t variable to operate on. * Decrements a uint32_t sample by one. * @param pCounter Pointer to the uint32_t variable to operate on. /** @def STAM_REL_U32_ADD * Increments a uint32_t sample by value. * @param pCounter Pointer to the uint32_t variable to operate on. * @param Addend The value to add. * Increments a uint32_t sample by value. * @param pCounter Pointer to the uint32_t variable to operate on. * @param Addend The value to add. /** @def STAM_REL_U64_INC * Increments a uint64_t sample by one. * @param pCounter Pointer to the uint64_t variable to operate on. * Increments a uint64_t sample by one. * @param pCounter Pointer to the uint64_t variable to operate on. /** @def STAM_REL_U64_DEC * Decrements a uint64_t sample by one. * @param pCounter Pointer to the uint64_t variable to operate on. * Decrements a uint64_t sample by one. * @param pCounter Pointer to the uint64_t variable to operate on. /** @def STAM_REL_U64_ADD * Increments a uint64_t sample by a value. * @param pCounter Pointer to the uint64_t variable to operate on. * @param Addend The value to add. * Increments a uint64_t sample by a value. * @param pCounter Pointer to the uint64_t variable to operate on. * @param Addend The value to add. * Counter sample - STAMTYPE_COUNTER. /** The current count. */ /** Pointer to a counter. */ /** Pointer to a const counter. */ /** @def STAM_REL_COUNTER_INC * Increments a counter sample by one. * @param pCounter Pointer to the STAMCOUNTER structure to operate on. /** @def STAM_COUNTER_INC * Increments a counter sample by one. * @param pCounter Pointer to the STAMCOUNTER structure to operate on. /** @def STAM_REL_COUNTER_DEC * Decrements a counter sample by one. * @param pCounter Pointer to the STAMCOUNTER structure to operate on. /** @def STAM_COUNTER_DEC * Decrements a counter sample by one. * @param pCounter Pointer to the STAMCOUNTER structure to operate on. /** @def STAM_REL_COUNTER_ADD * Increments a counter sample by a value. * @param pCounter Pointer to the STAMCOUNTER structure to operate on. * @param Addend The value to add to the counter. /** @def STAM_COUNTER_ADD * Increments a counter sample by a value. * @param pCounter Pointer to the STAMCOUNTER structure to operate on. * @param Addend The value to add to the counter. /** @def STAM_REL_COUNTER_RESET * Resets the statistics sample. /** @def STAM_COUNTER_RESET * Resets the statistics sample. * Profiling sample - STAMTYPE_PROFILE. /** Number of periods. */ /** Total count of ticks. */ /** Maximum tick count during a sampling. */ /** Minimum tick count during a sampling. */ /** Pointer to a profile sample. */ /** Pointer to a const profile sample. */ /** @def STAM_REL_PROFILE_START * Samples the start time of a profiling period. * @param pProfile Pointer to the STAMPROFILE structure to operate on. * @param Prefix Identifier prefix used to internal variables. /** @def STAM_PROFILE_START * Samples the start time of a profiling period. * @param pProfile Pointer to the STAMPROFILE structure to operate on. * @param Prefix Identifier prefix used to internal variables. /** @def STAM_REL_PROFILE_STOP * Samples the stop time of a profiling period and updates the sample. * @param pProfile Pointer to the STAMPROFILE structure to operate on. * @param Prefix Identifier prefix used to internal variables. /** @def STAM_PROFILE_STOP * Samples the stop time of a profiling period and updates the sample. * @param pProfile Pointer to the STAMPROFILE structure to operate on. * @param Prefix Identifier prefix used to internal variables. /** @def STAM_REL_PROFILE_STOP_EX * Samples the stop time of a profiling period and updates both the sample * and an attribution sample. * @param pProfile Pointer to the STAMPROFILE structure to operate on. * @param pProfile2 Pointer to the STAMPROFILE structure which this * interval should be attributed to as well. This may be NULL. * @param Prefix Identifier prefix used to internal variables. /** @def STAM_PROFILE_STOP_EX * Samples the stop time of a profiling period and updates both the sample * and an attribution sample. * @param pProfile Pointer to the STAMPROFILE structure to operate on. * @param pProfile2 Pointer to the STAMPROFILE structure which this * interval should be attributed to as well. This may be NULL. * @param Prefix Identifier prefix used to internal variables. * Advanced profiling sample - STAMTYPE_PROFILE_ADV. * Identical to a STAMPROFILE sample, but the start timestamp * is stored after the STAMPROFILE structure so the sampling * can start and stop in different functions. /** The STAMPROFILE core. */ /** The start timestamp. */ /** Pointer to a advanced profile sample. */ /** Pointer to a const advanced profile sample. */ /** @def STAM_REL_PROFILE_ADV_START * Samples the start time of a profiling period. * @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on. * @param Prefix Identifier prefix used to internal variables. /** @def STAM_PROFILE_ADV_START * Samples the start time of a profiling period. * @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on. * @param Prefix Identifier prefix used to internal variables. /** @def STAM_REL_PROFILE_ADV_STOP * Samples the stop time of a profiling period and updates the sample. * @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on. * @param Prefix Identifier prefix used to internal variables. /** @def STAM_PROFILE_ADV_STOP * Samples the stop time of a profiling period and updates the sample. * @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on. * @param Prefix Identifier prefix used to internal variables. /** @def STAM_REL_PROFILE_ADV_SUSPEND * Suspends the sampling for a while. This can be useful to exclude parts * covered by other samples without screwing up the count, and average+min times. * @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on. * @param Prefix Identifier prefix used to internal variables. The prefix * must match that of the resume one since it stores the * suspend time in a stack variable. /** @def STAM_PROFILE_ADV_SUSPEND * Suspends the sampling for a while. This can be useful to exclude parts * covered by other samples without screwing up the count, and average+min times. * @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on. * @param Prefix Identifier prefix used to internal variables. The prefix * must match that of the resume one since it stores the * suspend time in a stack variable. /** @def STAM_REL_PROFILE_ADV_RESUME * Counter to STAM_REL_PROFILE_ADV_SUSPEND. * @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on. * @param Prefix Identifier prefix used to internal variables. This must * match the one used with the SUSPEND! /** @def STAM_PROFILE_ADV_RESUME * Counter to STAM_PROFILE_ADV_SUSPEND. * @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on. * @param Prefix Identifier prefix used to internal variables. This must * match the one used with the SUSPEND! /** @def STAM_REL_PROFILE_ADV_STOP_EX * Samples the stop time of a profiling period and updates both the sample * and an attribution sample. * @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on. * @param pProfile2 Pointer to the STAMPROFILE structure which this * interval should be attributed to as well. This may be NULL. * @param Prefix Identifier prefix used to internal variables. /** @def STAM_PROFILE_ADV_STOP_EX * Samples the stop time of a profiling period and updates both the sample * and an attribution sample. * @param pProfileAdv Pointer to the STAMPROFILEADV structure to operate on. * @param pProfile2 Pointer to the STAMPROFILE structure which this * interval should be attributed to as well. This may be NULL. * @param Prefix Identifier prefix used to internal variables. * Ratio of A to B, uint32_t types. * @remark Use STAM_STATS or STAM_REL_STATS for modifying A & B values. /** Pointer to a uint32_t ratio. */ /** Pointer to const a uint32_t ratio. */ /** @defgroup grp_stam_r3 The STAM Host Context Ring 3 API * Registers a statistics sample. * @param pvSample Pointer to the sample. * @param enmType Sample type. This indicates what pvSample is pointing at. * @param pszName Sample name. The name is on this form "/<component>/<sample>". * Further nesting is possible. * @param enmUnit Sample unit. * @param pszDesc Sample description. * Registers a statistics sample if statistics are enabled. * @param pvSample Pointer to the sample. * @param enmType Sample type. This indicates what pvSample is pointing at. * @param pszName Sample name. The name is on this form "/<component>/<sample>". * Further nesting is possible. * @param enmUnit Sample unit. * @param pszDesc Sample description. /** @def STAM_REL_REG_USED * Registers a statistics sample which only shows when used. * @param pvSample Pointer to the sample. * @param enmType Sample type. This indicates what pvSample is pointing at. * @param pszName Sample name. The name is on this form "/<component>/<sample>". * Further nesting is possible. * @param enmUnit Sample unit. * @param pszDesc Sample description. * Registers a statistics sample which only shows when used, if statistics are enabled. * @param pvSample Pointer to the sample. * @param enmType Sample type. This indicates what pvSample is pointing at. * @param pszName Sample name. The name is on this form "/<component>/<sample>". * Further nesting is possible. * @param enmUnit Sample unit. * @param pszDesc Sample description. * @param pVM The VM handle. * @param pvSample The sample registered using STAMR3RegisterCallback. /** Pointer to a STAM sample reset callback. */ * Prints the sample into the buffer. * @param pVM The VM handle. * @param pvSample The sample registered using STAMR3RegisterCallback. * @param pszBuf The buffer to print into. * @param cchBuf The size of the buffer. /** Pointer to a STAM sample print callback. */ * Deregisters a statistics sample if statistics are enabled. * @param pvSample Pointer to the sample. * Deregisters a statistics sample if statistics are enabled. * @param pvSample Pointer to the sample. * Callback function for STAMR3Enum(). * @returns non-zero to halt the enumeration. * @param pszName The name of the sample. * @param enmType The type. * @param pvSample Pointer to the data. enmType indicates the format of this data. * @param enmUnit The unit. * @param enmVisibility The visibility. * @param pszDesc The description. * @param pvUser The pvUser argument given to STAMR3Enum(). /** Pointer to a FNSTAMR3ENUM(). */