489 lines
11 KiB
Markdown
489 lines
11 KiB
Markdown
# GDB Runtime Threshold Tuning Guide
|
||
|
||
Adjust WiFi monitor thresholds **on-the-fly** using GDB - no rebuild required!
|
||
|
||
## Best of Both Worlds
|
||
|
||
✅ **C code performance** - 10,000+ frames/sec
|
||
✅ **GDB tunability** - Adjust thresholds in real-time
|
||
✅ **No rebuild needed** - Change settings instantly
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
cd ~/Code/esp32/esp32-iperf
|
||
|
||
# Update components
|
||
cp wifi_monitor.c components/wifi_monitor/
|
||
cp .gdbinit .
|
||
|
||
# Rebuild once
|
||
idf.py build
|
||
idf.py -p /dev/ttyACM0 flash
|
||
|
||
# Enable GDB auto-load
|
||
mkdir -p ~/.config/gdb
|
||
echo "set auto-load safe-path /" >> ~/.config/gdb/gdbinit
|
||
```
|
||
|
||
## Start GDB Session
|
||
|
||
```bash
|
||
# Terminal 1: OpenOCD
|
||
idf.py openocd
|
||
|
||
# Terminal 2: GDB
|
||
idf.py gdb
|
||
```
|
||
|
||
## Quick Start
|
||
|
||
### View Current Thresholds
|
||
|
||
```gdb
|
||
(gdb) show_thresholds
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
WiFi Monitor Thresholds (GDB-tunable)
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
High NAV threshold: 5000 us
|
||
Duration mismatch log: 10000 us
|
||
PHY rate fallback: 100 Mbps
|
||
Duration multiplier: 2x expected
|
||
|
||
Collapse Detection:
|
||
Retry rate threshold: 20.0%
|
||
Avg NAV collapse: 10000 us
|
||
Collision percentage: 10.0%
|
||
Mismatch percentage: 5.0%
|
||
|
||
Logging Control:
|
||
Log every N mismatches: 1 (1=all, 10=every 10th)
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
```
|
||
|
||
### Use Preset Profiles
|
||
|
||
```gdb
|
||
# Sensitive - catch more issues (stricter thresholds)
|
||
(gdb) tune_sensitive
|
||
Thresholds set to SENSITIVE (catch more issues)
|
||
High NAV: 3000 us
|
||
Rate fallback: 150 Mbps
|
||
Retry rate: 15.0%
|
||
|
||
# Normal - balanced (default)
|
||
(gdb) tune_normal
|
||
Thresholds set to NORMAL (default)
|
||
|
||
# Relaxed - fewer false positives (lenient)
|
||
(gdb) tune_relaxed
|
||
Thresholds set to RELAXED (fewer false positives)
|
||
High NAV: 10000 us
|
||
Rate fallback: 50 Mbps
|
||
Retry rate: 30.0%
|
||
```
|
||
|
||
### Adjust Individual Thresholds
|
||
|
||
```gdb
|
||
# Set high NAV threshold to 8000 us (8ms)
|
||
(gdb) set_high_nav 8000
|
||
High NAV threshold set to 8000 us
|
||
|
||
# Set mismatch logging threshold to 15000 us
|
||
(gdb) set_mismatch_log 15000
|
||
Duration mismatch logging threshold set to 15000 us
|
||
|
||
# Set rate fallback to 50 Mbps
|
||
(gdb) set_rate_fallback 50
|
||
PHY rate fallback threshold set to 50 Mbps
|
||
|
||
# Set duration multiplier (NAV > 3x expected = mismatch)
|
||
(gdb) set_multiplier 3
|
||
Duration multiplier set to 3x expected
|
||
|
||
# Log every 10th mismatch (reduce verbosity)
|
||
(gdb) set_log_rate 10
|
||
Logging every 10 mismatch(es)
|
||
```
|
||
|
||
## Available Thresholds
|
||
|
||
### Detection Thresholds
|
||
|
||
| Threshold | Default | What It Does |
|
||
|-----------|---------|--------------|
|
||
| `threshold_high_nav_us` | 5000 | NAV above this = "high" |
|
||
| `threshold_duration_mismatch_us` | 10000 | Log mismatches when NAV exceeds this |
|
||
| `threshold_phy_rate_fallback_mbps` | 100 | PHY rate below this = fallback |
|
||
| `threshold_duration_multiplier` | 2 | NAV > expected × this = mismatch |
|
||
|
||
### Collapse Detection Thresholds
|
||
|
||
| Threshold | Default | What It Does |
|
||
|-----------|---------|--------------|
|
||
| `threshold_retry_rate_percent` | 20.0 | Retry rate for collapse |
|
||
| `threshold_avg_nav_collapse_us` | 10000 | Avg NAV for collapse |
|
||
| `threshold_collision_percent` | 10.0 | Collision % for collapse |
|
||
| `threshold_mismatch_percent` | 5.0 | Duration mismatch % for collapse |
|
||
|
||
### Logging Control
|
||
|
||
| Threshold | Default | What It Does |
|
||
|-----------|---------|--------------|
|
||
| `log_every_n_mismatches` | 1 | Log every Nth mismatch (1=all) |
|
||
|
||
## Tuning Examples
|
||
|
||
### Example 1: Noisy 2.4GHz Environment
|
||
|
||
Problem: Too many false positives on 2.4GHz
|
||
|
||
```gdb
|
||
# Use relaxed profile
|
||
(gdb) tune_relaxed
|
||
|
||
# Or manually adjust
|
||
(gdb) set_high_nav 10000 # 10ms threshold
|
||
(gdb) set_rate_fallback 24 # 2.4GHz rates lower
|
||
(gdb) set_multiplier 3 # Allow 3x mismatch
|
||
(gdb) set_log_rate 10 # Log every 10th
|
||
(gdb) continue
|
||
```
|
||
|
||
Now only severe issues trigger alerts.
|
||
|
||
### Example 2: Clean 5GHz Network
|
||
|
||
Problem: Want to catch subtle issues
|
||
|
||
```gdb
|
||
# Use sensitive profile
|
||
(gdb) tune_sensitive
|
||
|
||
# Or manually adjust
|
||
(gdb) set_high_nav 3000 # 3ms threshold
|
||
(gdb) set_rate_fallback 200 # Should stay >200 Mbps
|
||
(gdb) set_multiplier 1.5 # Catch 1.5x mismatches
|
||
(gdb) set_log_rate 1 # Log everything
|
||
(gdb) continue
|
||
```
|
||
|
||
Catches issues early before collapse.
|
||
|
||
### Example 3: Production Monitoring
|
||
|
||
Problem: Need to reduce log spam
|
||
|
||
```gdb
|
||
# Keep normal thresholds but reduce logging
|
||
(gdb) tune_normal
|
||
(gdb) set_log_rate 100 # Log every 100th mismatch
|
||
(gdb) set_mismatch_log 20000 # Only log severe (>20ms)
|
||
(gdb) continue
|
||
```
|
||
|
||
Statistics still track everything, but logs are cleaner.
|
||
|
||
### Example 4: Debugging Specific Issue
|
||
|
||
Problem: Investigating NAV spikes around 7-8ms
|
||
|
||
```gdb
|
||
# Fine-tune for specific range
|
||
(gdb) set_high_nav 6000 # Start counting at 6ms
|
||
(gdb) set_mismatch_log 7000 # Log anything >7ms
|
||
(gdb) set_multiplier 1 # Catch all mismatches
|
||
(gdb) set_log_rate 1 # Log everything
|
||
(gdb) continue
|
||
|
||
# Now watch for those specific spikes
|
||
```
|
||
|
||
### Example 5: Live WiFi Load Test
|
||
|
||
```gdb
|
||
# Start with normal
|
||
(gdb) tune_normal
|
||
(gdb) continue
|
||
|
||
# Run iperf from another machine
|
||
# Watch serial output...
|
||
|
||
# If too noisy, relax on the fly
|
||
(gdb) Ctrl-C
|
||
(gdb) set_log_rate 20
|
||
(gdb) continue
|
||
|
||
# If not catching issues, make sensitive
|
||
(gdb) Ctrl-C
|
||
(gdb) tune_sensitive
|
||
(gdb) continue
|
||
```
|
||
|
||
**Tune while testing - no rebuild!**
|
||
|
||
## Direct Variable Access
|
||
|
||
You can also set variables directly:
|
||
|
||
```gdb
|
||
# Set variables directly
|
||
(gdb) set threshold_high_nav_us = 7500
|
||
(gdb) set threshold_phy_rate_fallback_mbps = 75
|
||
(gdb) set log_every_n_mismatches = 5
|
||
|
||
# Or use C-style
|
||
(gdb) print threshold_high_nav_us = 7500
|
||
$1 = 7500
|
||
```
|
||
|
||
## Monitor Effects in Real-Time
|
||
|
||
```gdb
|
||
# Set thresholds
|
||
(gdb) tune_sensitive
|
||
(gdb) continue
|
||
|
||
# Watch serial monitor in other terminal
|
||
# See immediate effect on logging
|
||
|
||
# If too verbose
|
||
(gdb) Ctrl-C
|
||
(gdb) set_log_rate 10
|
||
(gdb) continue
|
||
|
||
# Logs immediately reduced by 10x!
|
||
```
|
||
|
||
## Preset Profile Comparison
|
||
|
||
### Sensitive Profile
|
||
|
||
```
|
||
High NAV: 3000 us (stricter)
|
||
Mismatch log: 5000 us
|
||
Rate fallback: 150 Mbps (higher)
|
||
Multiplier: 1.5x (catches more)
|
||
Retry rate: 15.0% (lower)
|
||
Avg NAV collapse: 5000 us
|
||
Collision %: 5.0%
|
||
Mismatch %: 3.0%
|
||
```
|
||
|
||
**Use for**: Clean networks, early issue detection, debugging
|
||
|
||
### Normal Profile (Default)
|
||
|
||
```
|
||
High NAV: 5000 us (balanced)
|
||
Mismatch log: 10000 us
|
||
Rate fallback: 100 Mbps
|
||
Multiplier: 2x
|
||
Retry rate: 20.0%
|
||
Avg NAV collapse: 10000 us
|
||
Collision %: 10.0%
|
||
Mismatch %: 5.0%
|
||
```
|
||
|
||
**Use for**: General monitoring, production
|
||
|
||
### Relaxed Profile
|
||
|
||
```
|
||
High NAV: 10000 us (lenient)
|
||
Mismatch log: 20000 us
|
||
Rate fallback: 50 Mbps (lower)
|
||
Multiplier: 3x (allows more)
|
||
Retry rate: 30.0% (higher)
|
||
Avg NAV collapse: 15000 us
|
||
Collision %: 15.0%
|
||
Mismatch %: 10.0%
|
||
```
|
||
|
||
**Use for**: Noisy environments, 2.4GHz, reduce false positives
|
||
|
||
## Tips & Best Practices
|
||
|
||
### 1. Start Conservative, Tune Down
|
||
|
||
```gdb
|
||
# Start sensitive to see what's happening
|
||
(gdb) tune_sensitive
|
||
(gdb) continue
|
||
|
||
# If too noisy, relax specific thresholds
|
||
(gdb) Ctrl-C
|
||
(gdb) set_log_rate 10
|
||
(gdb) continue
|
||
|
||
# Still too noisy? Adjust threshold
|
||
(gdb) Ctrl-C
|
||
(gdb) set_high_nav 8000
|
||
(gdb) continue
|
||
```
|
||
|
||
### 2. Use Logging Rate Control
|
||
|
||
```gdb
|
||
# Keep all detection active but reduce log spam
|
||
(gdb) tune_normal
|
||
(gdb) set_log_rate 20 # Log every 20th
|
||
(gdb) continue
|
||
|
||
# Statistics still count everything!
|
||
# Periodic stats show full picture
|
||
```
|
||
|
||
### 3. Match Band Characteristics
|
||
|
||
```gdb
|
||
# 2.4GHz - lower rates, more interference
|
||
(gdb) set_rate_fallback 24
|
||
(gdb) set_high_nav 8000
|
||
|
||
# 5GHz - higher rates, cleaner
|
||
(gdb) set_rate_fallback 100
|
||
(gdb) set_high_nav 5000
|
||
```
|
||
|
||
### 4. Experiment Live
|
||
|
||
```gdb
|
||
# Change settings while monitoring
|
||
(gdb) continue
|
||
# ... let it run ...
|
||
(gdb) Ctrl-C
|
||
(gdb) set_mismatch_log 15000
|
||
(gdb) continue
|
||
# ... see effect immediately ...
|
||
```
|
||
|
||
### 5. Save Custom Profiles
|
||
|
||
Create your own `.gdbinit` commands:
|
||
|
||
```gdb
|
||
# Add to .gdbinit
|
||
define tune_my_network
|
||
set threshold_high_nav_us = 6500
|
||
set threshold_phy_rate_fallback_mbps = 120
|
||
set log_every_n_mismatches = 5
|
||
printf "Custom profile loaded\n"
|
||
end
|
||
```
|
||
|
||
Then use:
|
||
|
||
```gdb
|
||
(gdb) tune_my_network
|
||
```
|
||
|
||
## Performance Impact
|
||
|
||
**Zero!** Threshold changes have no performance impact:
|
||
|
||
- ✅ Variables are checked per frame (already happening)
|
||
- ✅ No function calls added
|
||
- ✅ No memory allocation
|
||
- ✅ Still processes 10,000+ frames/sec
|
||
|
||
## Troubleshooting
|
||
|
||
### Thresholds Not Taking Effect
|
||
|
||
```gdb
|
||
# Verify threshold was set
|
||
(gdb) print threshold_high_nav_us
|
||
$1 = 8000
|
||
|
||
# Check spelling
|
||
(gdb) show_thresholds
|
||
```
|
||
|
||
### Too Much Logging
|
||
|
||
```gdb
|
||
# Reduce log rate
|
||
(gdb) set_log_rate 50 # Log every 50th
|
||
|
||
# Or increase mismatch threshold
|
||
(gdb) set_mismatch_log 20000 # Only log >20ms
|
||
```
|
||
|
||
### Not Catching Issues
|
||
|
||
```gdb
|
||
# Make more sensitive
|
||
(gdb) tune_sensitive
|
||
|
||
# Or lower specific threshold
|
||
(gdb) set_high_nav 3000
|
||
```
|
||
|
||
## Example Session
|
||
|
||
Complete workflow:
|
||
|
||
```bash
|
||
# Start debugging
|
||
$ idf.py gdb
|
||
|
||
# Check current settings
|
||
(gdb) show_thresholds
|
||
|
||
# Start monitoring
|
||
(gdb) continue
|
||
|
||
# Run iperf from another machine
|
||
# Watch serial output...
|
||
|
||
# Too many logs? Adjust
|
||
(gdb) Ctrl-C
|
||
(gdb) set_log_rate 10
|
||
(gdb) continue
|
||
|
||
# Not catching subtle issues? Make sensitive
|
||
(gdb) Ctrl-C
|
||
(gdb) tune_sensitive
|
||
(gdb) continue
|
||
|
||
# Perfect! Check final settings
|
||
(gdb) Ctrl-C
|
||
(gdb) show_thresholds
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
WiFi Monitor Thresholds (GDB-tunable)
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
High NAV threshold: 3000 us
|
||
Duration mismatch log: 5000 us
|
||
PHY rate fallback: 150 Mbps
|
||
Duration multiplier: 1.5x expected
|
||
...
|
||
Log every N mismatches: 10
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
# Document these settings for your network!
|
||
```
|
||
|
||
## Summary
|
||
|
||
| Feature | Benefit |
|
||
|---------|---------|
|
||
| **Runtime tuning** | No rebuild needed |
|
||
| **GDB commands** | Easy to use |
|
||
| **Preset profiles** | Quick adjustment |
|
||
| **Zero overhead** | Full C code speed |
|
||
| **Live testing** | Tune while running |
|
||
| **Experiment freely** | Try different settings |
|
||
|
||
**Perfect combination of speed and flexibility!** 🎯
|
||
|
||
---
|
||
|
||
**Key Commands**:
|
||
- `show_thresholds` - See current settings
|
||
- `tune_sensitive` / `tune_normal` / `tune_relaxed` - Preset profiles
|
||
- `set_high_nav <us>` - Adjust high NAV threshold
|
||
- `set_log_rate <n>` - Control logging verbosity
|
||
- `continue` - Resume monitoring with new settings
|