README.eu-stacktrace: update for passthrough pipe demo

diff --git a/README.eu-stacktrace b/README.eu-stacktrace
index 3aaa63ea3e060514c56bd8a3507e43ec7abce61c..5a2320a78ea4ff8f9a6655a35402958dffe31ab6 100644 (file)
--- a/README.eu-stacktrace
+++ b/README.eu-stacktrace
@@ -1,6 +1,50 @@
 # eu-stacktrace development branch
 
+eu-stacktrace is (will be) a utility to process a stream of stack
+samples (such as those obtained from the Linux kernel's
+PERF_EVENT_SAMPLE facility) into a stream of stack traces (such as
+those obtained from PERF_EVENT_CALLCHAIN), freeing various profiling
+utilities from having to implement their own backtracing logic.
+
+For the time being, eu-stacktrace is meant to be fed data from a
+profiling tool via a pipe or fifo. We will see how well this idea
+works as implementation proceeds.
+
+The goal is to work with various profiler data formats. For the
+prototype, Serhei is working to support sysprof's data format. We'd
+like to adapt sysprof to distros compiled with omit-framepointer,
+which will require sysprof to consume PERF_EVENT_SAMPLE data. After
+that, supporting perf's native data format is an obvious prerequisite
+for merging this branch into elfutils. Ideally, we would like for
+eu-stacktrace to also convert between different profile data formats
+(e.g. taking sysprof data as input and emitting perf data, and
+vice-versa).
+
+## build & run (for now)
+
 Requirements:
 - /usr/include/sysprof-4 headers (e.g. `sysprof-devel` package on Fedora)
+- `sysprof` polkit actions installed systemwide (e.g. `sysprof` package on Fedora)
+- sysprof with the serhei/samples-via-fifo patchset [1]
+  - some detailed notes on how I compiled sysprof via jhbuild here [2];
+    these are unlikely to fit your needs exactly but include useful hints
+
+[1]: https://git.sr.ht/~serhei/sysprof-experiments/log/serhei/samples-via-fifo
+[2]: https://git.sr.ht/~serhei/config-files/tree/master/item/setup-development.md#1b-setup-for-codesysprofcode-development-with-codejhbuildcode-providing-upstream-gnome-apps-to-test-against
+
+Invoking `eu-stacktrace`:
+- mkfifo /tmp/test.fifo
+- eu-stacktrace --input=/tmp/test.fifo --output=test.syscap &
+- sysprof-cli --use-fifo=/tmp/test.fifo test.syscap
+
+## TODO
 
-...
+- support taking an FD for fork/exec pipes; then sysprof can fork eu-stacktrace
+- default to stdin/stdout for --input and --output
+- initial version of packet parsing for sysprof
+- implement --mode=none
+- implement --mode=naive
+- implement --mode=caching
+- testsuite
+- implement --format=perf; make sysprof headers optional through configury
+- ?? perhaps support for converting between input/output formats