A sketch of a command-line interface for apitrace
Carl Worth
cworth at cworth.org
Tue Oct 25 10:39:02 PDT 2011
Here's a proposal for functionality I would like to see in the upcoming
top-level apitrace command-line program. This should cover most all of
the functionality provided by the several binaries and scripts in the
current apitrace distribution. Thanks to Eric Anholt for his help in
designing this interface.
I would be happy for any feedback on this proposal. I'm planning to code
up all of this soon.
$ apitrace help
Usage apitrace <command> [<args> ...]
The available commands are as follows:
trace Generate a new trace by executing the given program
replay Replay the given trace visually
trim Trim a trace by including only the specified calls/frames
dump Output a textual dump of the given trace, in a C-like format
dump-state Output the OpenGL state in JSON format
dump-images Create image files for each frame/drawing operation of a trace
diff Identify differences in two traces or their various dumps
gui Launch a graphical user interface to explore a trace
Most commands acting on a trace accept the following common options:
--calls=[RANGE] Operate only on calls with index numbers within
the specified range.
--frames=[RANGE] Operate only on frames with index numbers within
the specified range.
--functions=[REGEXP] Operate only on function calls which have a
name that matches the given regular expression.
A [RANGE] can be any of the following:
Example Description
------- -----------
4 A single number specifying a single call or frame.
10-20 Two numbers separated by '-' (FIRST-LAST) specifying a
range of consecutive calls/frames from FIRST to LAST. If
either of FIRST or LAST is omitted, the first or last
call/frame index in the trace will be used.
1-100 at 5 Either of the above range specifications followed by '@'
and a number (INTERVAL). This specifies the inclusion of
only each INTERVAL call/frame within the range. For
example, 1-100 at 5 species frame 1, frame 5, frame 10,
... up to frame 100.
4,10-20 at 2 A comma separated list of any of the above range
specifications, specifying the union of the ranges.
Some commands have other, command-specific options. See
"apitrace help <command>" for details.
Hopefully, it's fairly clear what each of the above commands would
do. The "apitrace diff" command is one of the most flexible. For its
first argument, it can accept a trace, a file from a previous call to
"apitrace dump" or "apitrace dump-state", or a directory of images from
a call to "apitrace dump-images". The second argument could then be
either a trace or the same type of file/directory as the first argument.
That kind of diff means there's a lot of different functionality under a
single command, but I think it will be intuitive enough to be
appropriate. For the case where "apitrace diff" is given two traces,
we'll need a --compare option to say what should be compared, (calls, or
state dumps, or images).
Here's a survey of some of the existing programs/scripts and options and
how they map to the new interface:
Existing command New command
---------------- --------
LD_PRELOAD=/../glxtrace.so <program> apitrace trace <program>
glretrace <trace> apitrace replay <trace>
[--does not exist--] apitrace trim --frames=1-100 <trace>
tracedump <trace> apitrace dump <trace>
glretrace -D CALLNO apitrace dump-state --calls=CALLNO
glretrace -s PREFIX apitrace dump-images --output=PREFIX
jsondiff.py <state1> <state2> apitrace diff <state1> <state2>
retracediff.py <trace1> <trace2> apitrace diff --compare=images ...
snapdiff.py <dir1> <dir2> apitrace diff <dir1> <dir2>
tracediff.py <dump1> <dump2> apitrace diff <dump1> <dump2>
tracerepack.py apitrace trim
There are several other options to the existing glretrace that don't
become new commands (-b for benchmark mode, -db/-sb for selecting a
visual, -v for verbose, and -w for wait on final frame). Those could all
be supported as options under "apitrace replay".
The only existing script I see that isn't directly covered by the above
is tracecheck.py. That could probably be another option under "apitrace
replay". Something like --git-bisect-return-value or whatever.
Again, any thoughts will be appreciated.
-Carl
--
carl.d.worth at intel.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/apitrace/attachments/20111025/c321eb8b/attachment.pgp>
More information about the apitrace
mailing list