diff --git a/lib/libpmc/Makefile b/lib/libpmc/Makefile index fbb503e64223..513977001cdd 100644 --- a/lib/libpmc/Makefile +++ b/lib/libpmc/Makefile @@ -7,7 +7,7 @@ INCS= pmc.h pmclog.h WARNS?= 6 -MAN= pmc.3 pmc_allocate.3 pmclog.3 +MAN= pmc.3 pmc_allocate.3 pmc_disable.3 pmclog.3 MLINKS+= \ pmc_allocate.3 pmc_release.3 \ @@ -16,8 +16,7 @@ MLINKS+= \ pmc.3 pmc_configure_logfile.3 \ pmc.3 pmc_cpuinfo.3 \ pmc.3 pmc_detach.3 \ - pmc.3 pmc_disable.3 \ - pmc.3 pmc_enable.3 \ + pmc_disable.3 pmc_enable.3 \ pmc.3 pmc_event_names_of_class.3 \ pmc.3 pmc_flush_logfile.3 \ pmc.3 pmc_get_driver_stats.3 \ diff --git a/lib/libpmc/pmc_disable.3 b/lib/libpmc/pmc_disable.3 new file mode 100644 index 000000000000..f28d0b967a1e --- /dev/null +++ b/lib/libpmc/pmc_disable.3 @@ -0,0 +1,99 @@ +.\" 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 20, 2007 +.Os +.Dt PMC_ENABLE 3 +.Sh NAME +.Nm pmc_disable , +.Nm pmc_enable +.Nd administrative control of hardware performance counters +.Sh LIBRARY +.Lb libpmc +.Sh SYNOPSIS +.In pmc.h +.Ft int +.Fn pmc_disable "int cpu" "int pmc" +.Ft int +.Fn pmc_enable "int cpu" "int pmc" +.Sh DESCRIPTION +These functions allow specific hardware performance monitoring +counters in a system to be disabled and enabled administratively. +The hardware performance counters available on each CPU are numbered +using small non-negative integers, in a system dependent manner. +Disabled counters will not be available to applications for use. +.Pp +The invoking process needs to have the +.Dv PRIV_PMC_MANAGE +privilege to perform these operations. +.Pp +Function +.Fn pmc_disable +disables the hardware counter numbered by argument +.Fa pmc +on CPU number +.Fa cpu . +.Pp +Function +.Fn pmc_enable +enables the hardware counter numbered by argument +.Fa pmc +on CPU number +.Fa cpu . +.Sh IMPLEMENTATION NOTES +Hardware PMCs that are currently in use by applications cannot be +disabled. +Allocation of a process scope software PMC marks all +hardware PMCs in the system with the same pmc number as being in-use. +.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 +Function +.Fn pmc_disable +specified a hardware PMC is currently in use. +.It Bq Er EINVAL +Arguments +.Fa cpu +or +.Fa pmc +were invalid. +.It Bq Er ENXIO +Argument +.Fa cpu +specified a disabled CPU. +.It Bq Er EPERM +The current process lacks sufficient privilege to perform this +operation. +.El +.Sh SEE ALSO +.Xr pmc 3 , +.Xr pmc_cpuinfo 3 , +.Xr pmc_pmcinfo 3 , +.Xr hwpmc 4 , +.Xr pmccontrol 8 , +.Xr priv_check 9 \ No newline at end of file