Move the following functions into their own manual pages:

- pmc_attach(), pmc_detach().
- pmc_capabilities(), pmc_cpuinfo(), pmc_ncpu(), pmc_npmc(), pmc_pmcinfo(),
  pmc_width().
- pmc_get_driver_stats().
- pmc_get_msr().
- pmc_read(), pmc_rw(), pmc_write().
- pmc_set().
- pmc_start(), pmc_stop().

8 files changed, 772 insertions, 16 deletions

diff --git a/lib/libpmc/Makefile b/lib/libpmc/Makefile
index ea61d73..79c6716 100644
--- a/lib/libpmc/Makefile
+++ b/lib/libpmc/Makefile
@@ -9,39 +9,40 @@ WARNS?=	6
 
 MAN=	pmc.3
 MAN+=	pmc_allocate.3
+MAN+=	pmc_attach.3
+MAN+=	pmc_capabilities.3
 MAN+=	pmc_configure_logfile.3
 MAN+=	pmc_disable.3
 MAN+=	pmc_event_names_of_class.3
-MAN+=	pmc_name_of_capability.3
+MAN+=	pmc_get_driver_stats.3
+MAN+=	pmc_get_msr.3
 MAN+=	pmc_init.3
+MAN+=	pmc_name_of_capability.3
+MAN+=	pmc_read.3
+MAN+=	pmc_set.3
+MAN+=	pmc_start.3
 MAN+=	pmclog.3
 
 MLINKS+= \
 	pmc_allocate.3 pmc_release.3 \
+	pmc_attach.3 pmc_detach.3 \
+	pmc_capabilities.3 pmc_ncpu.3 \
+	pmc_capabilities.3 pmc_npmc.3 \
+	pmc_capabilities.3 pmc_pmcinfo.3 \
+	pmc_capabilities.3 pmc_cpuinfo.3 \
+	pmc_capabilities.3 pmc_width.3 \
 	pmc_configure_logfile.3 pmc_flush_logfile.3 \
 	pmc_configure_logfile.3 pmc_writelog.3 \
-	pmc.3 pmc_attach.3 \
-	pmc.3 pmc_cpuinfo.3 \
-	pmc.3 pmc_detach.3 \
 	pmc_disable.3 pmc_enable.3 \
-	pmc.3 pmc_get_driver_stats.3 \
 	pmc_name_of_capability.3 pmc_name_of_class.3 \
 	pmc_name_of_capability.3 pmc_name_of_cputype.3 \
 	pmc_name_of_capability.3 pmc_name_of_disposition.3 \
 	pmc_name_of_capability.3 pmc_name_of_event.3 \
 	pmc_name_of_capability.3 pmc_name_of_mode.3 \
 	pmc_name_of_capability.3 pmc_name_of_state.3 \
-	pmc.3 pmc_ncpu.3 \
-	pmc.3 pmc_npmc.3 \
-	pmc.3 pmc_pmcinfo.3 \
-	pmc.3 pmc_read.3 \
-	pmc.3 pmc_rw.3 \
-	pmc.3 pmc_set.3 \
-	pmc.3 pmc_start.3 \
-	pmc.3 pmc_stop.3 \
-	pmc.3 pmc_width.3 \
-	pmc.3 pmc_write.3 \
-	pmc.3 pmc_x86_get_msr.3
+	pmc_read.3 pmc_rw.3 \
+	pmc_read.3 pmc_write.3 \
+	pmc_start.3 pmc_stop.3
 
 MLINKS+= \
 	pmclog.3 pmclog_open.3 \
