From 472c72067316000d2de032f8063b3142c1268450 Mon Sep 17 00:00:00 2001 From: jkoshy Date: Fri, 23 Nov 2007 11:46:08 +0000 Subject: Describe pmc_allocate() and pmc_release() in their own manual page. --- lib/libpmc/pmc_allocate.3 | 184 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 lib/libpmc/pmc_allocate.3 (limited to 'lib/libpmc/pmc_allocate.3') diff --git a/lib/libpmc/pmc_allocate.3 b/lib/libpmc/pmc_allocate.3 new file mode 100644 index 0000000..2ca27ad --- /dev/null +++ b/lib/libpmc/pmc_allocate.3 @@ -0,0 +1,184 @@ +.\" 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_ALLOCATE 3 +.Sh NAME +.Nm pmc_allocate , +.Nm pmc_release +.Nd allocate and free performance monitoring counters +.Sh LIBRARY +.Lb libpmc +.Sh SYNOPSIS +.In pmc.h +.Ft int +.Fo pmc_allocate +.Fa "const char *eventspecifier" +.Fa "enum pmc_mode mode" +.Fa "uint32_t flags" +.Fa "int cpu" +.Fa "pmc_id_t *pmcid" +.Fc +.Ft int +.Fn pmc_release "pmc_id_t pmc" +.Sh DESCRIPTION +Function +.Fn pmc_allocate +allocates a performance monitoring counter that measures the events +named by argument +.Fa eventspecifier , +and writes the allocated handle to the location pointed to by argument +.Fa pmcid . +.Pp +Argument +.Fa eventspecifier +comprises an PMC event name followed by an optional comma separated +list of keywords and qualifiers. +The allowed syntax for argument +.Fa eventspecifier +is processor specific and is listed in section +.Sx "EVENT SPECIFIERS" +in the +.Xr pmc 3 +manual page. +.Pp +The desired PMC mode is specified by argument +.Fa mode . +Legal values for the +.Fa mode +argument are: +.Bl -tag -width ".Dv PMC_MODE_SS" -compact +.It Dv PMC_MODE_SC +Allocate a system-scope counting PMC. +.It Dv PMC_MODE_SS +Allocate a system-scope sampling PMC. +.It Dv PMC_MODE_TC +Allocate a process-scope counting PMC. +.It Dv PMC_MODE_TS +Allocate a process-scope sampling PMC. +.El +.Pp +Mode specific modifiers may be specified using argument +.Fa flags . +The flags supported at PMC allocation time are: +.Bl -tag -width ".Dv PMC_F_LOG_PROCEXIT" -compact +.It Dv PMC_F_DESCENDANTS +For process-scope PMCs, automatically track descendants of attached +processes. +.It Dv PMC_F_LOG_PROCCSW +For process-scope counting PMCs, generate a log event at every context +switch containing the incremental number of hardware events seen +by the process during the time it was executing on the CPU. +.It Dv PMC_F_LOG_PROCEXIT +For process-scope counting PMCs, accumulate hardware events seen +when the process was executing on a CPU and generate a log event +when an attached process exits. +.El +PMCs allocated with flags +.Dv PMC_F_LOG_PROCCSW +and +.Dv PMC_F_LOG_PROCEXIT +need a log file to be configured before they are started. +.Pp +For system scope PMCs, the argument +.Fa cpu +is a non-negative value that specifies the CPU number +that the PMC is to be allocated on. +Process scope PMC allocations should specify the constant +.Dv PMC_CPU_ANY +for this argument. +.Pp +Function +.Fn pmc_release +releases the PMC denoted by argument +.Fa pmcid . +.Sh RETURN VALUES +If successful, function +.Fn pmc_allocate +sets the location specified by argument +.Fa pmcid +to the handle of the allocated PMC and returns 0. +In case of an error, the function returns -1 and sets the global +variable +.Va errno +to indicate the error. +.Pp +.Rv -std pmc_release +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The argument +.Fa mode +to function +.Fn pmc_allocate +had an invalid value. +.It Bq Er EINVAL +Argument +.Fa cpu +to function +.Fn pmc_allocate +had an invalid CPU number. +.It Bq Er EINVAL +Argument +.Fa flags +contained flags that were unsupported or otherwise incompatible with +the requested PMC mode. +.It Bq Er EINVAL +Argument +.Fa eventspecifier +to function +.Fn pmc_allocate +specified an event not supported by hardware or contained a syntax +error. +.It Bq Er ENXIO +Function +.Fn pmc_allocate +requested the use of a hardware resource that was previously +administratively disabled. +.It Bq Er EOPNOTSUPP +The underlying hardware does not support the capabilities needed for +a PMC being allocated by a call to +.Fn pmc_allocate . +.It Bq Er EPERM +A system scope PMC allocation was attempted without adequate process +privilege. +.It Bq Er ESRCH +Function +.Fn pmc_release +was called without first having allocated a PMC. +.It Bq Er EINVAL +Argument +.Fa pmcid +to function +.Fn pmc_release +did not specify a PMC previously allocated by this process. +.El +.Sh SEE ALSO +.Xr pmc 3 , +.Xr pmc_attach 3 , +.Xr pmc_configure_logfile 3 , +.Xr pmc_start 3 , +.Xr hwpmc 4 -- cgit v1.1