VxDMon Help

VxD Monitor Version 1.0

Copyright (C) 1996, Bryce Cogswell and Mark Russinovich

The authors can be reached at cogswell@cs.uoregon.edu and mer@cs.uoregon.edu.

Introduction to VxDMon

Using VxDMon

Selecting a Profile

Viewing Performance Statistics

Viewing Control-Flow Information

Monitoring Your Own Services


Introduction to VxDMon

Introduction

VxDMon is a tool meant to allow for profiling of Windows 95 VxD performance and behavior. VxDMon's functionality is built on VxD service hooking. By using service hooking, VxDMon is able to monitor and time, via the Pentium's rdtsc (ReaD Time Stamp Counter) instruction, any and all VxD services including those of VxDs built into Windows and those added by a developer. In addition, VxDMon keeps track of VxD service call histories so that it can display useful information such as the list of all services that were called by a particular service during a monitoring session. This combination of VxD performance and call history information provides a never-before-seen look into the behavior of Windows.

VxD Service Hooking

Most VxD's export services that other VxDs can call through a mechanism similar to the dynamic linking used by DLLs. Because service calls go through a level of indirection, they can be hooked by patching a VxD's service table with addresses of hook procedures. VxDMon uses this facility to insert itself on the call path for VxD services selected in the user interface. It is then notified whenenver a VxD service starts as well as when it completes.

Peformance Monitoring

VxDMon uses the Pentiums built-in cycle counter to measure the duration of VxD service calls. The cycle counter is a 64-bit value that is incremented on every processor cycle, and an  instruction, whose assembly language mnemonic is rdtsc (ReaD-Time-Stamp-Counter), is used to read the value of the counter. VxDMon records the value of the counter whenever a service is called, and then updates the accumulated time spent in the service by adding the elapsed cycles seen when the service finishes. VxDMon also keeps track of how many times each VxD service being monitored is executed and uses this information to report the average number of cycles taken by individual calls to the service.

Control-Flow Monitoring

In addition to performance monitoring, the service wrappers that VxDMon uses for its service hooks also keep track of control-flow information. They do this by maintaining a list of services called by each monitored service. When a VxD service is called, VxDMon checks to see if it was called by another service, and if so, updates the callers list of called services. The user interface processes this information in order to generate both caller and callee views of particular VxD services behavior when the user requests it.


Running VxDMon

Using VxDMon

This section provides a high-level description of how to use VxDMon. Each windows menu and functionality are described in sections that specifically address them.

VxDMon was designed for Pentium processors and requires that VXDMON.EXE be in the same directory as VXDMON.VXD. It will run on a 386 or 486 processor, but performance information will not be available since only the Pentium has a cycle counter. VXDMON.VXD is a dynamic VxD, meaning that no changes to system.ini or the registry are necessary.

The typical way VxDMON is used is demonstrated in the following steps:

1. Select services to be monitored

2. Collect performance and control-flow information

3. View the gathered statistics

Selecting a Hook Profile

When VxDMon is started it checks to see if a hook profile exists in a file in the current directory called profile.dat. If a profile exists, VxDMon will ask if you desire that the services listed in the profile should be hooked. If no profile exists, the main window will open without a prompt. To create a hook profile the Capture|Select Services menu item must be selected, which will open a tree-view containing all the services listed in a file called services.dat. When a service is clicked upon in this view, it will toggle between a selected state, indicated with a green icon, and an unselected state, indicated with a red icon. Yellow icons are used to identify VxDs that have some, but not all, of their services selected for monitoring.

After a profile has been created, VxDMon must be told to begin monitoring the services selected. Choose the Options|Hook Now menu item in the selection window. A profile can be saved by choosing Options|Save Hook List.

Updating Statistics

Monitoring begins as soon as the services are hooked, and the statistics gathered by VxDMons VxD can be imported into the user interface by choosing Capture|Update Statistics in the main window. The latest statistics are read from the VxD by selecting Capture|Update, and reset to zero by selecting Capture|Reset. Depending on the value of the Preferences|Zero Statistics on Update selection, Capture|Update either accumulates the counts (off), or gives the counts since the previous Update (on).

Viewing Control-Flow Information

Control-flow information can be seen by double clicking on a service in the main window, or by highlighting a service and choosing Options|Show Ancestors or Options|Show Descendants. A services ancestors are all services that preceeded the service in the control-flow. The immediate ancestors of a service include all the services that directly called it. Correspondingly, the descendants of a service are those services that followed it in the control-flow. The immediate descendants are those services that were directly called by the service.

When ancestor or descendant information is selected, a new sub-window is opened that displays the control-flow hierarchy as a tree-view. The same ancestor/descendant selection facilities are available in the sub-window so that other services can have control-flow windows opened for them.

Finally, both the main window and the control-flow windows have save capabilities that dump the windows contents in formatted ASCII to a file.


Selecting a Profile

The profile selection window is opened with the Capture|Select Services menu item in the main window. A selection profile is displayed as a tree-view with VxD services being leaf nodes underneath the VxD they belong to. An example selection tree profile is shown below:

