### Clone and Setup pmu-tools Repository

Source: https://github.com/andikleen/pmu-tools/blob/master/ucevent/README.md

This snippet shows the commands to clone the pmu-tools repository from GitHub and navigate into the pmu-tools directory. This is the initial setup step before running any of the profiling tools.

```bash
# git clone https://github.com/andikleen/pmu-tools
# cd pmu-tools
```

--------------------------------

### Build and Use jevents Library and Tools

Source: https://context7.com/andikleen/pmu-tools/llms.txt

This bash script outlines the process of building and installing the 'jevents' C library, downloading event lists, and using the provided command-line tools like 'listevents', 'showevent', and 'event-rmap'. It requires navigating into the jevents directory and running make commands, with sudo for installation.

```bash
# Build jevents library
cd jevents
make
sudo make install

# Download event lists before using
../event_download.py

# List all events with jevents
./listevents

# Show event details
./showevent LLC_MISSES

# Reverse map: find event name from raw encoding
./event-rmap
```

--------------------------------

### Monitor CPU Frequency Bands with Filters

Source: https://github.com/andikleen/pmu-tools/blob/master/ucevent/README.md

This example monitors the percentage of time the CPU frequency is within specific bands. `PCU.PCT_FREQ_BAND0` and `PCU.PCT_FREQ_BAND1` are used with filters `filter_band0=20` and `filter_band1=30` to define the frequency thresholds.

```bash
# ucevent.py PCU.PCT_FREQ_BAND0,filter_band0=20 PCU.PCT_FREQ_BAND1,filter_band1=30
```

--------------------------------

### Measure PCI Bandwidth with ucevent.py

Source: https://github.com/andikleen/pmu-tools/blob/master/ucevent/README.md

This example demonstrates how to measure PCI bandwidth using `ucevent.py`. It specifies an interval of 2000 milliseconds for reporting and monitors the `CBO.PCIE_DATA_BYTES` event for 10 seconds using `sleep 10`. The output is separated by CPU socket.

```bash
# ucevent.py -I 2000  CBO.PCIE_DATA_BYTES sleep 10
```

--------------------------------

### Serving Data for dygraphs Plotting

Source: https://github.com/andikleen/pmu-tools/blob/master/ucevent/README.md

This example demonstrates how to serve the collected data (`out.csv`) and an HTML template (`dygraph-out.html`) using Python's built-in HTTP server. This allows the dygraphs JavaScript library to plot the data interactively in a web browser.

```bash
# mkdir web
# cp dygraph-out.html web/index.html
# cp out.csv web
# cd web
# python -m SimpleHTTPServer
# ... point web browser at localhost:8000 ...
```

--------------------------------

### Measure DIMM Page Hits with Specific Socket Binding

Source: https://github.com/andikleen/pmu-tools/blob/master/ucevent/README.md

This example measures DIMM page hits on socket 0 using `ucevent.py` with verbose output. It also binds the `numactl` workload to socket 0. The output shows the generated `perf stat` command and the collected metrics.

```bash
# ucevent.py -v --socket 0 iMC.PCT_REQUESTS_PAGE_HIT numactl --cpunodebind=0 workload
```

--------------------------------

### Serve Toplev Data via Web Interface with tl-serve

Source: https://context7.com/andikleen/pmu-tools/llms.txt

tl-serve.py starts a web server to display 'toplev' output in an interactive browser using dygraphs. It requires downloading the dygraphs JavaScript library. The tool takes a CSV file of measurements and serves it on http://localhost:9001/ by default.

```bash
# Download dygraphs (one-time setup)
wget http://dygraphs.com/1.0.1/dygraph-combined.js

# Collect toplev data
toplev --all -I 100 -o measurements.csv sleep 30

# Start web server
tl-serve.py measurements.csv

# Browse to http://localhost:9001/
```

--------------------------------

### Generating Excel output with toplev

Source: https://github.com/andikleen/pmu-tools/wiki/toplev-manual

