docs: define durationToPrev timing semantics

2 files changed, 16 insertions, 1 deletions

diff --git a/README.md b/README.md
index fb829a4..c9a57ef 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,19 @@ Maybe this is a spiritual successor of one of my previous projects, I/O Riot htt
 
 This works only on Linux!
 
+## Timing Semantics
+
+Each reported event pair has two timing counters:
+
+- `durationNs`: syscall runtime on the same thread (`exit(current) - enter(current)`).
+- `durationToPrevNs`: inter-syscall gap on the same thread (`enter(current) - exit(previous)`).
+
+Important details:
+
+- `durationToPrevNs` is tracked per `tid` (thread), not globally across all threads.
+- The first observed syscall pair for a thread has `durationToPrevNs = 0` because there is no prior exit timestamp.
+- `durationToPrevNs` is attributed to the current syscall pair (the one whose `enter` closes the gap).
+
 ## Fedora
 
 To get this running on Fedora 42, run:
@@ -50,4 +63,3 @@ We are using Inferno Flamegraphs:  https://github.com/jonhoo/inferno
 ```sh
 cargo install inferno
 ```
-
diff --git a/internal/event/pair.go b/internal/event/pair.go
index 1e9a544..4b93013 100644
--- a/internal/event/pair.go
+++ b/internal/event/pair.go
@@ -33,8 +33,11 @@ func NewPair(enterEv Event) *Pair {
 }
 
 func (e *Pair) CalculateDurations(prevPairTime uint64) {
+	// Duration is syscall runtime: exit(current) - enter(current).
 	e.Duration = e.ExitEv.GetTime() - e.EnterEv.GetTime()
 	if prevPairTime > 0 {
+		// DurationToPrev is the inter-syscall gap on the same TID:
+		// enter(current) - exit(previous).
 		e.DurationToPrev = e.EnterEv.GetTime() - prevPairTime
 	}
 }