CTRPP
The CTRPP tool is a pre-processor that parses and validates the manifest for your V2 provider. The tool generates .rc
resources with the strings needed by consumers of your provider, and it generates a .h
header with code that you use to provide your counter data. You should run the CTRPP tool during the build of your provider. You should use the generated code as a starting point when developing your provider instead of trying to generate this code yourself.
ctrpp -o codeFile -rc rcFile [-legacy] [-MemoryRoutines] [-NotificationCallback] [-prefix prefix] [-ch symFile] [-backcompat] inputFile
Option | Description |
---|---|
inputFile | Required: Specifies the name of the .man (XML manifest) file that defines your counters. |
-o codeFile | Required: Specifies the name of the .h code file to be generated by CTRPP. This file will contain C/C++ inline helper functions that simplify initializing and uninitializing your provider. |
-rc rcFile | Required: Specifies the name of the .rc (resource file) to be generated by CTRPP. This file will contain the provider's string table. |
-ch symFile | Specifies the name of the optional .h symbol file to be generated by CTRPP. This file will contain C/C++ symbols for the names and GUIDs of each counterset in the provider. |
-prefix prefix | Specifies the prefix to use for the variables and functions defined in the generated header file. |
-NotificationCallback | Changes the default signature of the CounterInitialize function to include parameters for specifying the name of ControlCallback, AllocateMemory, and FreeMemory callback functions. This argument has the same effect as including the callback attribute in the provider element. |
-migrate outputFile | Instead of generating .h and .rc files, upgrades the inputFile manifest to the latest version and saves it to outputFile. This switch cannot be used with other switches. Usage: CTRPP -migrate NewFile.man OldFile.man |
-BackCompat | Deprecated: Support for kernel-mode providers was added in Windows 7. By default, the code generated by CTRPP for kernel-mode providers will be incompatible with earlier versions of Windows (driver will fail to load due to missing Pcw*** APIs). Set -BackCompat to enable compatibility with earlier versions of Windows. The driver will dynamically load the necessary APIs and the generated code will silently disable the provider if the APIs are not available. |
-MemoryRoutines | Deprecated: When used with the -Legacy switch, includes templates for memory routines in the generated code. Otherwise, this argument has the same effect as the -NotificationCallback switch. |
-Legacy | Deprecated: Generates *.h , *.c , *.rc , and *_r.h files using the Windows Vista code templates (generates PerfAutoInitialize and PerfAutoCleanup instead of CounterInitialize and CounterCleanup). This switch can be used with -MemoryRoutines and -NotificationCallback but cannot be used with any other switches. Do not use the -o or -rc switches with this switch. The generated files will be named based on the name of the manifest and will be written to the directory that contained the manifest. Usage: CTRPP -legacy OldFile.man |
The CTRPP tool generates a .h
code file, an .rc
resource file, and optionally generates a .h
symbol file.
The CTRPP tool will generate a .rc
resource file that contains the localizable strings needed by consumers of the provider's countersets.
Important
The resources from this file must be included into your provider binary and the full path to the provider binary must be registered during the installation of your provider's manifest. Consumers that are unable to locate and load the resources will be unable to use your provider's countersets.
The string resources should be handled as follows:
- The developer edits the provider manifest (
.man
) file to set theapplicationIdentity
attribute of the provider to the name of a provider binary (.DLL, .SYS, or .EXE) that will contain the string resources for the provider and will be installed as part of the provider component. - The CTRPP tool reads the provider manifest and generates an
.rc
file. - The RC (resource compiler) tool compiles the data from the CTRPP-generated
.rc
file to generate a.res
file containing the binary resources. This can be done either by directly compiling the CTRPP-generated.rc
file OR by compiling another.rc
file that includes the CTRPP-generated.rc
file via an#include
directive. - The linker embeds the data from the RC-generated
.res
file into the provider binary. - During installation, the provider binary is copied onto the user's system and the provider manifest is registered using the lodctr tool. The lodctr tool converts the
applicationIdentity
attribute of the provider manifest into a full path and records the full path to the provider binary in the registry.- If the provider binary is in the same directory as the manifest, use:
lodctr.exe /m:"C:\full\manifest\path\manifest.man"
. lodctr will combine the specified manifest path with the manifest'sapplicationIdentity
attribute to form the full path. - Otherwise, use
lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path"
. lodctr will combine the specified binary path with the manifest'sapplicationIdentity
attribute to form the full path. - For diagnostic purposes, you can inspect the recorded full path by checking the
ApplicationIdentity
value of registry keyHKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}
. - If the binary is using MUI for localization, be sure to copy the MUI file along with the binary.
- If the provider binary is in the same directory as the manifest, use:
- During counterset collection, the consumer uses the recorded full path to the provider binary to locate and load the necessary strings from the provider binary's resources.
The CTRPP tool will generate a .h
C/C++ code file. If the provider manifest's providerType
attribute is set to userMode
, the generated code file will contain the following definitions that are helpful in coding a user-mode provider:
- An provider initialization function named prefixCounterInitialize.
- A provider cleanup function named prefixCounterCleanup.
- A global provider variable that stores the provider handle opened by the prefixCounterInitialize function. The variable's name is the value of the
symbol
attribute of theprovider
element in the manifest. This variable should be used in calls toPerfCreateInstance
,PerfDeleteInstance
, and other APIs for controlling your provider's data. - For each counterset, a global countersetGUID variable with the counterset GUID. The variable's name is the value of the
counterSet
element'ssymbol
attribute plus the suffix "GUID", e.g.MyCounterSetGUID
. This variable should be used in calls toPerfCreateInstance
,PerfDeleteInstance
, and other APIs for controlling your provider's data. - For each counter, a counter macro with the counter's
id
value. The macro's name is the value of thecounter
element'ssymbol
attribute. This macro should be used in calls toPerfSetCounterRefValue
,PerfSetULongLongCounterValue
, and other APIs for setting your provider's data.
In the function names, prefix refers to the value of the -prefix
command-line parameter. If the -prefix
parameter is not used the functions will be named CounterInitialize
and CounterCleanup
.
The CTRPP tool will generate a .h
C/C++ code file. If the provider manifest's providerType
attribute is set to kernelMode
, the generated code file will contain the following definitions that are helpful in coding a kernel-mode provider's countersets:
- A counterset initialization function named prefixRegisterCounterset. This function fills in a RegInfo structure then invokes PcwRegister, putting the resulting counterset registration handle into the global Counterset variable.
- A counterset cleanup function named prefixUnregisterCounterset. This function invokes PcwUnregister on the counterset registration handle in the global Counterset variable.
- An instance creation function named prefixCreateCounterset. This function fills in an array of PcwData structures then invokes PcwCreateInstance using the counterset registration handle in the global Counterset variable.
- An instance cleanup function named prefixCloseCounterset. This function invokes PcwCloseInstance.
- An instance reporting function named prefixAddCounterset to be used from the counterset callback function. This function fills in an array of PcwData structures then invokes PcwAddInstance.
- Windows SDK 20H1 and later: A RegInfo initialization function named prefixInitRegistrationInformationCounterset for use in advanced scenarios. This function fills in a RegInfo structure. This function can be used in cases where the generated prefixRegisterCounterset does not meet your needs, e.g. when you want to customize the values in the RegInfo structure or when you want to store the returned handle in another variable.
In the function names, prefix refers to the value of the -prefix
command-line parameter. If the -prefix
parameter is not used the functions will have no prefix.
Note
The generated prefixAddCounterset function is used when you have a counterset callback. The generated prefixCreateCounterset and prefixCloseCounterset functions are used when you do not have a counterset callback.
If the -ch parameter is specified on the command line, the CTRPP tool will generate a .h
symbol file. This file contains the C/C++ symbols for the names and GUIDs of each counterset in the provider. The symbols can be used when writing programs that are hard-coded to consume the data from this counterset using the PerfLib V2 Consumer functions.
Requirement | Value |
---|---|
Minimum supported client | Windows Vista [desktop apps only] |
Minimum supported server | Windows Server 2008 [desktop apps only] |