A sketch of a command-line interface for apitrace

[José Fonseca]

On Tue, Oct 25, 2011 at 6:39 PM, Carl Worth <cworth at cworth.org> wrote:
> 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

s/replay/retrace" for consistency with code and documentation.

>   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.

I don't know if there's a precedent of using @ for frequency.
Otherwise you may consider '/' like cron.

But I suspect that a numeric frequency will be of little or no use.
Much more interesting would be to specify a qualitative frequency,
such as "/draw", "/framebuffer", or "/frame", to specify every draw
call, every frambuffer object change, or every frame, respectively.
However we need to centralize the detection of what calls meet
draw/fbo/framebuffer/etc.

>     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).

I'd prefer diff-trace diff-images, diff-state, etc, as it's more
symmetrical/consistent with the dump commands, and feels less magical.
Especially because things such as traces dumps, json, images, are not
always easily recognizable without partially parsing them.

We might still leave a diff for non advanced users, if we manage to
auto-detect everything reliably.

> 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>

BTW, for trim, it would be really sweet if it could take a tracedump
output as input of which frames to select. This would make the process
really versatile: somebody will dump the trace to a file, open the
ascii text dump on vim/emacs/etc, manually delete the calls it doesn't
care, and then obtain a new one.

>  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.

tracecheck.py is quite tunable, and will likely be more tunable in the
future (as a bug can have many shapes -- correctness performance,
glError, messages, etc), so I believe it will deserve a proper
command.

> Again, any thoughts will be appreciated.

Minor details are subject to personal taste, but overall this looks quite nice.


I suppose that apitrace and qapitrace would live in /usr/bin, and
everything else in /usr/lib/apitrace/... . We'll also need to
standardize what  /usr/lib/apitrace tree will look like too. Maybe:
- bin (for subcommands such as glretrace)
- wrappers (for the wrapping .so/.dll/.dylib 's) ; on Linux they
likely need to have per-architecture subdirectories to allow
cross-tracing
- any thing else?


Just one general question: is your plan to re-implement all the python
scripts in C, or do you foresee a mixture of commands in C++/Python,
at least transitorily?


Jose