Welcome to PAPI for Windows
PAPI, or the Performance Application
Programming Interface is a machine independent
set of callable routines that provide access to the performance counters
on most modern processors. This version of PAPI implements the
interface for Windows NT, 2000 or XP running on Intel IA32 archtectures.
If you are reading this, you have successfully installed PAPI
on your machine.
Below are some topics you may wish to learn more about:
Caveats:
This release of PAPI for Windows contains the basic PAPI functionality.
It works, but it is still a work in progress. Some fundamental limitations
exist. For example, this implementation measures everything at the system
level, not the process or thread level. Although PAPI properly binds itself
to the processor on which it is called on a MultiProcessor Build of
Windows, PAPI will still measure all events on that processor at the system
rather than process level. Further, some advanced areas such as multiplexing,
overflow, and profiling have not been exhaustively tested and may not perform
as advertised. We hope to remove these restrictions in future releases. Check
the PAPI website
for information on current releases.
About this Installation
Three installation options were presented to you when you installed
WinPAPI:
Typical
The typical installation contains the following components:
- The WinPAPI DLL
to which you can link your instrumented programs.
- The WinPMC kernel driver
which supports the WinPAPI DLL and provides access to the low
level performance counter hardware.
- A collection of examples
that exercise the WinPAPI DLL Library and provide a variety
of metrics on your machine. These tests are provided both as precompiled
console executables, and as source projects in C or Fortran that can be
modified and rebuilt using Microsoft Visual C++ 6.0 or higher, and Compaq
Fortran 6.1 or higher.
- A WinPAPI Shell Application
that provides simple button access to a variety of functions.
- The Perfometer
DLL and Java GUI application to allow you to instrument and visually
monitor the performance of your applications.
- A MATLAB support folder that contains
tools to call PAPI functions from MATLAB, and example programs to show
you how.
In addition to the files mentioned above, the installer will also
create several shortcuts to these components and place them in the Start->Programs->WinPAPI
shortcut path for your convenience.
Compact
The compact installation includes only the linkable
WinPAPI DLL
and WinPMC kernel driver
. It assumes that you have access to the support and reference materials
from another source, such as the PAPI CVS repository
.
Custom
The custom installation allows you to select only those components
(such as just the help files) that you wish to install or reinstall
on your system. Note that for access to the full sources of the driver,
dll, and shell application, you must use the PAPI
CVS repository
.
The WinPAPI Shell Application
The Shell provides a simple interface to the basic functions
of PAPI on Windows. You can run the shell from the shortcut in the Start->Programs->WinPAPI
path, or by double-clicking the icon in the directory where WinPAPI
was installed. The Shell consists of a splash screen with eight buttons,
as described below:
Exit
Exits the Shell application.
Diagnostics
Displays a secondary menu of options as shown and described below:
Return
Removes this Dialog and returns to the main WinPAPI display screen.
Smoke Test
Checks for proper installation of the low
level PAPI components, verifies that the operating system is the Uniprocessor
Free Build (this version of PAPI will not run on the MultiProcessor
or Checked Build versions of Windows), and runs all of the C and Fortran
example programs found in the default locations. The examples provided
with PAPI will respond with a PASSED, SKIPPED or FAILED message, depending
on the outcome. You can add your own examples to the SmokeTest simply by
copying the executable to an appropriate directory. See the section on
programming your own
examples
for more details.
Driver Version
Displays the version number of the WinPMC kernel driver if it is enabled.
RDPMC Test
Tests the kernel driver functionality by attempting to issue a RDPMC assembly
instruction. This instruction is ordinarily disabled if the kernel is not
properly installed.
Hello Test
HelloNum Test
Two low level tests of the WinPMC kernel driver functionality. They send
a simple command to the kernel, which responds with an appropriate text string.
Task Switch
Counts the number of times the task switch routine is executed. Only available
for the checked or multiprocessor build.
<open>
Button available for future functionality.
Help
Web
Same as main screen. See below.
C Examples
Presents an Open File dialog, as shown below, that allows you
to select a precompiled C example to exercise specific PAPI functionality.
if you want to modify existing examples or create your own, see the section
on programming your own examples
. All examples will open and execute in a separate console window,
which will display the results and wait for a keypress on completion.
Fortran Examples
Similar to C Examples, above, allows you to select a precompiled Fortran
example. The Fortran examples mimic the C examples and are provided to
demonstrate how to access the PAPI functions from Fortran.
Perfometer
Executes the Perfometer.jar file, a graphical
performance visualization tool
for PAPI, written in Java. Perfometer monitors the performance of
a separately running program that has been instrumented with calls to
the Perfometer DLL. The instrumented program can run either on your machine
or another machine connected over a network.
Perfometer Examples
Presents an Open File dialog similar to that for the C or Fortran
examples. In this case, you can select a precompiled C or Fortran example
that has been instrumented with calls to the Perfometer DLL. The example
runs in a console window, and displays a message similar to the following:
With this message displayed, click the Perfometer button described
above to execute the Perfometer.jar file and click on the Connect Local
button to make a graphical connection to the target example. More
information on using Perfometer can be found elsewhere
.
Help
If enabled, opens this page in your default browser.
NOTES:
- If the help files are not found where expected,
this button will be dimmed.
- If your browser is already open, the proper page
may not be displayed.
Web
Links to the PAPI home page on the World Wide Web.
The PAPI Programmer's Reference
The PAPI programming interface consists of a collection of 6
high-level calls, and roughly 40 low-level calls for both C and Fortran.
Unix style man pages for each of these calls are available in html format
here
.
The Example Suites
Two sets of precompiled eamples are included with the WinPAPI Shell
Application. The first set is written in C and resides in the /tests directory.
The second similar set is written in Fortran and duplicates many of the
C examples. This set is in the /ftests directory. Both sets execute
as Windows console applications, and can be run quietly in batch mode to
provide go/no-go testing of the PAPI installation, or from a command line
to provide more detailed information.The examples provide a variety of measurements
of operations and functionality on your system and print their results to
the console window. If you run them from the Shell Application, they will
dynamically open in a console window that is dismissed with a keystroke
after the test completes. You can also run the examples directly by opening
a console window and typing the name of the test as shown below for the
C examples:
- Start->Run...
- Open: cmd OK
- >cd %root%\tests (where %root% is the root
directory where WinPAPI was installed)
- >zero (or any other test.exe file)
Programming your own examples
PAPI and the programs in the example suites were all developed using
Microsoft Visual Studio. The C compiler was Visual C++ 6.0, and the Fortran
compiler was Compaq Visual Fortran 6.6.0. If you want to modify any of
the existing examples or use them as templates to create your own programs,
you must have these or more recent tools installed on your computer. If
you do, you can click the shortcut to PAPI_tests.dsw or PAPI_ftests.dsw
found in the Start->Programs->WinPAPI path. These shortcuts will
open a workspace in Visual Studio that contains projects for all the examples
included with this installation. You can then open the source for any example
to examine how things are done, or use any of the projects to pattern the
development of a test of your own. Note that the files in all the projects
are referenced by paths relative to the existing project. If you move
anything, the builds are likely to break.
In addition to the basic C and Fortran examples, several examples in
both languages are provided to demonstrate the Perfometer interface. You
can open the perfometer_tests.dsw project file to view and experiment with
these examples.
Typical Output
from some C Examples
The programs included with the Example Suites are intended to
illustrate a variety of features of PAPI, or solutions to specific user
problems. They also serve as examples of programming with PAPI. The
best way to understand what the tests are doing is to browse the source
code included in the "Typical" installation. If you do not have Microsoft
Visual Studio installed, any other text editor will work. These source
files can be found in:
%root%\src\tests (where %root% is the root directory where WinPAPI
was installed).
The output obtained on an 850 MHz Pentium III for a number of
the C examples can be viewed here
.
The Perfometer Graphic Visualization Tool
Perfometer is a collection of components that allow you to quickly
create a visual interface to the performance of PAPI metrics in your code.
These components include:
- perfometer.lib -- the library to which your code links
- perfometer.dll -- the shared library that provides the client
functionality
- perfometer.jar -- the Java GUI interface that displays the results
You can instrument your code by linking it to perfometer.lib, and adding
calls to perfometer() or mark_perfometer() as appropriate. Several examples
are provided in both source and compiled forms to illustrate how this
is done. The source code for the Perfometer library and GUI is not
distributed with this installation. The source code and project to rebuild
these components is available in the PAPI CVS repository
.
The Perfometer GUI can be invoked through the Perfometer button
in the PAPI Shell Application or through the Start->Programs->WinPAPI->Perfometer
shortcut. Either way produces a window similar to the one shown below:
The area below the top button bar will initially be blank, indicating
that the GUI is not connected to an executing program. You can use the
Connect Local or Connect to Net buttons to begin
receiving data from running instrumented programs that are waiting for a
connection. The color changes in the bar chart indicate calls to mark_perfometer()
with varying color paramters. The other interface features of the Perfometer
GUI are best discovered by inspection and experimentation.
The WinPAPI Dynamic Link Library
The WinPAPI DLL consists of two pieces:
- WinPAPI.DLL, installed (typically) in C:\WINNT\system32\,
and
- WinPAPI.lib, the linkable library, found in %root%\src\win2k\substrate\Release.
The library is placed in this arcane location to make sure that the
test projects can find it where they expect it to be in the development
environment. You can copy it to your own projects as desired.
To incorporate PAPI calls into your codes, you must include
WinPAPI.lib and papi.h, fpapi.h or papi_test.h in your project. You
can do this either by referencing the files in this directory tree,
or by copying the files to your local project.
The source code for the PAPI library is not distributed with
this installation. If you would like access to the source code and
project to rebuild the library, you must use the
PAPI CVS repository
.
The WinPMC Kernel Driver
The WinPMC Kernel Driver is a small (~3K) code that provides
access to the normally restricted assembly instructions that allow programming
of the hardware performance monitoring counters found on all Pentium
class x86 cpus. If the driver has been installed successfully, the Driver
Test button in the WinPAPI Shell will be enabled and the tests it performs
will be successful.
The driver file, WinPMC.sys, requires administrator privileges
to be installed in C:\WINNT\system32\drivers. Also, the registry must
be modified for this service to be recognized by calling programs. DO
NOT attempt to install this driver on a new machine by simply copying the
file!
As with the PAPI library, The source code for the Kernel Driver
is not distributed with this installation. The source code for the
library is available in the PAPI CVS repository
. In addition to Microsoft Visual Studio, you must also have a current
version of the Microsoft NTDDK
installed on your computer to rebuild the driver.
The structure of PAPI files and folders on your disk
The folder structure created on your disk to hold the PAPI installation
may appear rather arcane and complex. This is because it must reproduce
the folder structure of the development environment in order for the test
applications to build successfully. The structure of the default install
is shown graphically below:
CVS access to the complete sources for PAPI
Access to all of the PAPI sources for Windows and all other
supported platforms is available through the
PAPI CVS Repository
.
CVS
is a sophisticated version control system used primarily in
the Unix world to allow multiple developers to work on a project simultaneously.
You can interactively browse the PAPI CVS Repository through the WWW
by visiting the
PAPI CVS Web
, or you can download a branch of the PAPI CVS tree using a program
for Windows such as WinCVS
. Contact the PAPI development team
if you would like to participate in PAPI development.
|
|