This example shows how to generate an XLSX Excel file from toplev output using the --xlsx argument. It includes options for adding charts (--xchart) and normalized data sheets (--xnormalize). The generated file can be viewed with spreadsheet applications like gnumeric or Excel.

```bash
$ toplev -l3 --metrics --xlsx file.xlsx --xchart --xnormalize ./workloads/CLANG10s
```

--------------------------------

### Serve TLB Data with tl-serve

Source: https://github.com/andikleen/pmu-tools/blob/master/TOOLS.md

Displays toplev.py output in a web browser. Requires downloading the dygraphs JavaScript library. It works by running toplev.py to generate CSV data, then starting tl-serve.py to serve this data over HTTP.

```bash
wget http://dygraphs.com/1.0.1/dygraph-combined.js
toplev.py --all -I 100 -o x.csv ...
tl-serve.py x.csv
# Browse http://localhost:9001/
```

--------------------------------

### Self-Profiling with Cycle Counting (C)

Source: https://github.com/andikleen/pmu-tools/blob/master/jevents/README.md

Demonstrates simplified self-profiling using the rdpmc library to read CPU cycles. Requires /sys/devices/cpu/rdpmc to be enabled. Note that this is a basic example and real benchmarks may need more sophisticated setups.

```c
#include "rdpmc.h"

struct rdpmc_ctx ctx;
unsigned long long start, end;

if (rdpmc_open(PERF_COUNT_HW_CPU_CYCLES, &ctx) < 0) ... error ...
start = rdpmc_read(&ctx);
... your workload ...
end = rdpmc_read(&ctx);

```

--------------------------------

### Plotting toplev output with tl-barplot

Source: https://github.com/andikleen/pmu-tools/wiki/toplev-manual

This section illustrates how to generate time-series plots from toplev output using the tl-barplot.py tool. It shows how to specify CPUs, output files, and provides an example for plotting multiple threads of a core. Plotting requires the matplotlib library.

```bash
toplev.py -l3 -I 100 -x, -o x.csv workload
tl-barplot.py --cpu C0-T0 -o workload-c0-t0.png
tl-barplot.py --cpu C0-T1 -o workload-c0-t1.png
```

--------------------------------

### Plot Time Series Data with interval-plot

Source: https://context7.com/andikleen/pmu-tools/llms.txt

This command-line tool visualizes time-series performance data collected by 'toplev' or 'perf stat'. It takes a CSV file as input and generates plots using matplotlib. Options allow specifying plot levels and metrics. Requires matplotlib to be installed.

```bash
# Collect interval data with toplev
toplev -l2 -I 100 -x, -o data.csv sleep 30

# Plot the data
interval-plot data.csv

# Collect and plot perf stat data
perf stat -I 1000 -x, -o perf.csv -e cycles,instructions sleep 20
interval-plot perf.csv

# Configure plot details
interval-plot --level 1 --metrics data.csv
```

--------------------------------

### Set up ucevent Environment and Export Path

Source: https://github.com/andikleen/pmu-tools/blob/master/ucevent/README.md

These commands set up the environment for running ucevent.py. It involves changing the directory to 'ucevent' and adding the current directory to the PATH environment variable. This ensures that `ucevent.py` can be executed directly.

```bash
# cd pmu-tools/ucevent
# export PATH=$PATH:$(pwd)
```

--------------------------------

### Sampling with ocperf

Source: https://github.com/andikleen/pmu-tools/wiki/toplev-manual

This snippet demonstrates how to use ocperf to record sampling events for a workload and then analyze the results with perf report. It also shows how ocperf can be used to directly generate and run sampling commands.

```bash
% ocperf.py record -e mem_load_uops_retired.l1_hit:pp workload
% perf report
```

```bash
ocperf.py --show-sample --run-sample workload
```

--------------------------------

### Generate Toplev Measurement Script

Source: https://github.com/andikleen/pmu-tools/wiki/Running-toplev-offline

