--- a
+++ b/pp_interface
@@ -0,0 +1,391 @@
+
+As promised the first draft of the new post-profiling tools interface
+ 
+This is mostly describing the ideal interface w/o much
+regard to implementation problems, though I do mention
+a couple of things.
+ 
+It's obviously a work in progress ... I would appreciate comments,
+especially on things I've left out.
+ 
+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.
+
+[FIXME] add a --demangle as well for symmetry ? 
+
+
+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 ...
+ 
+[FIXME] can we use something similar for the daemon start up ?
+ 
+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] XML output ? 
+[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] what makes incompatible profiles ?
+ 
+[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.