Sample libpshwpc Event Configuration File

Here's an example XML event configuration file that you might use for measuring specific hardware performance events with libpshwpc or psrun. This example uses PAPI as the performance counter access method.

<?xml version="1.0" encoding="UTF-8" ?>
<ps_hwpc_eventlist class="PAPI" domain="all">
  <!-- This is a comment -->
  <ps_hwpc_event type="preset" name="PAPI_TOT_INS" />
  <ps_hwpc_event type="preset" name="PAPI_TOT_CYC" />
</ps_hwpc_eventlist>

This configuration file requests counting of two PAPI "standard" events: PAPI_TOT_INS and PAPI_TOT_CYC. It also requests that the events are counted at both the user and kernel/system counting domain.

It's important to ensure that all XML attributes in the document (version, encoding, class, domain, type, and name) are provided exactly as shown and that arguments (1.0, UTF-8, PAPI, all, preset, and the names of the PAPI standard events that you'd like to measure) are enclosed in double-quotes (XML is more strict in that regard than the HTML with which you may already be familiar).

Not all attributes are required to be present in the configuration file; some have default values. In this example, you could omit the attributes encoding and domain (the default counting domain is "user"). All of the other attributes shown have no default values, so you must supply them.

You should also make sure that the XML prologue (the first line, beginning with "<?xml version=...") is present as well or the XML parser in PerfSuite will not accept the document.

This example also shows how you can insert comments into the configuration file: anything surrounded by "<!--" and "-->" will be ignored. This can be a helpful way to document a group of events that you find particularly useful, are related in some way to measurements of interest to you, or that may be targeted to a particular processor type.

In general, all you need to do is to add or subtract ps_hwpc_event lines using your favorite text editor (note: you're limited to a maximum of 32 such lines) and to replace the event names shown in bold with the events of your choice and you should be all set to go. You may want to double-check that the events in your file are actually available on the computer where your program will run - if so, you might find the PerfSuite utility psinv helpful.

A number of predefined configuration files are available that you can use as-is or modify to suit your needs. You can find these files located in the directory share/perfsuite/xml/pshwpc, relative to the top-level directory of your PerfSuite installation.