aux/trace: add GALLIUM_TRACE_TRIGGER mode

similar to amd/radv driver debug modes for sqtt, this specifies a filename
which is checked on every flush(PIPE_FLUSH_END_OF_FRAME); when it exists,
the next frame (and only that frame) is captured into the trace

to use, specify a file with the env var, run your app, and 'touch /path/to/file'
when you want to capture a trace

Reviewed-by: Adam Jackson <ajax@redhat.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/10058>

docs/gallium/debugging.rst

@@ -32,6 +32,13 @@ specified file. Paths may be relative or absolute; relative paths are relative
 to the working directory.  For example, setting it to "trace.xml" will cause
 the trace to be written to a file of the same name in the working directory.
 
+.. envvar:: GALLIUM_TRACE_TRIGGER <string> ("")
+
+If set while :ref:`trace` is active, this variable specifies a filename to monitor.
+Once the file exists (e.g., from the user running 'touch /path/to/file'), a single
+frame will be recorded into the trace output.
+Paths may be relative or absolute; relative paths are relative to the working directory.
+
 .. envvar:: GALLIUM_DUMP_CPU <bool> (false)
 
 Dump information about the current CPU that the driver is running on.

src/gallium/auxiliary/driver_trace/tr_context.c

@@ -1370,6 +1370,9 @@ trace_context_flush(struct pipe_context *_pipe,
       trace_dump_ret(ptr, *fence);
 
    trace_dump_call_end();
+
+   if (flags & PIPE_FLUSH_END_OF_FRAME)
+      trace_dump_check_trigger();
 }
 
 

src/gallium/auxiliary/driver_trace/tr_dump.c

@@ -43,6 +43,11 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+/* for access() */
+#ifdef _WIN32
+# include <io.h>
+#endif
+
 #include "pipe/p_compiler.h"
 #include "os/os_thread.h"
 #include "util/os_time.h"
@@ -63,11 +68,41 @@ static mtx_t call_mutex = _MTX_INITIALIZER_NP;
 static long unsigned call_no = 0;
 static bool dumping = false;
 
+static bool trigger_active = true;
+static char *trigger_filename = NULL;
+
+void
+trace_dump_trigger_active(bool active)
+{
+   trigger_active = active;
+}
+
+void
+trace_dump_check_trigger(void)
+{
+   if (!trigger_filename)
+      return;
+
+   mtx_lock(&call_mutex);
+   if (trigger_active) {
+      trigger_active = false;
+   } else {
+      if (!access(trigger_filename, 2 /* W_OK but compiles on Windows */)) {
+         if (!unlink(trigger_filename)) {
+            trigger_active = true;
+         } else {
+            fprintf(stderr, "error removing trigger file\n");
+            trigger_active = false;
+         }
+      }
+   }
+   mtx_unlock(&call_mutex);
+}
 
 static inline void
 trace_dump_write(const char *buf, size_t size)
 {
-   if (stream) {
+   if (stream && trigger_active) {
       fwrite(buf, size, 1, stream);
    }
 }
@@ -175,6 +210,7 @@ static void
 trace_dump_trace_close(void)
 {
    if (stream) {
+      trigger_active = true;
       trace_dump_writes("</trace>\n");
       if (close_stream) {
          fclose(stream);
@@ -182,6 +218,7 @@ trace_dump_trace_close(void)
          stream = NULL;
       }
       call_no = 0;
+      free(trigger_filename);
    }
 }
 
@@ -234,6 +271,13 @@ trace_dump_trace_begin(void)
        * time.
        */
       atexit(trace_dump_trace_close);
+
+      const char *trigger = debug_get_option("GALLIUM_TRACE_TRIGGER", NULL);
+      if (trigger) {
+         trigger_filename = strdup(trigger);
+         trigger_active = false;
+      } else
+         trigger_active = true;
    }
 
    return true;

src/gallium/auxiliary/driver_trace/tr_dump.h

@@ -108,6 +108,9 @@ void trace_dump_ptr(const void *value);
 void trace_dump_surface_ptr(struct pipe_surface *_surface);
 void trace_dump_transfer_ptr(struct pipe_transfer *_transfer);
 
+void trace_dump_trigger_active(bool active);
+void trace_dump_check_trigger(void);
+
 /*
  * Code saving macros.
  */