M29 Follow-up: Generate Full Linux Hardware PMU Perf Artifacts

Context

PR #89 adds the Linux perf workflow, including:

• make perf-stat
• make perf-record
• scripts/perf_stat.sh
• scripts/perf_record.sh
• constrained Docker Desktop Linux artifacts under results/

The current artifacts are intentionally labeled as constrained-environment validation because Docker Desktop on macOS does not expose usable hardware PMU counters.

Current constrained preflight result:

perf stat -e cycles,instructions,branches,branch-misses,cache-references,cache-misses -- true

reported the required hardware counters as:

<not supported>

Therefore, PR #89 must not be treated as full hardware PMU evidence.

Goal

Generate and commit full Linux hardware PMU perf artifacts from a real PMU-capable Linux environment.

Acceptable environments include:

• bare-metal Linux laptop/desktop
• university Linux lab machine
• self-hosted GitHub runner on real Linux hardware
• Linux server with hardware perf_event access
• VM only if hardware PMU counters are actually exposed

Required Preflight

Run:

uname -a
perf --version
cat /proc/sys/kernel/perf_event_paranoid
perf stat -e cycles,instructions,branches,branch-misses,cache-references,cache-misses -- true

Acceptable result:

numeric values for all required counters
no <not supported>
no permission denied
no operation not permitted

Required counters:

cycles
instructions
branches
branch-misses
cache-references
cache-misses

Implementation Steps

1. Check out the repo on the PMU-capable Linux machine.
2. Build from a clean commit.
3. Run the full perf-stat workflow without partial mode:

make perf-stat

4. Run the perf-record workflow:

make perf-record

5. Confirm artifacts include:

Artifact: full hardware PMU evidence
Unsupported counters detected: no
Dirty tree: no

6. Confirm results/perf_stat_linux.txt contains numeric values for:

cycles
instructions
branches
branch-misses
cache-references
cache-misses

7. Confirm metadata is present:

git commit
dirty tree status
uname/kernel
compiler version
perf version
CPU/hardware info where available

8. Run:

make check

9. Commit regenerated artifacts under results/.

Acceptance Criteria

• Full PMU-capable Linux preflight passes.
• No required hardware counters are reported as <not supported>.
• results/perf_stat_linux.txt contains numeric hardware counter values.
• results/perf_stat_linux.txt is labeled full hardware PMU evidence.
• results/perf_report_linux.txt is regenerated from the same clean commit.
• Artifacts include clean git metadata.
• make check passes.
• Docs distinguish prior constrained Docker artifacts from full PMU artifacts.
• No production latency or optimization claim is made beyond the measured evidence.

Non-Goals

Do not:

• fake or synthesize hardware counter values
• treat software counters as equivalent to PMU counters
• relabel Docker Desktop output as full evidence
• broaden the milestone into optimization work
• claim benchmark generality beyond the measured environment