home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / perf.h < prev    next >
Text File  |  1998-04-25  |  11KB  |  303 lines
  1.  
  2. /*****************************************************************************
  3.  *
  4.  *   (C) Copyright MICROSOFT Corp., 1988-1990
  5.  *
  6.  *   Title:     PERF.H - Include file for perf monitor
  7.  *
  8.  *   Version:   1.00
  9.  *
  10.  *   Date:
  11.  *
  12.  *   Author:    FCF
  13.  *
  14.  *-----------------------------------------------------------------------------
  15.  *
  16.  *   Change log:
  17.  *
  18.  *   DATE        REV DESCRIPTION
  19.  *   ----------- --- -----------------------------------------------------------
  20.  */
  21.  
  22. /*  See dos\dos386\vxd\perf\example for a sample VxD that registers as */
  23. /*  a perf server.                                                     */
  24.  
  25. /* defines */
  26.  
  27. #define MAXNAMELEN            50    /* maximum number of characters in
  28.                                    service name, stat name, or key names */
  29. #define MAXCOMPLEXSUBSTAT    8    /* maximum number of stats making
  30.                                    up a complex stat */
  31.     
  32. /* structures and flags used for the ring-0 interface */
  33.  
  34. struct perf_server_0 {
  35.     unsigned long    psrv0_Level;    /* Must be zero for this level */
  36.     unsigned long    psrv0_Flags;
  37.     char            *psrv0_pszServerName;
  38.     char           *psrv0_pszServerNodeName;
  39.     void           *psrv0_pControlFunc;
  40. };
  41.  
  42. struct perf_stat_0 {
  43.     unsigned long    pst0_Level;    /* Must be zero for this level */
  44.     unsigned long    pst0_Flags;
  45.     char           *pst0_pszStatName;
  46.     char           *pst0_pszStatNodeName;
  47.     char           *pst0_pszStatUnitName;
  48.     char           *pst0_pszStatDescription;
  49.     void           *pst0_pStatFunc;
  50. };
  51.  
  52. /* Values for psrv0_Flags follow */
  53.  
  54. /* Values for pst0_Flags follow */
  55.  
  56. /* pst0_pStatFunc points either directly to data (always a DWORD for now) */
  57. /* or, if PSTF_FUNCPTR_BIT is set, to a _cdecl function.  This function   */
  58. /* accepts a stat handle as it's argument and returns the stat in eax     */
  59.  
  60. #define PSTF_FUNCPTR        0x00000001
  61.  
  62. /* The data referenced by this stat is always a counter, e.g. number of   */
  63. /* bytes read.  It is up to the client to differentiate this into a rate. */
  64. /* If PSTF_RATE is set, then the text associated with this stat assumes   */
  65. /* that the stat will be differentiated with respect to time.  It's       */
  66. /* possible that two stats will refer to the same data - one with this    */
  67. /* bit set and one without, with help text appropriate for each.          */
  68.  
  69. #define PSTF_COUNT        0x00000000
  70. #define PSTF_RATE        0x00000002
  71.  
  72. /* A recommendation as to the frequency of update.  Bytes read/second     */
  73. /* can change quite rapidly, but updating # of shares will not change     */
  74. /* as often, and (currently) vcache cache size is static.  Perf clients   */
  75. /* are free to ignore these values, and free to define update frequency.  */
  76.  
  77. #define PSTF_FREQ_HIGH        0x00000000
  78. #define PSTF_FREQ_LOW        0x00000004
  79. #define PSTF_FREQ_STATIC    0x00000008
  80. #define PSTF_FREQ_MASK        (PSTF_FREQ_STATIC | PSTF_FREQ_LOW |    \
  81.                  PSTF_FREQ_HIGH)
  82.  
  83.  
  84. /* A recommendation as to the scale type.  Bytes read/second may be more  */
  85. /* appropriately displayed on a log10 scale, while memory available might */
  86. /* be better on a linear scale.  Perf clients are free to ignore this.    */
  87.  
  88. #define PSTF_SCALE_LINEAR    0x00000000
  89. #define PSTF_SCALE_LOG10    0x00000010
  90. #define PSTF_SCALE_LOG2        0x00000020
  91. #define PSTF_SCALE_MASK        (PSTF_SCALE_LINEAR | PSTF_SCALE_LOG10 | \
  92.                  PSTF_SCALE_LOG2)
  93.  
  94. /* XLATOFF */
  95.  
  96. unsigned long PERF_Server_Register( struct perf_server_0 * );
  97. void PERF_Server_Deregister( unsigned long hReg );
  98. unsigned long PERF_Server_Add_Stat( unsigned long hReg, struct perf_stat_0 );
  99. void PERF_Server_Remove_Stat( unsigned long hStat );
  100.  
  101. /* XLATON */
  102.  
  103. /* Control messages sent to perf server's control function.  The control */
  104. /* function is optional, set it to NULL if you don't want any control    */
  105. /* messages.  Perf servers are free to ignore any messages they want.    */
  106. /* Control functions take two DWORD parameters; a message (dwMsg) and a  */
  107. /* DWORD of message-dependent data (dwData).                              */
  108.  
  109. /* The following defines are values for dwMsg:                             */
  110. #define PMSG_START_STAT                0x11
  111. #define PMSG_STOP_STAT                0x12
  112.  
  113. /* PMSG_START_STAT: Notifies that a perf client is going to start        */
  114. /*     watching this stat.  dwData contains the stat handle.             */
  115. /* PMSG_STOP_STAT: Notifies that a perf client is no longer              */
  116. /*     watching this stat.  dwData contains the stat handle.             */
  117. /* Stats which are expensive to maintain should only be kept while some- */
  118. /* one is watching them.  Note that there can be more than one stat      */
  119. /* client, so don't just stop keeping track of a stat if you receive     */
  120. /* a PMSG_STOP_STAT.  The server should keep a counter of the number     */
  121. /* of PMSG_START_STAT's it receives for a particular counter, decrement  */
  122. /* it for each PMSG_STOP_STAT and stop keeping track of the stat when the*/
  123. /* counter reaches zero.                                                 */
  124. /* Most stats are trivial to maintain and just involve incrementing a    */
  125. /* counter.  For stats like these, perf servers should always increment  */
  126. /* the counter and ignore messages to start and stop.                    */
  127.  
  128.  
  129. /* IOCTL apis understood by perf (from ring 3 client) */
  130.  
  131. #define IOCTL_PERF_GET_STATS        0x10
  132. #define IOCTL_PERF_START_STAT        0x11
  133. #define IOCTL_PERF_STOP_STAT        0x12
  134. /* On entry to the IOCTL_PERF_GET_STATS ioctl:
  135.     lpvInBuffer     pointer to array of DWORD stat handles
  136.     cbInBuffer        size of array, in bytes
  137.     lpvOutBuffer    pointer to result array (can be same as lpvInBuffer)
  138.     cbOutBuffer        size of destination array
  139. */
  140.  
  141. /* ASM
  142.  
  143. ; Ring-0 macros to aid stat registration
  144.  
  145. Reg_Perf_Srv MACRO level:REQ, flags:REQ, servername:REQ, nodename:REQ, controlfunc:REQ
  146.     local    nothere
  147.     VxDcall    PERF_Get_Version
  148.     or    eax, eax
  149.     jz    nothere
  150.  
  151.     IF (OPATTR(controlfunc)) AND 00010000y     ;; register
  152.         push    controlfunc
  153.     ELSE
  154.         push    OFFSET32 controlfunc
  155.     ENDIF
  156.  
  157.     IF (OPATTR(nodename)) AND 00010000y        ;; register
  158.         push    nodename
  159.     ELSE
  160.         push    OFFSET32 nodename
  161.     ENDIF
  162.  
  163.     IF (OPATTR(servername)) AND 00010000y        ;; register
  164.         push    servername
  165.     ELSE
  166.         push    OFFSET32 servername
  167.     ENDIF
  168.     
  169.     push    flags
  170.         push    level
  171.     push    esp
  172.     VxDcall    PERF_Server_Register
  173.     add    esp, 6*4
  174. nothere:
  175.     ENDM
  176.  
  177. Reg_Perf_Stat MACRO srvhandle:REQ, level:REQ, flags:REQ, name:REQ, nodename:REQ, unitname:REQ, desc:REQ, func:REQ
  178.     IF (OPATTR(func)) AND 00010000y        ;; register
  179.         push    func
  180.     ELSE
  181.         push    OFFSET32 func
  182.     ENDIF
  183.  
  184.     IF (OPATTR(desc)) AND 00010000y        ;; register
  185.         push    desc
  186.     ELSE
  187.         push    OFFSET32 desc
  188.     ENDIF
  189.  
  190.     IF (OPATTR(unitname)) AND 00010000y    ;; register
  191.         push    unitname
  192.     ELSE
  193.         push    OFFSET32 unitname
  194.     ENDIF
  195.  
  196.     IF (OPATTR(nodename)) AND 00010000y    ;; register
  197.         push    nodename
  198.     ELSE
  199.         push    OFFSET32 nodename
  200.     ENDIF
  201.  
  202.     IF (OPATTR(name)) AND 00010000y        ;; register
  203.         push    name
  204.     ELSE
  205.         push    OFFSET32 name
  206.     ENDIF
  207.     
  208.     push    flags
  209.     push    level
  210.     push    esp
  211.     push    srvhandle
  212.     VxDcall    PERF_Server_Add_Stat
  213.     add    esp, 9*4
  214.     ENDM
  215.  
  216. Begin_Service_Table PERF
  217. PERF_Service PERF_Get_Version, LOCAL
  218. PERF_Service PERF_Server_Register, LOCAL
  219. PERF_Service PERF_Server_Deregister, LOCAL
  220. PERF_Service PERF_Server_Add_Stat, LOCAL
  221. PERF_Service PERF_Server_Remove_Stat, LOCAL
  222. End_Service_Table PERF
  223.  
  224. */
  225.  
  226. /* Registry constants follow.  A sample perf registry tree might look like
  227.    this:
  228.  
  229. HKEY_LOCAL_MACHINE\STATS\VFAT            
  230.               NAME="32-bit file system"
  231.                  \READS
  232.                +---    NAME="Reads per second"
  233.                |       HANDLE=<4 byte binary value>
  234.           Required |       DESCRIPTION="The number of file read requests
  235.                |                    per second"
  236.                |       VALUE=<some dynamic registry identifier>
  237.                +---    DIFFERENTIATE="TRUE"
  238.  
  239.                +---    MIBID="1.3.4.7.3"
  240.                |       STARTSCALE=1000
  241.           Optional |       FREQUENCY="HIGH"
  242.                +---    SCALETYPE="LOG10"
  243.  
  244. */
  245.  
  246. #define HKEY_PERF_ROOT            HKEY_LOCAL_MACHINE
  247. #define PERF_REG_KEY            "STATS"
  248. #define PERF_REG_NAME_SRV_NAME        "NAME"
  249. #define PERF_REG_NAME_STAT_NAME        "NAME"
  250. #define PERF_REG_NAME_STAT_FREQ        "FREQUENCY"
  251. #define PERF_REG_NAME_STAT_HANDLE    "HANDLE"
  252. #define PERF_REG_NAME_STAT_DESC        "DESCRIPTION"
  253. #define PERF_REG_NAME_STAT_VALUE    "VALUE"
  254. #define PERF_REG_NAME_STAT_DIFF        "DIFFERENTIATE"
  255. #define PERF_REG_NAME_STAT_SCALETYPE    "SCALETYPE"
  256. #define PERF_REG_NAME_STAT_STARTSCALE    "STARTSCALE"
  257.  
  258. #define PERF_REG_VAL_STAT_TRUE        "TRUE"
  259. #define PERF_REG_VAL_STAT_FALSE        "FALSE"
  260. #define PERF_REG_VAL_STAT_HIGH        "HIGH"
  261. #define PERF_REG_VAL_STAT_LOW        "LOW"
  262. #define PERF_REG_VAL_STAT_LINEAR    "LINEAR"
  263. #define PERF_REG_VAL_STAT_LOG10        "LOG10"
  264. #define PERF_STAT_PREFIX            "STAT"
  265.  
  266. /* complex stat defines */
  267.  
  268. #define PSTF_INT_COMPLEX    0x00000010
  269. #define PSTF_EXT_COMPLEX    0x00000020
  270. /* A complex statistic has no data value of its own-- it just defines two */
  271. /* or more regular stats that may be added together to appear as a single */
  272. /* value in the UI.  For example: VFAT->bytes written/sec and VFAT->bytes */
  273. /* read/sec are simplex (normal) stats that each have a data counter.     */
  274. /* VFAT->total bytes/sec is a complex stat made up of those two simplex   */
  275. /* stats.  When the UI wants to display a complex stat's value, it gets   */
  276. /* the data value for the simplex stats contained in it and adds those    */
  277. /* values together.  To define a complex stat, set either PSTF_INT_COMPLEX*/
  278. /* or PSTF_EXT_COMPLEX when registering the stat.  The pst0_pStatFunc     */
  279. /* member should be set to point at a table of pointers to strings        */
  280. /* containing the registry key names of the simplex stats.  The pointer   */
  281. /* table should be null-terminated.  If PSTF_INT_COMPLEX is set, all      */
  282. /* stats must be internal to the VxD.  If PST_EXT_COMPLEX, the stats can  */
  283. /* be from other VxDs (including the one registering the complex stat).   */
  284. /* For internal complex stats, the key names in the table are the same      */
  285. /* as the key names used to register the stat.  For example: VFAT         */
  286. /* registers itself with the "VFAT" key name, and registers two simple    */
  287. /* stats with "BReadSec" and "BWriteSec" key names.  It then registers a  */
  288. /* complex stat with a "BTotSec" key name, where the pst0_pStatFunc          */
  289. /* points to a table of pointers; the first pointer would point to        */
  290. /* "BReadSec", the next pointer in the table would point to "BWriteSec",  */
  291. /* and the next pointer would be NULL to signifiy the end of the list.    */
  292. /* This is convenient because the "BReadSec" string already exists.  If   */
  293. /* PSTF_EXT_COMPLEX is set, the strings that the pointer table points to  */
  294. /* also have to contain the registry key name of the VxD which registered */
  295. /* them.  In the above example, if VFAT were to set the PSTF_EXT_COMPLEX  */
  296. /* flag the strings pointed to by the table would have to be              */
  297. /* "VFAT\BReadSec" and "VFAT\BWriteSec".  The advantage of setting this   */
  298. /* flag is that you can specify external stats, like "NDIS\PacketsSec".   */
  299.  
  300. /* This is complicated to explain, but very easy to do.                   */
  301. /* See dos\dos386\vxd\perf\example\example.asm for an example of how to   */
  302. /* register a complex stat.                                               */
  303.