6 files changed, 46 insertions, 27 deletions
diff --git a/lib/libpmc/pmc.3 b/lib/libpmc/pmc.3
index a031928..9dd25f0 100644
--- a/lib/libpmc/pmc.3
+++ b/lib/libpmc/pmc.3
@@ -261,7 +261,14 @@ CPU is running unprivileged code.
 .It Li PMC_CAP_WRITE
 The ability to write to performance counters.
 .El
-.Ss Functional Grouping
+.Ss CPU Naming Conventions
+CPUs are named using small integers from zero uptil, but
+excluding, the value returned by function
+.Fn 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.
+.Ss 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.
@@ -342,7 +349,7 @@ system.
 Retrieve statistics maintained by
 .Xr hwpmc 4 .
 .It Fn pmc_ncpu
-Determine the number of CPUs in the system.
+Determine the greatest possible CPU number on the system.
 .It Fn pmc_npmc
 Return the number of hardware PMCs present in a given CPU.
 .It Fn pmc_pmcinfo
diff --git a/lib/libpmc/pmc_allocate.3 b/lib/libpmc/pmc_allocate.3
index 2ca27ad..03f9078 100644
--- a/lib/libpmc/pmc_allocate.3
+++ b/lib/libpmc/pmc_allocate.3
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
+.\" Copyright (c) 2007-2008 Joseph Koshy.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -23,7 +23,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 20, 2007
+.Dd September 22, 2008
 .Os
 .Dt PMC_ALLOCATE 3
 .Sh NAME
@@ -156,7 +156,7 @@ error.
 .It Bq Er ENXIO
 Function
 .Fn pmc_allocate
-requested the use of a hardware resource that was previously
+requested the use of a hardware resource that was absent or
 administratively disabled.
 .It Bq Er EOPNOTSUPP
 The underlying hardware does not support the capabilities needed for
diff --git a/lib/libpmc/pmc_capabilities.3 b/lib/libpmc/pmc_capabilities.3
index 97dc1a3..9a7b6e9 100644
--- a/lib/libpmc/pmc_capabilities.3
+++ b/lib/libpmc/pmc_capabilities.3
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
+.\" Copyright (c) 2007-2008 Joseph Koshy.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -23,7 +23,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 24, 2007
+.Dd September 22, 2008
 .Os
 .Dt PMC_CAPABILITIES 3
 .Sh NAME
@@ -96,8 +96,11 @@ in the system.
 .Pp
 Function
 .Fn pmc_ncpu
-is a convenience function that returns the number of CPUs in the
-system.
+is a convenience function that returns the maximum CPU number in
+the system.
+On systems that support sparsely numbered CPUs, not all CPUs may
+be physically present.
+Applications need to be prepared to deal with nonexistent CPUs.
 .Pp
 Function
 .Fn pmc_npmc
@@ -201,11 +204,11 @@ may fail with the following errors:
 .It Bq Er EINVAL
 The argument
 .Fa cpu
-specified a non-existent CPU.
+was invalid.
 .It Bq Er ENXIO
 The argument
 .Fa cpu
-specified a disabled CPU.
+specified a disabled or absent CPU.
 .El
 .Pp
 A call to function
diff --git a/lib/libpmc/pmc_disable.3 b/lib/libpmc/pmc_disable.3
index f28d0b9..cd837d3 100644
--- a/lib/libpmc/pmc_disable.3
+++ b/lib/libpmc/pmc_disable.3
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
+.\" Copyright (c) 2007-2008 Joseph Koshy.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -23,7 +23,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 20, 2007
+.Dd September 22, 2008
 .Os
 .Dt PMC_ENABLE 3
 .Sh NAME
@@ -85,7 +85,7 @@ were invalid.
 .It Bq Er ENXIO
 Argument
 .Fa cpu
-specified a disabled CPU.
+specified a disabled or absent CPU.
 .It Bq Er EPERM
 The current process lacks sufficient privilege to perform this
 operation.