On the system where toplev is installed, generate a script to perform the performance measurement on the target system. This script uses the previously collected cpuinfo and topology files. Various options can be passed to customize the measurement.

```shell
toplev --force-topology topology --force-cpuinfo cpuinfo --gen-script <toplev options> > script
```

--------------------------------

### Analyze CPU Retiring Bottlenecks with toplev.py

Source: https://github.com/andikleen/pmu-tools/wiki/toplev-manual

This command uses toplev.py to analyze the 'Retiring' metric, indicating CPU slots fraction where the CPU was retiring uops. It helps identify if the CPU is busy executing instructions or stalled. The output shows the percentage of time spent retiring and provides details on sampling events.

```bash
% toplev.py -l3 --single-thread ./c1-o2  numbers
RET     Retiring:			       83.66%
RET     Retiring.Base:			  83.62%
	This metric represents slots fraction where the CPU was
	retiring uops not originated from the microcode-sequencer...
	Sampling events:  inst_retired.prec_dist:pp
```

--------------------------------

### event_download: Event List Downloader with Bash

Source: https://context7.com/andikleen/pmu-tools/llms.txt

The event_download script downloads Intel perfmon event lists from GitHub for CPU event resolution. It supports downloading events for the current CPU, all supported CPUs, or specific CPU strings.  It also allows the user to specify a custom perfmon repository or override the CPU information source.

```bash
./event_download.py
./event_download.py -a
./event_download.py GenuineIntel-06-55-04
export PERFMONDIR=file:///tmp/perfmon
./event_download.py
export CPUINFO=/path/to/cpuinfo
./event_download.py
```

--------------------------------

### Analyze CPU Backend Bound Bottlenecks with toplev.py (Assembly)

Source: https://github.com/andikleen/pmu-tools/wiki/toplev-manual

This command analyzes the 'Backend_Bound' metric, indicating CPU stalls due to memory or core computation issues. The output details percentages for Memory Bound (L1, L3) and Core Bound (Ports_Utilization), providing insights into bandwidth and execution bottlenecks. It uses an optimized AVX2 assembly version of the code.

```bash
% toplev.py -l3 --single-thread ./c-asm  numbers
BE      Backend_Bound:			  64.15%
BE/Mem  Backend_Bound.Memory_Bound:	      ...
BE/Mem  Backend_Bound.Memory_Bound.L1_Bound:    49.32%
	This metric represents how often CPU was stalled without
	missing the L1 data cache...
	Sampling events:  mem_load_uops_retired.l1_hit:pp,mem_load_uops_retired.hit_lfb:pp
BE/Mem  Backend_Bound.Memory_Bound.L3_Bound:    48.68%
	This metric represents how often CPU was stalled on L3 cache
	or contended with a sibling Core...
	Sampling events:  mem_load_uops_retired.l3_hit:pp
BE/Core Backend_Bound.Core_Bound:	       28.27%
BE/Core Backend_Bound.Core_Bound.Ports_Utilization: 28.27%
	This metric represents cycles fraction application was
	stalled due to Core computation issues (non divider-
	related)...
```

--------------------------------

### ocperf Python API

Source: https://context7.com/andikleen/pmu-tools/llms.txt

This Python module provides a programmatic interface for event resolution and conversion to perf format. It allows users to find event maps, get events by symbolic name, and override CPU detection using environment variables. This enables integrating event information into custom scripts and tools.

```python
import ocperf

# Find event map for current CPU
emap = ocperf.find_emap()
if not emap:
    sys.exit("Unknown CPU or cannot find event table")

# Get event by symbolic name
ev = emap.getevent("BR_MISP_EXEC.ANY")
if ev:
    print("name:", ev.output())
    print("raw form:", ev.output(use_raw=True))
    print("description:", ev.desc)

# Override CPU detection with environment variable
# export EVENTMAP=GenuineIntel-06-37
# or point to specific CSV file
# export EVENTMAP=/path/to/events.csv
```

