Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PMC(3)		       FreeBSD Library Functions Manual			PMC(3)

NAME
     pmc -- library for	accessing hardware performance monitoring counters

LIBRARY
     Performance Monitoring Counters Interface Library (libpmc,	-lpmc)

SYNOPSIS
     #include <pmc.h>

DESCRIPTION
     The Performance Monitoring	Counters Interface Library (libpmc, -lpmc)
     provides a	programming interface that allows applications to use hardware
     performance counters to gather performance	data about specific processes
     or	for the	system as a whole.  The	library	is implemented using the
     lower-level facilities offered by the hwpmc(4) driver.

   Key Concepts
     Performance monitoring counters (PMCs) are	represented by the library
     using a software abstraction.  These ``abstract'' PMCs can	have one two
     scopes:

     +o	 System	scope.	These PMCs measure events in a whole-system manner,
	 i.e., independent of the currently executing thread.  System scope
	 PMCs are allocated on specific	CPUs and do not	migrate	between	CPUs.
	 Non-privileged	process	are allowed to allocate	system scope PMCs if
	 the hwpmc(4) sysctl tunable: security.bsd.unprivileged_syspmcs	is
	 non-zero.

     +o	 Process scope.	 These PMCs only measure hardware events when the pro-
	 cesses	they are attached to are executing on a	CPU.  In an SMP	sys-
	 tem, process scope PMCs migrate between CPUs along with their target
	 processes.

     Orthogonal	to PMC scope, PMCs may be allocated in one of two operational
     modes:

     +o	 Counting PMCs measure events according	to their scope (system or
	 process).  The	application needs to explicitly	read these counters to
	 retrieve their	value.

     +o	 Sampling PMCs cause the CPU to	be periodically	interrupted and	infor-
	 mation	about its state	of execution to	be collected.  Sampling	PMCs
	 are used to profile specific processes	and kernel threads or to pro-
	 file the system as a whole.

     The scope and operational mode for	a software PMC are specified at	PMC
     allocation	time.  An application is allowed to allocate multiple PMCs
     subject to	availability of	hardware resources.

     The library uses human-readable strings to	name the event being measured
     by	hardware.  The syntax used for specifying a hardware event along with
     additional	event specific qualifiers (if any) is described	in detail in
     section EVENT SPECIFIERS below.

     PMCs are associated with the process that allocated them and will be
     automatically reclaimed by	the system when	the process exits.  Addition-
     ally, process-scope PMCs have to be attached to one or more target	pro-
     cesses before they	can perform measurements.  A process-scope PMC may be
     attached to those target processes	that its owner process would otherwise
     be	permitted to debug.  An	owner process may attach PMCs to itself	allow-
     ing it to measure its own behavior.  Additionally,	on some	machine	archi-
     tectures, such self-attached PMCs may be read cheaply using specialized
     instructions supported by the processor.

     Certain kinds of PMCs require that	a log file be configured before	they
     may be started.  These include:
     +o	 System	scope sampling PMCs.
     +o	 Process scope sampling	PMCs.
     +o	 Process scope counting	PMCs that have been configured to report PMC
	 readings on process context switches or process exits.
     Upto one log file may be configured per owner process.  Events logged to
     a log file	may be subsequently analyzed using the pmclog(3) family	of
     functions.

   Supported CPUs
     The CPUs known to the PMC library are named by the	enum pmc_cputype enu-
     meration.	Supported CPUs include:
     PMC_CPU_AMD_K7	     AMD Athlon	CPUs.
     PMC_CPU_AMD_K8	     AMD Athlon64 CPUs.
     PMC_CPU_INTEL_ATOM	     Intel Atom	CPUs and other CPUs conforming to ver-
			     sion 3 of the Intel performance measurement
			     architecture.
     PMC_CPU_INTEL_CORE	     Intel Core	Solo and Core Duo CPUs,	and other CPUs
			     conforming	to version 1 of	the Intel performance
			     measurement architecture.
     PMC_CPU_INTEL_CORE2     Intel Core2 Solo, Core2 Duo and Core2 Extreme
			     CPUs, and other CPUs conforming to	version	2 of
			     the Intel performance measurement architecture.
     PMC_CPU_INTEL_P5	     Intel Pentium CPUs.
     PMC_CPU_INTEL_P6	     Intel Pentium Pro CPUs.
     PMC_CPU_INTEL_PII	     Intel Pentium II CPUs.
     PMC_CPU_INTEL_PIII	     Intel Pentium III CPUs.
     PMC_CPU_INTEL_PIV	     Intel Pentium 4 CPUs.
     PMC_CPU_INTEL_PM	     Intel Pentium M CPUs.

   Supported PMCs
     PMC supported by this library are named by	the enum pmc_class enumera-
     tion.  Supported PMC kinds	include:
     PMC_CLASS_IAF     Fixed function hardwre counters presents	in CPUs	con-
		       forming to the Intel performance	measurement architec-
		       ture version 2 and later.
     PMC_CLASS_IAP     Programmable hardware counters present in CPUs conform-
		       ing to the Intel	performance measurement	architecture
		       version 1 and later.
     PMC_CLASS_K7      Programmable hardware counters present in AMD Athlon
		       CPUs.
     PMC_CLASS_K8      Programmable hardware counters present in AMD Athlon64
		       CPUs.
     PMC_CLASS_P4      Programmable hardware counters present in Intel Pentium
		       4 CPUs.
     PMC_CLASS_P5      Programmable hardware counters present in Intel Pentium
		       CPUs.
     PMC_CLASS_P6      Programmable hardware counters present in Intel Pentium
		       Pro, Pentium II,	Pentium	III, Celeron, and Pentium M
		       CPUs.
     PMC_CLASS_TSC     The timestamp counter on	i386 and amd64 architecture
		       CPUs.

   PMC Capabilities
     Capabilities of performance monitoring hardware are denoted using the
     enum pmc_caps enumeration.	 Supported capabilities	include:
     PMC_CAP_CASCADE	   The ability to cascade counters.
     PMC_CAP_EDGE	   The ability to count	negated	to asserted transi-
			   tions of the	hardware conditions being probed for.
     PMC_CAP_INTERRUPT	   The ability to interrupt the	CPU.
     PMC_CAP_INVERT	   The ability to invert the sense of the hardware
			   conditions being measured.
     PMC_CAP_PRECISE	   The ability to perform precise sampling.
     PMC_CAP_QUALIFIER	   The hardware	allows monitored to be further quali-
			   fied	in some	system dependent way.
     PMC_CAP_READ	   The ability to read from performance	counters.
     PMC_CAP_SYSTEM	   The ability to restrict counting of hardware	events
			   to when the CPU is running privileged code.
     PMC_CAP_THRESHOLD	   The ability to ignore simultaneous hardware events
			   below a programmable	threshold.
     PMC_CAP_USER	   The ability to restrict counting of hardware	events
			   to those when the CPU is running unprivileged code.
     PMC_CAP_WRITE	   The ability to write	to performance counters.

   CPU Naming Conventions
     CPUs are named using small	integers from zero uptil, but excluding, the
     value returned by function	pmc_ncpu().  On	platforms supporting sparsely
     numbered CPUs not all the numbers in this range will denote valid CPUs.
     Operations	on non-existent	CPUs will return an error.

   Functional Grouping of the API
     This section contains a brief overview of the available functionality in
     the PMC library.  Each function listed here is described further in its
     own manual	page.

     Administration
	     pmc_disable(), pmc_enable()
			       Administratively	disable	(enable) specific per-
			       formance	monitoring counter hardware.  Counters
			       that are	disabled will not be available to
			       applications to use.

     Convenience Functions
	     pmc_event_names_of_class()
			       Returns a list of event names supported by a
			       given PMC type.
	     pmc_name_of_capability()
			       Convert a PMC_CAP_* flag	to a human-readable
			       string.
	     pmc_name_of_class()
			       Convert a PMC_CLASS_* constant to a human-read-
			       able string.
	     pmc_name_of_cputype()
			       Return a	human-readable name for	a CPU type.
	     pmc_name_of_disposition()
			       Return a	human-readable string describing a
			       PMC's disposition.
	     pmc_name_of_event()
			       Convert a numeric event code to a human-read-
			       able string.
	     pmc_name_of_mode()
			       Convert a PMC_MODE_* constant to	a human-read-
			       able name.
	     pmc_name_of_state()
			       Return a	human-readable string describing a
			       PMC's current state.

     Library Initialization
	     pmc_init()	       Initialize the library.	This function must be
			       called before any other library function.

     Log File Handling
	     pmc_configure_logfile()
			       Configure a log file for	hwpmc(4) to write
			       logged events to.
	     pmc_flush_logfile()
			       Flush all pending log data in hwpmc(4)'s
			       buffers.
	     pmc_writelog()    Append arbitrary	user data to the current log
			       file.

     PMC Management
	     pmc_allocate(), pmc_release()
			       Allocate	(free) a PMC.
	     pmc_attach(), pmc_detach()
			       Attach (detach) a process scope PMC to a	tar-
			       get.
	     pmc_read(), pmc_write(), pmc_rw()
			       Read (write) a value from (to) a	PMC.
	     pmc_start(), pmc_stop()
			       Start (stop) a software PMC.
	     pmc_set()	       Set the reload value for	a sampling PMC.

     Queries
	     pmc_capabilities()
			       Retrieve	the capabilities for a given PMC.
	     pmc_cpuinfo()     Retrieve	information about the CPUs and PMC
			       hardware	present	in the system.
	     pmc_get_driver_stats()
			       Retrieve	statistics maintained by hwpmc(4).
	     pmc_ncpu()	       Determine the greatest possible CPU number on
			       the system.
	     pmc_npmc()	       Return the number of hardware PMCs present in a
			       given CPU.
	     pmc_pmcinfo()     Return information about	the state of a given
			       CPU's PMCs.
	     pmc_width()       Determine the width of a	hardware counter in
			       bits.

     x86 Architecture Specific API
	     pmc_get_msr()     Returns the processor model specific register
			       number associated with pmc.  Applications may
			       then use	the x86	RDPMC instruction to directly
			       read the	contents of the	PMC.

   Signal Handling Requirements
     Applications using	PMCs are required to handle the	following signals:

     SIGBUS  When the hwpmc(4) module is unloaded using	kldunload(8), pro-
	     cesses that have PMCs allocated to	them will be sent a SIGBUS
	     signal.

     SIGIO   The hwpmc(4) driver will send a PMC owning	process	a SIGIO	signal
	     if:

	     +o	 If any	process-mode PMC allocated by it loses all its target
		 processes.

	     +o	 If the	driver encounters an error when	writing	log data to a
		 configured log	file.  This error may be retrieved by a	subse-
		 quent call to pmc_flush_logfile().

   Typical Program Flow
     1.	  An application would first invoke function pmc_init()	to allow the
	  library to initialize	itself.

     2.	  Signal handling would	then be	set up.

     3.	  Next the application would allocate the PMCs it desires using	func-
	  tion pmc_allocate().

     4.	  Initial values for PMCs may be set using function pmc_set().

     5.	  If a log file	is necessary for the PMCs to work, it would be config-
	  ured using function pmc_configure_logfile().

     6.	  Process scope	PMCs would then	be attached to their target processes
	  using	function pmc_attach().

     7.	  The PMCs would then be started using function	pmc_start().

     8.	  Once started,	the values of counting PMCs may	be read	using function
	  pmc_start().	For PMCs that write events to the log file, this
	  logged data would be read and	parsed using the pmclog(3) family of
	  functions.

     9.	  PMCs are stopped using function pmc_stop(), and process scope	PMCs
	  are detached from their targets using	function pmc_detach().

     10.  Before the process exits, its	may release its	PMCs using function
	  pmc_release().  Any configured log file may be closed	using function
	  pmc_configure_logfile().

