First draft of post-profiling interface

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

As promised the first draft of the new post-profiling tools interface

It's obviously a work in progress ... I would appreciate comments,
especially on things I've left out, and where I've lost it completely.
I suppose it sounds a bit over-complex but I think it degrades
gracefully, so that the common cases are simple enough - so this
is a matter of good documentation really.

1. Basic principles
-------------------

There are five basic things a user needs to specify to the post-profile tools :

a) common options such as --help, --version
b) specifications of which sample files to operate upon
c) processing options (what gets included in the workings) 
d) output and formatting options (what gets output, and how)
e) "special" options 

Of these, obviously a), and hopefully b) and some of c) can be universally
shared between the interfaces.

2. Common basic options
-----------------------

--help (-?)

	As generated by popt.

--usage

	As generated by popt.

--version (-v) 

	As currently, "op_summary: oprofile 0.3cvs compiled on May 15 2002 16:43:40"

--verbose (-V)

	Maybe we can have more fine-grained --debug later, but for now this will do

--no-demangle (n/a)

	We demangle by default. This is for avoiding demangler bugs and the like.

3. Profile specifications
-------------------------

Each tool needs at least one sample file + associated binary image to operate on,
and some tools (op_diff, op_summary) can have more than one. It would
be very useful for the user to be able to conveniently specify a subset of profiles,
and we can use the same method for every tool.

Each profile is a tuple of :

a) Session name
b) Binary
c) App binary (for shared libraries, e.g. /bin/ls using /lib/libc.so)
d) Event name
e) Event count
f) Process ID
g) CPU nr.
h) the actual binary to bfd_open
i) the actual samples file to use 

Some of these may be "null" paramaters, namely c),f),g),h),i) (and possibly e) depending
on what we do about multiplexing).

h) is a special case since it is not part of the profile as such. By default
it is derived from b), but allowing its specification is needed for op_diff
of two differently compiled binary + profile pairs. Similar goes for i)

So if we provide a way to specify some set of profiles via the command line,
we need to support each of these. My first idea is something like this :

op_report session:run1 image:/usr/bin/oprofiled

Here's a complete list of tags :

	sample-file: <filename>
		An actual sample file. If this is given, no other tags are allowed

	binary: <filename>
		The binary to use.

[FIXME] need to work on the semantics of this one in presence with other tags

	session: <sessionlist>
		A comma-separated list of session names to resolve in. Absence of this
		tag, unlike all others, means "the current session"

	session-exclude: <sessionlist>
		A comma list of sessions to exclude ...

	image: <imagelist>
		Comma list of image names to resolve. Each entry may be relative
		path, or wordexp() style name, or full path, e.g.

		'image:/usr/bin/oprofiled,*op*,./oprofpp'

		"image:" is default tag, allowing old-style "op_report /usr/bin/oprofiled"

	image-exclude: <imagelist> 
		Comma list of images to exclude from the final list

	lib-image: <imagelist>
		Comma list of library images to consider. Thus when looking for glibc samples
		due to oprofiled, op_report /usr/bin/oprofiled 'lib-image:*libc*' will show only
		those. If not specified, these samples are NOT included by default, EXCEPT
		in the presence of automerging if image:*libc*, for example.

	lib-image-exclude: <imagelist>
		Similar to image-exclude ...

	event: eventname
		Specify a particular event type e.g. CPU_CLK_UNHALTED

	count: count
		Specify the count for that event e.g. 30000

	unit-mask: mask
		Specify the unit mask for that event.

[FIXME] How to encode this unit mask ? Can we do better than op_start does ??

	cpu: <cpulist>
		Comma-separated list of cpu numbers to consider

	pid: <pidlist>
		Comma list of pid's to consider

If a tag is not specified, then it will match all values (with the exception of
session:).

[FIXME] is there anything else we can usefully have ? do we need all the above ?

Note: we can use a common method for comma-separated lists :

list ::= listitem ',' list | listitem
listitem ::= listchar listchar*
listchar ::= '\,' | '*' | '?' | alphanum 

i.e. we allow escape for entries with commas in it, and we allow
globbing.

4. op_alias
-----------

The above is rather tedious syntax, and is likely to stay that way
even with improvements. So we can have a command line tool / config file, e.g. :

# cat .oprofile/aliases
run1-oprofiled session:run1 image:/usr/bin/oprofiled

# op_report run1-oprofiled

for convenience. This is essentially a stored query facility ...

5. op_report
------------

née oprofpp.

This tool is used for providing symbol-based summaries of a particular image.
The profile spec must resolve to exactly one profile, unless it is possible to
auto-merge the resolved list from the profile spec (see below). 

op_report <flags> <profile-spec>
	--version (-v)
	--usage
	--help (-?)
	--verbose (-V)
	--no-demangle
	--symbols (-l)
	--dump-gprof (-g)
	--output <output spec> (-o) 
	--sort <sort spec> (-s)
	--ignore-symbols <symbollist> (-i)
	--exclude-symbols <symbollist> (-e)
	<profile spec>

