FreeBSD PMC Validation Suite

Kernel-level validation framework for FreeBSD's hwpmc subsystem on modern x86 platforms, with a focus on AMD EPYC/Zen architecture. Validates core PMCs, uncore PMCs, IBS, multiplexing correctness, and process attach behavior.

Requirements

• FreeBSD 13.x / 14.x with hwpmc loaded
• pmcstat in PATH
• Python 3.9+ and pytest
• C compiler (cc) for workload compilation
• Root (or unprivileged PMC access configured)

# Install dependencies
pkg install python311 py311-pip py311-pytest

# Load hwpmc
kldload hwpmc
# Or permanently: echo 'hwpmc_load="YES"' >> /boot/loader.conf

# Verify
sysctl hw.pmc.nclasses   # should be > 0
pmcstat -L | head -20    # list available events

Quick Start

# Smoke test (30s)
./scripts/run_validation.sh --suite smoke

# Full suite
./scripts/run_validation.sh

# Specific suite: mux | attach | ibs | uncore | core | all
./scripts/run_validation.sh --suite attach --verbose

Test Coverage

Suite	File	What It Validates
core	test_counting_accuracy.py	Counter accuracy, reproducibility, IPC bounds
mux	test_multiplexing.py	Multiplexing correctness, scaling, no starvation
attach	test_attach.py	PMC attach to live processes, error handling, cleanup
ibs	test_ibs.py	AMD IBS fetch/op sampling (AMD-only)
uncore	test_uncore.py	L3 cache, memory bandwidth, Data Fabric (AMD)
system	test_system_wide.py	System-wide counting, per-CPU mode, sampling

Project Structure

pmc-validation/
├── conftest.py              # pytest fixtures: hwpmc detection, CPU info, cleanup
├── lib/
│   ├── pmc.py               # PmcCounter, PmcSampler, PmcMultiplexSession
│   └── workload.py          # WorkloadProcess: deterministic C workloads
├── tests/
│   ├── test_counting_accuracy.py
│   ├── test_multiplexing.py
│   ├── test_attach.py
│   ├── test_ibs.py
│   ├── test_uncore.py
│   └── test_system_wide.py
├── workloads/               # C source for deterministic test workloads
│   ├── loop_workload.c      # Integer loop (predictable instruction count)
│   ├── memory_workload.c    # Random-access (LLC miss / NUMA pressure)
│   └── branch_workload.c    # Branch predictor stress
├── scripts/
│   ├── run_validation.sh    # CI/CD entry point
│   ├── collect_pmc_data.sh  # Raw data collection helper
│   └── analyze_results.py   # Parse logs, detect anomalies, generate reports
├── docs/
│   └── test_plan.md         # Formal test plan with pass criteria
└── reports/                 # Generated test output (gitignored)

Key Design Principles

Ground truth first. Every accuracy test establishes a baseline with known-behavior workloads before exercising edge cases.

Error paths are first-class. Attach to dead PIDs, invalid event names, resource exhaustion — all must fail gracefully without kernel panics.

Reproducibility. Tests compile and run their own deterministic C workloads at -O0 so instruction counts are calculable from source.

AMD-aware. IBS and Data Fabric tests run only on AMD hardware (auto-skipped otherwise). EPYC-specific metrics (Infinity Fabric, per-CCD L3) are explicitly covered.

Analyzing Results

# Text summary
python3 scripts/analyze_results.py reports/LATEST/ --format text

# JSON for CI ingestion
python3 scripts/analyze_results.py reports/LATEST/ --format json -o results.json

# CSV for spreadsheet
python3 scripts/analyze_results.py reports/LATEST/ --format csv -o results.csv

Troubleshooting

Symptom	Fix
hwpmc not loaded	kldload hwpmc
All counters return 0	Check sysctl hw.pmc.nclasses > 0, run as root
High variance between runs	Disable powerd CPU frequency scaling
IBS tests skipped	Expected on non-AMD hardware
EPERM on attach	sysctl security.bsd.unprivileged_proc_debug=1

References

• man 4 hwpmc — FreeBSD hwpmc kernel interface
• man 8 pmcstat — pmcstat usage
• FreeBSD kernel source: sys/dev/hwpmc/hwpmc_amd.c
• AMD PPR for EPYC (pub #55803)

Target Platforms

• FreeBSD kernel PMU validation
• AMD EPYC platform bring-up
• Performance tooling verification
• CI/CD regression detection for hwpmc changes

---

Powered by FreeBSD hwpmc + pytest