gputrace: capture gates, CUDA/Metal parity toolchain, and analysis consolidation

.github/workflows/ci.yaml

@@ -17,6 +17,15 @@ jobs:
           go-version-file: go.mod
           check-latest: true
 
+      - name: Check formatting
+        run: |
+          unformatted=$(gofmt -l $(git ls-files '*.go'))
+          if [ -n "$unformatted" ]; then
+            echo "These files are not gofmt-formatted; run 'make fmt':"
+            echo "$unformatted"
+            exit 1
+          fi
+
       - name: Vet
         run: go vet ./...
 

.gitignore

@@ -52,3 +52,10 @@ gputrace_bin
 # Local watch/debug artifacts
 watch_*
 beads.svg
+brain/
+
+# Capture artifacts
+*.pprof
+*.pftrace
+*.gpucapture/
+.hermes/

Makefile

@@ -6,19 +6,51 @@ AXPERMS_BIN := $(HOME)/go/bin/axperms
 BUNDLE_ID := com.tmc.gputrace
 AXPERMS_BUNDLE_ID := com.github.tmc.gputrace.axperms
 
-.PHONY: all build test vet install reinstall clean sign-bundle setup-permissions reset-permissions fullreinstall reset test-permissions axperms setup-axperms help
+.PHONY: all build test vet fmt checkfmt check install reinstall clean sign-bundle setup-permissions reset-permissions fullreinstall reset test-permissions axperms setup-axperms help
+
+GO_FILES = $(shell git ls-files '*.go')
 
 all: build
 
 build:
 	go install ./cmd/gputrace
 
+# test reports how many cases it skipped, because "ok" and a skip are the same
+# line in go test's default output. Most of the skips are opt-in integration
+# tests waiting on an environment variable (see docs/TESTING.md); a suite that
+# says ok while a third of it sat out is telling the truth and meaning less
+# than it reads.
 test:
-	go test ./...
+	@go test -json ./... | go run ./internal/cmd/testcensus
+
+# test-gated reports which opt-in variables are set and which are not, so the
+# skip count above is attributable rather than merely known.
+test-gated:
+	@echo "Opt-in test variables (see docs/TESTING.md):"
+	@for v in TRACE_PROCESSOR_SHELL GPUTRACE_TEST_TRACE GPUTRACE_MIO_SETUP_DATA_PATH \
+	          GPUTRACE_PERF_FIXTURE GPUTRACE_TEST_METALLIB GPUTRACE_PARITY_TRACE; do \
+		eval val=\$$$$v; \
+		if [ -n "$$val" ]; then echo "  set    $$v=$$val"; else echo "  unset  $$v"; fi; \
+	done
+	@echo "Unset variables leave their tests skipped; go test reports that as ok."
 
 vet:
 	go vet ./...
 
+fmt:
+	gofmt -w $(GO_FILES)
+
+# checkfmt fails instead of rewriting, so CI and pre-push can use it.
+checkfmt:
+	@unformatted=$$(gofmt -l $(GO_FILES)); \
+	if [ -n "$$unformatted" ]; then \
+		echo "These files are not gofmt-formatted; run 'make fmt':"; \
+		echo "$$unformatted"; \
+		exit 1; \
+	fi
+
+check: checkfmt vet test
+
 install: clean build setup-permissions
 	@echo "Reinstall complete with fresh permissions"
 
@@ -149,6 +181,9 @@ help:
 	@echo "  build              - Build gputrace"
 	@echo "  test               - Run Go tests"
 	@echo "  vet                - Run go vet"
+	@echo "  fmt                - Rewrite tracked Go files with gofmt"
+	@echo "  checkfmt           - Fail if any tracked Go file is unformatted"
+	@echo "  check              - checkfmt + vet + test"
 	@echo "  reinstall          - Rebuild binary and refresh signed app bundle"
 	@echo "  fullreinstall      - Clean + rebuild + fresh permissions (resets TCC)"
 	@echo "  clean              - Remove app bundle (forces macgo to recreate)"

api_surface_test.go