--------------------------------

### Serving toplev plots with tl-serve

Source: https://github.com/andikleen/pmu-tools/wiki/toplev-manual

This snippet explains how to use the experimental tl-serve tool to plot toplev CSV files in a web browser using dygraphs. It involves downloading dygraph, running tl-serve, and accessing the plots via localhost:9001. This tool supports multiple CPUs and interactive plotting.

```bash
wget http://dygraphs.com/1.0.1/dygraph-combined.js
```

```bash
toplev.py -x, -I 100 -o x.csv workload &
tl-serve.py x.csv
```

--------------------------------

### Access Intel MSRs using msr.py Python Library

Source: https://context7.com/andikleen/pmu-tools/llms.txt

This Python code demonstrates using the 'msr' library to read and write Intel Model Specific Registers (MSRs). It shows how to target specific CPUs, write values, and manipulate bits using functions like readmsr, writemsr, and changebit. Requires the msr library to be installed.

```python
import msr

# Read MSR from specific CPU
value = msr.readmsr(0x123, cpu=3)
print(f"MSR 0x123 on CPU 3: {value:x}")

# Write MSR on all CPUs
msr.writemsr(0x123, 0x1)

# Set bit 0 in MSR 0x123 on all CPUs
current = msr.readmsr(0x123, cpu=0)
msr.writemsr(0x123, current | 1)

# Clear bit 5 using changebit
msr.changebit(0x123, bit=5, val=0)
```

--------------------------------

### List Available Metrics with ucevent.py

Source: https://github.com/andikleen/pmu-tools/blob/master/ucevent/README.md

Running `ucevent.py` without any arguments lists the available uncore metrics, categorized by component like CBO (Core Buffer Occupancy) and PCU (Power Control Unit). This command helps in discovering what can be monitored.

```bash
# ucevent.py
```

--------------------------------

### List PCU Events with Descriptions

Source: https://github.com/andikleen/pmu-tools/blob/master/ucevent/README.md

This command lists all events related to the Power Management Control Unit (PCU), including their descriptions. The `--desc` flag shows descriptions, and `--cat PCU` filters for PCU events. `--unsupported` may also be included to show all possible events.

```bash
# ucevent.py --desc --unsupported --cat PCU
```

--------------------------------

### Monitor Multiple Performance Metrics Simultaneously

Source: https://context7.com/andikleen/pmu-tools/llms.txt

This command allows for monitoring several performance metrics concurrently, such as memory bandwidth, PCIe data bytes, and QPI data bandwidth. It uses the 'ucevent' tool and specifies a short monitoring interval and duration. The output is a combined stream of the requested metrics.

```bash
ucevent -I 1000 MEM.BW_TOTAL,CBO.PCIE_DATA_BYTES,QPI.DATA_BW sleep 10
```

--------------------------------

### Using Equations to Scale Metrics with ucevent.py

Source: https://github.com/andikleen/pmu-tools/blob/master/ucevent/README.md

Illustrates the use of `ucevent.py` to apply equations for scaling performance metrics, such as converting BYTES to more readable units like KB, MB, or GB. Equations must be quoted to handle spaces or parentheses correctly. Wildcards are not permitted in equations, and only events from the same unit can be referenced.

```bash
ucevent.py "CBO.MEM_WB_BYTES / KB"
```

--------------------------------

### Manually Specifying Event Groups with ucevent

Source: https://github.com/andikleen/pmu-tools/blob/master/ucevent/README.md

Demonstrates how to manually group performance monitoring events using curly braces `{}` with the `ucevent` command. This ensures that events within the group are monitored concurrently, reducing potential inaccuracies. Events not fitting within the available counters or filters for a unit may result in errors.

```bash
# ucevent '{' iMC.MEM_BW_WRITES iMC.MEM_BW_WRITES_TOTAL '}'
```

--------------------------------

### Setting Proxy for Internet Access

Source: https://github.com/andikleen/pmu-tools/wiki/Running-ocperf-toplev-when-not-on-the-internet

