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().
This commit is contained in:
jkoshy
parent
b9948f58e5
commit
9b5ab01a49
@ -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 \
|
||||
|
||||
149
lib/libpmc/pmc_attach.3
Normal file
149
lib/libpmc/pmc_attach.3
Normal file
@ -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
|
||||
224
lib/libpmc/pmc_capabilities.3
Normal file
224
lib/libpmc/pmc_capabilities.3
Normal file
@ -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
|
||||
73
lib/libpmc/pmc_get_driver_stats.3
Normal file
73
lib/libpmc/pmc_get_driver_stats.3
Normal file
@ -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
|
||||
76
lib/libpmc/pmc_get_msr.3
Normal file
76
lib/libpmc/pmc_get_msr.3
Normal file
@ -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
|
||||
84
lib/libpmc/pmc_read.3
Normal file
84
lib/libpmc/pmc_read.3
Normal file
@ -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
|
||||
73
lib/libpmc/pmc_set.3
Normal file
73
lib/libpmc/pmc_set.3
Normal file
@ -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
|
||||
76
lib/libpmc/pmc_start.3
Normal file
76
lib/libpmc/pmc_start.3
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user