@@ -19,7 +19,6 @@ var (
 	_ func(*gputrace.Trace) ([]*gputrace.EncoderTiming, error)                                                  = gputrace.ExtractTimingData
 	_ func(*gputrace.Trace) (*timing.Store0TimingData, error)                                                   = gputrace.ExtractStore0Timing
 	_ func(*gputrace.Trace, *timing.Store0TimingData) []*gputrace.EncoderTiming                                 = gputrace.ConvertStore0ToEncoderTimings
-	_ func(*gputrace.Trace) []*gputrace.EncoderTiming                                                           = gputrace.GenerateSyntheticTiming
 	_ func(*gputrace.Trace) (*gputrace.ShaderMetricsReport, error)                                              = gputrace.ExtractShaderMetrics
 	_ func(...string) *gputrace.ShaderSourceMapper                                                              = gputrace.NewShaderSourceMapper
 	_ func(io.Writer, *gputrace.ShaderMetricsReport) error                                                      = gputrace.FormatShadersSimple
@@ -71,9 +70,6 @@ func TestFacadeCalls(t *testing.T) {
 	if _, err := gputrace.ExtractStatistics(trace); err != nil {
 		t.Fatalf("ExtractStatistics: %v", err)
 	}
-	if timings := gputrace.GenerateSyntheticTiming(trace); len(timings) == 0 {
-		t.Fatal("GenerateSyntheticTiming returned no timings")
-	}
 	if extractor := gputrace.NewTimingMetricsExtractor(trace); extractor == nil {
 		t.Fatal("NewTimingMetricsExtractor returned nil")
 	}

api_timing.go

@@ -21,11 +21,6 @@ func ConvertStore0ToEncoderTimings(t *Trace, store0Data *timing.Store0TimingData
 	return timing.ConvertStore0ToEncoderTimings(t, store0Data)
 }
 
-// GenerateSyntheticTiming generates synthetic timing data for t.
-func GenerateSyntheticTiming(t *Trace) []*EncoderTiming {
-	return timing.GenerateSyntheticTiming(t)
-}
-
 // NewTimingMetricsExtractor returns a timing metrics extractor for t.
 func NewTimingMetricsExtractor(t *Trace) *TimingMetricsExtractor {
 	return timing.NewTimingMetricsExtractor(t)
@@ -36,6 +31,29 @@ func FormatTimingMetrics(metrics *TimingMetrics) string {
 	return timing.FormatTimingMetrics(metrics)
 }
 
+// LowSampleMarker follows a row measured from a single dispatch.
+const LowSampleMarker = timing.LowSampleMarker
+
+// TimingSourceUnavailable marks a trace that carries no timing measurement at
+// all, as distinct from one measured approximately.
+const TimingSourceUnavailable = timing.TimingSourceUnavailable
+
+// LowSampleFootnote explains LowSampleMarker, or returns "" when unused.
+func LowSampleFootnote(timings []*KernelTiming) string {
+	return timing.LowSampleFootnote(timings)
+}
+
+// FilterMinCalls keeps rows measured from at least min dispatches and reports
+// how many it dropped.
+func FilterMinCalls(timings []*KernelTiming, min int) ([]*KernelTiming, int) {
+	return timing.FilterMinCalls(timings, min)
+}
+
+// MinCallsNote states what a --min-calls filter removed.
+func MinCallsNote(min, dropped, total int) string {
+	return timing.MinCallsNote(min, dropped, total)
+}
+
 // ExportTimingMetricsJSON writes timing metrics as JSON.
 func ExportTimingMetricsJSON(w io.Writer, metrics *TimingMetrics) error {
 	return timing.ExportTimingMetricsJSON(w, metrics)

api_trace.go

@@ -4,13 +4,42 @@ import (
 	"io"
 
 	"github.com/tmc/gputrace/internal/command"
+	"github.com/tmc/gputrace/internal/trace"
 )
 
+// IsLibraryUUID reports whether label identifies a Metal library rather than a
+// function.
+func IsLibraryUUID(label string) bool {
+	return trace.IsLibraryUUID(label)
+}
+
+// IsArchiveFunctionName reports whether name identifies a function only by the
+// shader archive it came from. A capture records an archive's content id where
+// it records a function name for a library the capture describes, so such a
+// kernel has a distinct, stable identity but no readable name. Only the
+// profiler's streamData carries the name.
+func IsArchiveFunctionName(name string) bool {
+	return trace.IsArchiveFunctionName(name)
+}
+
 // ParseDetailedCommandBuffer parses command buffer cbIndex from t.
+//
+// It reads and rescans the whole capture file on every call. Use OpenCapture
+// when walking more than one command buffer.
 func ParseDetailedCommandBuffer(t *Trace, cbIndex int) (*command.DetailedCommandBuffer, error) {
 	return command.ParseDetailedCommandBuffer(t, cbIndex)
 }
 
+// Capture holds a capture file and its command-buffer index for repeated
+// detailed parses.
+type Capture = command.Capture
+
+// OpenCapture reads t's capture file and command-buffer index once, so that
+// walking every command buffer does not reread the file per buffer.
+func OpenCapture(t *Trace) (*Capture, error) {
+	return command.OpenCapture(t)
+}
+
 // DumpCommandBuffer writes command buffer cbIndex from t to w.
 func DumpCommandBuffer(t *Trace, w io.Writer, cbIndex int) error {
 	return command.DumpCommandBuffer(t, w, cbIndex)

capture/capture.go

@@ -0,0 +1,40 @@
+// Package capture runs a Metal workload under the GPUToolsCapture interposer.
+package capture
+
+import (
+	"context"
+	"io"
+
+	internal "github.com/tmc/gputrace/internal/capture"
+)
+
+// ErrNotInterposable reports that dyld will not load the capture interposer
+// into the target executable.
+var ErrNotInterposable = internal.ErrNotInterposable
+
+// Options configure a capture run.
+type Options struct {
+	// Output is the .gputrace bundle to create.
+	Output string
+	// Dir is the workload's working directory. Empty inherits the caller's.
+	Dir string
+	// Env adds environment entries in KEY=value form.
+	Env []string
+	// Stdout and Stderr receive workload output. Nil discards it.
+	Stdout io.Writer
+	Stderr io.Writer
+}
+
+// Eligible reports whether dyld will honor the capture interposer for path.
+func Eligible(path string) error { return internal.Eligible(path) }
+
+// Run executes argv under the capture interposer and returns the trace path.
+func Run(ctx context.Context, opts Options, argv ...string) (string, error) {
+	return internal.Run(ctx, internal.Options{
+		Output: opts.Output,
+		Dir:    opts.Dir,
+		Env:    opts.Env,
+		Stdout: opts.Stdout,
+		Stderr: opts.Stderr,
+	}, argv...)
+}

cmd/axperms/main.go

@@ -21,6 +21,16 @@ import (
 
 //
 
+// openSettingsPane opens a System Settings pane with `open`. A failure is not
+// fatal: every caller also prints instructions or falls back to polling. It
+// must not be silent though, or a headless run sleeps and then reports a
+// confusing downstream error instead of the actual cause.
+func openSettingsPane(url string) {
+	if err := exec.Command("open", url).Run(); err != nil {
+		fmt.Fprintf(os.Stderr, "warning: could not open %s: %v\n", url, err)
+	}
+}
+
 var (
 	axIsProcessTrusted            func() bool
 	axIsProcessTrustedWithOptions func(uintptr) bool
@@ -172,17 +182,17 @@ func main() {
 	}
 
 	if *openSettings {
-		exec.Command("open", paneURLs[PaneAccessibility]).Run()
+		openSettingsPane(paneURLs[PaneAccessibility])
 		return
 	}
 
 	if *openScreenRecording {
-		exec.Command("open", paneURLs[PaneScreenRecording]).Run()
+		openSettingsPane(paneURLs[PaneScreenRecording])
 		return
 	}
 
 	if *openFDA {
-		exec.Command("open", paneURLs[PaneFullDiskAccess]).Run()
+		openSettingsPane(paneURLs[PaneFullDiskAccess])
 		return
 	}
 
@@ -261,7 +271,7 @@ func main() {
 			if !axIsProcessTrusted() {
 				fmt.Fprintf(os.Stderr, "\nPlease grant Accessibility permission to axperms in System Settings,\n")
 				fmt.Fprintf(os.Stderr, "then run this command again.\n")
-				exec.Command("open", paneURLs[PaneAccessibility]).Run()
+				openSettingsPane(paneURLs[PaneAccessibility])
 				os.Exit(1)
 			}
 		}
@@ -438,7 +448,7 @@ func findAppInPrivacyList(appName string, paneURL string) (found bool, enabled b
 	if debugMode {
 		fmt.Printf("[DEBUG] Opening pane: %s\n", paneURL)
 	}
-	exec.Command("open", paneURL).Run()
+	openSettingsPane(paneURL)
 	time.Sleep(1 * time.Second)
 
 	pid := findSystemSettingsPID()
@@ -559,7 +569,7 @@ func listPrivacyApps(paneName string, paneURL string) {
 	pid := findSystemSettingsPID()
 	if pid == 0 {
 		fmt.Println("System Settings not running. Opening...")
-		exec.Command("open", paneURL).Run()
+		openSettingsPane(paneURL)
 		time.Sleep(2 * time.Second)
 		pid = findSystemSettingsPID()
 		if pid == 0 {
@@ -759,7 +769,7 @@ func findRowForApp(appName string, paneURL string) (found bool, row uintptr) {
 	pid := findSystemSettingsPID()
 	if pid == 0 {
 		fmt.Println("System Settings not running. Opening...")
-		exec.Command("open", paneURL).Run()
+		openSettingsPane(paneURL)
 		time.Sleep(2 * time.Second)
 		pid = findSystemSettingsPID()
 		if pid == 0 {
@@ -922,7 +932,7 @@ func watchPermission() {
 	fmt.Println("Please grant Accessibility permission in System Settings.")
 
 	// Open settings
-	exec.Command("open", "x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_Accessibility").Run()
+	openSettingsPane("x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_Accessibility")
 
 	// Trigger initial prompt
 	triggerPrompt()