A sketch of a command-line interface for apitrace

[Carl Worth]

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>