Changeset View
Standalone View
lib/libpmc/pmc.3
Show All 17 Lines | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" 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 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd May 28, 2022 | .Dd June 3, 2022 | ||||
.Dt PMC 3 | .Dt PMC 3 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm pmc | .Nm pmc | ||||
.Nd library for accessing hardware performance monitoring counters | .Nd library for accessing hardware performance monitoring counters | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libpmc | .Lb libpmc | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
▲ Show 20 Lines • Show All 91 Lines • ▼ Show 20 Lines | |||||
.Xr pmclog 3 | .Xr pmclog 3 | ||||
family of functions. | family of functions. | ||||
.Ss Supported CPUs | .Ss Supported CPUs | ||||
The CPUs known to the PMC library are named by the | The CPUs known to the PMC library are named by the | ||||
.Vt "enum pmc_cputype" | .Vt "enum pmc_cputype" | ||||
enumeration. | enumeration. | ||||
Supported CPUs include: | Supported CPUs include: | ||||
.Pp | .Pp | ||||
.Bl -tag -width "Li PMC_CPU_INTEL_CORE2" -compact | .Bl -tag -width "Li PMC_CPU_ARMV7_CORTEX_A15" -compact | ||||
.It Li PMC_CPU_AMD_K7 | .It Li PMC_CPU_AMD_K7 | ||||
.Tn "AMD Athlon" | .Tn "AMD Athlon" | ||||
CPUs. | CPUs. | ||||
.It Li PMC_CPU_AMD_K8 | .It Li PMC_CPU_AMD_K8 | ||||
.Tn "AMD Athlon64" | .Tn "AMD Athlon64" | ||||
CPUs. | CPUs. | ||||
.It Li PMC_CPU_INTEL_ATOM | .It Li PMC_CPU_INTEL_ATOM | ||||
.Tn Intel | .Tn Intel | ||||
Show All 11 Lines | |||||
performance measurement architecture. | performance measurement architecture. | ||||
.It Li PMC_CPU_INTEL_CORE2 | .It Li PMC_CPU_INTEL_CORE2 | ||||
.Tn Intel | .Tn Intel | ||||
.Tn "Core2 Solo" , | .Tn "Core2 Solo" , | ||||
.Tn "Core2 Duo" | .Tn "Core2 Duo" | ||||
and | and | ||||
.Tn "Core2 Extreme" | .Tn "Core2 Extreme" | ||||
CPUs, and other CPUs conforming to version 2 of the | CPUs, and other CPUs conforming to version 2 of the | ||||
.Tn Intel | .Tn Intel | ||||
mhorne: Making a note for future work: we ought to find a better solution for this list of AMD and… | |||||
Done Inline Actions
Is there an implicit definition that could work instead? *rummages into dmesg.boot* Like whatever test outputs "TSC: P-state invariant, performance statistics" at boot? (13.1 amd64) pauamma_gundo.com: > avoid trying (and failing) to maintain a list of specific CPU models.
Is there an implicit… | |||||
performance measurement architecture. | performance measurement architecture. | ||||
.It Li PMC_CPU_PPC_7450 | |||||
.Tn PowerPC | |||||
MPC7450 CPUs. | |||||
.It Li PMC_CPU_PPC_E500 | |||||
.Tn PowerPC | |||||
e500 Core CPUs. | |||||
.It Li PMC_CPU_PPC_970 | |||||
.Tn IBM | |||||
.Tn PowerPC | |||||
970 CPUs. | |||||
.It Li PMC_CPU_PPC_POWER8 | |||||
.Tn IBM | |||||
.Tn POWER8 and | |||||
Not Done Inline ActionsI believe this also covers POWER9 CPUs. mhorne: I believe this also covers POWER9 CPUs. | |||||
Done Inline Actions
Maybe add that to sys/sys/pmc.h in that case? I went by the current content: __PMC_CPU(PPC_POWER8, 0x390, "IBM POWER8") \ pauamma_gundo.com: > I believe this also covers POWER9 CPUs.
Maybe add that to sys/sys/pmc.h in that case? I went… | |||||
Not Done Inline ActionsIt does cover POWER9 CPUs too. The reason there is only PPC_POWER8 class in sys/sys/pmc.h is that POWER9 counters are programmed exactly like the POWER8 ones. luporl: It does cover POWER9 CPUs too.
The reason there is only PPC_POWER8 class in sys/sys/pmc.h is… | |||||
Done Inline ActionsThanks. Will add as a trademark, then. pauamma_gundo.com: Thanks. Will add as a trademark, then. | |||||
.Tn POWER9 | |||||
CPUs. | |||||
.It Li GENERIC | |||||
Generic | |||||
.It Li PMC_CPU_ARMV7_CORTEX_A5 | |||||
.Tn ARMv7 | |||||
.Tn Cortex A5 | |||||
CPUs. | |||||
.It Li PMC_CPU_ARMV7_CORTEX_A7 | |||||
.Tn ARMv7 | |||||
.Tn Cortex A7 | |||||
CPUs. | |||||
.It Li PMC_CPU_ARMV7_CORTEX_A8 | |||||
.Tn ARMv7 | |||||
.Tn Cortex A8 | |||||
CPUs. | |||||
.It Li PMC_CPU_ARMV7_CORTEX_A9 | |||||
.Tn ARMv7 | |||||
.Tn Cortex A9 | |||||
CPUs. | |||||
.It Li PMC_CPU_ARMV7_CORTEX_A15 | |||||
.Tn ARMv7 Cortex A15 | |||||
CPUs. | |||||
.It Li PMC_CPU_ARMV7_CORTEX_A17 | |||||
.Tn ARMv7 | |||||
.Tn Cortex A17 | |||||
CPUs. | |||||
.It Li PMC_CPU_ARMV8_CORTEX_A53 | |||||
ARMv8 | |||||
.Tn Cortex A53 | |||||
CPUs. | |||||
.It Li PMC_CPU_ARMV8_CORTEX_A57 | |||||
ARMv8 | |||||
.Tn Cortex A57 | |||||
CPUs. | |||||
.It Li PMC_CPU_ARMV8_CORTEX_A76 | |||||
ARMv8 | |||||
.Tn Cortex A76 | |||||
CPUs. | |||||
.El | .El | ||||
.Ss Supported PMCs | .Ss Supported PMCs | ||||
PMC supported by this library are named by the | PMCs supported by this library are named by the | ||||
.Vt enum pmc_class | .Vt enum pmc_class | ||||
enumeration. | enumeration. | ||||
Supported PMC kinds include: | Supported PMC classes include: | ||||
.Pp | .Pp | ||||
.Bl -tag -width "Li PMC_CLASS_IAF" -compact | .Bl -tag -width "Li PMC_CLASS_POWER8" -compact | ||||
.It Li PMC_CLASS_IAF | .It Li PMC_CLASS_IAF | ||||
Fixed function hardware counters presents in CPUs conforming to the | Fixed function hardware counters presents in CPUs conforming to the | ||||
.Tn Intel | .Tn Intel | ||||
performance measurement architecture version 2 and later. | performance measurement architecture version 2 and later. | ||||
.It Li PMC_CLASS_IAP | .It Li PMC_CLASS_IAP | ||||
Programmable hardware counters present in CPUs conforming to the | Programmable hardware counters present in CPUs conforming to the | ||||
.Tn Intel | .Tn Intel | ||||
performance measurement architecture version 1 and later. | performance measurement architecture version 1 and later. | ||||
.It Li PMC_CLASS_K7 | .It Li PMC_CLASS_K7 | ||||
Programmable hardware counters present in | Programmable hardware counters present in | ||||
.Tn "AMD Athlon" | .Tn "AMD Athlon" | ||||
CPUs. | CPUs. | ||||
.It Li PMC_CLASS_K8 | .It Li PMC_CLASS_K8 | ||||
Programmable hardware counters present in | Programmable hardware counters present in | ||||
.Tn "AMD Athlon64" | .Tn "AMD Athlon64" | ||||
CPUs. | CPUs. | ||||
.It Li PMC_CLASS_TSC | .It Li PMC_CLASS_TSC | ||||
The timestamp counter on i386 and amd64 architecture CPUs. | The timestamp counter on i386 and amd64 architecture CPUs. | ||||
.It Li PMC_CLASS_ARMV7 | |||||
.Tn ARMv7 | |||||
.It Li PMC_CLASS_ARMV8 | |||||
.Tn ARMv8 | |||||
.It Li PMC_CLASS_PPC970 | |||||
.Tn IBM | |||||
.Tn PowerPC | |||||
970 class. | |||||
.It Li PMC_CLASS_POWER8 | |||||
.Tn IBM | |||||
.Tn POWER8 | |||||
class. | |||||
.It Li PMC_CLASS_SOFT | .It Li PMC_CLASS_SOFT | ||||
Software events. | Software events. | ||||
.El | .El | ||||
.Ss PMC Capabilities | .Ss PMC Capabilities | ||||
Capabilities of performance monitoring hardware are denoted using | Capabilities of performance monitoring hardware are denoted using | ||||
the | the | ||||
.Vt "enum pmc_caps" | .Vt "enum pmc_caps" | ||||
enumeration. | enumeration. | ||||
▲ Show 20 Lines • Show All 158 Lines • ▼ Show 20 Lines | |||||
.It Dv SIGIO | .It Dv SIGIO | ||||
The | The | ||||
.Xr hwpmc 4 | .Xr hwpmc 4 | ||||
driver will send a PMC owning process a | driver will send a PMC owning process a | ||||
.Dv SIGIO | .Dv SIGIO | ||||
signal if: | signal if: | ||||
.Bl -bullet | .Bl -bullet | ||||
.It | .It | ||||
If any process-mode PMC allocated by it loses all its | any process-mode PMC allocated by it loses all its | ||||
target processes. | target processes. | ||||
.It | .It | ||||
If the driver encounters an error when writing log data to a | the driver encounters an error when writing log data to a | ||||
configured log file. | configured log file. | ||||
This error may be retrieved by a subsequent call to | This error may be retrieved by a subsequent call to | ||||
.Fn pmc_flush_logfile . | .Fn pmc_flush_logfile . | ||||
.El | .El | ||||
.El | .El | ||||
.Ss Typical Program Flow | .Ss Typical Program Flow | ||||
.Bl -enum | .Bl -enum | ||||
.It | .It | ||||
Show All 28 Lines | |||||
family of functions. | family of functions. | ||||
.It | .It | ||||
PMCs are stopped using function | PMCs are stopped using function | ||||
.Fn pmc_stop , | .Fn pmc_stop , | ||||
and process scope PMCs are detached from their targets using | and process scope PMCs are detached from their targets using | ||||
function | function | ||||
.Fn pmc_detach . | .Fn pmc_detach . | ||||
.It | .It | ||||
Before the process exits, its may release its PMCs using function | Before the process exits, it may release its PMCs using function | ||||
.Fn pmc_release . | .Fn pmc_release . | ||||
Any configured log file may be closed using function | Any configured log file may be closed using function | ||||
.Fn pmc_configure_logfile . | .Fn pmc_configure_logfile . | ||||
Not Done Inline ActionsWhile I'm touching this file: shouldn't this be pmc_close_logfile instead? pauamma_gundo.com: While I'm touching this file: shouldn't this be `pmc_close_logfile` instead? | |||||
Not Done Inline ActionsIt seems that pmc_configure_logfile(-1) is used to flush and close any open logfile for the process. The exact difference in intent/functionality between this and pmc_close_logfile() is not obvious on a quick glance. So, I think it is okay to leave this as-is for now. mhorne: It seems that `pmc_configure_logfile(-1)` is used to flush and close any open logfile for the… | |||||
.El | .El | ||||
.Sh EVENT SPECIFIERS | .Sh EVENT SPECIFIERS | ||||
Event specifiers are strings comprising of an event name, followed by | Event specifiers are strings comprising of an event name, followed by | ||||
optional parameters modifying the semantics of the hardware event | optional parameters modifying the semantics of the hardware event | ||||
being probed. | being probed. | ||||
Event names are PMC architecture dependent, but the PMC library defines | Event names are PMC architecture dependent, but the PMC library defines | ||||
machine independent aliases for commonly used events. | machine independent aliases for commonly used events. | ||||
.Pp | .Pp | ||||
▲ Show 20 Lines • Show All 108 Lines • Show Last 20 Lines |
Making a note for future work: we ought to find a better solution for this list of AMD and Intel processors. What is here is so outdated as to not be useful (or worse, misleading); instead we need to find the words to communicate that "most AMD and Intel processors are supported", but avoid trying (and failing) to maintain a list of specific CPU models.