Extensible Counter Loading & Unloading Utilities
Design Specification and Overview
created: 15 Feb 93
a-robw
russbl
updated: 16 Nov 95
a-robw
Overview
Device driver, service and application developers that wish to provide
performance measuring capability in their software must have a way to
incorporate the names of the performance counters and counter objects
into the registry. Currently the only methods available are the manual
installation of the names into the registry or for each developer to
devise a scheme to do it programmatically. Since the "correct" way to
do this is poorly documented and difficult to explain, the following
utilities and library functions are provided to make the installation
and removal of these extensible counters much simpler and less prone
to error and confusion.
The two command line utilities provided with Windows NT are shown below.
> LodCtr MyDriver.INI
> UnLodCtr MyDriver
LoadPerf.DLL is provided to the software developer to provide access
to these same functions (in both Unicode & ANSI formats) from within
a setup program.
LoadPerfCounterTextStrings (
LPTSTR szCommandLine
BOOL bQuietModeFlag)
UnloadPerfCounterTextStrings (
LPTSTR szCommandLine,
BOOL bQuietMode)
The contents of the string arguments in the above functions are the
same as those for the command line.
The installation utility (LodCtr) accepts as an argument the name of
the device or application's counter .INI file. The format of the .INI
file is described in detail later in this document. This utility will
enter the counter names and explain text stored in the .INI file into
the corresponding data file and update the necessary keys and values
for the extensible performance counter DLL.
The removal utility UnLodCtr accepts as an argument, the name of the
regsistry key which is to have its names removed from the data files.
This key is the registry key that the application, service or device
driver us using under the ...\Services key and has the Performance
subkey.
The extensible performance counter DLL must be written to look up
the base values of the counter names and explain text during
initialization for this to function properly.
.INI file format
The .ini file for the extensible performance counter will consist
of keys and values in a format similar to that of a MS-Windows
.INI file (e.g. WIN.INI) This will allow a format that is somewhat
self-documenting as well as allow current Win32 utilities to process
it and parse the data (e.g. GetPrivateProfileString). A single file
was selected to minimize the development and maintenance overhead of
adding or modifying counters and adding foreign language support.
The contents of the .INI file are described below:
Usage Notes:
The following assumptions are made in the use of counter names and
explain text and should be followed in order to insure predictable and
reliable operation.
- Index number ranges must not be overlapping between drivers
The range of index numbers used by an extensible counter
must fall between the first and last values (see below).
(gaps are allowed within the range used). If LodCtr is used
then this won't be a problem.
- Names must be assigned to EVEN numbers and Explain text assigned
to ODD numbers.
If the convention is followed as shown in the examples below,
where each item is given an offset of an even number starting
from 0, then LodCtr will do the right thing and make this
assignment automatically. For this to work, however, the offest
values MUST ALWAYS BE EVEN NUMBERS.
- Manual assignment of counter index values is not recommended.
Failure to follow all the assumptions or manually modifying
or "hard-coding" index values may result in counter name
text corruption or erroneous display of names.
- Symbol file format must conform to the following:
#define NAME decimal_number
The symbol file processor is pretty dumb and can read .H header
files but will only understand lines that conform to the above
format. (in line comments after the number are OK) see the
example below for more information.
// Begin .INI file format
[info]
drivername=<name of device found under the CurrentControlSet\Services key>
symbolfile=<.h file containing symbolic offsets of counters>
[languages] // one key (value optional) for each language supported in file
009=
.
.
.
.
[text] // counter & explain text for customer-defined counters
offset_langid_NAME=text
offset_langid_HELP=text
// offset must be a symbolic constant (from symbolfile)
// offset value must be an even number (see code example for why)
// NAME and HELP are literal text and identify counter names or
// explain text
// langid must be listed as a key under [languages]
// text must be entered on a single line (though it can be a long one)
// end .INI file format
The .ini file must be loaded into the registry before the extensible
performance counter DLL is initialized (e.g. during or immediately
after the driver is loaded for the first time. Once the counter names
are loaded, however, they will remain until they are removed or NT is
reinstalled.
Following is an example of how the various components of an extensible
counter would incorporate the definitions of the .INI file and the use
of the LodCtr and UnLodCtr utilities. This example has one object and
two counters.
// begin devdef.H file
// legal constant definitions
#define OBJECT_1 0
#define DEVICE_COUNTER_1 2
#define DEVICE_COUNTER_2 4
// end devdef.H file
// BEGIN: Object & Counter structure initialization file
// defines static structures used to build the perf data that is
// returned by the extensible counter routines
#include "devdef.h"
MY_DEVICE_CTR_DEFINITION MyDeviceCtrDefinition = {
{ sizeof(MY_DEVICE_CTR_DEFINITION) + SIZE_OF_CTR_DATA,
sizeof(MY_DEVICE_CTR_DEFINITION),
sizeof(PERF_OBJECT_TYPE),
OBJECT_1,
0,
OBJECT_1,
0,
PERF_DETAIL_ADVANCED,
(sizeof(MY_DEVICE_CTR_DEFINITION-sizeof(PERF_OBJECT_TYPE))/
sizeof(PERF_COUNTER_DEFINITION),
1,
0,
0
},
{ sizeof(PERF_COUNTER_DEFINITION),
DEVICE_COUNTER_1,
0,
DEVICE_COUNTER_1,
0,
0,
PERF_DETAIL_ADVANCED,
PERF_COUNTER_COUNTER,
sizeof(DWORD),
DEVICE_COUNTER_1_DATA_OFFSET
},
{ sizeof(PERF_COUNTER_DEFINITION),
DEVICE_COUNTER_2,
0,
DEVICE_COUNTER_2,
0,
0,
PERF_DETAIL_ADVANCED,
PERF_COUNTER_COUNTER,
sizeof(DWORD),
DEVICE_COUNTER_2_DATA_OFFSET,
}
};
// END: Object & Counter structure initialization file
// begin .INI file example
[info]
drivername=DriverName
symbolfile=devdef.h
[languages]
009=English
00C=OtherLanguage
[text]
OBJECT_1_009_NAME=Device Name
OBJECT_1_009_HELP=Displays performance statistics on Device Name
OBJECT_1_00C_NAME=Device Name in other language
OBJECT_1_00C_HELP=Displays performance of Device Name in other language
DEVICE_COUNTER_1_009_NAME=Counter A
DEVICE_COUNTER_1_009_HELP=Displays the current value of Counter A
DEVICE_COUNTER_1_00C_NAME=Counter A in other language
DEVICE_COUNTER_1_00C_HELP=Displays the value of Counter A in other language
DEVICE_COUNTER_2_009_NAME=Counter B
DEVICE_COUNTER_2_009_HELP=Displays the current rate of Devices B
DEVICE_COUNTER_2_00C_NAME=Counter B in other language
DEVICE_COUNTER_2_00C_HELP=Displays the rate of Device B in other language
// end .INI file
OpenPerformanceData ( ... args ... )
{
.
.
.
// execute this code before accessing or passing any perf. data
// objects.
status = RegOpenKeyEx (
HKEY_LOCAL_MACHINE,
"\\System\\CurrentControlSet\\Service\\DriverName\\Performance",
NULL,
SAM,
&hKeyDriverPerf);
size = sizeof (DWORD);
Status = RegQueryValueEx (
hKeyDriverPerf,
"First Counter"
0L,
&type,
(LPBYTE)&dwFirstCounter,
&size);
size = sizeof (DWORD);
Status = RegQueryValueEx(
hKeyDriverPerf,
"First Help"
0L,
&type,
(LPBYTE)&dwFirstHelp,
&size);
//
// NOTE: the initialization program could also retrieve
// LastCounter and LastHelp if they wanted to do
// bounds checking on the new number. e.g.
//
// counter->CounterNameTitleIndex += dwFirstCounter;
// if (counter->CounterNameTitleIndex > dwLastCounter) {
// LogErrorToEventLog (INDEX_OUT_OF_BOUNDS);
// }
For each counter object {
Object->ObjectNameTitleIndex += dwFirstCounter;
Object->ObjectHelpTitleIndex += dwFirstHelp;
for each counter definition in the object {
counter->CounterNameTitleIndex += dwFirstCounter;
counter->CounterHelpTitleIndex += dwFirstHelp;
}
}
RegCloseKey (hKeyDriverPerf);
.
.
.
}
When LodCtr has loaded the contents of the .INI file the following
registry keys will have been updated. The ":" indicates a Value of
a Key; other symbols are keys in the registry.
MACHINE
SYSTEM
CurrentControlSet
Services
<devicename>
Performance
:First Counter (updated to show current value)
:First Help (updated to show current value)
:Last Counter (updated to show current value)
:Last Help (updated to show current value)
MACHINE
SOFTWARE
Microsoft
Windows NT
CurrentVersion
Perflib
:Last Counter (updated to show current value)
:Last Help (updated to show current value)
After UnLodCtr is run to remove a driver's counters from the data file,
the following changes to the registry will take place
MACHINE
SYSTEM
CurrentControlSet
Services
<devicename>
Performance
:First Counter (value deleted)
:First Help (value deleted)
:Last Counter (value deleted)
:Last Help (value deleted)
MACHINE
SOFTWARE
Microsoft
Windows NT
CurrentVersion
Perflib
:Last Counter (updated to show current value)
:Last Help (updated to show current value)