rjmcmahon
/
FiWiTSF
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

README: document affine TSF library and example build 

Made-with: Cursor
This commit is contained in:
Robert McMahon 2026-03-31 20:13:56 -07:00
parent abaf7e66fb
commit b5bd67757b
1 changed files with 34 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
README.md
View File

@ -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.