1 files changed, 51 insertions, 0 deletions
diff --git a/ext/hsdbg_trace/hsdbg_trace.h b/ext/hsdbg_trace/hsdbg_trace.h
new file mode 100644
index 0000000..a819f9c
--- /dev/null
+++ b/ext/hsdbg_trace/hsdbg_trace.h
@@ -0,0 +1,51 @@
+// hsdbg function-trace runtime.
+//
+// Build your program with -finstrument-functions and link this in; the compiler
+// then calls the enter/exit hooks below on every function, and they append a
+// timestamped record to a fixed ring buffer. hsdbg reads that buffer straight
+// out of the live process and turns it into the flame-chart timeline, so no
+// breakpoints and no hand-picking of functions are needed.
+//
+//   clang -finstrument-functions -g your_prog.c hsdbg_trace.c -o your_prog
+//
+// The record layout and the three exported symbols are the contract hsdbg reads
+// against; keep them in sync with the reader on the debugger side.
+#pragma once
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    enum
+    {
+        HSDBG_TRACE_ENTER = 0,
+        HSDBG_TRACE_EXIT = 1,
+
+        // 1,048,576 records ~= 32 MB; plenty for a short profiled run
+        HSDBG_TRACE_CAPACITY = 1u << 20,
+    };
+
+    // 32 bytes, naturally aligned so hsdbg can read the array with one memory
+    // fetch and cast without worrying about padding differences
+    struct HsdbgTraceRecord
+    {
+        uint64_t timestamp_ns; // CLOCK_MONOTONIC nanoseconds
+        uint64_t function;     // address of the entered/exited function
+        uint64_t thread_id;    // pthread_threadid_np of the running thread
+        uint32_t kind;         // HSDBG_TRACE_ENTER or HSDBG_TRACE_EXIT
+        uint32_t reserved;
+    };
+
+    // the ring buffer and how far it has been filled. hsdbg reads hsdbg_trace_head
+    // first, then the records below it; head is published only after a record's
+    // fields are fully written
+    extern struct HsdbgTraceRecord hsdbg_trace_records[HSDBG_TRACE_CAPACITY];
+    extern const uint64_t hsdbg_trace_capacity;
+    extern uint64_t hsdbg_trace_head; // total records ever written (monotonic)
+
+#ifdef __cplusplus
+}
+#endif