From b5bd67757b5aac678e46bb97fa7530e77f2ef50b Mon Sep 17 00:00:00 2001
From: Robert McMahon <rjmcmahon@rjmcmahon.com>
Date: Tue, 31 Mar 2026 20:13:56 -0700
Subject: [PATCH] README: document affine TSF library and example build

Made-with: Cursor
---
 README.md | 37 ++++++++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 8c2c442..5022022 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,13 @@
 # FiWiTSF
 
-Userspace tool (C11, `SCHED_FIFO`) that periodically reads a **master** 802.11 TSF from mac80211 **debugfs** and nudges **follower** interfaces toward it by writing their `tsf` files.
-
 Repository root: `~/Code/FiWiTSF` (standalone; not part of a Linux kernel tree).
 
+This repo contains two related pieces:
+
+1. **`tsf_sync_rt_starter`** — C11 userspace tool using `SCHED_FIFO` that reads a **master** 802.11 TSF from mac80211 **debugfs** and nudges **follower** interfaces by writing their `tsf` files (hardware alignment).
+
+2. **`tsf_affine`** — Library-style C code (`tsf_affine.h` / `tsf_affine.c`) that keeps an **affine map** per radio (master TSF → each radio TSF) from paired samples, so scheduling can stay on a **master timeline** without stepping every radio’s hardware TSF. With **N** radios and one master, there are **N−1** fitted maps plus identity on the master. See `TEAM_EMAIL_affine_tsf_mapping.txt` for the design note you can share with the team.
+
 ## Hosting (Gitea, SSH)
 
 Canonical server: **[git.umbernetworks.com](https://git.umbernetworks.com)**.
@@ -57,20 +61,47 @@ git clone git@git.umbernetworks.com:rjmcmahon/FiWiTSF.git
 make
 ```
 
+Produces:
+
+- `tsf_sync_rt_starter` — RT TSF sync (needs debugfs; see below)
+- `tsf_affine_example` — demo that trains 24 affine maps and prints a master→all lookup (no Wi-Fi required)
+
 ## Requirements
 
+**`tsf_sync_rt_starter`**
+
 - Linux with mac80211 and `CONFIG_MAC80211_DEBUGFS`
 - `debugfs` mounted (e.g. on `/sys/kernel/debug`)
 - Privileges for real-time scheduling (`root` or `CAP_SYS_NICE`)
 
+**`tsf_affine` / `tsf_affine_example`**
+
+- C11 toolchain and `-lm` (as in the `Makefile`). No debugfs or RT privileges unless you wire samples to real hardware yourself.
+
 ## Usage
 
+### Hardware TSF sync (debugfs)
+
 ```bash
 sudo ./tsf_sync_rt_starter -h
 ```
 
 See `-h` / `--help` for options (`-m`, `-f`, `-p`, `-j`, etc.).
 
+### Affine mapping API
+
+Include `tsf_affine.h` and compile with `tsf_affine.c`. Typical flow:
+
+- `tsf_affine_pool_init(pool, n_radios, master_idx, window_cap)`
+- For each paired snapshot: `tsf_affine_pool_sample(pool, radio_idx, master_tsf, radio_tsf)` (master index ignored)
+- Lookup: `tsf_affine_pool_master_to_all(pool, master_tsf, out_array)` or `tsf_affine_pool_master_to_radio(...)`
+
+Run the demo:
+
+```bash
+./tsf_affine_example
+```
+
 ## Note
 
-Experimental tooling for lab and bring-up. Production systems often replace debugfs with a dedicated kernel interface or driver hook.
+Experimental tooling for lab and bring-up. Production systems often replace debugfs with a dedicated kernel interface or driver hook. The affine layer is meant for **software** scheduling against a master TSF; features that require true hardware TSF alignment still need the driver/MAC path.