This snippet shows how to configure the HTTPS proxy environment variable. This is often sufficient in corporate environments to allow tools to download necessary resources.

```bash
export https_proxy=https://proxyname...
```

--------------------------------

### Configuring Multiplexing Interval with sysfs

Source: https://github.com/andikleen/pmu-tools/blob/master/ucevent/README.md

Shows how to adjust the multiplexing interval for performance monitoring events via the sysfs filesystem. This allows users to control how frequently the PMU driver switches between different sets of events during measurement. A shorter interval can reduce inaccuracies but may increase core wakeups. The default is 4ms.

```bash
echo 10 > /sys/bus/event_source/devices/uncore_name/perf_event_mux_interval_ms
```

--------------------------------

### Monitor QPI Interconnect Traffic with ucevent

Source: https://context7.com/andikleen/pmu-tools/llms.txt

This command monitors QPI interconnect data bandwidth over a specified duration. It requires the 'ucevent' tool and outputs numerical bandwidth values. No specific input files are needed, but the output is a stream of data.

```bash
ucevent -I 1000 QPI.DATA_BW sleep 20
```

--------------------------------

### toplev: TopDown Microarchitectural Analysis with Bash

Source: https://context7.com/andikleen/pmu-tools/llms.txt

The toplev tool uses Intel's TopDown methodology to identify CPU pipeline bottlenecks. It provides hierarchical analysis across multiple levels, supporting single-threaded programs, bottleneck analysis, and drill-down capabilities.  It integrates with the Linux perf interface to measure and analyze performance.

```bash
toplev -l2 program
toplev -l1 --single-thread program
toplev -NB program
toplev -NB --run-sample program
toplev --drilldown --only-bottleneck program
toplev -l3 --no-desc -I 100 -x, sleep 10
toplev --all --core C0 taskset -c 0,1 program
toplev --all --xlsx output.xlsx -a sleep 10
toplev --host --guest -l2 program
```

--------------------------------

### Cloning pmu-events Repository from GitHub

Source: https://github.com/andikleen/pmu-tools/wiki/Running-ocperf-toplev-when-not-on-the-internet

This demonstrates how to clone the `perfmon` repository from GitHub, which contains CPU event files. The `PERFMONDIR` environment variable can then be set to point to this local repository.

```bash
git clone https://github.com/intel/perfmon
```

```bash
export PERFMONDIR=file:///path/to/perfmon
```

--------------------------------

### cputop: CPU Topology Query with Bash

Source: https://context7.com/andikleen/pmu-tools/llms.txt

The cputop tool queries CPU topology, generates CPU masks for taskset, and enables/disables hyperthreading. It allows querying specific cores, threads, sockets, and CPU types.  The tool supports complex queries combining conditions for flexible control over CPU resources.

```bash
cputop "socket == 0"
cputop "thread == 0 and socket == 0"
cputop "thread == 1" offline
cputop offline online
toplev $(cputop core taskset) workload
cputop atom
cputop "type == 'atom'"
cputop "socket == 0 and thread == 0"
```

--------------------------------

### Manually Setting Event Map Environment Variables

Source: https://github.com/andikleen/pmu-tools/wiki/Running-ocperf-toplev-when-not-on-the-internet

This shows how to manually specify the paths to event map files using environment variables like `EVENTMAP`, `OFFCORE`, and `UNCORE`. These can override default settings and specify specific CPU identifiers.

```bash
export EVENTMAP=/path/to/GenuineIntel...-core.json
export OFFCORE=...
export UNCORE=...
```

--------------------------------

### Downloading All Event Lists with event_download.py

Source: https://github.com/andikleen/pmu-tools/wiki/Running-ocperf-toplev-when-not-on-the-internet

This command downloads all available CPU event lists using the `event_download.py` script. The downloaded files are typically stored in `~/.cache/pmu-events` and can be copied to offline systems.

```bash
event_download.py -a
```

