A sketch of a command-line interface for apitrace

Carl Worth cworth at cworth.org
Tue Oct 25 13:01:14 PDT 2011


Thanks for the quick feedback, José.

On Tue, 25 Oct 2011 19:47:10 +0100, José Fonseca <jose.r.fonseca at gmail.com> wrote:
> >   replay       Replay the given trace visually
> 
> s/replay/retrace" for consistency with code and documentation.

I consciously avoided "retrace" because we're _not_ actually tracing
anything again, (that is, not unless you run something like:

	apitrace trace apitrace replay <trace>

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

'/' totally makes sense. Consider me convinced.

> But I suspect that a numeric frequency will be of little or no use.

The use I had in mind for this was to easily be able to trim down the
number of images captured for a trace, (since there's often so much
similarity in nearby frames).

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

Yes, we'll need something to capture this (like the existing -S=WHEN
option to glretrace). My plan for that, (which I neglected to capture in
the writeup), was a separate option --every=WHEN. I think this can
combine well with the existing numeric --frames selection:

	apitrace dump-images --frames=200-300 --every=draw

I had imagined this --every option to be something unique to
dump-images. But it is similar to the --functions=REGEXP I proposed,
(simply providing a few named classes for which functions are considered
to be "draw" functions or frame boundaries). So I'll give some thought
to what we might do here for a general option.

> However we need to centralize the detection of what calls meet
> draw/fbo/framebuffer/etc.

Definitely!

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

OK. I should have come to the same conclusion when I realized that the
"diff <trace-file> <trace-file>" couldn't auto-detect what to
compare. That --compare option I proposed was a last-minute addition I
threw in just while typing the email.

Much better to just get rid of it and have diff commands that match our
dump commands.

You said "diff-trace" where I had simply "dump". Which direction would
you like to resolve that? I like getting away from any command that's
not strictly "diff", but I'm not sure that "apitrace dump-trace <trace>"
makes it very clear what this operation is doing. So what might we name
this case? How about dump-calls and diff-calls? Any other idea?

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

Right. So let's postpone that one to the future. Another long-term thing
I'd like to see is an "apitrace bisect" for identifying some minimal set
of calls that trigger some problematic issue.

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

Good idea. We could also generalize all the commands to take any of our
formats (trace, calls, state, or images) as a means of specifying which
calls/frames to dump/compare/etc. We're basically already doing that in
the diff case, so it would be nice to make that common for trim,
etc. (It would be nice even for "apitrace trace". After carefully
trimming one trace, I could easily create a new one trimmed just right
From the start without having to go through a separate trim operation.)

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

OK. So that's another one to put on the long-term todo list. It's a
ticky one to find a good name for, (I already want "apitrace bisect" for
something else as described above, this is a sort of git-bisect-helper
command, but that's not a good name).

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

Thanks. I think doing this design work upfront is really going to pay
off as good usability in the long term.

> I suppose that apitrace and qapitrace would live in /usr/bin, and
> everything else in /usr/lib/apitrace/...

Or you could require "apitrace gui" to get the gui and have only
apitrace in /usr/bin. Your call on that one.

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

Since we already have to do all the path-searching stuff to setup our
LD_PRELOAD (or whatever) for "apitrace trace" I think there's very
little additional code needed to exec existing scripts written in
python, etc. And I definitely prefer to use existing code rather than
writing new code where I can.

It wouldn't even be too hard to support a common convention where
dropping a new program into /usr/lib/apitrace/apitrace-foo means that
"apitrace foo" now works, (and could even list the new command in
"apitrace help" and call out to "apitrace-foo --help" for "apitrace help
foo").

So that argues for at least renaming existing things like tracediff.sh
to /usr/lib/apitrace/apitrace-diff-calls or so. This apitrace- prefix
for binaries might even be enough so that we don't need a separate /bin
under /usr/lib/apitrace.

-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/9fc4ab10/attachment.pgp>


More information about the apitrace mailing list