@@ -96,4 +96,4 @@ operation.
 .Xr pmc_pmcinfo 3 ,
 .Xr hwpmc 4 ,
 .Xr pmccontrol 8 ,
-.Xr priv_check 9
-\ No newline at end of file
+.Xr priv_check 9
diff --git a/lib/libpmc/pmc_start.3 b/lib/libpmc/pmc_start.3
index b132d0f..7fb474a 100644
--- a/lib/libpmc/pmc_start.3
+++ b/lib/libpmc/pmc_start.3
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
+.\" Copyright (c) 2007-2008 Joseph Koshy.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -23,7 +23,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 25, 2007
+.Dd September 22, 2008
 .Os
 .Dt PMC_START 3
 .Sh NAME
@@ -69,7 +69,8 @@ Function
 .Fn pmc_stop
 specified a PMC that was never started.
 .It Bq Er ENXIO
-The specified PMC had system scope and its associated CPU was disabled.
+The specified PMC had system scope and its associated CPU was disabled or
+absent.
 .El
 .Sh SEE ALSO
 .Xr pmc 3 ,
diff --git a/share/man/man4/hwpmc.4 b/share/man/man4/hwpmc.4
index 31a6918..7034cd4 100644
--- a/share/man/man4/hwpmc.4
+++ b/share/man/man4/hwpmc.4
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2003-2007 Joseph Koshy
+.\" Copyright (c) 2003-2008 Joseph Koshy
 .\" Copyright (c) 2007 The FreeBSD Foundation
 .\" All rights reserved.
 .\"
@@ -28,7 +28,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 24, 2007
+.Dd September 22, 2008
 .Dt HWPMC 4
 .Os
 .Sh NAME
@@ -307,8 +307,8 @@ has returned.
 The returned error code reflects any pending error state inside
 .Nm .
 .It Dv PMC_OP_GETCPUINFO
-Retrieve information about the number of CPUs on the system and
-the number of hardware performance monitoring counters available per-CPU.
+Retrieve information about the highest possible CPU number for the system,
+and the number of hardware performance monitoring counters available per CPU.
 .It Dv PMC_OP_GETDRIVERSTATS
 Retrieve module statistics (for analyzing the behavior of
 .Nm
@@ -490,6 +490,12 @@ via the RDTSC instruction.
 .Ss SMP Symmetry
 The kernel driver requires all physical CPUs in an SMP system to have
 identical performance monitoring counter hardware.
+.Ss Sparse CPU Numbering
+On platforms that sparsely number CPUs and which support hot-plugging
+of CPUs, requests that specify non-existent or disabled CPUs will fail
+with an error.
+Applications allocating system-scope PMCs need to be aware of
+the possibility of such transient failures.
 .Ss x86 TSC Handling
 Historically, on the x86 architecture,
 .Fx
@@ -735,17 +741,19 @@ PMCs directly with the RDPMC instruction.
 .It Bq Er ENXIO
 A
 .Dv PMC_OP_GETPMCINFO
-operation was requested for a disabled CPU.
+operation was requested for an absent or disabled CPU.
 .It Bq Er ENXIO
-A system-wide PMC on a disabled CPU was requested to be allocated with
-.Dv PMC_OP_PMCALLOCATE .
+A
+.Dv PMC_OP_PMCALLOCATE
+operation specified allocation of a system-wide PMC on an absent or
+disabled CPU.
 .It Bq Er ENXIO
 A
 .Dv PMC_OP_PMCSTART
 or
 .Dv PMC_OP_PMCSTOP
-request was issued for a system-wide PMC that was allocated on a
-currently disabled CPU.
+request was issued for a system-wide PMC that was allocated on a CPU
+that is currently absent or disabled.
 .It Bq Er EOPNOTSUPP
 A
 .Dv PMC_OP_PMCALLOCATE