Clicking on a VxD or a service toggles the hook status of the VxD or service. When a service is selected as hooked, a green icon is associated with it. If the service is not selected, a red icon is associated with it. Finally, a yellow icon indicates that some services beneath the object are selected and others are not. The selection status of groups of services can be toggled by clicking on their parent VxD, or by holding down the shift key and selecting the start and end services of the group.

The Options menu is shown below:

Menu choices are described here:

Hook/Unhook Now	Applies the current hook profile and initiates monitoring of the selected services.

Save Hook List	Saves the current hook profile to profile.dat.

Close	Closes the window.


Performance Monitoring

Viewing Performance Statistics

After services have been hooked VxDMon begins accumulating performance information such as total time spent in services and number of times services have been invoked. This data is not displayed in the main window until the update function is selected. The update function is found under the Capture menu:

The menu items are described below:

Select Services	Opens the hook profile selection window.

Update Statistics	Updates the display with current monitoring information. The short-cut key is Ctrl+U.

Reset Statistics	Does not update the display, but resets the accumulated statistics to zero. The short-cut key is Ctrl+R.

Show Ancestors	Pops open a window of ancestor control-flow information for the currently highlighted service.

Show Descendants	Pops open a window of descendant control-flow information for the currently highlighed service.

The Preferences menu contains additional options that affect how statistics are displayed. These menu items include:

Show Uncalled	Many times the hook profile will contain services that have not been executed at the time of an update. By default these services are not shown, however this toggle can force their display in the performance window.

Overhead Compensation	The monitoring code in VxDMon introduces a small overhead into the cycle counts that are obtained by the monitoring wrappers. By default, VxDMon automatically determines its average overhead and  removes this value from the displayed cycle counts. This toggle can force VxDMon to display un-compensated measurements.

Zero Statistics on Update	Have the Capture|Update function reset counts to zero automatically (obviates the need to select Capture|Reset on each update).

Viewing and Interpreting Performance Data

When the performance data is updated with statistics from hooked services that have been executed, the main VxDMon window will look something like this:

The fields are defined as follows:

VxD Service	The service name as it appears in services.dat.

Ordinal	Each exported VxD service must have a unique numeric identifier for its use in Windows. This identifier is a 32-bit value where the VxD identifier makes up the high 16-bits and a number unique to the VxD makes up the low 16-bits. For example, service 2 of VxD 1 would have an ordinal value of 0x00010002.

Entries	The number of times the service has been invoked.

Exits	The number of times the service has completed.

Avg Cycles	The average number of cycles elapsed from the time a service is invoked until the service completes. This value includes time spent in any other services or Windows functions called from the service.

Total Cycles	The sum of the number of cycles spent in all invocations of the service.

Clicking on any of the column headings causes the data to be sorted by that criteria. For instance, clicking on Entries will result in the services with the most invocations to be at the top of the window. A sort criteria will remain in effect for any further updates until it is changed.

Information displayed in the main window can be saved to a file via the File menu:

Save	Dumps the current data to a file in ASCII format.

Save As	Prompts for the name of the file to save the data to and then saves it to the specified file in ASCII format..

File data is neatly formatted for easy importation into word processors.


Control-Flow Monitoring

Viewing Control-Flow Information

When a control-flow window is created by either double clicking on a service name or using the ancestor/descendant menu items in the main window, a tree-view like the following is displayed:

In this case the tree-view is showing the services that are called by VTD_Update_System_Clock. The red arrows are visual aids for quickly seeing that this is a descendant view; blue arrows are used for an ancestor view. When such a view is first created the tree-view is only expanded to show the first level descendants or ancestors. However, these services can be expanded to show more distant ancestors or descendants.

The Options menu allows for separate control-flow windows to be created for a high-lighted service and for the control-flow information to be saved as formatted ASCII text to a file. The menu is shown below with a brief description of its items:

Show Ancestors	Opens a new control-flow window that displays the ancestors of the service that is highlighted in the current window.

Show Descendants	Opens a new control-flow window that displays the descendants of the service that is highlighted in the current window.

Save Call Graph As	Prompts for a file name and then saves the information in the current window to the specified file in a formatted ASCII format.

Close	Closes the window.


Monitoring Your Own Services

VxDMon uses a file called services.dat to obtain its information on VxDs and their services. By adding to this file, you can extend VxDMon to be aware of new VxDs and services, including those that you might write. For example, lets assume that youve written a VxD called MyVxD that has one service, MyVxD_Get_Version. Further, the VxDs identifier is 0x990000. To make VxDMon aware of your VxD, you would add the following lines to the end of services.dat:

FFFFFFFF	MyVxD

00990000	MyVxD_Get_Version

Thats all there is to it. The FFFFFFFF denotes a VxD and is followed by the ordinals and names of all of the services it exports. The next time you run VxDMon, it will include MyVxD and its service, MyVxD_Get_Version, in its hook selection window.