- Improve clarity: use 'scope' to distinguish between process and system

  PMCs and 'mode' to distinguish between counting and sampling.
- Document PMC row dispositions.
- Document the requirement for PRIV_PMC_MANAGE privilege when issuing
  PMC_OP_PMCADMIN requests.

1 files changed, 39 insertions, 19 deletions

diff --git a/share/man/man4/hwpmc.4 b/share/man/man4/hwpmc.4
index 1eaf7b0..214524d 100644
--- a/share/man/man4/hwpmc.4
+++ b/share/man/man4/hwpmc.4
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 22, 2007
+.Dd November 24, 2007
 .Dt HWPMC 4
 .Os
 .Sh NAME
@@ -50,27 +50,23 @@ PMCs are allocated using the
 request.
 A successful
 .Dv PMC_OP_PMCALLOCATE
-request will return an integer handle to the requesting process.
+request will return a handle to the requesting process.
 Subsequent operations on the allocated PMC use this handle to denote
 the specific PMC.
 A process that has successfully allocated a PMC is termed an
 .Dq "owner process" .
 .Pp
-PMCs may be allocated to operate in process-private or in system-wide
-modes.
-.Bl -tag -width ".Em Process-private"
-.It Em Process-private
-In process-private mode, a PMC is active only when a thread belonging
+PMCs may be allocated with process or system scope.
+.Bl -tag -width ".Em Process-scope"
+.It Em "Process-scope"
+The PMC is active only when a thread belonging
 to a process it is attached to is scheduled on a CPU.
-.It Em System-wide
-In system-wide mode, a PMC operates independently of processes and
+.It Em "System-scope"
+The PMC operates independently of processes and
 measures hardware events for the system as a whole.
 .El
 .Pp
-The
-.Nm
-driver supports the use of hardware PMCs for counting or for
-sampling:
+PMCs may be allocated for counting or for sampling:
 .Bl -tag -width ".Em Counting"
 .It Em Counting
 In counting modes, the PMCs count hardware events.
@@ -86,10 +82,10 @@ These instruction pointer samples are usually directed to a log file
 for subsequent analysis.
 .El
 .Pp
-These modes of operation are orthogonal; a PMC may be configured to
-operate in one of four modes:
+Scope and operational mode are orthogonal; a PMC may thus be
+configured to operate in one of the following four modes:
 .Bl -tag -width indent
-.It Process-private, counting
+.It Process-scope, counting
 These PMCs count hardware events whenever a thread in their attached process is
 scheduled on a CPU.
 These PMCs normally count from zero, but the initial count may be
@@ -99,7 +95,7 @@ operation.
 Applications can read the value of the PMC anytime using the
 .Dv PMC_OP_PMCRW
 operation.
-.It Process-private, sampling
+.It Process-scope, sampling
 These PMCs sample the target processes instruction pointer after they
 have seen the configured number of hardware events.
 The PMCs only count events when a thread belonging to their attached
@@ -110,7 +106,7 @@ operation prior to starting the PMC.
 Log files are configured using the
 .Dv PMC_OP_CONFIGURELOG
 operation.
-.It System-wide, counting
+.It System-scope, counting
 These PMCs count hardware events seen by them independent of the
 processes that are executing.
 The current count on these PMCs can be read using the
@@ -120,7 +116,7 @@ These PMCs normally count from zero, but the initial count may be
 set using the
 .Dv PMC_OP_SETCOUNT
 operation.
-.It System-wide, sampling
+.It System-scope, sampling
 These PMCs will periodically sample the instruction pointer of the CPU
 they are allocated on, and will write the sample to a log for further
 processing.
@@ -243,6 +239,27 @@ The
 .Nm
 driver is being unloaded from the kernel.
 .El
+.Ss PMC ROW DISPOSITIONS
+A PMC row is defined as the set of PMC resources at the same hardware
+address in the CPUs in a system.
+Since process scope PMCs need to move between CPUs following their
+target threads, allocation of a process scope PMC reserves all PMCs in
+a PMC row for use only with process scope PMCs.
+Accordingly a PMC row will be in one of the following dispositions:
+.Bl -tag -width ".Dv PMC_DISP_STANDALONE" -compact
+.It Dv PMC_DISP_FREE
+Hardware counters in this row are free and may be use to satisfy
+either of system scope or process scope allocation requests.
+.It Dv PMC_DISP_THREAD
+Hardware counters in this row are in use by process scope PMCs
+and are only available for process scope allocation requests.
+.It Dv PMC_DISP_STANDALONE
+Some hardware counters in this row have been administratively
+disabled or are in use by system scope PMCs.
+Non-disabled hardware counters in such a row may be used
+for satisfying system scope allocation requests.
+No process scope PMCs will use hardware counters in this row.
+.El
 .Sh PROGRAMMING API
 The recommended way for application programs to use the facilities of
 the
@@ -285,6 +302,9 @@ Set the administrative state (i.e., whether enabled or disabled) for
 the hardware PMCs managed by the
 .Nm
 driver.
+The invoking process needs to possess the
+.Dv PRIV_PMC_MANAGE
+privilege.
 .It Dv PMC_OP_PMCALLOCATE
 Allocate and configure a PMC.
 On successful allocation, a handle to the PMC (a 32 bit value)