PMC based Performance Measurement in FreeBSD

About Articles How to contact me Projects Site Map

Joseph Koshy > Projects > PMC based Performance Measurement in FreeBSD

Features Status Architecture Snapshots Acknowledgements

PMC based Performance Measurement Tools for FreeBSD

This is a performance measurement framework for FreeBSD which uses the hardware performance measurement counters in modern CPUs to provide low-overhead, non-intrusive, system-wide measurement of production systems.

Some parts of this work are present in FreeBSD 6.0 and later. Development of new features is happening in -CURRENT.

Alert: I'm currently looking for sponsors for PmcTools work. Please contact me if you would like to help support my work.

These pages are being slowly moved over to the FreeBSD wiki at Please check there too for information and updates.


Jan 2007
Looking for sponsors for PmcTools.
11 Nov 2006
LibElf is now in -CURRENT.
01 Nov 2006
LibElf patch and test suite.
01 Jun 2006
New wiki page:
02 Apr 2006
pmcstat(8) in -CURRENT can now log events over a network socket.
20 Mar 2006
[patch] Profiling of Kernel Modules
18 Feb 2006
21 Oct 2005
Experimental Wiki page for possible Pmc based projects.
01 Jul 2005
pmcstat(8) gprof output mode in -CURRENT, many bug fixes. You may want to browse the bug list.
19 Apr 2005
The equivalent of Snapshot 6 is now in FreeBSD -CURRENT.
Dec 2004
A short tutorial for the API is now available.

Planned features and their status

Feature Status Description
SMP support? Ready Supports profiling on multi-processor systems.
System-wide event counting? Ready Allows you to get a global view of the events happening on hardware as the system runs.
System-wide statistical sampling? Ready Allows you to profile userland and kernel (including interrupt handlers) at the same time.
Process-"virtual" PMCs? Ready Measure hardware events seen by the system when specific processes are scheduled on the CPU(s).
Profiling "kernel threads" Ready Allows you to profile specific kernel threads.
Profiling threaded code Needs testing. Allows you to profile threaded applications.
Profiling of loadable kernel modules and dlopen() libraries Ready. Allows dynamically loaded objects (in the kernel or in userland) to be profiled.
Allow perfmon instructions like RDPMC? Ready Allows processes that allocated and attached PMCs to themselves to use low-overhead machine instructions to read their PMCs.
Simultaneous process-virtual and system-wide profiling? Ready Allows you to get a bird-eye view of system-wide hot-spots and drill down further into troublesome processes.
Multiple processes using PMCs at the same time? Ready The hwpmc(4) driver multiplexes available PMC resources, allowing multiple PMC-using processes to be executing concurrently.
Works on stock (i.e., optimized) binaries? Ready You can do basic profiling on stock binaries.
Callgraphs? Under design An oft-requested feature.
Integration with system profiling tools gprof(1), kgmon(8)? In progress. You can use gprof(1) for your analyses, for now.
Cross-architecture PMC API? Ready See pmc(3).
Remote logging? Ready Profile logs can be collected and analysed on a different system; allows for profiling embedded systems.
Low-overhead? Partially characterized Target: less than 5% processor overhead when active. Negligible overhead when present but turned off. We appear to be on target for most workloads.
Supports all PMCs on CPUs running FreeBSD's Tier-1&2 architectures? Partially there Currently the following PMCs are supported: AMD64 "K8", AMD Athlon XP "K7", Intel P-Pro/P-II/P-III/Celeron/Pentium-M, Intel P4(HTT). Intel Pentium/MMX support is planned shortly (if I can get -CURRENT to run on it).
GUI Analysis tools? Planned Help wanted! PAPI interface, spiffy GUI viewers are desired.
Documentation In progress Manual pages: for the library pmc(3), driver hwpmc(4) and the administrative tools pmcstat(8), pmccontrol(8). A tutorial on using the pmc(3) API is also in progress.
Test-suite? Planned. A test suite for pmc(3) and hwpmc(4) is planned.
Scripting language API? In progress A Python wrapper around pmc(3) is being written.

Status of Components

Item State Description
Kernel Module [hwpmc(4)] Done

Implementations are available for AMD Athlon XP, AMD Athlon 64, Intel P4/HTT and Intel P-Pro/P-II/P-III class CPUs.

Programming API [pmc(3)] Done

An API to access the facilities offered by hwpmc(4).

pmccontrol(8) Done.

Administrative control of the hwpmc(4) driver.

pmcstat(8) Done.

Performance measurements using hwpmc(4).

Python Wrapper Available A Python Wrapper for pmc(3). A wrapper for pmclog(3) is under development.
Test Suite In Design A regression test suite for pmc(3) and hwpmc(4).
PAPI interface In design

How the machine-dependent layer of the PAPI library will interface with this subsystem.

Log file format Done

This is the format of the log file generated by hwpmc(4). A set of parser routines ( pmclog_* ) for the format is present in pmclog(3).

A reporting tool equivalent to gprof(1) Done

Use pmcstat(8) -g to generate gprof compatible flat profiles.

AMD x86-64 Support Done

AMD64 now has 'first-class' support.

Alpha/PPC/Sparc64/IA-64/Other Support Desired I don't have access to these machines. If you want to see these implemented please consider loaning hardware.

System architecture

The system has the following parts (Figure 1):

FCPI Architecture


  1. A loadable kernel module that manages the on-CPU performance counters and collects performance data. This module will also interface with other parts of the kernel to collect the other book-keeping data needed.
  2. A userland daemon (pmcstat(8)) that manages the data collection process.
  3. Userland tools that analyze the captured data and present the result of the analysis to the user. Simple analyses may be run using pmcstat(8) and .
  4. Support for APIs like PAPI that measure per-process performance.

Related Work

There are many projects similar to this one. These are listed on a separate page.


I would like to gratefully acknowledge the help and encouragement from my friends in this project:

Last Modified: Sat Apr 21 22:53:23 2007
Site Search Google