Document changes in behaviour due to sparse CPU numbering support.

5 files changed, 29 insertions, 18 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 ,