Table of Contents
This section describes in detail how ocount is used.
Unless the --events option is specified, ocount will use
the default event for your system. For most systems, the default event is some
cycles-based event, assuming your processor type supports hardware performance
counters. The event specification used for ocount is slightly
different from that required for profiling -- a count value
is not needed. You can see the event information for your CPU using ophelp.
More information on event specification can be found at Section 3, “Specifying performance counter events”.
The ocount command syntax is:
ocount [ options ] [ --system-wide | --process-list <pids> | --thread-list <tids> | --cpu-list <cpus> [ command [ args ] ] ] |
ocount has 5 run modes:
One and only one of these 5 run modes must be specified when you run ocount.
If you run ocount using a run mode other than command [args], press Ctrl-c
to stop it when finished counting (e.g., when the monitored process ends). If you background ocount
(i.e., with ’&’) while using one these run modes, you must stop it in a controlled manner so that
the data collection process can be shut down cleanly and final results can be displayed.
Use kill -SIGINT <ocount-PID> for this purpose.
Following is a description of the ocount options.
command [args]
The command or application to be profiled. The [args] are the input arguments that the command or application requires. The command and its arguments must be positioned at the end of the command line, after all other ocount options.
--process-list / -p [PIDs]
Use this option to count events for one or more already-running applications, specified via a comma-separated list (PIDs). Event counts will be collected for all children of the passed process(es) as well.
--thread-list / -r [TIDs]
Use this option to count events for one or more already-running threads, specified via a comma-separated list (TIDs). Event counts will not be collected for any children of the passed thread(s).
--system-wide / -s
This option is for counting events for all processes running on your system. You must have root authority to run ocount in this mode.
--cpu-list / -C [CPUs]
This option is for counting events on a subset of processors on your system. You must have root authority to run ocount in this mode. This is a comma-separated list, where each element in the list may be either a single processor number or a range of processor numbers; for example: ’-C 2,3,4-11,15’.
--events / -e [event1[,event2[,...]]]
This option is for passing a comma-separated list of event specifications for counting. Each event spec is of the form:
name[:unitmask[:kernel[:user]]] |
When no event specification is given, the default event for the running processor type will be used for counting. Use ophelp to list the available events for your processor type.
--separate-thread / -t
This option can be used in conjunction with either the --process-list or
--thread-list option to display event counts on a per-thread (per-process) basis.
Without this option, all counts are aggregated.
--separate-cpu / -c
This option can be used in conjunction with either the --system-wide or
--cpu-list option to display event counts on a per-cpu basis. Without this option,
all counts are aggregated.
--time-interval / -i interval_length[:num_intervals]
Note: The interval_length is given in milliseconds.
However, the current implementation only supports 100 ms
granularity, so the given interval_length will be rounded
to the nearest 100 ms. Results collected for each time
interval are printed immediately instead of the default
of one dump of cumulative event counts at the end of the
run. Counters are reset to zero at the start of each
interval.
If num_intervals is specified, ocount exits after the
specified number of intervals occur.
--brief-format / -b
Use this option to print results in the following brief format:
[optional cpu or thread,]<event_name>,<count>,<percent_time_enabled>
[ <int> ,]< string >,< u64 >,< double >
|
If --timer-interval is specified, a separate line formatted as
timestamp,<num_seconds_since_epoch>[.n]
|
is printed ahead of each dump of event counts. If the time interval specified is less than one second, the timestamp will have 1/10 second precision.
--output-file / -f outfile_name
Results are written to outfile_name instead of interactively to the terminal.
--verbose / -V
Use this option to increase the verbosity of the output.
--version -v
Show ocount version.
--help / -h
Show a help message.