From 677d4530c2e5cb40d9dfb39e8d246e6bd2469e71 Mon Sep 17 00:00:00 2001 From: Joseph Koshy Date: Sun, 25 Nov 2007 06:38:55 +0000 Subject: [PATCH] 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(). --- lib/libpmc/Makefile | 33 ++--- lib/libpmc/pmc_attach.3 | 149 ++++++++++++++++++++ lib/libpmc/pmc_capabilities.3 | 224 ++++++++++++++++++++++++++++++ lib/libpmc/pmc_get_driver_stats.3 | 73 ++++++++++ lib/libpmc/pmc_get_msr.3 | 76 ++++++++++ lib/libpmc/pmc_read.3 | 84 +++++++++++ lib/libpmc/pmc_set.3 | 73 ++++++++++ lib/libpmc/pmc_start.3 | 76 ++++++++++ 8 files changed, 772 insertions(+), 16 deletions(-) create mode 100644 lib/libpmc/pmc_attach.3 create mode 100644 lib/libpmc/pmc_capabilities.3 create mode 100644 lib/libpmc/pmc_get_driver_stats.3 create mode 100644 lib/libpmc/pmc_get_msr.3 create mode 100644 lib/libpmc/pmc_read.3 create mode 100644 lib/libpmc/pmc_set.3 create mode 100644 lib/libpmc/pmc_start.3 diff --git a/lib/libpmc/Makefile b/lib/libpmc/Makefile index ea61d736ab2..79c67160412 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 00000000000..62b0be6b089 --- /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 00000000000..7506454412b --- /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 00000000000..d8bfe233b60 --- /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 00000000000..6a2b94274bd --- /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 00000000000..6056feac253 --- /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 00000000000..a9e438af9df --- /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 00000000000..b132d0f339a --- /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