EVENT SPECIFIERS
     Event specifiers are strings comprising of	an event name, followed	by
     optional parameters modifying the semantics of the	hardware event being
     probed.  Event names are PMC architecture dependent, but the PMC library
     defines machine independent aliases for commonly used events.

     Event specifiers spellings	are case-insensitive and space characters,
     periods, underscores and hyphens are considered equivalent	to each	other.
     Thus the event specifiers "Example	Event",	"example-event", and
     "EXAMPLE_EVENT" are equivalent.

   PMC Architecture Dependent Events
     PMC architecture dependent	event specifiers are described in the follow-
     ing manual	pages:

     PMC Class		Manual Page
     PMC_CLASS_IAF	pmc.iaf(3)
     PMC_CLASS_IAP	pmc.atom(3), pmc.core(3), pmc.core2(3)
     PMC_CLASS_K7	pmc.k7(3)
     PMC_CLASS_K8	pmc.k8(3)
     PMC_CLASS_P4	pmc.p4(3)
     PMC_CLASS_P5	pmc.p5(3)
     PMC_CLASS_P6	pmc.p6(3)
     PMC_CLASS_TSC	pmc.tsc(3)

   Event Name Aliases
     Event name	aliases	are PMC-independent names for commonly used events.
     The following aliases are known to	this version of	the pmc	library:

     branches
	     Measure the number	of branches retired.

     branch-mispredicts
	     Measure the number	of retired branches that were mispredicted.

     cycles  Measure processor cycles.	This event is implemented using	the
	     processor's Time Stamp Counter register.

     dc-misses
	     Measure the number	of data	cache misses.

     ic-misses
	     Measure the number	of instruction cache misses.

     instructions
	     Measure the number	of instructions	retired.

     interrupts
	     Measure the number	of interrupts seen.

     unhalted-cycles
	     Measure the number	of cycles the processor	is not in a halted or
	     sleep state.

COMPATIBILITY
     The interface between the pmc library and the hwpmc(4) driver is intended
     to	be private to the implementation and may change.  In order to ease
     forward compatibility with	future versions	of the hwpmc(4)	driver,	appli-
     cations are urged to dynamically link with	the pmc	library.

     The pmc API is currently under development.

SEE ALSO
     pmc.atom(3), pmc.core(3), pmc.core2(3), pmc.iaf(3), pmc.k7(3), pmc.k8(3),
     pmc.p4(3),	pmc.p5(3), pmc.p6(3), pmc.tsc(3), pmclog(3), hwpmc(4),
     pmccontrol(8), pmcstat(8)

HISTORY
     The pmc library first appeared in FreeBSD 6.0.

AUTHORS
     The Performance Monitoring	Counters Interface Library (libpmc, -lpmc)
     library was written by Joseph Koshy <jkoshy@FreeBSD.org>.

FreeBSD	9.3		       November	24, 2008		   FreeBSD 9.3

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | EVENT SPECIFIERS | COMPATIBILITY | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=pmc&sektion=3&manpath=FreeBSD+8.2-RELEASE>

home | help