hardware-counters

Collect and interpret CPU hardware performance counters with perf, PAPI, and Intel PCM.

Updated Aug 27, 2026

Search Tags:#perf #papi #ipc #pmu #cache-misses #branch-mispredictions #performance-counters

Ready to run

npx skills add https://github.com/awfixers-stuff/opencode-config --skill hardware-counters-awfixers-stuff

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: hardware-counters
Source: https://github.com/awfixers-stuff/opencode-config/tree/main/skills/hardware-counters
Command: npx skills add https://github.com/awfixers-stuff/opencode-config --skill hardware-counters-awfixers-stuff

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Measure and interpret low-level CPU performance metrics to diagnose performance bottlenecks, quantify instruction and cache behavior, and correlate hardware events to source-level hotspots.

Core Features & Use Cases

Collect aggregate hardware event counts and derived metrics using perf stat and custom PMU event lists to compute IPC, CPI, and MPKI.
Use perf record and perf annotate to correlate cache misses and branch mispredictions to source lines, and use PAPI for portable counter access in C programs.
Real-world example: identify whether a workload is memory-bound by comparing IPC and LLC miss rates, then use perf annotate to locate the offending code region for cache optimization.

Quick Start

Use the hardware-counters skill to collect instructions, cycles, cache-misses, and branch-misses with perf, compute IPC and miss rates, and suggest hotspots to inspect with perf annotate.

Frequently Asked Questions about hardware-counters

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I use Linux perf to collect hardware performance counters like cache-misses and branch-mispredictions?▼

Use the hardware-counters skill to collect hardware performance counters with Linux perf stat and custom PMU event lists. It guides you through selecting PMU events and aggregating counts for cache-misses and branch-mispredictions to diagnose CPU bottlenecks.

What is a good IPC or CPI threshold for identifying CPU performance bottlenecks?▼

IPC and CPI thresholds help identify CPU performance bottlenecks by quantifying instruction and cache behavior. The skill provides specific formulas for calculating IPC, CPI, and MPKI, alongside threshold recommendations to determine if a workload is memory-bound.

How do I correlate cache misses to specific source lines using perf annotate?▼

Correlate cache misses to source lines using perf record and perf annotate workflows. The skill provides procedures to map low-level hardware events directly to source-level hotspots, enabling targeted cache optimization for offending code regions.

Can I access PMU events portably in C programs using PAPI?▼

Yes, you can access PMU events in C programs using PAPI. The skill outlines PAPI usage patterns for portable counter access, allowing native applications to measure and interpret low-level CPU metrics directly within the code.

Does this skill support system-wide bandwidth and core IPC sampling with Intel PCM?▼

Yes, the skill supports Intel PCM for system-wide bandwidth and core IPC sampling. It provides guidance on collecting aggregate hardware event counts and derived metrics to measure and interpret low-level CPU performance across the entire system.