| .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. |
| .\" and Copyright (C) 2013 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" Written by Ivana Varekova <varekova@redhat.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH PERFMONCTL 2 2013-02-13 Linux "Linux Programmer's Manual" |
| .SH NAME |
| perfmonctl \- interface to IA-64 performance monitoring unit |
| .SH SYNOPSIS |
| .nf |
| .B #include <syscall.h> |
| .B #include <perfmon.h> |
| .sp |
| .BI "long perfmonctl(int " fd ", int " cmd ", void *" arg ", int " narg "); |
| .fi |
| .IR Note : |
| There is no glibc wrapper for this system call; see NOTES. |
| .SH DESCRIPTION |
| The IA-64-specific |
| .BR perfmonctl () |
| system call provides an interface to the |
| PMU (performance monitoring unit). |
| The PMU consists of PMD (performance monitoring data) registers and |
| PMC (performance monitoring control) registers, |
| which gather hardware statistics. |
| |
| .BR perfmonctl () |
| applies the operation |
| .I cmd |
| to the input arguments specified by |
| .IR arg . |
| The number of arguments is defined by \fInarg\fR. |
| The |
| .I fd |
| argument specifies the perfmon context to operate on. |
| |
| Supported values for |
| .I cmd |
| are: |
| .TP |
| .B PFM_CREATE_CONTEXT |
| .nf |
| .BI "perfmonctl(int " fd ", PFM_CREATE_CONTEXT, pfarg_context_t *" ctxt ", 1); |
| .fi |
| Set up a context. |
| |
| The |
| .I fd |
| parameter is ignored. |
| A new perfmon context is created as specified in |
| .I ctxt |
| and its file descriptor is returned in \fIctxt->ctx_fd\fR. |
| |
| The file descriptor can be used in subsequent calls to |
| .BR perfmonctl () |
| and can be used to read event notifications (type |
| .IR pfm_msg_t ) |
| using |
| .BR read (2). |
| The file descriptor is pollable using |
| .BR select (2), |
| .BR poll (2), |
| and |
| .BR epoll (7). |
| |
| The context can be destroyed by calling |
| .BR close (2) |
| on the file descriptor. |
| .TP |
| .B PFM_WRITE_PMCS |
| .\" pfm_write_pmcs() |
| .nf |
| .BI "perfmonctl(int " fd ", PFM_WRITE_PMCS, pfarg_reg_t *" pmcs ", n); |
| .fi |
| Set PMC registers. |
| .TP |
| .B PFM_WRITE_PMDS |
| .nf |
| .BI "perfmonctl(int " fd ", PFM_WRITE_PMDS, pfarg_reg_t *" pmds ", n); |
| .fi |
| .\" pfm_write_pmds() |
| Set PMD registers. |
| .TP |
| .B PFM_READ_PMDS |
| .\" pfm_read_pmds() |
| .nf |
| .BI "perfmonctl(int " fd ", PFM_READ_PMDS, pfarg_reg_t *" pmds ", n); |
| .fi |
| Read PMD registers. |
| .TP |
| .B PFM_START |
| .\" pfm_start() |
| .nf |
| .\" .BI "perfmonctl(int " fd ", PFM_START, arg, 1); |
| .BI "perfmonctl(int " fd ", PFM_START, NULL, 0); |
| .fi |
| Start monitoring. |
| .TP |
| .B PFM_STOP |
| .\" pfm_stop() |
| .nf |
| .BI "perfmonctl(int " fd ", PFM_STOP, NULL, 0); |
| .fi |
| Stop monitoring. |
| .TP |
| .B PFM_LOAD_CONTEXT |
| .\" pfm_context_load() |
| .nf |
| .BI "perfmonctl(int " fd ", PFM_LOAD_CONTEXT, pfarg_load_t *" largs ", 1); |
| .fi |
| Attach the context to a thread. |
| .TP |
| .B PFM_UNLOAD_CONTEXT |
| .\" pfm_context_unload() |
| .nf |
| .BI "perfmonctl(int " fd ", PFM_UNLOAD_CONTEXT, NULL, 0); |
| .fi |
| Detach the context from a thread. |
| .TP |
| .B PFM_RESTART |
| .\" pfm_restart() |
| .nf |
| .BI "perfmonctl(int " fd ", PFM_RESTART, NULL, 0); |
| .fi |
| Restart monitoring after receiving an overflow notification. |
| .TP |
| .B PFM_GET_FEATURES |
| .\" pfm_get_features() |
| .nf |
| .BI "perfmonctl(int " fd ", PFM_GET_FEARURES, pfarg_features_t *" arg ", 1); |
| .fi |
| .TP |
| .B PFM_DEBUG |
| .\" pfm_debug() |
| .nf |
| .BI "perfmonctl(int " fd ", PFM_DEBUG, " val ", 0); |
| .fi |
| If |
| .I val |
| is nonzero, enable debugging mode, otherwise disable. |
| .TP |
| .B PFM_GET_PMC_RESET_VAL |
| .\" pfm_get_pmc_reset() |
| .nf |
| .BI "perfmonctl(int " fd ", PFM_GET_PMC_RESET_VAL, pfarg_reg_t * " req ", n); |
| .fi |
| Reset PMC registers to default values. |
| .\" |
| .\" |
| .\" .TP |
| .\" .B PFM_CREATE_EVTSETS |
| .\" |
| .\" create or modify event sets |
| .\" .nf |
| .\" .BI "perfmonctl(int " fd ", PFM_CREATE_EVTSETS, pfarg_setdesc_t *desc , n); |
| .\" .fi |
| .\" .TP |
| .\" .B PFM_DELETE_EVTSETS |
| .\" delete event sets |
| .\" .nf |
| .\" .BI "perfmonctl(int " fd ", PFM_DELETE_EVTSET, pfarg_setdesc_t *desc , n); |
| .\" .fi |
| .\" .TP |
| .\" .B PFM_GETINFO_EVTSETS |
| .\" get information about event sets |
| .\" .nf |
| .\" .BI "perfmonctl(int " fd ", PFM_GETINFO_EVTSETS, pfarg_setinfo_t *info, n); |
| .\" .fi |
| .SH RETURN VALUE |
| .BR perfmonctl () |
| returns zero when the operation is successful. |
| On error, \-1 is returned and |
| .I errno |
| is set to indicate the cause of the error. |
| .SH VERSIONS |
| .BR perfmonctl () |
| is available since Linux 2.4. |
| .SH CONFORMING TO |
| .BR perfmonctl () |
| is Linux-specific and is available only on the IA-64 architecture. |
| .SH NOTES |
| Glibc does not provide a wrapper for this system call; call it using |
| .BR syscall (2). |
| .SH SEE ALSO |
| .BR gprof (1) |
| |
| The perfmon2 interface specification |