diff --git a/lib/libpmc/pmc_attach.3 b/lib/libpmc/pmc_attach.3
new file mode 100644
index 0000000..62b0be6
--- /dev/null
+++ b/lib/libpmc/pmc_attach.3
@@ -0,0 +1,149 @@
+.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" This software is provided by Joseph Koshy ``as is'' and
+.\" any express or implied warranties, including, but not limited to, the
+.\" implied warranties of merchantability and fitness for a particular purpose
+.\" are disclaimed.  in no event shall Joseph Koshy be liable
+.\" for any direct, indirect, incidental, special, exemplary, or consequential
+.\" damages (including, but not limited to, procurement of substitute goods
+.\" or services; loss of use, data, or profits; or business interruption)
+.\" however caused and on any theory of liability, whether in contract, strict
+.\" liability, or tort (including negligence or otherwise) arising in any way
+.\" out of the use of this software, even if advised of the possibility of
+.\" such damage.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 25 2007
+.Os
+.Dt PMC_ATTACH 3
+.Sh NAME
+.Nm pmc_attach ,
+.Nm pmc_detach
+.Nd attaching and detaching process scope PMCs to target processes
+.Sh LIBRARY
+.Lb libpmc
+.Sh SYNOPSIS
+.In pmc.h
+.Ft int
+.Fn pmc_attach "pmc_id_t pmcid" "pid_t pid"
+.Ft int
+.Fn pmc_detach "pmc_id_t pmcid" "pid_t pid"
+.Sh DESCRIPTION
+These functions control the set of target processes tracked by a
+process scope PMC.
+.Pp
+Function
+.Fn pmc_attach
+is used to attach a process scope PMC specified by argument
+.Fa pmcid
+to a target process specified by argument
+.Fa pid .
+Argument
+.Fa pid
+may be zero to denote the current process.
+If the PMC was allocated with modifier
+.Dv PMC_F_DESCENDANTS ,
+the PMC will additionally attach to current and future descendents of
+the specified target process.
+The PMC should be in a quiescent state (i.e., not running).
+.Pp
+Function
+.Fn pmc_detach
+is used to detach a process scope PMC specified by argument
+.Fa pmcid
+from a process specified by argument
+.Fa pid .
+Argument
+.Fa pid
+may be zero to denote the current process.
+.Sh RETURN VALUES
+.Rv -std
+.Sh ERRORS
+A call to function
+.Fn pmc_attach
+may fail with the following errors:
+.Bl -tag -width Er
+.It Bq Er EBUSY
+Argument
+.Fa pmcid
+specified a PMC that was not in a quiescent state.
+.It Bq Er EBUSY
+The target process specified by function
+.Fa pmc_attach
+is being tracked by another process scope PMC that uses the same PMC
+hardware resources.
+.It Bq Er EEXIST
+The target process is already being tracked by the specified PMC.
+.It Bq Er EINVAL
+Argument
+.Fa pmcid
+specified a PMC with system scope.
+.It Bq Er EINVAL
+Argument
+.Fa pid
+specified an illegal process id.
+.It Bq Er EINVAL
+The current process does not own a PMC with the handle specified in
+argument
+.Fa pmcid .
+.It Bq Er EPERM
+The caller lacked the privilege needed to attach PMCs to
+the specified target process.
+.It Bq Er EPERM
+(i386 and amd64 architectures) The PMC specified by argument
+.Fa pmcid
+has been setup to allow the use of the RDPMC instruction for
+self measurement.
+.It Bq Er ESRCH
+The current process does not own any PMCs.
+.It Bq Er ESRCH
+The process specified by argument
+.Fa pid
+did not exist.
+.El
+.Pp
+A call to function
+.Fn pmc_detach
+may fail with the following errors:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+Argument
+.Fa pmcid
+specified a PMC with system scope.
+.It Bq Er EINVAL
+Argument
+.Fa pid
+specified an illegal process id.
+.It Bq Er EINVAL
+The current process does not own a PMC with the handle specified in
+argument
+.Fa pmcid .
+.It Bq Er EINVAL
+The specified PMC was not attached to the target process.
+.It Bq Er ESRCH
+The current process does not own any PMCs.
+.It Bq Er ESRCH
+The process specified by argument
+.Fa pid
+is not being monitored by
+.Xr hwpmc 4 .
+.It Bq Er ESRCH
+The process specified by argument
+.Fa pid
+did not exist.
+.El
+.Sh SEE ALSO
+.Xr pmc 3 ,
+.Xr pmc_start 3 ,
+.Xr pmc_stop 3 ,
+.Xr hwpmc 4
diff --git a/lib/libpmc/pmc_capabilities.3 b/lib/libpmc/pmc_capabilities.3
new file mode 100644
index 0000000..7506454
--- /dev/null
+++ b/lib/libpmc/pmc_capabilities.3
@@ -0,0 +1,224 @@
+.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" This software is provided by Joseph Koshy ``as is'' and
+.\" any express or implied warranties, including, but not limited to, the
+.\" implied warranties of merchantability and fitness for a particular purpose
+.\" are disclaimed.  in no event shall Joseph Koshy be liable
+.\" for any direct, indirect, incidental, special, exemplary, or consequential
+.\" damages (including, but not limited to, procurement of substitute goods
+.\" or services; loss of use, data, or profits; or business interruption)
+.\" however caused and on any theory of liability, whether in contract, strict
+.\" liability, or tort (including negligence or otherwise) arising in any way
+.\" out of the use of this software, even if advised of the possibility of
+.\" such damage.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 24, 2007
+.Os
+.Dt PMC_CAPABILITIES 3
+.Sh NAME
+.Nm pmc_capabilities ,
+.Nm pmc_cpuinfo ,
+.Nm pmc_ncpu ,
+.Nm pmc_npmc ,
+.Nm pmc_pmcinfo ,
+.Nm pmc_width
+.Nd retrieve information about performance monitoring counters
+.Sh LIBRARY
+.Lb libpmc
+.Sh SYNOPSIS
+.In pmc.h
+.Ft int
+.Fn pmc_capabilities "pmc_id_t pmc" "uint32_t *caps"
+.Ft int
+.Fn pmc_cpuinfo "const struct pmc_cpuinfo **cpu_info"
+.Ft int
+.Fn pmc_ncpu void
+.Ft int
+.Fn pmc_npmc "int cpu"
+.Ft int
+.Fn pmc_pmcinfo "int cpu" "struct pmc_pmcinfo **pmc_info"
+.Ft int
+.Fn pmc_width "pmc_id_t pmc" "uint32_t *width"
+.Sh DESCRIPTION
+These functions retrieve information about performance monitoring 
+hardware.
+.Pp
+Function
+.Fn pmc_capabilities
+retrieves the hardware capabilities of a PMC.
+Argument
+.Fa pmc
+is a PMC handle obtained by a prior call to
+.Fn pmc_allocate .
+The function sets argument
+.Fa caps
+to a bitmask of capabilities supported by the PMC denoted by
+argument
+.Fa pmc .
+PMC capabilities are described in
+.Xr pmc 3 .
+.Pp
+Function
+.Fn pmc_cpuinfo
+retrieves information about the CPUs in the system.
+Argument
+.Fa cpu_info
+will be set to point to an internal structure with information about
+the system's CPUs.
+The caller should not free this pointer value.
+This structure has the following fields:
+.Bl -tag -width "pm_classes" -offset indent -compact
+.It pm_cputype
+Specifies the CPU type.
+.It pm_ncpu
+Specifies the number of CPUs in the system.
+.It pm_npmc
+Specifies the number of PMC rows per CPU.
+.It pm_nclass
+Specifies the number of distinct classes of PMCs in the system.
+.It pm_classes
+Contains an array of
+.Vt "struct pmc_classinfo"
+descriptors describing the properties of each class of PMCs
+in the system.
+.El
+.Pp
+Function
+.Fn pmc_ncpu
+is a convenience function that returns the number of CPUs in the
+system.
+.Pp
+Function
+.Fn pmc_npmc
+is a convenience function that returns the number of PMCs available
+in the CPU specified by argument
+.Fa cpu .
+.Pp
+Function
+.Fn pmc_pmcinfo
+returns information about the current state of the PMC hardware
+in the CPU specified by argument
+.Fa cpu .
+The location specified by argument
+.Fa pmc_info
+is set to point an array of
+.Vt "struct pmc_info"
+structures each describing the state of one PMC in the CPU.
+These structure contain the following fields:
+.Bl -tag -width pm_ownerpid -offset indent -compact
+.It pm_name
+A human readable name for the PMC.
+.It pm_class
+The PMC class for the PMC.
+.It pm_enabled
+Non-zero if the PMC is enabled.
+.It pm_rowdisp
+The disposition of the PMC row for this PMC.
+Row dispositions are documented in
+.Xr hwpmc 4 .
+.It pm_ownerpid
+If the hardware is in use, the process id of the owner of the PMC.
+.It pm_mode
+The PMC mode as described in
+.Xr pmc 3 .
+.It pm_event
+If the hardware is in use, the PMC event being measured.
+.It pm_flags
+If the hardware is in use, the flags associated with the PMC.
+.It pm_reloadcount
+For sampling PMCs, the reload count associated with the PMC.
+.El
+.Pp
+Function
+.Fn pmc_width
+is used to retrieve the width in bits of the hardware counters
+associated with a PMC.
+Argument
+.Fa pmc
+is a PMC handle obtained by a prior call to
+.Fn pmc_allocate .
+The function sets the location pointed to by argument
+.Fa width
+to the width of the physical counters associated with PMC
+.Fa pmc .
+.Sh RETURN VALUES
+Functions
+.Fn pmc_ncpu
+and
+.Fn pmc_npmc
+returns a positive integer if successful or -1 in case of an error.
+.Pp
+Functions
+.Fn pmc_capabilities ,
+.Fn pmc_cpuinfo ,
+.Fn pmc_pmcinfo
+and
+.Fn pmc_width
+return 0 if successful; otherwise the value -1 is returned and the
+global variable
+.Va errno
+is set to indicate the error.
+.Sh ERRORS
+A call to function
+.Fn pmc_capabilities
+may fail with the following errors:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The argument to the function was invalid.
+.El
+.Pp
+Calls to functions
+.Fn pmc_cpuinfo ,
+.Fn pmc_ncpu
+and
+.Fn pmc_npmc
+may fail with the following errors:
+.Bl -tag -width Er
+.It Bq Er ENXIO
+A prior call to
+.Fn pmc_init
+to initialize the PMC library had failed.
+.El
+.Pp
+A call to function
+.Fn pmc_pmcinfo
+may fail with the following errors:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The argument
+.Fa cpu
+specified a non-existent CPU.
+.It Bq Er ENXIO
+The argument
+.Fa cpu
+specified a disabled CPU.
+.El
+.Pp
+A call to function
+.Fn pmc_width
+may fail with the following errors:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The argument to the function was invalid.
+.El
+.Sh SEE ALSO
+.Xr pmc 3 ,
+.Xr pmc_allocate 3 ,
+.Xr pmc_get_driver_stats 3 ,
+.Xr pmc_name_of_capability 3 ,
+.Xr pmc_name_of_cputype 3 ,
+.Xr pmc_name_of_class 3 ,
+.Xr pmc_name_of_event 3 ,
+.Xr pmc_name_of_mode 3 ,
+.Xr hwpmc 4
diff --git a/lib/libpmc/pmc_get_driver_stats.3 b/lib/libpmc/pmc_get_driver_stats.3
new file mode 100644
index 0000000..d8bfe23
--- /dev/null
+++ b/lib/libpmc/pmc_get_driver_stats.3
@@ -0,0 +1,73 @@
+.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" This software is provided by Joseph Koshy ``as is'' and
+.\" any express or implied warranties, including, but not limited to, the
+.\" implied warranties of merchantability and fitness for a particular purpose
+.\" are disclaimed.  in no event shall Joseph Koshy be liable
+.\" for any direct, indirect, incidental, special, exemplary, or consequential
+.\" damages (including, but not limited to, procurement of substitute goods
+.\" or services; loss of use, data, or profits; or business interruption)
+.\" however caused and on any theory of liability, whether in contract, strict
+.\" liability, or tort (including negligence or otherwise) arising in any way
+.\" out of the use of this software, even if advised of the possibility of
+.\" such damage.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 25, 2007
+.Os
+.Dt PMC_GET_DRIVER_STATS 3
+.Sh NAME
+.Nm pmc_get_driver_stats
+.Nd retrieve driver statistics
+.Sh LIBRARY
+.Lb libpmc
+.Sh SYNOPSIS
+.In pmc.h
+.Ft int
+.Fn pmc_get_driver_stats "struct pmc_driverstats *gms"
+.Sh DESCRIPTION
+The function
+.Fn pmc_get_driver_statistics
+retrieves a snapshot of the usage statistics maintained by
+.Xr hwpmc 4
+into the memory area pointed to by argument
+.Fa gms .
+.Pp
+The returned structure includes the following fields:
+.Bl -tag -width pmc_intr_bufferfull -offset indent -compact
+.It pm_intr_ignored
+The number of sampling interrupts ignored.
+.It pm_intr_processed
+The number of sampling interrupts processed.
+.It pm_intr_bufferfull
+The number of sampling interrupts dropped due to lack of space
+in the sample buffer.
+.It pm_syscalls
+The number of system calls into
+.Xr hwpmc 4 .
+.It pm_syscalls_errors
+The number of system calls into
+.Xr hwpmc 4
+that failed.
+.It pm_buffer_requests
+The number of log buffer requests so far.
+.It pm_buffer_requests_failed
+The number of log buffer requests that failed due to lack of buffers.
+.It pm_log_sweeps
+The number of sample buffer processing sweeps.
+.El
+.Sh RETURN VALUES
+.Rv -std
+.Sh SEE ALSO
+.Xr pmc 3 ,
+.Xr hwpmc 4
diff --git a/lib/libpmc/pmc_get_msr.3 b/lib/libpmc/pmc_get_msr.3
new file mode 100644
index 0000000..6a2b942
--- /dev/null
+++ b/lib/libpmc/pmc_get_msr.3
@@ -0,0 +1,76 @@
+.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" This software is provided by Joseph Koshy ``as is'' and
+.\" any express or implied warranties, including, but not limited to, the
+.\" implied warranties of merchantability and fitness for a particular purpose
+.\" are disclaimed.  in no event shall Joseph Koshy be liable
+.\" for any direct, indirect, incidental, special, exemplary, or consequential
+.\" damages (including, but not limited to, procurement of substitute goods
+.\" or services; loss of use, data, or profits; or business interruption)
+.\" however caused and on any theory of liability, whether in contract, strict
+.\" liability, or tort (including negligence or otherwise) arising in any way
+.\" out of the use of this software, even if advised of the possibility of
+.\" such damage.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 25, 2007
+.Os
+.Dt PMC_GET_MSR 3
+.Sh NAME
+.Nm pmc_get_msr
+.Nd x86 architecture-specific PMC operations
+.Sh LIBRARY
+.Lb libpmc
+.Sh SYNOPSIS
+.In pmc.h
+.Ft int
+.Fn pmc_get_msr "pmc_id_t pmc" "uint32_t *msr"
+.Sh DESCRIPTION
+The function
+.Fn pmc_get_msr
+returns the processor model specific register number associated with
+a PMC for subsequent use with RDPMC instructions.
+Argument
+.Fa pmc
+specifies a process scope counting PMC.
+The function will write the model specific register number associated
+with the PMC to the location pointed to by argument
+.Fa msr .
+.Pp
+After successful completion of this function, applications
+can directly read the contents of PMC hardware using
+RDPMC instructions.
+.Sh RETURN VALUES
+.Rv -std pmc_get_msr
+.Sh ERRORS
+A call to
+.Fn pmc_get_msr
+may fail with the following errors:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The PMC handle specified was invalid.
+.It Bq Er EINVAL
+The PMC specified did not have process scope or counting mode.
+.It Bq Er EINVAL
+The PMC specified was allocated with the
+.Dv PMC_F_DESCENDANTS
+flag.
+.It Bq Er EINVAL
+The specified PMC is already attached to target processes other
+than the owner.
+.It Bq Er ENOSYS
+The underlying hardware does not support an RDPMC instruction.
+.El
+.Sh SEE ALSO
+.Xr pmc 3 ,
+.Xr hwpmc 4
diff --git a/lib/libpmc/pmc_read.3 b/lib/libpmc/pmc_read.3
new file mode 100644
index 0000000..6056fea
--- /dev/null
+++ b/lib/libpmc/pmc_read.3
@@ -0,0 +1,84 @@
+.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" This software is provided by Joseph Koshy ``as is'' and
+.\" any express or implied warranties, including, but not limited to, the
+.\" implied warranties of merchantability and fitness for a particular purpose
+.\" are disclaimed.  in no event shall Joseph Koshy be liable
+.\" for any direct, indirect, incidental, special, exemplary, or consequential
+.\" damages (including, but not limited to, procurement of substitute goods
+.\" or services; loss of use, data, or profits; or business interruption)
+.\" however caused and on any theory of liability, whether in contract, strict
+.\" liability, or tort (including negligence or otherwise) arising in any way
+.\" out of the use of this software, even if advised of the possibility of
+.\" such damage.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 25, 2007
+.Os
+.Dt PMC_READ 3
+.Sh NAME
+.Nm pmc_read ,
+.Nm pmc_rw ,
+.Nm pmc_write ,
+.Nd read and write hardware performace counters
+.Sh LIBRARY
+.Lb libpmc
+.Sh SYNOPSIS
+.In pmc.h
+.Ft int
+.Fn pmc_read "pmc_id_t pmc" "pmc_value_t *value"
+.Ft int
+.Fn pmc_rw "pmc_id_t pmc" "pmc_value_t newvalue" "pmc_value_t *oldvaluep"
+.Ft int
+.Fn pmc_write "pmc_id_t pmc" "pmc_value_t value"
+.Sh DESCRIPTION
+These functions read and write the current value of a PMC.
+.Pp
+Function
+.Fn pmc_read
+with read the current value of the PMC specified by argument
+.Fa pmc
+and write it to the location specified by argument
+.Fa value .
+.Pp
+Function
+.Fn pmc_write
+will set the current value of the PMC specified by argument
+.Fa pmc
+to the value specified by argument
+.Fa value .
+.Pp
+Function
+.Fn pmc_rw
+combines a read and a write into a single atomic operation.
+.Pp
+For write operations the PMC should be a quiesced state.
+.Sh RETURN VALUES
+.Rv -std
+.Sh ERRORS
+A call to these functions may fail with the following errors:
+.Bl -tag -width Er
+.It Bq Er EBUSY
+A write operation specified a currently running PMC.
+.It Bq Er EINVAL
+Argument
+.Fa pmc
+specified a PMC not in a readable state.
+.It Bq Er EINVAL
+The PMC specified by argument
+.Fa pmc
+was not owned by the current process.
+.El
+.Sh SEE ALSO
+.Xr pmc 3 ,
+.Xr hwpmc 4
diff --git a/lib/libpmc/pmc_set.3 b/lib/libpmc/pmc_set.3
new file mode 100644
index 0000000..a9e438a
--- /dev/null
+++ b/lib/libpmc/pmc_set.3
@@ -0,0 +1,73 @@
+.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" This software is provided by Joseph Koshy ``as is'' and
+.\" any express or implied warranties, including, but not limited to, the
+.\" implied warranties of merchantability and fitness for a particular purpose
+.\" are disclaimed.  in no event shall Joseph Koshy be liable
+.\" for any direct, indirect, incidental, special, exemplary, or consequential
+.\" damages (including, but not limited to, procurement of substitute goods
+.\" or services; loss of use, data, or profits; or business interruption)
+.\" however caused and on any theory of liability, whether in contract, strict
+.\" liability, or tort (including negligence or otherwise) arising in any way
+.\" out of the use of this software, even if advised of the possibility of
+.\" such damage.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 25, 2007
+.Os
+.Dt PMC_SET 3
+.Sh NAME
+.Nm pmc_set
+.Nd set the reload count of a sampling PMC
+.Sh LIBRARY
+.Lb libpmc
+.Sh SYNOPSIS
+.In pmc.h
+.Ft int
+.Fn pmc_set "pmc_id_t pmc" "pmc_value_t value"
+.Sh DESCRIPTION
+Function
+.Fn pmc_set
+is used to set the reload value of sampling PMCs.
+Argument
+.Fa pmc
+specified the handle a previously allocate sampling mode PMC.
+Argument
+.Fa value
+specifies the reload count.
+.Pp
+Sampling PMCs will interrupt the CPU after the number of
+hardware events specified by the reload count are seen.
+After the sampling interrupt is processed the underlying hardware will
+be reloaded with the specified count and the hardware
+automatically restarted by
+.Xr hwpmc 4 .
+.Pp
+Function
+.Fn pmc_set
+should be called on PMC in a quiescent state.
+.Sh RETURN VALUES
+.Rv -std pmc_set
+.Sh ERRORS
+A call to
+.Fn pmc_set
+may fail with the following errors:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The current process did not own a PMC with the specified handle.
+.It Bq Er EBUSY
+The specified PMC was already running.
+.El
+.Sh SEE ALSO
+.Xr pmc 3 ,
+.Xr hwpmc 4
diff --git a/lib/libpmc/pmc_start.3 b/lib/libpmc/pmc_start.3
new file mode 100644
index 0000000..b132d0f
--- /dev/null
+++ b/lib/libpmc/pmc_start.3
@@ -0,0 +1,76 @@
+.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" This software is provided by Joseph Koshy ``as is'' and
+.\" any express or implied warranties, including, but not limited to, the
+.\" implied warranties of merchantability and fitness for a particular purpose
+.\" are disclaimed.  in no event shall Joseph Koshy be liable
+.\" for any direct, indirect, incidental, special, exemplary, or consequential
+.\" damages (including, but not limited to, procurement of substitute goods
+.\" or services; loss of use, data, or profits; or business interruption)
+.\" however caused and on any theory of liability, whether in contract, strict
+.\" liability, or tort (including negligence or otherwise) arising in any way
+.\" out of the use of this software, even if advised of the possibility of
+.\" such damage.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 25, 2007
+.Os
+.Dt PMC_START 3
+.Sh NAME
+.Nm pmc_start ,
+.Nm pmc_stop
+.Nd start and stop a PMC
+.Sh LIBRARY
+.Lb libpmc
+.Sh SYNOPSIS
+.In pmc.h
+.Ft int
+.Fn pmc_start "pmc_id_t pmc"
+.Ft int
+.Fn pmc_stop "pmc_id_t pmc"
+.Sh DESCRIPTION
+These functions are used to start and stop a PMC.
+.Pp
+Function
+.Fn pmc_start
+starts the PMC specified by argument
+.Fa pmc .
+If the specified PMC has process scope and has not been attached
+to any targets, it will be attached to the current process.
+.Pp
+Function
+.Fn pmc_stop
+stops the PMC specified by argument
+.Fa pmc .
+.Sh RETURN VALUES
+.Rv -std
+.Sh ERRORS
+A call to these functions may fail with the following errors:
+.Bl -tag -width Er
+.It Bq Er EDOOFUS
+Function
+.Fn pmc_start
+specified a PMC that requires a log file and no log file was
+configured.
+.It Bq Er EINVAL
+The specified PMC is in the process of being deleted.
+.It Bq Er EINVAL
+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.
+.El
+.Sh SEE ALSO
+.Xr pmc 3 ,
+.Xr hwpmc 4