--------------------------------

### Display Memory Read/Write Bandwidth with Scaling

Source: https://github.com/andikleen/pmu-tools/blob/master/ucevent/README.md

This command displays the memory read and write bandwidth in Gigabytes per second (GB/s). It uses the `--scale GB` option to format the output and monitors `iMC.MEM_BW_WRITES` and `iMC.MEM_BW_READS` events.

```bash
# ucevent.py  --scale GB iMC.MEM_BW_WRITES iMC.MEM_BW_READS
```

--------------------------------

### List Available Uncore Events

Source: https://context7.com/andikleen/pmu-tools/llms.txt

This command lists all available uncore (microarchitectural) performance events that can be monitored. It utilizes the 'ucevent --list' command. The output is a plain text list of event names.

```bash
ucevent --list
```

--------------------------------

### ocperf: Symbolic Event Name Wrapper with Bash

Source: https://context7.com/andikleen/pmu-tools/llms.txt

The ocperf tool wraps Linux perf to enable symbolic Intel event names, automatically downloading event lists. This allows users to use human-readable event names instead of raw codes. It supports listing events, using events with perf stat, recording data, and reporting on recorded data.

```bash
ocperf list
ocperf stat -e BR_MISP_EXEC.ANY,INST_RETIRED.ANY program
ocperf record -c default -e LLC_MISSES program
ocperf report
ocperf --force-download list
```

--------------------------------

### Check for Available Uncore Devices

Source: https://context7.com/andikleen/pmu-tools/llms.txt

These commands check for the presence of uncore performance monitoring devices on the system. 'lspci | grep Performance' lists PCI devices related to performance, and 'ls -d /sys/bus/event_source/devices/uncore_*' checks the sysfs filesystem for uncore device entries. They output system information.

```bash
lspci | grep Performance
```

```bash
ls -d /sys/bus/event_source/devices/uncore_*
```

--------------------------------

### Utilize jevents C Library for Linux Performance Events

Source: https://context7.com/andikleen/pmu-tools/llms.txt

This C code snippet demonstrates using the 'jevents' library for simplified access to Linux performance events. It shows how to perform self-profiling using direct counter reads with rdpmc_open, rdpmc_read, and rdpmc_close, and how to resolve symbolic event names into perf_event_attr structures.

```c
#include "jevents.h"
#include "rdpmc.h"
#include <linux/perf_event.h>

// Self-profiling with direct counter reads
struct rdpmc_ctx ctx;
unsigned long long start, end;

if (rdpmc_open(PERF_COUNT_HW_CPU_CYCLES, &ctx) < 0) {
    perror("rdpmc_open");
    exit(1);
}

start = rdpmc_read(&ctx);
// ... your workload ...
end = rdpmc_read(&ctx);
printf("Cycles: %llu\n", end - start);
rdpmc_close(&ctx);

// Resolve symbolic event names
struct perf_event_attr attr;
if (resolve_event("LLC_MISSES", &attr) < 0) {
    fprintf(stderr, "Event not found\n");
    exit(1);
}

// Modify attributes as needed
attr.sample_period = 100000;
attr.sample_type = PERF_SAMPLE_ADDR | PERF_SAMPLE_IP;

// Open with resolved event
if (rdpmc_open_attr(&attr, &ctx) < 0) {
    perror("rdpmc_open_attr");
    exit(1);
}

// Read counters
unsigned long long count = rdpmc_read(&ctx);
printf("Event count: %llu\n", count);

```

--------------------------------

### Generate CSV for Complex Workload Analysis with toplev.py

Source: https://github.com/andikleen/pmu-tools/wiki/toplev-manual

This command generates a CSV file for analyzing complex workloads using toplev.py with interval and CSV output options. The `-I` option specifies the interval in microseconds, and `-x,` tells toplev to output comma-separated values. The resulting CSV can be processed by other tools.

```bash
% toplev.py -I 1000 -l3 -x, -o tl-build.csv make
...
```