--symbols <symbol-list>

	This is the standard sorted summary produced by oprofpp, as specified
by -i, -e, -s, -o. The default for op_report will be "op_report --symbols \*"
or something similar.

--dump-gprof

	Simple gprof dump as we have now. Incompatible with other options.

--output <outputspec>

    What fields to output in what order, as follows :

	v       vma offset
	s       nr samples
	S       nr accumulated samples
	p       nr percent samples
	P       nr accumulated percent samples
	n       symbol name
	m	mangled symbol name
	l       source file name and line nr
	L       base name of source file and line nr
	i       image name (these two are useful for merged)
	I       base name of image name
	h       a leading header (not a field ...)
	d       detailed samples for each selected symbol

[FIXME]	... more ?? 

--sort <sortspec>

	What field to sort by, as follows :

	v       vma offset
	s       nr samples
	n       symbol name
	m	mangled symbol name
	l       source file name and line nr
	L       base name of source file and line nr
	i       image name (these two are useful for merged)
	I       base name of image name
	r	sort whatever in reverse

[FIXME]	... more ?? 

--ignore-symbols <symbollist>

	comma-separated list of symbols to ignore. Ignored symbols are included
	in percentage calculations etc, but not output

[FIXME] mangling ??

--exclude-symbols <symbollist>

	comma-separated list of symbols to exclude. Excluded symbols are neither
	included in calculations nor output

[FIXME] Note that this has lost our current ability to compare counter 0,1
side by side, since we consider only events not counters now. How could
we restore this in a sane way ? If the spec expands to two profiles with
differing events, how can we format and allow sorting/field specification ?

6. op_annotate
--------------

née op_to_source. Our basic source / asm annotation tool.

op_annotate
	--version (-v)
	--usage
	--help (-?)
	--verbose (-V)
	--source-dir <dir>
	--output-dir <dir>
	--include <filelist>
	--exclude <filelist>
	--source (-s)
	--assembly (-a)
	--mixed (-m)
	<profile spec>

Profile spec must produce exactly 1 profile after auto-merge etc.

Options are as they are currently, except

--source

	specifies the source-based per-file annotation

--assembly

	specifies the objdump annotated asm output

--mixed

	specified the src/asm objdump annotated output

[FIXME]  for all tools, what about the "ignore less than..." option ?

7. op_summary
-------------

nee op_time. This is used for either global symbol- or image-based summaries
inside of one session only.

op_summary 
	--version (-v)
	--usage
	--help (-?)
	--verbose (-V)
	--no-demangle
	--symbol-summary (-l)
	--output <output spec> (-o) 
	--sort <sort spec> (-s)
	--merge <merge spec>
	--ignore-symbols <symbollist> (-i)
	--exclude-symbols <symbollist> (-e)
	<profile spec>

All as before.

--symbol-summary

Turns on symbol-based global summary. Make sure to have a 
useful default output spec in these cases.

--merge <merge spec>

Unlike the single-profile tools, it can be useful for us to not auto-merge
profile specs giving more than one profile result. Two profiles of the same
thing on CPU #0, and CPU #1, we might want to keep separate in the summary.  So
we don't do it by default for op_summary, but allow the user to specify merges
as follows :

	cpu

		Merge all cpu-specific profiles.

	pid

		Merge all process-id specific profiles.

	lib

		Merge all app-specific library profiles.

[FIXME] What else am I missing from this ?

8. op_diff
----------

Of the general form :

op_diff <profile spec 1> <profile spec 2>

where 1 is to be diffed against 2. If each is more > 1 profile,
auto-merging should take place as before, if needed. We also
can use binary: in the profile spec.

[FIXME] what's the delimiter between each profile spec ??

[FIXME] --merge as with op_summary ??

9. auto merging
---------------

If a profile spec leaves e.g

	/usr/bin/oprofiled .... cpu #0
	/usr/bin/oprofiled .... cpu #1

or some other "mergable" set of profiles, and exactly 1 is required,
then we should automatically merge them into one profile for the purposes
required, along with a note to the user of what we've done.

Also consider :

	/lib/libc.so
		/usr/bin/oprofiled
		/bin/ls
		/usr/bin/apache

We should expect something like :

# op_report /lib/libc.so
op_report: Merging the following profiles into this report :
	/lib/libc.so (/usr/bin/oprofiled)
	/lib/libc.so (/bin/ls)
	/lib/libc.so (/usr/bin/apache)
....

So the message would ideally indicate exactly the differing parts
that got merged. (it is a matter of documentation + user education
to tell them that if they want just the apache profile for libc,
they do op_report /usr/bin/apache lib-image:/lib/libc.so )

Sometimes we might not want to them to merge though, e.g. op_summary to
show the differing process IDs separately for a number of images. So that's
why we have --merge where appropriate.